NBIOTProtocolAccessGuideWord格式文档下载.docx
《NBIOTProtocolAccessGuideWord格式文档下载.docx》由会员分享,可在线阅读,更多相关《NBIOTProtocolAccessGuideWord格式文档下载.docx(59页珍藏版)》请在冰豆网上搜索。
图1-1LWM2M协议栈
∙LWM2MObjects:
每个对象对应客户端的某个特定功能实体。
LWM2M规范定义了以下标准Objects,比如
ourn:
oma:
lwm2m:
2;
(LWM2MServerObject);
3;
(LWM2MAccessControlObject);
o每个object下可以有很多resource,比如Firmwareobject可以有Firmware版本号,size等resource;
oVendor可以自己定义object。
∙LWM2MProtocol:
定义了一些逻辑操作,比如Read,Write,Execute,DiscoverorObserve等。
LWM2M协议的具体内容和消息格式可以参考OMA的网站
https:
//en.wikipedia.org/wiki/OMA_LWM2M
CoAP协议的说明
CoAP(ConstrainedApplicationProtocol)协议是IETF提出的一种面向网络的协议,采用了与HTTP类似的特征,核心内容为资源抽象、REST式交互以及可扩展的头选项等。
CoAP协议基于REST构架,REST是指表述性状态转换架构,是互联网资源访问协议的一般性设计风格。
为了克服HTTP对于受限环境的劣势,CoAP既考虑到数据报长度的最优化,又考虑到提供可靠通信。
一方面,CoAP提供URI,REST式的方法如GET、POST、PUT和DELETE,以及可以独立定义的头选项提供的可扩展性。
另一方面,CoAP基于轻量级的UDP协议,并且允许IP多播。
为了弥补UDP传输的不可靠性,CoAP定义了带有重传机制的事务处理机制。
并且提供资源发现机制,并带有资源描述。
CoAP协议栈示意图
CoAP由UDP作为承载,遵循UDP基本的协议报文格式,UDP数据内容部分按照CoAP协议报文格式进行写入传输。
CoAP协议格式说明如下:
●【Ver】版本编号,指示CoAP协议的版本号。
类似于HTTP1.0HTTP1.1。
版本编号占2位,取值为01B。
●【T】报文类型,CoAP协议定义了4种不同形式的报文:
CON报文,NON报文,ACK报文和RST报文。
●【TKL】CoAP标识符长度。
CoAP协议中具有两种功能相似的标识符,一种为MessageID(报文编号),一种为Token(标识符)。
其中每个报文均包含消息编号,但是标识符对于报文来说是非必须的。
●【Code】功能码/响应码。
Code在CoAP请求报文和响应报文中具有不同的表现形式,Code占一个字节,它被分成了两部分,前3位一部分,后5位一部分,为了方便描述它被写成了c.dd结构。
其中0.XX表示CoAP请求的某种方法,而2.XX、4.XX或5.XX则表示CoAP响应的某种具体表现。
●【MessageID】报文编号。
●【Token】标识符具体内容,通过TKL指定Token长度。
●【Option】报文选项,通过报文选项可设定CoAP主机、CoAPURI、CoAP请求参数和负载媒体类型等等。
●【11111111B】CoAP报文和具体负载之间的分隔符。
CoAP支持多个Option,CoAP的Option的表示方法比较特殊,采用增量的方式描述。
一般情况下Option部分包含OptionDelta、OptionLength和OptionVal三部分:
●【OptionDelta】表示Option的增量,当前的Option的具体编号等于之前所有OptionDelta的总和。
●【OptionLength】表示OptionVal终端设备的具体长度。
●【OptionVal终端设备】表示Option具体内容。
协议报文示意图
CoAP协议报文中具体数值的意义参考CoAP协议:
IETFRFC7252。
Object
ObjectInstance
Resource
权限
值
数据类型
摄像头(100)
最大像素(0)
R
12,000,000
Integer
像素
(1)
RW
最大光圈
(2)
2.2
Float
最小光圈(3)
32
光圈(4)
5.6
快门(5)
E
当前图像(6)
二进制图像
Opaque(二进制)
…
1
8,000,000
光线传感器(101)
GPS(102)
陀螺仪(103)
1.2资源模型
LWM2M协议定义了三层资源模型:
Object,ObjectInstance,Resource,每一层都用数字ID来标识。
其中,Object是传感器类别,ObjectInstance是传感器具体实例,Resource是传感器的属性和读数等,每个Resource具有不同的权限和数据类型,包括可读(R)/可写(W)/可执行(E)。
一个终端设备上可能存在多个Object,每个Object可能存在多个ObjectInstance。
例如,把手机看作一个终端设备,则手机上有摄像头,光线传感器,GPS,陀螺仪等多种传感器,每种传感器便是一个Object。
假定摄像头的ObjectID为100,手机上有前后两个摄像头,即两个ObjectInstance,ID分别为0,1。
每一个摄像头包括了像素,镜头焦距,光圈,快门值,快门等多种Resource。
手机上的部分资源如下:
(ObjectID,ResourceID为示例)
可以使用类似于路径的方式来表示某个资源,例如/100表示Object100(即摄像头),/100/0表示Object100,ObjectInstance0(即摄像头0),/100/0/0表示Object100,ObjectInstance0,Resource0(即摄像头0的的最大像素)。
IPSO的文档<
IPSO-Smart-Objects-Starter-Pack>
<
IPSO-Smart-Objects-Expansion-Pac>
中定义了一些常用传感器的ObjectID和ResourceID,终端设备应按照IPSO文档声明终端上的相关资源。
LWM2M的资源模型与OneNET的数据模型对应如下:
LWM2M
OneNET
备注
终端设备
设备Device
平台为每个设备分配唯一ID
Object,ObjectInstance,Resource
数据流
数据流的名称按照规则ObjectID_ObjectInstanceID_ResourceID生成,例如手机摄像头的例子中,资源/100/0/1对应的数据流为100_0_1
ResourceValue
数据点
资源在某个时间点上传的值,与时间戳一起,形成数据点,存储在OneNET
1.3订阅(Observe机制)
NB-IOT终端设备通过LWM2M协议的订阅(Observe)/上报(Notify)机制将数据上传到OneNET平台。
订阅可以在Object层,ObjectInstance层,Resource层,订阅上层Object时,其所属的所有ObjectInstance都可以上报数据;
订阅ObjectInstance时,其所属的所有Resource都可以上报数据。
每层订阅都是独立的,由资源路径唯一标识。
例如,同时订阅了/100/0和/100/0/0,则/100/0/0的数据会上报两次;
只取消订阅/100/0或者/100/0/0中的某一个,/100/0/0的数据还是会上传。
设备上线时,平台会主动下发Observe消息订阅设备上的所有ObjectInstance(可以在创建设备时关闭自动订阅),也可以使用API订阅感兴趣的资源。
UE与平台间的通信接口基于LWM2M协议,在LWM2M协议以下基于CoAP协议,通信消息包括四部分:
第一部分是发起Bootstrap,BootstrapWrite,Bootstrap完成,第二部分是注册、注销、更新注册消息;
第三部分是观测消息、取消观测、消息上报;
第四部分是设备管理操作,包括read/write/execute操作。
2、SDK使用说明
根据应用的使用方式,基于已经集成SDK的模组,应用可以采取两种方式:
第一种方式是APP集成在模组上,这种场景下应用使用SDK提供的API接口实现;
第二种方式是APP工作在自己的MCU上,同时使用集成了SDK的模组来提供OneNet及NBIOT接入的相关功能,这种场景下应用使用SDK的AT接口。
应用厂家使用集成完SDK的芯片和模组分为两种,第一种是使用SDK提供的API接口,这种方式所有的操作都是同步的,要求APP和模组在同一个芯片核内。
第二种方式是使用AT接口,这种方式所有操作都是异步的,应用可以在自己的MCU中完成自己的应用的开发。
后面分开介绍不同的接口应用的编写。
2.1API接口模式的应用
SDK的API接口包括对基础通信套件进行初始化、反初始化以及其他操作、相应的配置文件、回调函数以及结构体,SDK提供的API接口如下:
2.1.1API接口模式的应用
cis_ret_tcis_init(void**context,void*config,uint32_tsize);
功能:
根据输入的config文件进行SDK初始化
参数及返回值:
参数名称
参数含义
类型
context
上下文信息
void**
指向void*指针地址的指针变量,基础通信套件在初始化成功后会将申请到的上下文结构体地址写入该变量中
config
配置文件信息
void*
size
config的大小
uint32_t
typedefunsigned_int16uint16_t;
返回值
返回值含义
CIS_RET_ERROR
失败
CIS_RET_OK
成功
cis_ret_tcis_deinit(void*context);
反初始化操作,释放SDK占用的资源
上下文结构体地址
cis_ret_tcis_register(void*context,constcis_callback_t*cb);
SDK初始化完成后,该接口向平台进行注册
cb
设备回调
constcis_callback_t*
cis_ret_tcis_unregister(void*context);
该接口用于向服务器发起注销操作
cis_ret_tcis_addobject(void*context,cis_oid_tobjectid,constcis_inst_bitmap_t*bitmap,constcis_res_config_t*resource);
SDK初始化完成后,使用该接口添加object
objectid
cis_oid_t*
bitmap
实例位图
constcis_inst_bitmap_t*
resource
属性数量及操作数量
constcis_res_config_t*
cis_ret_tcis_delobject(void*context,cis_oid_tobjectid);
SDK使用该接口删除object
oid_t*
uint32_tcis_pump(void*context);
用户在初始化完成后,调用该接口驱动SDK运行,SDK在该接口中调度多个任务,包括根据网络回复和状态发起注册消息,根据设定的lifetime定期发起更新注册消息,根据observe参数的设置上报notify消息。
有任务待完成,不能进入休眠模式。
0xFFFFFFFF
可随时进入休眠,自定义休眠时间
1~
0xFFFFFFFF-1
可随时进入休眠,并限定最长休眠时间,单位ms
cis_ret_tcis_change(void*context,oid_tobjectid,iid_tinstid,rid_trid);
SDK提供该接口,用户使用该接口通知SDK有数值变化。
SDK检查当前值是否被平台observe,如果是,检查是否满足observe条件,在条件满足时向平台上报该数据。
objectid
对象ID
cis_oid_t
instid
实例ID
cis_iid_t
rid
资源ID
cis_rid_t
uint32_tcis_update_reg(void*context,uint32_tlifetime,boolwithObjects);
SDK提供该接口,用户使用该接口通知SDK更新注册的lifetime。
如果withObjects参数为true,则同时更新object信息,如果withObjects参数为false,则只更新lifetime。
lifetime
生命周期
withObjects
是否同时更新对象信息
bool
true为更新对象信息,false为不更新对象信息。
cis_ret_tcis_notify(void*context,cis_ret_tresult,cis_data_t*data,uint16_tcount,cis_mid_tmsgid);
当网络侧发来读、写、执行、观测、设置参数请求时,SDK会调用相关回调函数,并传输相应msgid,待真正操作完成时,应用程序使用cis_notify接口返回结果(对于读,需要填写result及data字段,其中result表示读操作成功与否,如果成功,则result设为CIS_CALLBACK_READ_SUCCESS,则data字段填入实际读结果,如果失败,则data为空;
对于写、执行、观测、设置参数,只需分别将操作结果result设置为CIS_CALLBACK_WRITE_SUCCESS、CIS_CALLBACK_EXECUTE_SUCCESS、CIS_CALLBACK_OBSERVE_SUCCESS、CIS_CALLBACK_OBSERVE_PARAMS_SUCCESS或相应的错误值,并将data置空);
或者,应用程序应根据网络侧所设置的数据上报策略自行调用相应AT指令接口填入上报数据,而该AT指令最终会调用cis_notify接口进行数据上报,需要填写data字段,即需要上报的数据,result字段设为CIS_CALLBACK_NOTIFY_SUCCESS。
result
操作结果
cis_ret_t
data
上报的数据
cis_data_t*
count
uint16_t
msgid
消息ID
cis_mid_t
该msgid从cis_on_observe函数获取
cis_ret_tcis_version(void*context,cis_version_t*ver);
获取当前SDK版本时调用本接口获取当前SDK版本
ver
基础通信套件版本
cis_version_t*
主版本号和副版本号为cis_version_t结构体里的两个uint8_t型字段
cis_ret_tcis_uri_make(cis_oid_toid,cis_iid_tiid,cis_rid_trid,cis_uri_t*uri);
根据输入的ObjectID、InstanceID及ResourceID生成URI
oid
ObjectID
iid
IntanceID
ResourceID
uri
待生成的URI
cis_uri_t*
SDK将向该指针指向的结构体中填入相应内容
cis_ret_tcis_uri_update(cis_uri_t*uri);
根据应用程序填入cis_uri_t结构体的ObjectID、InstanceID及ResourceID更新结构体flag
待更新的URI
应用程序在自行更改cis_uri_t结构体相关ID后可调用该API,基础通信套件将更新flag字段
cis_ret_tcis_data_copy(cis_data_t**dst,constcis_data_t*src);
拷贝cis_data_t型源数据至目标地址
dst
目标数据
cis_data_t**
src
源数据
constcis_data_t*
cis_ret_tcis_data_free(cis_data_t*data);
释放cis_data_t型指针指向的内存
待释放数据
cis_data_t*
2.1.2数据结构和回调函数
2.1.2.1回调函数接口
回调函数含义
读资源值回调
cis_read_callback_t
typedefcis_ret_t(*cis_read_callback_t)
(constvoid*context,
cis_uri_t*uri,
cis_data_tdata_t*value,
cis_mid_tmsgid);
写资源值回调
cis_write_callback_t
typedefcis_ret_t(*cis_write_callback_t)
constcis_data_t*value,
执行回调
cis_e