NBIOTProtocolAccessGuideWord格式文档下载.docx

1、图1-1 LWM2M协议栈LWM2M Objects：每个对象对应客户端的某个特定功能实体。LWM2M 规范定义了以下标准Objects，比如ourn:oma:lwm2m:2; （LWM2M Server Object）；3; （LWM2M Access Control Object）；o每个object下可以有很多resource，比如Firmware object可以有Firmware版本号，size等resource；oVendor可以自己定义object。LWM2M Protocol：定义了一些逻辑操作，比如Read, Write, Execute, Discover or Obser

2、ve等。LWM2M协议的具体内容和消息格式可以参考OMA的网站https:/en.wikipedia.org/wiki/OMA_LWM2MCoAP协议的说明CoAP（Constrained Application Protocol）协议是IETF提出的一种面向网络的协议，采用了与HTTP类似的特征，核心内容为资源抽象、REST式交互以及可扩展的头选项等。CoAP协议基于REST构架，REST是指表述性状态转换架构，是互联网资源访问协议的一般性设计风格。为了克服HTTP对于受限环境的劣势，CoAP既考虑到数据报长度的最优化，又考虑到提供可靠通信。一方面，CoAP提供URI，REST式的方法如GE

3、T、POST、PUT和DELETE，以及可以独立定义的头选项提供的可扩展性。另一方面，CoAP基于轻量级的UDP协议，并且允许IP多播。为了弥补UDP传输的不可靠性，CoAP定义了带有重传机制的事务处理机制。并且提供资源发现机制，并带有资源描述。CoAP协议栈示意图CoAP由UDP作为承载，遵循UDP基本的协议报文格式，UDP数据内容部分按照CoAP协议报文格式进行写入传输。CoAP协议格式说明如下：【Ver】版本编号，指示CoAP协议的版本号。类似于HTTP 1.0 HTTP 1.1。版本编号占2位，取值为01B。【T】报文类型，CoAP协议定义了4种不同形式的报文：CON报文，NON报文，

4、ACK报文和RST报文。【TKL】CoAP标识符长度。CoAP协议中具有两种功能相似的标识符，一种为Message ID（报文编号），一种为Token（标识符）。其中每个报文均包含消息编号，但是标识符对于报文来说是非必须的。【Code】功能码/响应码。Code在CoAP请求报文和响应报文中具有不同的表现形式，Code占一个字节，它被分成了两部分，前3位一部分，后5位一部分，为了方便描述它被写成了c.dd结构。其中0.XX表示CoAP请求的某种方法，而2.XX、4.XX或5.XX则表示CoAP响应的某种具体表现。【Message ID】报文编号。【Token】标识符具体内容，通过TKL指定Tok

5、en长度。【Option】报文选项，通过报文选项可设定CoAP主机、CoAP URI、CoAP请求参数和负载媒体类型等等。【1111 1111B】CoAP报文和具体负载之间的分隔符。CoAP支持多个Option，CoAP的Option的表示方法比较特殊，采用增量的方式描述。一般情况下Option部分包含Option Delta、Option Length和Option Val三部分：【Option Delta】表示Option的增量，当前的Option的具体编号等于之前所有Option Delta的总和。【Option Length】表示Option Val终端设备的具体长度。【Option

6、Val终端设备】表示Option具体内容。协议报文示意图CoAP协议报文中具体数值的意义参考CoAP协议：IETF RFC7252。ObjectObject InstanceResource权限值数据类型摄像头 （100）最大像素（0）R12,000,000Integer像素（1）RW最大光圈（2）2.2Float最小光圈（3）32光圈（4）5.6快门（5）E当前图像（6）二进制图像Opaque （二进制）18,000,000光线传感器（101）GPS（102）陀螺仪（103）1.2资源模型LWM2M 协议定义了三层资源模型：Object, Object Instance, Resource,

7、 每一层都用数字ID来标识。其中，Object 是传感器类别，Object Instance 是传感器具体实例，Resource是传感器的属性和读数等，每个 Resource 具有不同的权限和数据类型，包括可读（R） /可写（W） /可执行（E）。一个终端设备上可能存在多个 Object, 每个 Object 可能存在多个 Object Instance。例如，把手机看作一个终端设备，则手机上有摄像头，光线传感器，GPS，陀螺仪等多种传感器，每种传感器便是一个 Object。假定摄像头的 Object ID 为 100，手机上有前后两个摄像头，即两个 Object Instance, ID 分

8、别为 0, 1。每一个摄像头包括了像素，镜头焦距，光圈，快门值，快门等多种 Resource。手机上的部分资源如下：（Object ID, Resource ID为示例）可以使用类似于路径的方式来表示某个资源，例如 /100 表示 Object 100 （即摄像头），/100/0 表示 Object 100, Object Instance 0 （即摄像头0），/100/0/0 表示 Object 100, Object Instance 0, Resource 0 （即摄像头0的的最大像素）。IPSO 的文档 , 中定义了一些常用传感器的 Object ID 和 Resource ID，终端

9、设备应按照IPSO文档声明终端上的相关资源。LWM2M 的资源模型与OneNET 的数据模型对应如下：LWM2MOneNET备注终端设备设备 Device平台为每个设备分配唯一IDObject, Object Instance, Resource数据流数据流的名称按照 规则ObjectID_ObjectInstanceID_ResourceID 生成，例如手机摄像头的例子中，资源 /100/0/1 对应的数据流为 100_0_1Resource Value数据点资源在某个时间点上传的值，与时间戳一起，形成数据点，存储在OneNET1.3订阅（Observe机制） NB-IOT 终端设备通过 L

10、WM2M 协议的订阅（Observe）/上报（Notify） 机制将数据上传到OneNET 平台。订阅可以在 Object 层，Object Instance 层，Resource 层，订阅上层Object时，其所属的所有Object Instance 都可以上报数据；订阅 Object Instance 时，其所属的所有Resource 都可以上报数据。每层订阅都是独立的，由资源路径唯一标识。例如，同时订阅了 /100/0 和 /100/0/0，则 /100/0/0 的数据会上报两次；只取消订阅 /100/0 或者 /100/0/0中的某一个, /100/0/0 的数据还是会上传。设备上线时

11、，平台会主动下发Observe 消息订阅设备上的所有Object Instance （可以在创建设备时关闭自动订阅），也可以使用 API 订阅感兴趣的资源。UE与平台间的通信接口基于LWM2M协议，在LWM2M协议以下基于CoAP协议，通信消息包括四部分：第一部分是发起Bootstrap，Bootstrap Write，Bootstrap完成，第二部分是注册、注销、更新注册消息；第三部分是观测消息、取消观测、消息上报；第四部分是设备管理操作，包括read/write/execute操作。2、SDK使用说明根据应用的使用方式，基于已经集成SDK的模组, 应用可以采取两种方式：第一种方式是APP集

12、成在模组上，这种场景下应用使用SDK提供的API接口实现；第二种方式是APP工作在自己的MCU上，同时使用集成了SDK的模组来提供OneNet及NBIOT接入的相关功能，这种场景下应用使用SDK的AT接口。应用厂家使用集成完SDK的芯片和模组分为两种，第一种是使用SDK提供的API接口，这种方式所有的操作都是同步的，要求APP和模组在同一个芯片核内。第二种方式是使用AT接口，这种方式所有操作都是异步的，应用可以在自己的MCU中完成自己的应用的开发。后面分开介绍不同的接口应用的编写。2.1 API接口模式的应用SDK的API接口包括对基础通信套件进行初始化、反初始化以及其他操作、相应的配置文件、

13、回调函数以及结构体，SDK提供的API接口如下：2.1.1 API接口模式的应用cis_ret_t cis_init （void * context, void * config, uint32_t size）;功能：根据输入的config文件进行SDK初始化参数及返回值：参数名称参数含义类型context上下文信息void *指向void *指针地址的指针变量，基础通信套件在初始化成功后会将申请到的上下文结构体地址写入该变量中config配置文件信息void *sizeconfig的大小uint32_ttypedef unsigned _int16 uint16_t;返回值返回值含义CIS_

14、RET_ERROR失败CIS_RET_OK成功cis_ret_t cis_deinit （void * context）;反初始化操作，释放SDK占用的资源上下文结构体地址cis_ret_t cis_register （void * context, const cis_callback_t* cb）;SDK初始化完成后，该接口向平台进行注册cb设备回调const cis_callback_t*cis_ret_t cis_unregister （void * context）;该接口用于向服务器发起注销操作cis_ret_t cis_addobject （void * context, cis

15、_oid_t objectid, const cis_inst_bitmap_t* bitmap, const cis_res_config_t* resource）;SDK初始化完成后，使用该接口添加objectobject idcis_oid_t *bitmap实例位图const cis_inst_bitmap_t*resource属性数量及操作数量const cis_res_config_t*cis_ret_t cis_delobject （void * context, cis_oid_t objectid）;SDK使用该接口删除objectoid_t *uint32_t cis_pu

16、mp （void * context）;用户在初始化完成后，调用该接口驱动SDK运行，SDK在该接口中调度多个任务，包括根据网络回复和状态发起注册消息，根据设定的lifetime定期发起更新注册消息，根据observe参数的设置上报notify消息。有任务待完成，不能进入休眠模式。0xFFFFFFFF可随时进入休眠，自定义休眠时间1 0xFFFFFFFF - 1可随时进入休眠，并限定最长休眠时间，单位mscis_ret_t cis_change （void * context, oid_t objectid, iid_t instid, rid_t rid）;SDK提供该接口，用户使用该接口通

17、知SDK有数值变化。SDK检查当前值是否被平台observe，如果是，检查是否满足observe条件，在条件满足时向平台上报该数据。objectid对象IDcis_oid_tinstid实例IDcis_iid_trid资源IDcis_rid_tuint32_t cis_update_reg （void * context, uint32_t lifetime, bool withObjects）;SDK提供该接口，用户使用该接口通知SDK更新注册的lifetime。如果withObjects 参数为true，则同时更新object信息，如果withObjects参数为false，则只更新lif

18、etime。lifetime生命周期withObjects是否同时更新对象信息booltrue为更新对象信息，false为不更新对象信息。cis_ret_t cis_notify （void* context, cis_ret_t result, cis_data_t* data, uint16_t count, cis_mid_t msgid）;当网络侧发来读、写、执行、观测、设置参数请求时，SDK会调用相关回调函数，并传输相应msgid，待真正操作完成时，应用程序使用cis_notify接口返回结果（对于读，需要填写result及data字段，其中result表示读操作成功与否，如果成功，

19、则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接口进

20、行数据上报，需要填写data字段，即需要上报的数据，result字段设为CIS_CALLBACK_NOTIFY_SUCCESS。result操作结果cis_ret_tdata上报的数据cis_data_t *countuint16_tmsgid消息IDcis_mid_t该msgid从cis_on_observe函数获取cis_ret_t cis_version （void * context, cis_version_t* ver）;获取当前SDK版本时调用本接口获取当前SDK版本ver基础通信套件版本cis_version_t*主版本号和副版本号为cis_version_t 结构体里的两个u

21、int8_t型字段cis_ret_t cis_uri_make（cis_oid_t oid, cis_iid_t iid, cis_rid_t rid, cis_uri_t* uri）;根据输入的Object ID、Instance ID及Resource ID生成URIoidObject IDiidIntance IDResource IDuri待生成的URIcis_uri_t*SDK将向该指针指向的结构体中填入相应内容cis_ret_t cis_uri_update （cis_uri_t* uri）;根据应用程序填入cis_uri_t结构体的Object ID、Instance ID及Re

22、source ID更新结构体flag待更新的URI应用程序在自行更改cis_uri_t结构体相关ID后可调用该API，基础通信套件将更新flag字段cis_ret_t cis_data_copy（cis_data_t* dst, const cis_data_t * src）;拷贝cis_data_t型源数据至目标地址dst目标数据cis_data_t*src源数据const cis_data_t *cis_ret_t cis_data_free（cis_data_t * data）;释放cis_data_t型指针指向的内存待释放数据cis_data_t*2.1.2 数据结构和回调函数2.1.2.1 回调函数接口回调函数含义读资源值回调cis_read_callback_t typedef cis_ret_t （*cis_read_callback_t）（const void * context,cis_uri_t* uri,cis_data_tdata_t* value,cis_mid_t msgid）;写资源值回调cis_write_callback_t typedef cis_ret_t （*cis_write_callback_t）const cis_data_t* value, 执行回调cis_e