OneNET-NBIoT物联网套件

简介

OneNET推出的NB-IoT物联网套件为用户提供“终端-平台-应用”整体解决方案，帮助企业快速实现NB-IoT能力升级。

主要面向基于蜂窝的窄带物联网（Narrow Band Internet of Things, NB-IoT）场景下物联网应用，聚焦于低功耗广覆盖（LPWA）物联网市场。具有覆盖广、连接多、速率低、成本低、功耗低、架构优等特点。

基于NB-IOT的LwM2M协议和CoAP协议实现UE与OneNET平台的通信，其中实现数据传输的协议为CoAP，应用层协议由LwM2M实现。

Coap协议有以下特点：

• 基于轻量级的UDP协议之上，具有重传机制
• 协议支持IP多播
• 协议包头小，仅为4个字节
• 功耗低，适用于低功耗物联网场景

LwM2M属于轻量级的协议，适用于各种物联网设备，LwM2M定义了三个逻辑实体：

• LwM2M Server 服务器
• LwM2M Client 客户端，负责执行服务器的命令和上报执行结果
• LwM2M 引导服务器 Bootstrap Server，负责配置LwM2M客户端

重要定义及数据结构

用户配置结构体

用于配置网络参数，其定义如下：

typedef struct
{
    uint8_t     bs_enabled;
    uint8_t     dtls_enabled;
    uint8_t    *ip;
    uint8_t    *port;
    uint8_t    *auth_code;
    uint8_t    *psk;
}cis_user_cfg_t;

挂接回调函数结构体

在cis连接实例初始化时需要传入回调函数的结构体，其定义如下：

struct st_cis_callback
{
    cis_read_callback_t         onRead;
    cis_write_callback_t        onWrite;
    cis_exec_callback_t         onExec;
    cis_observe_callback_t      onObserve;
    cis_discover_callback_t     onDiscover;
    cis_set_params_callback_t   onSetParams;
    cis_event_callback_t        onEvent;
};
typedef struct st_cis_callback cis_callback_t;

回调函数的定义常见API列表。

对象实例结构体

用于标识实例数量及是否对平台开放订阅，其定义如下：

struct st_cis_inst_bitmap
{
    cis_instcount_t  instanceCount;
    cis_instcount_t  instanceBytes;
    const uint8_t   *instanceBitmap;
};
typedef struct st_cis_inst_bitmap cis_inst_bitmap_t;

资源数量结构体

用于标识读写和执行资源数量，其定义如下：

struct st_cis_res_count
{
    cis_attrcount_t attrCount;
    cis_actcount_t  actCount;
};
typedef struct st_cis_res_count        cis_res_count_t;

URI结构体

用于表示对象、实例和资源的编号及有效标识，其定义如下：

struct st_uri
{
    uint8_t      flag;           
    cis_oid_t    objectId;
    cis_iid_t    instanceId;
    cis_rid_t    resourceId;
};
typedef struct st_uri cis_uri_t;

data数据结构体

在与平台交互data数据时使用的结构体，其定义如下：

struct st_cis_data
{
    cis_rid_t               id;
    cis_datatype_t          type;

    struct
    {
        uint32_t            length;
        uint8_t            *buffer;
    }asBuffer;

    union
    {
        bool                asBoolean;
        int64_t             asInteger;
        double              asFloat;
    } value;
} ;
typedef struct st_cis_data cis_data_t;

参数设置结构体

用于平台下发的参数设置信息，其定义如下：

struct st_cis_observe_attr
{
    uint8_t     toSet;
    uint8_t     toClear;
    cis_time_t  minPeriod;
    cis_time_t  maxPeriod;
    float       greaterThan;
    float       lessThan;
    float       step;
};
typedef struct st_cis_observe_attr cis_observe_attr_t;

API列表

cis_init

该函数用于cis连接实例初始化，函数原型如下：

cis_ret_t cis_init(void **context, cis_user_cfg_t *cis_user_cfg, void *DMconf);

cis_deinit

该函数用于cis连接实例去初始化，函数原型如下：

cis_ret_t cis_deinit(void **context);

cis_register

该函数用于cis实例初始化完成后，该接口向平台进行注册，函数原型如下：

cis_ret_t cis_register(void *context, cis_time_t lifetime, const cis_callback_t *cb);

cis_unregister

该函数用于向服务器发起注销操作，函数原型如下：

cis_ret_t cis_unregister(void *context);

cis_addobject

该接口用于添加object信息，函数原型如下：

cis_ret_t cis_addobject(void                     *context, 
                        cis_oid_t                 objectid, 
                        const cis_inst_bitmap_t  *bitmap，
                        const cis_res_count_t    *rescount);

cis_delobject

该接口用于删除object信息，函数原型如下：

cis_ret_t cis_delobject(void * context, cis_oid_t objectid);

cis_pump

该接口用于在初始化完成后，调用该接口驱动cis实例运行，基础通信套件在该接口中调度多个任务，包括根据网络回复和状态发起注册消息，根据设定的 lifetime 定期发起更新注册消息等。函数原型如下：

uint32_t cis_pump(void *context);

cis_update_reg

该接口用于通知平台更新注册的 lifetime。如果withObjects 参数为 true，则同时更新 object 信息，如果 withObjects 参数为 false，则只更新 lifetime。函数原型如下：

uint32_t cis_update_reg(void *context, uint32_t lifetime, bool withObjects);

cis_response

当网络侧发来读、写、执行、观测、设置参数等请求时，CIS实例会调用相关回调函数，并在回调中携带相应msgid，待操作完成时，应用程序使用 cis_response 接口返回结果。如果操作成功：对于读操作，如果是这组读操作的最后一条返回，则result设为 CIS_RESPONSE_READ，如果不是最后一条消息，result 设置为 CIS_RESPONSE_CONTINUE。uri是读取的当前数据的标识，msgid 是该条请求的标识，使用对应 callback 携带的 msgid；对于写、执行、观测、设置参数，分别将操作结果 result 设置为 CIS_RESPONSE_WRITE 、 CIS_RESPONSE_EXECUTE 、CIS_RESPONSE_OBSERVE、 CIS_RESPONSE_OBSERVE_PARAMS，uri 和 value 为 null。如果请求的操作失败，包括读、写、执行、观测、设置参数，则将 uri 和 value 置为空，result 设置为对应的错误结果。函数原型如下：

cis_ret_t cis_response (void             *context,
                        const cis_uri_t  *uri, 
                        const cis_data_t *value,
                        cis_mid_t         mid, 
                        cis_coapret_t     result);

cis_notify

应用程序根据网络侧所设置的数据上报策略调用cis_notify接口进行数据上报，一组上报操作最多可以上报一个instance 的数据，如果需要上报多个 instance 的数据，需要将数据分为多组进行上报。另外，每一次调用上报一个 resource 的数据，用户需要提供对应observe消息的msgid和该resouce 对应的uri，对于一组上报，如果不是最后一条消息，则 result 字 段 应 为CIS_NOTIFY_CONTINUE，如果是最后一条消息，result 应该为CIS_NOTIFY_CONTENT。requestACK为保留参数，表示该组上报消息是否需要以 CON 形式上报。函数原型如下：

cis_ret_t cis_notify(void              *context, 
                     const cis_uri_t   *uri, 
                     const cis_data_t  *value,
                     cis_mid_t          mid, 
                     cis_coapret_t      result, 
                     bool               needAck);

cis_uri_make

使用该接口生成标准uri结构体，函数原型如下：

cis_ret_t cis_uri_make(cis_oid_t  oid, 
                       cis_iid_t  iid, 
                       cis_rid_t  rid, 
                       cis_uri_t *uri);

cis_read_callback_t

读操作回调函数，函数原型如下：

typedef cis_coapret_t(*cis_read_callback_t) (void        *context,
                                             cis_uri_t   *uri,
                                             cis_mid_t    mid);

cis_write_callback_t

写操作回调函数，函数原型如下：

typedef cis_coapret_t (*cis_write_callback_t)(void               *context,
                                              cis_uri_t          *uri,
                                              const cis_data_t   *value,
                                              cis_attrcount_t     attrcount,
                                              cis_mid_t           mid);

cis_exec_callback_t

执行操作回调函数，函数原型如下：

typedef cis_coapret_t (*cis_exec_callback_t)(void           *context,
                                             cis_uri_t      *uri,
                                             const uint8_t  *buffer,
                                             uint32_t        length,
                                             cis_mid_t       mid);

cis_observe_callback_t

对象订阅操作回调函数，函数原型如下：

typedef cis_coapret_t (*cis_observe_callback_t)(void           *context,
                                                cis_uri_t      *uri,
                                                bool            flag,
                                                cis_mid_t       mid);

cis_discover_callback_t

资源发现操作回调函数，函数原型如下：

typedef cis_coapret_t (*cis_discover_callback_t)(void       *context,
                                                 cis_uri_t  *uri,
                                                 cis_mid_t   mid);

cis_set_params_callback_t

设置参数操作回调函数，函数原型如下：

typedef cis_coapret_t (*cis_set_params_callback_t)(void                 *context,
                                                   cis_uri_t            *uri,
                                                   cis_observe_attr_t    parameters,
                                                   cis_mid_t             mid);

cis_event_callback_t

事件回调函数，函数原型如下：

typedef void (*cis_event_callback_t)(void *context, cis_evt_t id, void *param);

使用示例

完整示例较大，可参考components\cloud\onenet\nb-iot\sample\cis_sample_main.c的实现。