全部文档
概述 硬件支持 快速开发指南 内核 驱动 通用组件 专业组件 常见问题

OneNET Kit


目录

MQTT(S)接入协议

MQTT-简介

OneNET-MQTT组件是基于Paho mqtt Embedded C v1.1.0源码包上做的开发,提供自动注册设备、平台接入、主题订阅、消息发布、命令下发、心跳保持、离线重连,并支持TLS加密传输。

MQTT-源码目录结构

OneNET-MQTT 源代码目录结构如下表所示:

目录 说明
mqtts_device mqtt设备相关接口实现及主业务实现
authorization 鉴权相关接口实现
cert 存放平台根证书

MQTT-架构设计

为了保证设备在异常状态下实现快速重连,设计框架如下:

onenet_mqtts

  • 获取设备信息。包含OneNET平台MQTTS物联网套件上注册的产品ID,产品access_key,设备名称,非自动化注册设备还需要获取设备ID和设备key。
  • 初始化。包含MQTT网络相关接口的初始化、MQTT客户端初始化、订阅相关接口初始化(主题和相应的消息回调初始化)、发布消息队列初始化。
  • 设备注册。设备向注册服务器注册一个设备,用户只提供产品ID,产品accesskey,设备名, 其中设备名需要保证唯一,可以采用SN、IMEI等,支持数字、字母、字符''和'-',长度不超过64。设备支持反复注册。注册前会计算API访问的Token。
  • 网络和设备连接。开启TLS加密传输时,需要用到平台CA证书,网络连接成功后进行设备连接。设备连接前会计算设备连接的Token(默认过期时间是2032/1/1,可根据用户需求更改),作为MQTT接入平台时的客户端密码。
  • 订阅。根据初始化的订阅主题(目前5个主题)进行订阅,每个主题最多尝试3次,每个主题订阅成功后,注册该主题的回调函数。若此5个主题中有任何一个订阅不成功,会关闭客户端,关闭网络,重新进行网络和设备连接。
  • 发布。会查询发布消息队列中是否有消息(消息队列中的消息结构体包含主题类型、数据和数据长度),有消息就会将要发布的消息发布到对应的主题。消息的服务质量默认为Qos1(用户可修改),因此发布后会同步等待ACK,若超时则判断为失败,会关闭客户端和网络,重新进行网络和设备连接。
  • 消息接收及心跳处理。订阅的5个主题,若平台有发布此5个主题的消息,则会接收到并执行主题消息回调函数。心跳包会在用户配置的心跳间隔时间发送,以保持设备的长连接。若消息接收失败,会关闭客户端和网络,重新进行网络和设备连接。

MQTT-平台相关

OneNET支持的订阅Topic :

系统topic 用途 QoS 可订阅
1 $sys/{pid}/{device-name}/dp/post/json/accepted 系统通知"设备上传数据点成功" 0
2 $sys/{pid}/{device-name}/dp/post/json/rejected 系统通知"设备上传数据点失败" 0
3 $sys/{pid}/{device-name}/cmd/request/+ 系统向设备下发命令 0
4 $sys/{pid}/{device-name}/cmd/response/+/+ 系统回复"设备命令应答成功或失败" 0
5 $sys/{pid}/{device-name}/image/# 设备镜像相关所有主题 0

OneNET支持的发布Topic :

系统topic 用途 QoS 可发布
1 $sys/{pid}/{device-name}/dp/post/json 设备上传数据点 0/1
2 $sys/{pid}/{device-name}/cmd/response/{cmdid} 设备回复命令应答 0/1
3 $sys/{pid}/{device-name}/image/update 设备更新镜像中属性 0/1
4 $sys/{pid}/{device-name}/image/get 设备镜像信息查询 0/1

加密与非加密

连接协议 地址 端口 说明
MQTT 183.230.40.16 8883 加密接口
MQTT 183.230.40.96 1883 非加密接口

MQTT-使用说明

图形化配置

使用OneNET MQTT套件需要通过Menuconfig的图形化工具进行配置选择,配置的路径如下所示:

(Top) → Components → Cloud → OneNET → MQTT Kit
[*] Enable onenet mqtt-kit
[ ]     Enable onenet device auto register
[ ]     Enable mqtt-kit TLS encrypt

进行OneNET MQTT Kit 选项配置需要先在Menuconfig中选中Enable onenet mqtt-kit,然后再进行其他的配置选择。

  • Enable onenet device auto register:使能自动完成OneNET平台的设备注册。
  • Enable mqtt-kit TLS encrypt:使能OneNET MQTT的加密传输。

MQTT-注意事项

1. 关闭OneNET MQTT组件

开启OneNET MQTT组件后会自动勾选Paho MQTT组件,当用户反向取消该组件时记得手动关闭Paho MQTT组件。

2. 关闭OneNET MQTT的加密传输

开启OneNET MQTT的加密传输功能后会自动勾选Paho MQTT组件和mbedtls加密组件,当用户反向取消OneNET MQTT的加密传输功能时记得手动关闭Paho MQTT的加密配置项,并同时关闭mbedtls组件。

LwM2M/CoAP接入协议


LwM2M-简介

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

终端侧通过移植SDK可以实现基于轻量化的CoAP+LwM2M协议进行传输,降低物联网终端功耗。

主要面向基于蜂窝的窄带物联网(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客户端。

LwM2M-代码目录结构

OneNET-NBIoT-Kit源代码目录结构如下表所示:

目录 说明
ciscore CoAP实现、LwM2M实现、主业务逻辑实现
porting 系统适配相关
sample 示例

LwM2M-架构设计

架构

OneNET NB-IOT组件负责UE和平台间的交互。

协议栈结构如图1所示,包括了三部分的内容,最下层是基于UDP协议的CoAP实现,中间是基于CoAP的LwM2M协议实现,最上层是在LwM2M协议里面使用的IPSO定义的资源模型,用于对传感器以及传感器属性进行标识,该部分内容遵循IPSO组织制定的Profile规范。

protocols

​ 图1:协议栈结构

​ LwM2M协议架构如图2所示。

relationship

​ 图2:LwM2M协议架构

流程

cis_pump函数是整个组件的核心,负责几乎全部的逻辑处理。为保证对各平台的适应性,采用单一的状态机循环机制,UE从bootstrap、register、update以及各指令(read、write、exec、observe、notify、discover)均是通过不断的状态和数据链表轮询进行。

cis_pump逻辑主要分为①和②两部分,①主要为数据的主动上报逻辑,②为平台指令的被动接收执行,与外部的数据传递主要是通过几个链表和缓冲区进行。

逻辑①: 负责UE向平台的注册,且lifetime到期前进行update。

逻辑②: 负责执行平台下发的指令。Recv缓冲区负责缓存平台发送的数据,pump会不停的轮询 缓冲区数据进行协议解析,然后交由用户线程进行指令的最终执行。并通过requestlist 和notifylist/observelist的查找比对,上报response或者数据。

LwM2M-功能

设备接入

设备可以通过连接BootStrap或者直连NBIoT接入机接入。

connect

  1. Bootstrap接入:设备连接OneNET NBIoT套件的BootStrap地址,BootStrap服务器会根据设 备注册区域及负载将接入机地址分配给终端,终端根据该地址连接NBIoT接入机。
  2. 接入机直连:设备选择一个平台提供的接入机直连地址进行连接。

订阅

可以在平台设置自动订阅(设备注册成功后,平台主动发起),也可以在平台手动订阅(通过页面订阅按钮,或者调用订阅API)。设备成功订阅后,设备可以主动上报数据。

subscribe

  1. IoT平台侧主动向终端设备发送订阅消息(Observe)来订阅设备资源列表中所有可观测的资源。
  2. 终端设备接收到订阅消息后,检查需要订阅的资源是否可以被订阅且状态正常,如果是则返回订阅结果Success。
  3. 订阅成功后,终端可以上报数据。

即时命令

在平台通过页面或者API对设备下发即时命令,若设备在线且核心网未老化,可成功下发。

immediate_command

  1. 业务平台下发即时命令。
  2. OneNET平台收到命令后立即下发命令到终端设备。
  3. 终端设备发送命令响应消息。
  4. OneNET平台将对应的响应命令转发到业务平台。

缓存命令

若设备离线,可通过调用API对设备下发缓存命令。缓存命令生效后,若设备有上行消息,则OneNET缓存命令服务会立即下发缓存命令。

cache_command

  1. 业务平台下发缓存命令。
  2. OneNET收到命令后先将命令缓存到本地。
  3. 待设备上线后,OneNET将缓存的命令下发到设备。
  4. 设备发送命令响应消息。
  5. OneNET将对应的响应命令转发到业务平台。

数据上报

平台支持NON类型和CON类型的数据上报方式。

upload

  1. 设备按照数据上报规则,上传携带订阅资源具体数值的Notify消息(即相应观测的传感器数据值),直到OneNET取消资源订阅。
  2. OneNET接收到数据后根据配置的存储策略保存数据或者上报数据到业务平台。
  3. OneNET将数据上报到业务平台。
  4. OneNET发送确认消息给终端设备。

安全性

authcode鉴权码

​ 用户可以在平台配置设备的authcode,设备注册时携带该authcode,可用于设备鉴权,防止设备被其他用户盗用,增加了设备的安全性。

DTLS安全连接

​ 平台支持基于PSK(pri-sharedkey, 预置共享秘钥)的DTLS协议,在用户设备和OneNET之间建立安全通道,用于认证和数据安全传输。

security

  1. 设备在OneNET注册时,平台随机生成一个PSK码作为预置共享密钥key
  2. 设备与平台利用握手协议,通过发送带有Cookie值、密钥K等参数的消息相互认证
  3. 建立安全通道,进行数据传输

LwM2M-使用说明

图形化配置

使用OneNET-NBIoT-Kit需要通过Menuconfig的图形化工具进行配置选择,配置的路径如下所示:

(Top) → Components → Cloud → OneNET → NB-IoT Kit
[*] Enable onenet nbiot-kit
[*]     Using nbiot-kit device auth code
(abcdefg)   Input device auth code
[*]     Enable onenet nbiot-kit log (NEW)
(3)         Log output level (NEW)
(200)       Log buffer size (NEW)
[*]     Enable onenet nbiot-kit memtrace
[*]     Enable onenet nbiot-kit sample (NEW)

进行OneNET-NBIoT-Kit选项配置需要先在Menuconfig中选中Enable onenet nbiot-kit,然后再进行其他的配置选择。

  • Using nbiot-kit device auth code:是否打开auth code功能,对应OneNET平台的鉴权码。
  • Input device auth code:用于输入设备鉴权码,对应OneNET平台的Auth_Code配置。
  • Enable onenet nbiot-kit log:是否打开nbiot-kit日志。
  • Log output level:日志输出级别。
  • Log buffer size:日志buffer大小。
  • Enable onenet nbiot-kit memtrace:是否打开动态内存跟踪功能。
  • Enable onenet nbiot-kit sample:是否打开示例。

LwM2M-注意事项

1. OneNET NBIoT Kit 组件未开源,如有需要请联系我们

EDP接入协议


EDP-简介

EDP (Enhanced Device Protocol增强设备协议)是OneNET平台根据物联网特点专门定制的完全公开的基于TCP的协议,可以广泛应用到家居、交通、物流、能源以及其他行业应用中。

具有以下功能特点:

  1. 长连接协议;
  2. 数据加密传输;
  3. 终端数据点上报,支持的数据点类型为:浮点数(float)、整型(int)、字符串、JSON对象/二进制数据;
  4. 平台消息下发(支持离线消息);
  5. 端到端数据转发。

EDP-代码目录结构

OneNET-EDP源代码目录结构如下表所示:

目录 说明
edp_kit 协议层实现
edp_enc 数据包加密实现
edp_sample 示例

EDP-使用说明

图形化配置

使用OneNET-EDP需要通过Menuconfig的图形化工具进行配置选择,配置的路径如下所示:

(Top) → Components → Cloud → OneNET → EDP
[*] Enable OneNET EDP protocal
[ ]     Enable EDP crypt
[ ]     Enable EDP sample

进行OneNET-EDP选项配置需要先在Menuconfig中选中Enable OneNET EDP protocal,然后再进行其他的配置选择。

  • Enable EDP crypt:使能EDP协议加密传输。
  • Enable EDP sample:使能EDP示例。doc/onenet_edp_api.md)

EDP-注意事项

1.加密选项

开启EDP的加密功能后,会自动勾选mbedtls加密组件,当反向取消EDP的加密功能时,需要手动关闭mbedtls加密组件。

MQTT接入协议-API


MQTT-数据结构

g_onenet_info

通过MQTT协议与OneNET平台进行连接的时候,设备端相关的基本信息保存在g_onenet_info结构体中,其定义如下:

typedef struct
{   
    char                           ip[16];
    int                            port;
    char                           pro_id[10];
    char                           access_key[48];
    char                           dev_name[64+1];
    char                           dev_id[16];
    char                           key[48];
    unsigned int                   keepheart_interval;
    unsigned short                 device_register; 
    subscribe_message_handlers_t   subscribe_message_handlers[USER_MESSAGE_HANDLERS_NUM];
} onenet_info_t;
onenet_info_t g_onenet_info;
重要成员 说明
ip OneNET平台MQTT连接地址,分为TLS加密连接和TCP非加密连接而不同,本组件已定义
port 与连接IP对应的端口,本组件已定义
pro_id 产品ID,OneNET平台注册MQTT套件后会得到该产品ID
access_key 平台连接key,OneNET平台注册MQTT套件后会得到该access_key
dev_name 设备名称,由用户定义,平台有相关定义规则要求
dev_id 设备ID,如果配置开启自动注册,则客户端注册时自动获取,否则在Onenet平台上得到
key 设备key,如果配置开启自动注册,则客户端注册时自动获取,否则在Onenet平台上得到
keepheart_interval 心跳间隔时间,由用户定义
device_register 设备端连接注册状态,1:已注册;0:未注册
subscribe_message_handlers 消息订阅处理函数数组,用以指向不同主题(Topic)的消息处理函数,本组件数组长度为5

g_onenet_mqtts

OneNET-MQTT组件相关的定义实现在g_onenet_mqtts结构体中,包括MQTT网络层相关定义和MQTT客户端相关定义,如下:

typedef struct
{   
    Network      network;
    MQTTClient   client;
} onenet_mqtts_t;
onenet_mqtts_t  g_onenet_mqtts
重要成员 说明
network 网络层相关定义结构体,详见Paho-MQTT部分介绍
client 客户端相关定义结构体,详见Paho-MQTT部分介绍

onenet_event_t

OneNet-MQTTS所有可能事件由如下枚举体定义:

typedef enum
{   
    ONENET_EVENT_START = 0,
    ONENET_EVENT_DEVICE_REGISTER_OK,
    ONENET_EVENT_DEVICE_REGISTER_FAIL,
    ONENET_EVENT_MQTTS_DEVICE_CONNECTTING,
    ONENET_EVENT_MQTTS_DEVICE_CONNECT_SUCCESS,
    ONENET_EVENT_MQTTS_DEVICE_CONNECT_FAIL,
    ONENET_EVENT_MQTTS_DEVICE_DISCONNECT,
    ONENET_EVENT_KEEP_HEARTBEAT_SUCCESS,
    ONENET_EVENT_SEND_DATA,
    ONENET_EVENT_SUBSCRIBE_SUCCESS,
    ONENET_EVENT_SEND_UNSSUBSCRIBE,
    ONENET_EVENT_PUBLISH_SUCCESS,
    ONENET_EVENT_RECV_CMD,
    ONENET_EVENT_CHECK_MQTTS_DEVICE_STATUS,
    ONENET_EVENT_CHECK_NETWORK,
    ONENET_EVENT_FAULT_PROCESS,

} onenet_event_t;
重要成员 说明
ONENET_EVENT_START OneNet-MQTTS流程开始事件
ONENET_EVENT_DEVICE_REGISTER_OK 设备注册成功事件
ONENET_EVENT_DEVICE_REGISTER_FAIL 设备注册失败事件
ONENET_EVENT_MQTTS_DEVICE_CONNECTTING MQTT设备连接事件
ONENET_EVENT_MQTTS_DEVICE_CONNECT_SUCCESS MQTT设备连接成功事件
ONENET_EVENT_MQTTS_DEVICE_CONNECT_FAIL MQTT设备连接失败事件
ONENET_EVENT_MQTTS_DEVICE_DISCONNECT MQTT设备连接断开事件
ONENET_EVENT_KEEP_HEARTBEAT_SUCCESS 心跳保持成功事件
ONENET_EVENT_SEND_DATA 数据发送事件
ONENET_EVENT_SUBSCRIBE_SUCCESS 主题订阅成功事件
ONENET_EVENT_SEND_UNSSUBSCRIBE 发送主题退订事件
ONENET_EVENT_PUBLISH_SUCCESS 主题发布成功事件
ONENET_EVENT_RECV_CMD 设备收到下发命令事件
ONENET_EVENT_CHECK_MQTTS_DEVICE_STATUS 检查设备状态事件
ONENET_EVENT_CHECK_NETWORK 检查网络层事件
ONENET_EVENT_FAULT_PROCESS OneNet-MQTTS流程失败事件

mq_msg

设备通过消息队列发布主题时,主题包含的数据由结构体mq_msg定义,如下:

typedef struct mq_msg_t
{   
    int    topic_type; 
    char   data_buf[128]; 
    int    data_len; 
}mq_msg;
重要成员 说明
topic_type 主题类型,包括:
0:DATA_POINT_TOPIC
1:DEVICE_IMAGE_GET_TOPIC
2:DEVICE_IMAGE_UPDATE_TOPIC
3:CHILD_DEVICE_TOPIC
data_buf 消息内容数组
data_len 消息长度

MQTT-API列表

接口 说明
onenet_event_callback Onenet发生事件回调函数总接口
onenet_authorization Onenet连接Token计算
onenet_get_device_info 设备信息获取
onenet_mqtts_init Onenet-mqtts初始化
onenet_mqtts_device_is_connected 设备mqtt连接状态查询
onenet_mqtts_device_register 设备mqtt自动注册
onenet_mqtts_device_link 设备与Onenet建立连接
onenet_mqtts_device_disconnect 设备断开与Onenet连接
onenet_mqtts_device_subscribe 设备mqtt消息订阅
onenet_mqtts_client_unsubscribe 设备mqtt消息退订
onenet_mqtts_device_publish_cycle 设备mqtt消息循环发布
onenet_mqtts_device_publish 设备mqtt消息发布
onenet_mqtts_publish 发布数据发送到mqtt消息队列
onenet_mqtts_device_start 设备mqtt流程开始
onenet_mqtts_device_end 设备mqtt流程结束

onenet_event_callback

Onenet接入时发生事件的回调函数总接口,对于不同的事件,用户可以在该函数内注册自己所需的回调处理函数。其函数原型如下:

void onenet_event_callback(onenet_event_t onenet_event);
参数 说明
onenet_event 发生事件的名称,由以上onenet_event_t中定义
返回 说明
void

onenet_authorization

计算设备注册或连接时需要用到的Token令牌,当参数et设置时间小于当前时间时,onenet平台会认为Token令牌过期从而拒绝该访问。其函数原型如下:

int onenet_authorization(char             *ver,
                         char             *res,
                         unsigned int     et,
                         char             *access_key,
                         char             *dev_name,
                         char             *authorization_buf,
                         unsigned short   authorization_buf_len,
                         _Bool            flag);
参数 说明
ver 参数组版本号,日期格式,目前仅支持"2018-10-31"
res 产品ID,OneNET平台注册MQTT套件后会得到该产品ID
et Token过期时间expirationTime,unix时间
access_key API访问时是产品access_key;设备连接时是设备key
dev_name API访问时传NULL;设备连接时是本设备的设备名称
authorization_buf 计算所得Token字符串的缓存区
authorization_buf_len Token字符串的缓存区长度
flag 1:用于计算API访问的Token(注册时用)
0:用于计算设备连接的Token
返回 说明
0 计算成功
1 计算失败

onenet_get_device_info

设备信息获取,获得连接所需的PRODUCT_ID、ACCESS_KEY、DEVICE_NAME、DEVICE_ID、USER_KEY、心跳间隔等信息,这些信息由用户事先在"onenet_device_sample.h"头文件中填写。函数原型如下:

int onenet_get_device_info(void);
参数 说明
void
返回 说明
OS_TRUE 获取成功
OS_FALSE 获取失败

onenet_mqtts_init

Onenet-mqtts初始化,包括网络、客户端结构、消息订阅主题(topic)的初始化。函数原型如下:

void onenet_mqtts_init(void);
参数 说明
void
返回 说明
void

onenet_mqtts_device_is_connected

设备mqtt连接状态查询,指的mqtt协议层连接状态。其函数原型如下:

int onenet_mqtts_device_is_connected(void);
参数 说明
void
返回 说明
0 已断开
1 已连接

onenet_mqtts_device_register

用于onenet-mqtt自动注册功能,设备连接注册服务器,发送注册信息,接收注册回复信息,最后断开注册服务器网络。设备名需要保证唯一,建议采用SN、IMEI等,支持数字、字母、字符'_'和'-',长度不超过64。其函数原型如下:

int onenet_mqtts_device_register(const char   *access_key,
                                 const char   *pro_id,
                                 const char   *serial,
                                 char         *dev_id,
                                 char         *key);
参数 说明
access_key OneNET平台注册MQTT套件后得到该access_key,可由onenet_get_device_info获得
pro_id OneNET平台注册MQTT套件后得到该ID,可由onenet_get_device_info获得
serial 本设备的设备名称,可由onenet_get_device_info获得
dev_id 存储平台返回的设备ID字符串的缓存区
key 存储平台返回的设备key字符串的缓存区
返回 说明
OS_FALSE 注册成功
OS_TRUE 注册失败

设备与OneNET平台建立MQTT连接,包括网络层和协议层连接。网络连接失败会直接返回,设备接入OneNET失败会先断开网络再返回。其函数原型如下:

int onenet_mqtts_device_link(void);
参数 说明
void
返回 说明
OS_FALSE 接入失败
OS_TRUE 接入成功

onenet_mqtts_device_disconnect

设备断开与OneNET的MQTT连接,该函数只断开协议层连接。其函数原型如下:

void onenet_mqtts_device_disconnect(void);
参数 说明
void
返回 说明
void

onenet_mqtts_device_subscribe

设备mqtt消息订阅,订阅在onenet_mqtts_init()中已初始化的主题(Topic),目前最大值设置为5个,注册Topic对应的消息回调函数。每个主题订阅最多尝试3次,非法订阅平台会断开连接。该函数原型如下:

int onenet_mqtts_device_subscribe(void);
参数 说明
void
返回 说明
OS_FALSE 订阅失败
OS_TRUE 订阅成功

onenet_mqtts_client_unsubscribe

设备mqtt消息退订,退订topicFilter指定主题(Topic)的消息。其函数原型如下:

int onenet_mqtts_client_unsubscribe(const char *topicFilter);
参数 说明
topicFilter 需要退订的主题名称
返回 说明
OS_FALSE 退订失败
OS_TRUE 退订成功

onenet_mqtts_device_publish_cycle

设备mqtt消息循环发布,在每次发布间隔时间超过预置定时时间(可在"onenet_device_sample.h"头文件中设置,预置为10s)后,从本函数中构建的示例缓存区中获取消息数据并进行发布。其函数原型如下:

int onenet_mqtts_device_publish_cycle(os_tick_t *last_publish_tick)
参数 说明
last_publish_tick 上次发布时的时间,以cycle为单位
返回 说明
OS_FALSE 发布失败
OS_TRUE 发布成功

onenet_mqtts_device_publish

设备mqtt消息发布,从预置的MQTT消息队列获取消息数据并发布,预置队列消息需要包含发布的主题,数据,数据长度。消息的服务质量默认为QOS1,平台支持QOS0、QOS1、不支持QOS2。其函数原型如下:

int onenet_mqtts_device_publish(void);
参数 说明
void
返回 说明
OS_FALSE 发布失败
OS_TRUE 发布成功

onenet_mqtts_publish

MSH接口输入命令,将想要发布的固定格式的mqtt消息数据发送到预置的mqtt消息队列,以进行发布。 MSH命令的输入参数只能是3个: 第一个参数:onenet_mqtts_publish; 第二个参数:0-数据点或 1-获取镜像或 2-更新镜像; 第三个参数:要发布的数据。 例如:onenet_mqtts_publish 0 {"id":101,"dp":{"humi":[{"v":32,}],"temp":[{"v":25,}]}} 其函数原型如下:

void onenet_mqtts_publish(int argc,  char *argv[]);
参数 说明
argc 传参个数
argv[] 参数值数据
返回 说明
void

onenet_mqtts_device_start

MSH接口输入命令,该函数预置一个完整的Onenet-MQTT接入并保持范例的框架,包括mqtt独立线程初始化,网络、客户端和消息队列初始化,客户端注册,网络连接,客户端连接,预置主题消息订阅、发布及心跳保持等功能,详见使用示例介绍。 MSH命令为:onenet_mqtts_device_start 其函数原型如下:

void onenet_mqtts_device_start(void);
参数 说明
void
返回 说明
void

onenet_mqtts_device_end

MSH接口输入命令,对onenet_mqtts_device_start函数启动的mqtt流程的结束退出。 MSH命令为:onenet_mqtts_device_end 其函数原型如下:

void onenet_mqtts_device_end(void);
参数 说明
void
返回 说明
void

LwM2M接入协议-API

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;
重要成员 说明
bs_enabled BS流程开关
dtls_enabled DTLS功能开关
ip 服务器ip地址
port 服务器端口号
auth_code 校验码
psk 共享密钥

挂接回调函数结构体

在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;
重要成员 说明
onRead 读操作回调函数
onWrite 写操作回调函数
onExec 执行操作回调函数
onObserve 对象订阅操作回调函数
onDiscover 资源发现操作回调函数
onSetParams 参数设置操作回调函数
onEvent 事件回调函数

回调函数的定义常见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;
重要成员 说明
instanceCount 对象实例数量
instanceBytes instanceBitmap字节长度
instanceBitmap 实例位图,1表示有效,0表示无效。实例位图可视为一个数组,数组第0个字节的最高位对应于第0个实例,以此类推

资源数量结构体

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

struct st_cis_res_count
{
    cis_attrcount_t attrCount;
    cis_actcount_t  actCount;
};
typedef struct st_cis_res_count        cis_res_count_t;
重要成员 说明
attrCount 可读写操作资源数量
actCount 可执行操作资源数量

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;
重要成员 说明
flag 有效标识,常见URI_FLAG_XXX定义
objectId 对象ID
instanceId 实例ID
resourceId 资源ID

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;
重要成员 说明
id 资源ID
type 资源类型,常见cis_datatype_t定义
asBuffer 字符串数据
value bool、int、float数据

参数设置结构体

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

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;
重要成员 说明
toSet 设置标志位,参见ATTR_FLAG_XXX定义
toClear 清除标志位
minPeriod 最小时间间隔,单位为秒
maxPeriod 最大时间间隔
greaterThan 观测数据大于该值时立即上报
lessThan 观测数据小于该值时立即上报
step 观测数据变化的最小区间

LwM2M-API列表

接口 说明
cis_init cis连接实例初始化
cis_deinit cis连接实例去初始化
cis_register 向OneNET平台注册cis连接实例
cis_unregister 向OneNET平台注销连接
cis_addobject 添加object
cis_delobject 删除object
cis_pump cis模块主调度接口
cis_update_reg 更新注册信息,包含心跳或者object信息
cis_response 向平台回复操作结果
cis_notify 向平台上报数据
cis_uri_make 创建URI结构体
cis_read_callback_t 请求读数据操作回调函数
cis_write_callback_t 请求写数据操作回调函数
cis_exec_callback_t 请求执行操作回调函数
cis_observe_callback_t 请求观测操作回调函数
cis_discover_callback_t 请求发现操作回调函数
cis_set_params_callback_t 请求参数设置操作回调函数
cis_event_callback_t 事件回调函数

cis_init

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

cis_ret_t cis_init(void **context, cis_user_cfg_t *cis_user_cfg, void *DMconf);
参数 说明
context cis上下文
cis_user_cfg 用户初始化配置项
DMconf 设备管理配置,非DM时传NULL,当前不支持DM功能
返回 说明
非0 操作失败
0 操作成功

cis_deinit

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

cis_ret_t cis_deinit(void **context);
参数 说明
context cis上下文
返回 说明
非0 操作失败
0 操作成功

cis_register

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

cis_ret_t cis_register(void *context, cis_time_t lifetime, const cis_callback_t *cb);
参数 说明
context cis上下文
lifetime 保活周期
cb 回调接口的结构体
返回 说明
非0 操作失败
0 操作成功

cis_unregister

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

cis_ret_t cis_unregister(void *context);
参数 说明
context cis上下文
返回 说明
非0 操作失败
0 操作成功

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);
参数 说明
context cis上下文
objectid object 编号
bitmap 每一位表示一个实例,有效地实例为 1,无效的为 0
rescount 资源的可读写,可执行数量
返回 说明
非0 操作失败
0 操作成功

cis_delobject

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

cis_ret_t cis_delobject(void * context, cis_oid_t objectid);
参数 说明
context cis上下文
objectid object 编号
返回 说明
非0 操作失败
0 操作成功

cis_pump

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

uint32_t cis_pump(void *context);
参数 说明
context cis上下文
返回 说明
-1 无待处理任务
0 有待处理任务

cis_update_reg

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

uint32_t cis_update_reg(void *context, uint32_t lifetime, bool withObjects);
参数 说明
context cis上下文
lifetime 保活周期
withObjects 是否更新object信息
返回 说明
-1 操作失败
0 操作成功

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);
参数 说明
context cis上下文
uri 该条操作的值对应的uri
value 上报的数据
mid 需要回复的消息ID
result 操作结果
返回 说明
非0 操作失败
0 操作成功

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);
参数 说明
context cis上下文
uri 该条操作的值对应的uri
value 上报的数据
mid 需要回复的消息ID
result 操作结果
needAck 是否要求ack
返回 说明
非0 操作失败
0 操作成功

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);
参数 说明
oid 对象id
iid 实例id
rid 资源id
uri 待生成的uri
返回 说明
-1 操作失败
0 操作成功

cis_read_callback_t

读操作回调函数,函数原型如下:

typedef cis_coapret_t(*cis_read_callback_t) (void        *context,
                                             cis_uri_t   *uri,
                                             cis_mid_t    mid);
参数 说明
context cis上下文
uri 实例id
mid 消息id
返回 说明
非0 操作失败
0 操作成功

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);
参数 说明
context cis上下文
uri 实例id
value 平台下发的写入数据数组
attrcount 资源数量,即是value数组元素数量
mid 消息id
返回 说明
非0 操作失败
0 操作成功

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);
参数 说明
context cis上下文
uri 实例id
buffer 平台下发的执行操作命令
length buffer长度
mid 消息id
返回 说明
非0 操作失败
0 操作成功

cis_observe_callback_t

对象订阅操作回调函数,函数原型如下:

typedef cis_coapret_t (*cis_observe_callback_t)(void           *context,
                                                cis_uri_t      *uri,
                                                bool            flag,
                                                cis_mid_t       mid);
参数 说明
context cis上下文
uri 实例id
flag 订阅或者取消订阅标识
mid 消息id
返回 说明
非0 操作失败
0 操作成功

cis_discover_callback_t

资源发现操作回调函数,函数原型如下:

typedef cis_coapret_t (*cis_discover_callback_t)(void       *context,
                                                 cis_uri_t  *uri,
                                                 cis_mid_t   mid);
参数 说明
context cis上下文
uri 实例id
mid 消息id
返回 说明
非0 操作失败
0 操作成功

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);
参数 说明
context cis上下文
uri 实例id
parameters 平台下发的参数结构体
mid 消息id
返回 说明
非0 操作失败
0 操作成功

cis_event_callback_t

事件回调函数,函数原型如下:

typedef void (*cis_event_callback_t)(void *context, cis_evt_t id, void *param);
参数 说明
context cis上下文
id 事件id
param 事件参数
返回 说明

EDP接入协议-API


EDP-数据结构

消息类型

平台与设备之间的交互消息类型定义如下:

消息类型 流向 描述
CONN_REQ 1 C->S 客户端请求与服务端建立连接
CONN_RESP 2 S->C 服务端确认连接建立
PUSH_DATA 3 C<->S 转发(透传)数据
CONN_CLOSE 4 S->C 连接关闭
UPDATE_REQ 5 C->S 上报当前使用的软件信息
UPDATE_RESP 6 S->C 平台下发当前最新的软件信息
SAVE_DATA 8 C<->S 存储(&转发)数据
SAVE_ACK 9 S->C 存储确认
CMD_REQ 10 S->C 命令请求
CMD_RESP 11 C->S 命令回复
PING_REQ 12 C->S 心跳请求
PING_RESP 13 S->C 心跳响应
ENCRYPT_REQ 14 C->S 加密请求
ENCRYPT_RESP 15 S->C 加密回复

EDP-API列表

接口 说明
PacketConnect1 连接OneNET平台
PacketConnect2 连接OneNET平台
GetEdpPacket 接收EDP数据包
EdpPacketType 获取EDP包类型
PacketPushdata 转发数据
UnpackPushdata 解析转发数据
PacketSavedataJson 打包存储数据
UnpackSavedataJson 解析存储数据
PacketPing 打包心跳包

PacketConnect1

该函数用于打包由设备到设备云的EDP协议包,连接设备云的请求(登录认证方式1),其函数原型如下:

EdpPacket *PacketConnect1(const char *devid, const char *auth_key);
参数 说明
devid 设备ID,申请设备时平台返回的ID
auth_key 鉴权信息(api-key),从平台申请
返回 说明
EdpPacket* EDP协议包

说明:返回的EDP包发送给设备云后,需要客户程序删除该包。

PacketConnect2

该函数用于打包由设备到设备云的EDP协议包,连接设备云的请求(登录认证方式2),其函数原型如下:

EdpPacket *PacketConnect2(const char *userid, const char *auth_info);
参数 说明
userid 用户ID,在平台注册账号时平台返回的用户ID
auth_info 鉴权信息(api-key),从平台申请,具备唯一性
返回 说明
EdpPacket* EDP协议包

说明:返回的EDP包发送给设备云后,需要客户程序删除该包。

GetEdpPacket

该函数用于将接收到的二进制流,分解成一个一个的EDP包,函数原型如下:

EdpPacket *GetEdpPacket(RecvBuffer *buf);
参数 说明
buf 接收缓存
返回 说明
EdpPacket* EDP协议包

说明:返回的EDP包使用后,需要客户程序删除该包。

EdpPacketType

该函数用于获取一个EDP包的消息类型,客户程序根据消息类型做不同的处理,函数原型如下:

uint8 EdpPacketType(EdpPacket *pkg);
参数 说明
pkg EDP协议包
返回 说明
uint8 消息类型

PacketPushdata

该函数用于打包设备到设备云的EDP协议包,设备与设备之间转发数据,其函数原型如下:

EdpPacket *PacketPushdata(const char *dst_devid, const char *data, uint32 data_len);
参数 说明
dst_devid 目的设备ID
data 数据
data_len 数据长度
返回 说明
EdpPacket* EDP协议包

说明:返回的EDP包使用后,需要客户程序删除该包。

UnpackPushdata

该函数用于解包由设备云到设备的EDP协议包,设备与设备之间转发数据,其函数原型如下:

int32 UnpackPushdata(EdpPacket *pkg, char **src_devid, char **data, uint32 *data_len);
参数 说明
pkg EDP包,必须是pushdata包
src_devid 源设备ID
data 数据
data_len 数据长度
返回 说明
int32 =0表示解析成功,<0则表示解析失败

说明:通过函数GetEdpPacket和EdpPacketType判断出是pushdata后,将整个响应EDP包作为参数,由该函数进行解析,返回的源设备ID(src_devid)和数据(data)都需要客户端释放。

PacketSavedataJson

该函数用于打包设备到设备云的EDP协议包,存储数据(json格式数据),其函数原型如下:

EdpPacket *PacketSavedataJson(const char *dst_devid, 
                              cJSON      *json_obj, 
                              int         type, 
                              uint16      msg_id);
参数 说明
dst_devid 目的设备ID
json_obj json数据
type json的类型
msg_id 消息标志
返回 说明
EdpPacket* EDP协议包

说明:返回的EDP包发送给设备云后,需要客户程序删除该包。

UnpackSavedataJson

该函数用于解包由设备云到设备的EDP协议包,存储数据(json格式数据),其函数原型如下:

int32 UnpackSavedataJson(EdpPacket *pkg, cJSON **json_obj);
参数 说明
pkg EDP包,必须是savedata包的json数据包
json_obj json数据
返回 说明
int32 =0表示解析成功,<0则表示解析失败

说明:返回的json数据(json_obj)需要客户端释放。

PacketPing

该函数用于打包由设备到设备云的EDP心跳包,该函数原型如下:

EdpPacket *PacketPing(void);
参数 说明
返回 说明
EdpPacket* EDP协议包

说明:返回的EDP包发送给设备云后,需要客户程序删除该包。

results matching ""

    No results matching ""