用户可以直接通过SDK提供的MQTT API与阿里云物联网平台通信,也即用户可以通过向指定的topic发送消息的方式将数据发送到阿里云物联网平台,也可以通过订阅指定的topic从阿里云物联网平台接收数据,这些topic都是用户自己定义的。

直接使用MQTT TOPIC与物联网平台通信的流程示意图如下:

说明:

  • 通过调用IOT_MQTT_Construct()接口调用, 建立设备和云平台之间的长连接
    • 这个接口是用来向云平台发起连接请求的,其参数中需要的"签名信息"可以通过dev_sign功能中的IOT_Sign_MQTT()获得
    • 连接成功的话,会返回一个handle参数,这就是连接的句柄,可用作之后所有MQTT网络接口的入参
  • 通过IOT_MQTT_Subscribe()接口调用,可以向云平台表达设备将接收哪些Topic上的报文
  • 然后进入业务主循环
    • 通过IOT_MQTT_Publish()IOT_MQTT_Publish_Simple(),可将消息上报到云端
    • IOT_MQTT_Yield()用于接收云端下发的消息,并调用用户在IOT_MQTT_Subscribe()时指定的回调函数,用于对数据进行处理

例子程序讲解

MQTT上云的例子程序在src/mqtt/examples/mqtt_example.c,在“快速体验”一章中已对其进行过逐段的讲解。请参考“以MQTT Topic编程方式接入设备”一节。

功能API接口

函数名 说明
IOT_MQTT_CheckStateNormal MQTT连接后,调用此函数检查长连接是否正常
IOT_MQTT_Construct MQTT实例的构造函数,入参为iotx_mqtt_param_t结构体,连接MQTT服务器,并返回被创建句柄
IOT_MQTT_Destroy MQTT实例的摧毁函数,入参为 IOT_MQTT_Construct创建的句柄
IOT_MQTT_Publish MQTT会话阶段,组织一个完整的MQTT Publish报文,向服务端发送消息发布报文
IOT_MQTT_Publish_Simple MQTT会话阶段,组织一个完整的MQTT Publish报文,向服务端发送消息发布报文,参数中不含结构体等复杂数据类型
IOT_MQTT_Subscribe MQTT会话阶段,组织一个完整的MQTT Subscribe报文,向服务端发送订阅请求
IOT_MQTT_Subscribe_Sync MQTT会话阶段,组织一个完整的MQTT Subscribe报文,向服务端发送订阅请求,并等待应答
IOT_MQTT_Unsubscribe MQTT会话阶段,组织一个完整的MQTT UnSubscribe报文,向服务端发送取消订阅请求
IOT_MQTT_Yield MQTT会话阶段,MQTT主循环函数,内含了心跳的维持,服务器下行报文的收取等

需要实现的HAL接口

以下函数为可选实现,如果希望SDK提供MQTT通道功能,则需要用户对接

函数名 说明
HAL_UptimeMs 返回设备加电以来到当前时间点过去的毫秒数
HAL_SleepMs 按照入参指定的毫秒数睡眠相应时间
HAL_SSL_Destroy 销毁一个TLS连接,用于MQTT功能,加密连接的情况
HAL_SSL_Establish 建立一个TLS连接,用于MQTT功能,加密连接的情况
HAL_SSL_Read 从一个TLS连接中读数据,用于MQTT功能,加密连接的情况
HAL_SSL_Write 向一个TLS连接中写数据,用于MQTT功能,加密连接的情况
HAL_TCP_Destroy 销毁一个TLS连接,用于MQTT功能
HAL_TCP_Establish 建立一个TCP连接,包含了域名解析的动作和TCP连接的建立
HAL_TCP_Read 在指定时间内,从TCP连接读取流数据,并返回读到的字节数
HAL_TCP_Write 在指定时间内,向TCP连接发送流数据,并返回发送的字节数

注: SDK提供的用户API接口都列在src/mqtt/mqtt_api.h,可能需要对接的HAL函数都列在src/mqtt/mqtt_wrapper.h,以代码为准。