产品中心
串口服务器
SP501LW
MQTT远程配置

MQTT远程配置

设备连接 MQTT 服务器后，可通过下发配置 JSON 修改网络、协议、串口和工作模式参数。配置写入后设备会延迟重启，重启后参数生效。

HTTP接口

接口 方法 描述
/mqttPOST配置 MQTT 客户端、Topic、QoS、retain 等参数
/mqtt_infoGET读取 MQTT 当前配置

所有 POST 请求体为 JSON，成功返回：

{
  "code": 200
}

MQTT下发配置

设备连接 MQTT 服务器后会订阅配置中的 mqtt_pub_topic。平台向该 Topic 发布配置 JSON 后，设备会写入配置并延迟重启。

标准格式：

{
  "action": "config",
  "data": {
    "use_mqtt": "1",
    "mqtt_server": "mqtt.likong-iot.com",
    "mqtt_port": "1883",
    "mqtt_username": "demo",
    "mqtt_password": "demo",
    "mqtt_clientid": "client-id"
  }
}

也支持扁平格式：

{
  "action": "config",
  "use_mqtt": "1",
  "mqtt_server": "mqtt.likong-iot.com",
  "mqtt_port": "1883"
}
ℹ️

action、cmd、type 任一字段为 config 时触发配置写入。配置内容可放在 data、config 或 nvs 对象中。

配置示例

基础 MQTT 参数

{
  "action": "config",
  "data": {
    "use_mqtt": "1",
    "mqtt_server": "mqtt.likong-iot.com",
    "mqtt_port": "1883",
    "mqtt_username": "demo",
    "mqtt_password": "demo",
    "mqtt_clientid": "client-id",
    "mqtt_sub_topic": "device/resp",
    "mqtt_pub_topic": "device/cmd",
    "qos": "1",
    "retain": "0",
    "mqtt_send": "0"
  }
}

Modbus-RTU 网关模板

{
  "action": "config",
  "data": {
    "work_mode": "modbus_rtu",
    "poll_time": "30000",
    "modbus_items": [
      {
        "enabled": true,
        "slave_addr": "01",
        "function_code": "03",
        "register_addr": "0",
        "register_num": "2",
        "timeout": "1000",
        "interval_time": "2000",
        "data_format": "HEX",
        "report_format": "mqtt",
        "baud_rate": "9600",
        "data_bit": "8",
        "stop_bit": "1",
        "check_bit": "None"
      }
    ]
  }
}

综合配置

{
  "action": "config",
  "data": {
    "netconn": "1",
    "is_dhcp": "2",
    "static_ip": "192.168.1.50",
    "static_netmask": "255.255.255.0",
    "static_gateway": "192.168.1.1",
    "static_dns1": "8.8.8.8",
    "static_dns2": "114.114.114.114",
    "use_mqtt": "1",
    "mqtt_server": "mqtt.likong-iot.com",
    "mqtt_port": "1883",
    "mqtt_username": "demo",
    "mqtt_password": "demo",
    "mqtt_clientid": "client-id",
    "mqtt_sub_topic": "device/resp",
    "mqtt_pub_topic": "device/cmd",
    "qos": "1",
    "retain": "0",
    "use_tcp": "1",
    "tcpconn": "1",
    "tcp_server": "192.168.1.100",
    "tcp_port": "8888",
    "use_http": "0",
    "work_mode": "modbus_rtu",
    "poll_time": "30000",
    "baud_rate": "9600",
    "data_bit": "8",
    "check_bit": "None",
    "stop_bit": "1",
    "frame_time": "50",
    "frame_len": "512"
  }
}

下发规则

  • 仅处理字符串、数字、布尔字段，值会转成字符串存入 NVS。
  • 未列出的字符串、数字、布尔字段也可能被保存，但不一定会被固件使用。
  • device_sn、mqttconn、mqtt_type、tcp_send 通过 MQTT 下发时会被忽略。
  • 可通过 MQTT 配置 work_mode、poll_time、modbus_items，效果等同 Web 中的工作模式配置。
  • 配置消息成功写入后，不会再透传到串口。
  • 成功后设备向 mqtt_sub_topic 返回 {"code":200,"msg":"config updated"}。
  • 成功写入后设备会延迟重启，约 500ms。

网络配置键

键 说明 取值范围
netconn网络模式1=以太网，2=Wi-Fi
is_dhcpIP 模式1=DHCP，2=静态 IP
static_ip静态 IPIPv4 字符串
static_netmask子网掩码IPv4 字符串
static_gateway网关IPv4 字符串
static_dns1主 DNSIPv4 字符串
static_dns2备 DNSIPv4 字符串
wifi_ssidWi-Fi SSID字符串
wifi_passwordWi-Fi 密码字符串
ap_nameAP 名称字符串
ap_passwordAP 密码字符串
ap_wait_timeAP 等待时间大于 0 秒

MQTT配置键

键 说明 取值范围
use_mqtt是否启用 MQTT0/1
mqtt_server服务器地址主机名或 IP
mqtt_port服务器端口1-65535
mqtt_username用户名字符串
mqtt_password密码字符串
mqtt_clientidClient ID字符串，需唯一
mqtt_sub_topic发布/上报 Topic字符串，建议不超过 127 字节
mqtt_pub_topic订阅/下发 Topic字符串，建议不超过 127 字节
qosQoS0/1/2
retainretain 标志0/1
mqtt_send定时上报开关0=关闭，2=开启
mqtt_time定时上报周期大于 0 秒

TCP配置键

键 说明 取值范围
use_tcp是否启用 TCP0/1
tcpconnTCP 模式0=服务器，1=客户端，2=Modbus，等同服务器
tcp_server服务器地址主机名或 IP
tcp_port端口1-65535
tcp_time发送周期大于 0 秒
reg_packet注册包内容字符串，空则使用设备 MAC
reg_format注册包格式none/hex/ascii
heart_packet心跳包内容字符串，空则使用设备 MAC
heart_format心跳包格式none/hex/ascii
heart_interval心跳间隔大于 0 秒，默认 30

UDP配置键

键 说明 取值范围
use_udp是否启用 UDP0/1
udpconnUDP 模式0=服务器，1=客户端

HTTP配置键

键 说明 取值范围
use_http是否启用 HTTP0/1
http_port端口1-65535
httpconnHTTP 上报开关0/1
http_url上报 URLURL 字符串
http_header自定义 Header字符串
http_time上报周期大于 0 秒

工作与串口配置键

键 说明 取值范围
work_mode工作模式mqtt_tcp / modbus_tcp / modbus_rtu
poll_time轮询间隔1000-3600000 毫秒
modbus_itemsModbus 模板数组结构见参数设置页的 COMMAND 定义
baud_rate波特率1200/2400/4800/9600/19200/38400/57600/115200
data_bit数据位5/6/7/8
check_bit校验位None/Odd/Even
stop_bit停止位1/1.5/2
frame_time帧间隔正整数，单位毫秒
frame_len帧长度正整数，建议不超过 4096

系统配置键

键 说明 取值范围
host_names设备名称字符串
ntp_serverNTP 服务器域名或 IP
lgname登录用户名字符串
lgpwd登录密码字符串
device_type设备型号字符串
虚拟串口功能MQTT协议接入