OneNET-MQTT-Kit API

简介

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

重要定义及数据结构

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;

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

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;

mq_msg

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

typedef struct mq_msg_t
{   
    int    topic_type; 
    char   data_buf[128]; 
    int    data_len; 
}mq_msg;

API列表

onenet_event_callback

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

void onenet_event_callback(onenet_event_t onenet_event);

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);

onenet_get_device_info

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

int onenet_get_device_info(void);

onenet_mqtts_init

Onenet-mqtts初始化，包括网络、客户端结构、消息订阅主题（topic）的初始化。函数原型如下：

void onenet_mqtts_init(void);

onenet_mqtts_device_is_connected

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

int onenet_mqtts_device_is_connected(void);

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);

onenet_mqtts_device_link

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

int onenet_mqtts_device_link(void);

onenet_mqtts_device_disconnect

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

void onenet_mqtts_device_disconnect(void);

onenet_mqtts_device_subscribe

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

int onenet_mqtts_device_subscribe(void);

onenet_mqtts_client_unsubscribe

设备mqtt消息退订，退订topicFilter指定主题（Topic）的消息。其函数原型如下：

int onenet_mqtts_client_unsubscribe(const char *topicFilter);

onenet_mqtts_device_publish_cycle

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

int onenet_mqtts_device_publish_cycle(os_tick_t *last_publish_tick)

onenet_mqtts_device_publish

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

int onenet_mqtts_device_publish(void);

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[]);

onenet_mqtts_device_start

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

void onenet_mqtts_device_start(void);

onenet_mqtts_device_end

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

void onenet_mqtts_device_end(void);