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

MQTT

MQTT(Message Queuing Telemetry Transport,消息队列遥测传输协议),是一种基于发布/订阅模式的“轻量级”通讯协议,该协议构建于TCP/IP协议上,由IBM在1999年发布。MQTT最大优点在于,可以以极少的代码和有限的带宽,为连接远程设备提供实时可靠的消息服务。做为一种低开销、低带宽占用的即时通讯协议,使其在物联网、小型设备、移动应用等方面有较广泛的应用。

目录



简介

OneOS MQTT组件是基于Paho mqtt Embedded C v1.1.0源码包做的设计与开发,为用户提供网络初始化、客户端初始化与反初始化、网络连接与断开、客户端连接与断开、主题订阅与退订、消息发布、消息接收及回调、心跳维护、客户端连接状态查询等功能。

在安全性方便,支持基于MbedTLS和OneTLS密码库的TLS加密传输方式,最高支持TLS v1.3。在网络接口方面采用 BSD socket,通信方式支持无线通信模组和有线网络,在选择无线通信模组时可以参看OneOS MoLink相关文档,选择已经适配的模组将大大缩短开发周期。

MQTT协议是为大量计算能力有限,且工作在低带宽、不可靠的网络的远程传感器和控制设备通讯而设计的协议,它具有以下主要的几项特性: 1、使用发布/订阅消息模式,基于消息主题,提供一对多的消息发布,解除应用程序耦合; 2、对负载内容屏蔽的消息传输; 3、使用 TCP/IP 提供网络连接; 4、有三种消息发布服务质量(至多一次、至少一次、只有一次); 5、小型传输,开销很小(固定长度的头部是 2 字节),协议交换最小化,以降低网络流量; 6、使用 Last Will 和 Testament 特性通知有关各方客户端异常中断的机制。

MQTT

​ MQTT发布订阅模型

源码目录结构

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

目录 说明
MQTTPacket/src MQTT协议报文实现
MQTTClient-OneOS/src MQTT客户端实现
MQTTClient-OneOS/samples 示例
doc 文档

使用说明

图形化配置

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

(Top) → Components→ Network→ Protocols→ MQTT→ pahomqtt-v1.1.0
[*] Enable Paho MQTT
[*]     Enable Paho MQTT Client
[*]         Enable Paho MQTT TLS encrypt
[*]         Enable Paho MQTT sample

进行MQTT选项配置需要首先在Menuconfig中选中Enable Paho MQTT,然后再进行其它的配置选择。

  • Enable Paho MQTT:使能MQTT,下面选项都不选择时,则包含了协议包的序列化与反序列化。
  • Enable Paho MQTT Client:使能MQTT客户端。
  • Enable Paho MQTT TLS Encrypt:使能MQTT的加密连接。

  • Enable Paho MQTT sample:使能MQTT示例。

注意事项

1. 反向取消加密时注意点

开启MQTT客户端,使能TLS加密连接时,会自动勾选mbedtls加密库,当用户反向取消加密配置时,需要手动取消加密库的勾选项。

MQTT API

重要定义及数据结构

客户端网络结构体

用于记录服务器地址信息、证书信息、网络操作接口函数等,其定义如下:

typedef struct Network Network;
struct Network
{   
    const char   *pHostAddress;
    uint16_t      port;
    uint16_t      ca_crt_len;
    /* NULL: TCP connection, not NULL: SSL connection */
    const char   *ca_crt;
    /* connection handle: 0 or (uintptr_t)(-1) not connection */
    uintptr_t     handle;

    /* function pointer of recv mqtt data */
    int (*mqttread)(Network*, unsigned char *, int, int);
    /* function pointer of send mqtt data */
    int (*mqttwrite)(Network*, unsigned char *, int, int);
    /* function pointer of disconnect mqtt network */
    int (*disconnect)(Network*);
    /* function pointer of establish mqtt network */
    int (*connect)(Network*);
};
重要成员 说明
pHostAddress 服务器地址
port 服务器端口号
disconnect 断开网络连接操作函数
connect 建立网络连接操作函数

连接选项结构体

用于建立客户端连接时传入相关选项,其定义如下:

typedef struct
{
    /** The eyecatcher for this structure.  must be MQTC. */
    char                   struct_id[4];
    /** The version number of this structure.  Must be 0 */
    int                    struct_version;
    /** Version of MQTT to be used.  3 = 3.1 4 = 3.1.1 */
    unsigned char          MQTTVersion;
    MQTTString             clientID;
    unsigned short         keepAliveInterval;
    unsigned char          cleansession;
    unsigned char          willFlag;
    MQTTPacket_willOptions will;
    MQTTString             username;
    MQTTString             password;
} MQTTPacket_connectData;
重要成员 说明
MQTTVersion MQTT协议版本号
clientID 用户ID
keepAliveInterval 保活周期
cleansession 是否清除session信息
willFlag 是否使用临终遗言
will 临终遗言信息
username 用户名
password 用户密钥

消息结构体

用于描述消息的具体信息,其定义如下:

typedef struct MQTTMessage
{
    enum QoS          qos;
    unsigned char     retained;
    unsigned char     dup;
    unsigned short    id;
    void             *payload;
    size_t            payloadlen;
} MQTTMessage;
重要成员 说明
qos 服务等级
retained 是否保留
dup 重发标识
id 消息id
payload 消息数据
payloadlen 消息数据长度

接收消息处理结构体

用于接收消息的回调函数入参,其定义如下:

typedef struct MessageData
{
    MQTTMessage  *message;
    MQTTString   *topicName;
} MessageData;
重要成员 说明
message 消息结构体
topicName 主题名称

API列表

接口总览:

接口 说明
MQTTNetworkInit MQTT网络层初始化
MQTTNetworkConnect MQTT网络连接
MQTTNetworkDisconnect MQTT网络断开
MQTTClientInit MQTT客户端初始化
MQTTClientDeInit MQTT客户端反初始化
MQTTConnect MQTT建立客户端连接
MQTTIsConnected MQTT连接状态查询
MQTTDisconnect MQTT断开客户端连接
MQTTSubscribe MQTT消息订阅
messageHandler 接收消息回调函数
MQTTUnsubscribe MQTT消息退订
MQTTPublish MQTT消息发布
MQTTYield MQTT事务保持

MQTTNetworkInit

该函数用于对MQTT网络结构体进行初始化,其函数原型如下:

int MQTTNetworkInit(Network    *pNetwork,
                    const char *host,
                    uint16_t    port,
                    const char *ca_crt);
参数 说明
pNetwork 需要初始化的网络结构体
host 连接服务器地址
port 连接服务器端口
ca_crt CA证书,只在TLS加密连接下使用,打开宏“MQTT_USING_TLS”进行TLS加密连接则使用证书;关闭宏进行TCP连接,该参数传0。
返回 说明
int =0初始化成功;<0初始化失败

MQTTNetworkConnect

该函数用于MQTT网络连接,其函数原型如下:

int MQTTNetworkConnect(Network *pNetwork);
参数 说明
pNetwork 需要初始化的网络结构体
返回 说明
int =0连接成功;<0连接失败

MQTTNetworkDisconnect

该函数用于MQTT网络断开,其函数原型如下:

void MQTTNetworkDisconnect(Network *pNetwork);
参数 说明
pNetwork 需要初始化的网络结构体
返回 说明

MQTTClientInit

该函数用于初始化MQTT客户端,其函数原型如下:

void MQTTClientInit(MQTTClient    *c,
                    Network       *network,
                    unsigned int   command_timeout_ms,
                    unsigned char* sendbuf,
                    size_t         sendbuf_size,
                    unsigned char* readbuf,
                    size_t         readbuf_size);
参数 说明
c 指向需要初始化的MQTT客户端结构体
network 指向需要初始化的MQTT客户端的网络结构体,在MQTTNetworkInit()中进行初始化
command_timeout_ms 命令执行超时时间
sendbuf 客户端发送数据缓冲区地址
sendbuf_size 发送数据缓冲区容量
readbuf 客户端接收数据缓冲区地址
readbuf_size 接收数据缓冲区容量
返回 说明

MQTTClientDeInit

该函数用于反初始化MQTT客户端,其函数原型如下:

void MQTTClientDeInit(MQTTClient* c);
参数 说明
c 指向需要反初始化的MQTT客户端结构体
返回 说明

MQTTConnect

该函数用于实现MQTT应用层连接,其函数原型如下:

int MQTTConnect(MQTTClient *c, MQTTPacket_connectData *options);
参数 说明
c 客户端结构体指针
options 连接选项结构体指针
返回 说明
int =0初始化成功;<0初始化失败

MQTTIsConnected

该函数用于查询MQTT协议层连接状态,其函数原型如下:

int MQTTIsConnected(MQTTClient* client);
参数 说明
client 指向需要查询的客户端结构体
返回 说明
int =0初始化成功;<0初始化失败

MQTTDisconnect

该函数用于断开MQTT协议链接,该函数原型如下:

int MQTTDisconnect(MQTTClient* c);
参数 说明
c 指向需要断开连接的客户端结构体
返回 说明
int =0初始化成功;<0初始化失败

MQTTSubscribe

该函数用于实现MQTT消息订阅,该函数原型如下:

int MQTTSubscribe(MQTTClient    *c,
                  const char    *topicFilter,
                  enum QoS       qos,
                  messageHandler messageHandler);
参数 说明
c 指向需要订阅消息的客户端结构体
topicFilter 指向需要订阅的消息主题
qos 订阅消息的服务质量
messageHandler 指向订阅消息的回调函数
返回 说明
int =0初始化成功;<0初始化失败

messageHandler

接收消息回调函数,该函数原型如下:

typedef void (*messageHandler)(MessageData*);
参数 说明
MessageData 接收消息处理结构体
返回 说明

MQTTUnsubscribe

该函数用于退订MQTT主题,该函数原型如下:

int MQTTUnsubscribe(MQTTClient* c, const char* topicFilter);
参数 说明
c 指向需要退订消息的客户端结构体
topicFilter 指向需要退订的消息主题
返回 说明
int =0初始化成功;<0初始化失败

MQTTPublish

该函数用于发布MQTT消息,该函数原型如下:

int MQTTPublish(MQTTClient *c, const char *topicName, MQTTMessage *message);
参数 说明
c 指向需要发布消息的客户端结构体
topicName 指向需要发布的消息主题
message 指向需要发布的消息结构体
返回 说明
int =0初始化成功;<0初始化失败

MQTTYield

该函数用于保持MQTT事务,主要进行循环接收数据和心跳保持,该函数原型如下:

int MQTTYield(MQTTClient *c, int timeout_ms);
参数 说明
c 指向客户端结构体
timeout_ms 接收阻塞超时时间
返回 说明
int =0初始化成功;<0初始化失败

| 🔝回到顶部 |📖目录 |

results matching ""

    No results matching ""