设备使用指南

切换深色模式

MQTT 远程管理接口 ​

此接口连接 MQTT 远程管理服务器，与 Edge 终端业务 /gateway/.../up/down 分开。仅在设备配置了远程管理连接时工作；Edge 还要开启对应使能。它可管理配置和终端，也能重启设备，先明确管理权限和操作对象再接入。

默认主题 ​

主题用途
gateway/{gatewayId}/command/exec管理平台发布命令
gateway/{gatewayId}/event/ack网关先返回接收/解析阶段 ACK
gateway/{gatewayId}/event/execgetConfig 配置结果
gateway/{gatewayId}/up/infogetInfo / wifiInfo 结果
gateway/{gatewayId}/up/mote终端/组播命令结果
gateway/{gatewayId}/up/alive保留的存活消息主题；当前连接流程未启动周期发布
gateway/{gatewayId}/up/ssh、.../down/ssh配套平台远程维护通道，非终端应用数据

以上没有开头斜杠，定制主题按部署配置。此主题的历史消息格式为 {"alive":"start"} 和 {"alive":"alive"}；当前配套版本未启用周期发布，不保证每 30 秒收到存活消息。排查远程管理连接时使用 getInfo 的实际回应，不能以没有 up/alive 消息判断网关离线；管理连接正常也不代表终端在线或数据完整。

命令封装 ​

字段类型与规则
gatewayID8 字节网关 EUI 的 Base64，区别于业务接口的 HEX EUI 字符串
command命令字符串，见下表
tokenint32，请求关联值，与业务下行的射频 token 完全不同
environment字符串到字符串的映射，作为命令参数，不传原生数字/布尔对象
body可选 Base64 字符串；内容是对应 JSON/数据字节，不是直接嵌套对象

构造的只读例子：网关 EUI 1122334455667788，对应 Base64 ESIzRFVmd4g=。

json
{
  "gatewayID": "ESIzRFVmd4g=",
  "command": "getInfo",
  "token": 1001,
  "environment": {}
}

返回的 stdout 也为 Base64，先解码再解析内部 JSON。按 gatewayID 和 token 关联，订阅结果主题应在发命令前准备好。

event/ack 先于业务处理发送：其中 status=1 不能证明配置保存、终端操作、升级或无线下发已成功；解析失败可见 status=10。再检查命令结果主题、错误和最终设备状态；某些失败只记录日志，不能把“未收到错误”当成功。

命令与参数 ​

终端/组播对象和原生下行 JSON 格式见管理 REST与业务 MQTT。本节 body 中的 JSON 要先序列化、再 Base64。终端/组播管理只用于 Edge。

commandenvironment / body结果与影响
getInfo无额外参数up/info，网关信息
wifiInfo无额外参数up/info，连接状态
getConfig无额外参数event/exec，字符串配置映射；包含敏感信息
configenvironment 为对应完整字符串配置映射更新配置并重启；不是 REST GatewayConfig 对象
reboot无额外参数重启
upgradeenvironment.url、md5下载部署包、校验和更新后重启；只用匹配的正式包
ssh配套平台 host、port、username、password建立维护连接；不用于业务下发，本册不演示系统操作
mote:addbody：Mote 的 Base64up/mote；会改变记录/状态或下发
mote:add:batchbody：Mote[] 的 Base64up/mote；会改变记录/状态或下发
mote:getenvironment：idup/mote；查询
mote:listenvironment：search, alive 默认 false, limit 默认 10, offset 默认 0, class, group, filterGroupup/mote；查询
mote:updatebody：Mote 的 Base64up/mote；会改变记录/状态或下发
mote:timing:updatebody：Mote 接收延时部分对象（devEUI及至少一个延时） 的 Base64up/mote；会改变记录/状态或下发
mote:deleteenvironment：idup/mote；会改变记录/状态或下发
mote:delete:all无额外参数up/mote；会改变记录/状态或下发
mote:sendbody：原生下行 JSON 的 Base64up/mote；会改变记录/状态或下发
mote:queue:lenenvironment：idup/mote；查询
mote:rx2无额外参数up/mote；查询
group:addbody：MoteGroup 的 Base64up/mote；会改变记录/状态或下发
group:getenvironment：addrup/mote；查询
group:listenvironment：search, limit 默认 10, offset 默认 0up/mote；查询
group:updatebody：MoteGroup 的 Base64up/mote；会改变记录/状态或下发
group:deleteenvironment：addrup/mote；会改变记录/状态或下发
group:sendbody：原生下行 JSON 的 Base64up/mote；会改变记录/状态或下发
group:add:moteenvironment：addr, search, alive 默认 false, allCheck 默认 false, filterGroup；body：DevEUI 字符串数组 的 Base64up/mote；会改变记录/状态或下发
group:remove:moteenvironment：euiup/mote；会改变记录/状态或下发
group:remove:all:moteenvironment：addrup/mote；会改变记录/状态或下发

远程 config 的字段映射 ​

config 使用历史字符串参数协议，与网页 REST 的分组结构不同。先 getConfig，解码 stdout 并保留完整映射，只修改明确需要的键后提交；不要将其当作任意稀疏补丁，缺少频段/地址等键可能导致错误或意外改变。字符串开关一般为 "1" / "0"，频率为 Hz；headers 等结构按 getConfig 的字符串 JSON 保留。以下为当前 setConfig 实际读取的键，按设备能力使用。

  • gateway_eui
  • gateway_ip
  • gateway_router
  • gateway_mask
  • gateway_addr_type
  • rsu_ip
  • ntp_ip
  • net_priority
  • wifi_ssid
  • wifi_password
  • wifi_hidden
  • enable_4g
  • operator
  • enable_gps
  • is_restart
  • restart_times
  • auto_register_abp
  • bridge_mode
  • freq_mode
  • region_template_id
  • freq_band
  • freq_start
  • freq_end
  • enable_mqtt
  • mqtt_url
  • mqtt_username
  • mqtt_password
  • mqtt_ca
  • mqtt_cert
  • mqtt_cert_key
  • mqtt_client_id
  • mqtt_conf_url
  • mqtt_conf_username
  • mqtt_conf_password
  • mqtt_conf_ca
  • mqtt_conf_cert
  • mqtt_conf_cert_key
  • mqtt_conf_client_id
  • bridge_addr
  • basicstation_udp_bind
  • basicstation_gateway_id
  • basicstation_class_c
  • basicstation_lns_enabled
  • basicstation_lns_uri
  • basicstation_lns_trust
  • basicstation_lns_cert
  • basicstation_lns_key
  • basicstation_cups_enabled
  • basicstation_cups_uri
  • basicstation_cups_trust
  • basicstation_cups_cert
  • basicstation_cups_key
  • basicstation_cups_interval
  • basicstation_firmware_apply
  • http_url
  • http_headers
  • rs485_protocol
  • rs485_slave_id
  • rs485_baud_rate
  • rs485_mote_reg_num
  • rs485_check_crc
  • rs485_timeout
  • rs485_data_bits
  • rs485_parity
  • rs485_stop_bits

这些键的现场值从 getConfig 取得；不公开真实认证材料，也不在说明书演示执行 config、upgrade、reboot 或 ssh。管理 MQTT 不是事务型设备业务接口；执行结果需通过响应与重连后的实际配置复核。

字段的单位与读写边界 ​

上述字段清单用于与 getConfig 回读对照，不表示可随意组合成部分写请求。下表将常用组分开，所有 environment 值都用字符串。

参数组格式 / 示例用途与限制
gateway_eui16 位 HEX 字符串网关身份；不是 envelope 中 Base64 gatewayID
gateway_ip / gateway_router / gateway_maskIPv4 文本有线网络参数，与 gateway_addr_type 配合
gateway_addr_typedhcp / static保留本机支持的地址类型
ntp_ip / rsu_ipIP 或纯域名rsu_ip 是历史兼容名；同时提供时 ntp_ip 优先
net_priorityeth0.1 apcli0 ppp0空格分隔字符串，保留现场实际接口
wifi_ssid / wifi_password / wifi_hidden热点名称、密码、"1"或"0"维护热点参数，区别于 wifiInfo 的外部网络连接
enable_4g / enable_gps / operator"1"或"0"、APN 文本对应硬件和运营商配置
is_restart / restart_times"1"或"0"、HH:mm每日重启；先核对当前时间
auto_register_abp"1"或"0"Edge 自动登记白名单能力
bridge_modev3 / v4 / basicstation-udp / noneStd 转发方案；依实际支持使用
freq_mode / region_template_idtemplate / custom、模板 IDV4/Basic Station 依模板约束
freq_band / freq_start / freq_end区域、Hz 整数字符串例 "470300000"；不是 MHz 小数
enable_mqtt"1"或"0"Std 数据转发选择 / Edge 远程管理使能
mqtt_url / mqtt_conf_url带方案、端口的完整 MQTT URL业务/转发与远程管理分别配置
mqtt_* / mqtt_conf_* 认证字段用户名、密码、证书文本、Client ID保留回读映射；证书与私钥不公开
http_url / http_headers完整 URL、JSON 对象序列化后的字符串headers 示例值为 "{\"X-Site\":\"demo\"}"，不是直接嵌套对象
rs485_protocol / rs485_slave_idmodbus/private、数字字符串Edge 且硬件支持
rs485_baud_rate / rs485_mote_reg_num波特率、每终端寄存器数N 为正数，改变 N 会改变寄存器映射
rs485_check_crc / rs485_timeout"1"或"0"、ms 数字字符串超时是串口读取参数，不是终端无线响应期限
rs485_data_bits / rs485_parity / rs485_stop_bits5～8、78/79/69、1/2例如 "78" 表示 N 校验，不填字符串 N
basicstation_*回读的本机适配字段LNS/CUPS 分别处理，enabled 类用字符串开关

getConfig 还可能返回 gateway_type、signal_level_4g、wifi_enable 等状态/能力字段。当前远程 config 没有读取 wifi_enable 来修改热点开关，不能根据回读存在就认为它可写；需要调整热点开关时使用当前网页或完整 REST 配置。gateway_type 也不作为远程切模式命令。

回应从哪一层取值 ​

  • ACK JSON 的状态位在 items[0].status，不是顶层 status，也不是 REST code。
  • 结果 JSON 的 stdout 是 Base64，解码后才是对应命令 JSON。getConfig 解码后直接是字符串配置映射；getInfo 也直接返回字符串映射，计数等值仍是字符串；wifiInfo 返回 connect_info（ssid、connect），不是 REST 的 code/msg/data 包装。
  • mote / group 命令结果解码后为 {"code":0,"msg":"ok","data":...} 或 {"code":-1,"msg":"错误说明"}；这里的 msg 是字符串，不是 REST 的 msg.label / msg.err 对象。
  • mote:get / mote:delete 的 id 是 DevEUI；mote:queue:len 的 id 是 DevAddr。mote:rx2 的 freq 为 MHz、sf 为索引，与 REST RX2 同一规则。
  • body 本身是 Base64 字符串；其中 JSON 的 payload 等二进制字段仍按该对象的 Base64 合同编码，不能少做或多做一层。

从先订阅到解码结果的完整步骤见管理 MQTT 联调。

设备使用指南

© 2026 DeviceGuide