MQTT协议

👾

MQTT 协议接入，通过订阅和发布主题收发消息。设备订阅配置中的 publish 主题，向 subcribe 主题发布返回数据和定时上报数据。

ℹ️

设备默认类型为 ST100TH，返回字段会根据具体型号和传感器支持情况显示数值或 null。

ℹ️

出厂默认 MQTT 协议开启，TCP 和 HTTP 默认关闭；MQTT、TCP、HTTP 的定时上报默认关闭，默认上报间隔为 5 秒。协议启停或参数修改后，按 Web 页面提示重启后生效。

Topic方向

配置字段	设备行为	用途
publish	设备订阅该主题	平台向设备下发指令
subcribe	设备向该主题发布消息	设备返回响应和定时上报数据

⚠️

字段名 subcribe 沿用设备协议定义，请按该拼写下发配置。

功能类型

type	功能	返回
info	获取设备基本信息和实时数据	返回设备信息
customize	获取 MQTT、TCP、HTTP 和补偿配置	返回自定义信息
custom	配置 MQTT、TCP 或 HTTP 参数	返回自定义信息
compensate	设置温度、湿度、气压补偿	返回设备信息
restart	重启设备	设备重启
reset	恢复默认设置后重启	设备重启
ota	按 uri 进行 OTA 升级	进入升级流程

获取设备基本信息

向设备订阅的 publish 主题发送：

{
  "messageid": "3FBD8A5D-9824-D355-EF7A-B31A609522CC",
  "param": {
    "type": "info"
  }
}

字段	类型	长度	备注
messageid	String	48	消息ID，用于标识消息，设备返回时原样返回
type	String	32	消息类型，info 表示获取设备基本信息

指令正常设备向服务器返回：

{
  "messageid": "3FBD8A5D-9824-D355-EF7A-B31A609522CC",
  "code": 200,
  "type": "ST100TH",
  "device_name": "WIFI温湿度变送器",
  "data": {
    "temperature": 26.95,
    "humidity": 49.78,
    "pressure": 948.38,
    "altitude": 554.68
  },
  "compensate": {
    "t_compensate": 0,
    "h_compensate": 0,
    "p_compensate": 0
  },
  "set": {
    "mqtt_timed_report": 1,
    "mqtt_interval_time": 5,
    "tcp_timed_report": 0,
    "tcp_interval_time": 5,
    "http_timed_report": 0,
    "http_interval_time": 5
  },
  "net": {
    "connmethed": "wifi",
    "ssid": "LIKONG-IOT",
    "dhcp": 1,
    "ip": "192.168.31.213"
  },
  "sys": {
    "version": "HW:1.0.0_SDK:1.1.0",
    "runtime": 90,
    "eth_mac": "",
    "sta_mac": "E8:6B:EA:C2:32:8C"
  },
  "protocol": {
    "mqtt": 1,
    "http": 0,
    "tcpserver": 0,
    "tcpclient": 0
  }
}

字段	类型	长度	备注
messageid	String	48	消息ID
code	Int	8	状态码，200 表示成功
type	String	32	设备型号
device_name	String	32	设备名称
temperature	Float/Null	8	温度，单位：℃；不支持或传感器异常时为 null
humidity	Float/Null	8	湿度，单位：%RH；不支持或传感器异常时为 null
pressure	Float/Null	8	气压，单位：hPa；不支持或传感器异常时为 null
altitude	Float/Null	8	海拔，单位：米；由气压换算
t_compensate	Float	8	温度补偿，单位：℃
h_compensate	Float	8	湿度补偿，单位：%RH
p_compensate	Float	8	气压补偿，单位：hPa
connmethed	String	8	网络连接方式，wifi 表示无线连接
ssid	String	32	当前连接的 Wi-Fi SSID
dhcp	Int	8	是否 DHCP，1：启用，0：静态 IP
ip	String	16	设备 IP
version	String	24	固件版本
runtime	Int	8	设备运行时间，单位：秒
sta_mac	String	24	Wi-Fi MAC 地址
protocol	Object	/	各协议是否启用，1：启用，0：未启用

获取设备自定义信息

向设备订阅的 publish 主题发送：

{
  "messageid": "3FBD8A5D-9824-D355-EF7A-B31A609522CC",
  "param": {
    "type": "customize"
  }
}

设备返回当前 MQTT、TCP、HTTP 和补偿参数：

{
  "messageid": "3FBD8A5D-9824-D355-EF7A-B31A609522CC",
  "code": 200,
  "type": "ST100TH",
  "mqtt_info": {
    "enable": 1,
    "mqtt_server": "mqtt.example.com",
    "mqtt_port": 1883,
    "client_id": "ST100_123456",
    "username": "user",
    "password": "password",
    "publish": "/st100/down",
    "subcribe": "/st100/up",
    "qos": 0,
    "retain": 0,
    "timed_report": 1,
    "interval_time": 5
  },
  "tcp_info": {
    "enable": 0,
    "tcp_server": "192.168.1.100",
    "tcp_port": 8080,
    "timed_report": 0,
    "interval_time": 5
  },
  "http_info": {
    "enable": 0,
    "http_uri": "http://example.com/data",
    "timed_report": 0,
    "interval_time": 5
  },
  "compensate": {
    "t_compensate": 0,
    "h_compensate": 0,
    "p_compensate": 0
  }
}

自定义MQTT

向设备订阅的 publish 主题发送，配置成功后设备会向 subcribe 主题返回当前自定义信息。

{
  "messageid": "3FBD8A5D-9824-D355-EF7A-B31A609522CC",
  "param": {
    "type": "custom",
    "protocol": "mqtt",
    "enable": 1,
    "mqtt_server": "mqtt.example.com",
    "mqtt_port": 1883,
    "client_id": "ST100_123456",
    "username": "user",
    "password": "password",
    "publish": "/st100/down",
    "subcribe": "/st100/up",
    "qos": 0,
    "retain": 0,
    "timed_report": 1,
    "interval_time": 5
  }
}

字段	类型	备注
enable	Int	是否启用 MQTT，1：启用，0：关闭
mqtt_server	String	MQTT 服务器地址或域名
mqtt_port	Int	MQTT 服务器端口
client_id	String	MQTT Client ID
username	String	MQTT 用户名
password	String	MQTT 密码
publish	String	平台下发指令主题，设备会订阅此主题
subcribe	String	设备发布响应和定时上报主题
qos	Int	MQTT QoS
retain	Int	retain 标志
timed_report	Int	MQTT 定时上报，1：启用，0：关闭
interval_time	Int	MQTT 定时上报间隔，单位：秒

自定义TCP

该指令配置 TCP 通讯参数。TCP 协议可在 Web 协议管理中选择 TCP Server 或 TCP Client 工作方式。

{
  "messageid": "3FBD8A5D-9824-D355-EF7A-B31A609522CC",
  "param": {
    "type": "custom",
    "protocol": "tcp",
    "enable": 1,
    "tcp_server": "192.168.1.100",
    "tcp_port": 8080,
    "timed_report": 1,
    "interval_time": 5
  }
}

字段	类型	备注
enable	Int	是否启用 TCP，1：启用，0：关闭
tcp_server	String	TCP 服务器地址或域名
tcp_port	Int	TCP 服务器端口
timed_report	Int	TCP 定时上报，1：启用，0：关闭
interval_time	Int	TCP 定时上报间隔，单位：秒

自定义HTTP

HTTP 配置用于设置 HTTP Client 上报地址和定时上报参数。

{
  "messageid": "3FBD8A5D-9824-D355-EF7A-B31A609522CC",
  "param": {
    "type": "custom",
    "protocol": "http",
    "enable": 1,
    "http_uri": "http://example.com/data",
    "timed_report": 1,
    "interval_time": 5
  }
}

字段	类型	备注
enable	Int	是否启用 HTTP 上报，1：启用，0：关闭
http_uri	String	HTTP POST 上报地址
timed_report	Int	HTTP 定时上报，1：启用，0：关闭
interval_time	Int	HTTP 上报间隔，单位：秒

参数补偿

{
  "messageid": "3FBD8A5D-9824-D355-EF7A-B31A609522CC",
  "param": {
    "type": "compensate",
    "t_compensate": 0,
    "h_compensate": 0,
    "p_compensate": 0
  }
}

补偿值写入后，设备会返回最新设备信息。温度、湿度、气压补偿分别对应 t_compensate、h_compensate、p_compensate。

错误响应

当 type 不是设备支持的功能类型时，设备返回：

{
  "messageid": "3FBD8A5D-9824-D355-EF7A-B31A609522CC",
  "code": 204,
  "msg": "type not found"
}

重启设备

{
  "messageid": "3FBD8A5D-9824-D355-EF7A-B31A609522CC",
  "param": {
    "type": "restart"
  }
}

重置设备

{
  "messageid": "3FBD8A5D-9824-D355-EF7A-B31A609522CC",
  "param": {
    "type": "reset"
  }
}

OTA升级

{
  "messageid": "3FBD8A5D-9824-D355-EF7A-B31A609522CC",
  "param": {
    "type": "ota",
    "uri": "http://10.0.0.50/likong-iot/st100_v1.1.0.bin"
  }
}

⚠️

OTA 升级过程中请保持设备供电和网络稳定，升级地址需要设备可以访问。

安装与使用 HTTP协议接入