设备使用指南

切换深色模式

Edge MQTT 数据接口 ​

适用于 Edge 的 MQTT 数据服务器，不用于 Std 网关转发或 MQTT 远程管理。先在输出配置勾选 MQTT，填 Broker、端口、TLS、认证和 Client ID，保存后核对实际连接。

操作视频 ​

G4 Edge 实机：填写 MQTT、测试、保存重连和核对上行 · 下载视频

连续展示输出选择、数据服务器填写、实际连接测试、保存重启、重新登录回读及接收端验证。重启等待在片中明确提示后缩短。收到的是同一台 DTU 的真实心跳；本次测试 Broker 允许局域网匿名连接，生产认证/TLS和无线下行未验证。

主题与方向 ​

以下为当前默认主题；定制配置按实际发布/订阅主题核对。{gatewayId} 为 16 位网关 EUI，{DevEUI} 为 16 位终端 EUI，不带花括号。

主题网关动作应用系统动作
/gateway/{gatewayId}/up发布原生上行订阅
/gateway/{gatewayId}/down订阅原生下行发布
application/0/device/{DevEUI}/rx发布兼容上行订阅
application/0/device/{DevEUI}/tx订阅兼容下行发布
gateway/{gatewayId}/event/stats发布网关状态（无开头斜杠）按需订阅

兼容应用主题需要当前配置启用 compatOpen；不能因为原生主题有效就假定兼容主题也已开启。当前普通网页未提供该开关编辑入口，部署未开启时使用原生接口，或由维护方按配套配置启用。旧 1.0.6 文档写两类可混用，仍须满足此条件。

订阅可以用 + 匹配某一级，例如 /gateway/+/up；向一个具体目标发布下行时使用准确主题，不用通配符作为目标。当前应用上行按 QoS 0、非保留发布，接收方按自己的可靠性要求及时保存数据，不将断线期间数据视为保证补发。

原生上行 ​

以下为构造示例，MTIz 解码为 ASCII 123，不是传感器测量案例。

json
{
  "app": {
    "moteeui": "0011223344556677",
    "dir": "up",
    "userdata": {
      "seqno": 1,
      "port": 12,
      "payload": "MTIz"
    },
    "motetx": {
      "freq": 471.5,
      "modu": "LORA",
      "datr": "SF10BW125",
      "codr": "4/5",
      "adr": false
    },
    "gwrx": [
      {
        "eui": "1122334455667788",
        "time": "2026-10-17T08:00:00",
        "timefromgateway": true,
        "chan": 6,
        "rfch": 1,
        "rssi": -75,
        "lsnr": 8
      }
    ]
  }
}
字段类型 / 单位说明
app.moteeuiHEX 字符串终端 EUI
userdata.seqno整数上行计数；零值可能省略，不用于业务去重的唯一条件
userdata.port整数FPort，按终端协议区分业务
userdata.payloadBase64 字符串解密并经当前兼容处理的应用字节，不是整个 LoRaWAN 无线帧；27 字节旧帧的截断例外见数据与解析
userdata.decodedData可选对象匹配解码器产生的解析结果
motetx.freq数值，MHz终端发送频率
motetx.datr字符串SF 和带宽，例如 SF10BW125
motetx.adr布尔当前报文生成值，不作为终端 ADR 配置的回读凭据
gwrx[]数组网关接收信息：EUI、时间、信道、RSSI dBm、LSNR dB

时间字符串是否有时区后缀按实际报文处理，接收端保留原文；不要把无后缀时间擅自作为 UTC。

网关统计事件 ​

gateway/{gatewayId}/event/stats 是额外的网关状态事件，当前 JSON 有 gatewayID、ip、time、可选位置 location、configVersion、rxPacketsReceived、rxPacketsReceivedOK、txPacketsReceived、txPacketsEmitted、metaData、statsID。它不是 app 业务包；当前 gatewayID 是网关 EUI 原始 8 字节的 Base64（如 ESIzRFVmd4g=），不直接用来替换主题中的 HEX EUI。流量统计、CRC 统计和单台终端业务成功率分开解释。

兼容上行 ​

json
{
  "applicationID": "0",
  "applicationName": "0",
  "deviceName": "0011223344556677",
  "devEUI": "0011223344556677",
  "rxInfo": [
    {
      "gatewayID": "1122334455667788",
      "name": "Edge",
      "time": "2026-10-17T16:00:00+08:00",
      "rssi": -75,
      "loRaSNR": 8
    }
  ],
  "txInfo": {
    "frequency": 471500000,
    "dr": 2
  },
  "adr": false,
  "fCnt": 1,
  "fPort": 12,
  "data": "MTIz",
  "devAddr": "12345678"
}

data 是 Base64；frequency 是 Hz，原生 freq 是 MHz。当前兼容 dr 按 SF12→0 至 SF7→5 生成，不用该简化映射推断所有区域的完整速率计划。这是旧版应用 JSON 兼容格式，不是 ChirpStack V4 网关转发协议；此格式不承诺包含 decodedData。

单播下行 ​

原生接口向 /gateway/{gatewayId}/down 发布：

json
{
  "app": {
    "moteeui": "0011223344556677",
    "userdata": {
      "port": 2,
      "payload": "AQID"
    }
  }
}

AQID 是示例字节 01 02 03，不是推荐现场命令。userdata.port 和载荷必须符合目标终端的下行协议。兼容方式向目标终端 /tx 发布：

json
{
  "devEUI": "0011223344556677",
  "fPort": 2,
  "data": "AQID"
}

兼容 devEUI 可省略并从标准五段主题取值；使用定制主题时建议显式提供。原生消息中的 EUI 用 JSON 字符串，不是 Base64。

可选 Class C 射频字段 ​

app 字段单位 / 规则
freqHz；省略时用网关当前配置
sf7～12；省略时用当前配置
bandwidth0=125kHz，1=250kHz，2=500kHz
token旧组合值，保留兼容；正值存在时优先覆盖 freq/sf，不建议新接入使用

旧 token 为 频率kHz × 10 + SF索引，索引 0～5 对应 SF12～SF7。Class A 等下一次上行窗口，由实际调度确定接收参数；当前每个 DevAddr 的等待队列最多 100 条，满后新增请求可能被丢弃，重启会清空队列，不能当作持久任务存储。Class C 也必须与终端窗口一致。CN470 505.3MHz / SF12 只是旧默认示例，不用于所有区域或当前设备。

组播与结果 ​

json
{
  "app": {
    "groupAddr": "01020304",
    "userdata": {
      "port": 2,
      "payload": "AQID"
    }
  }
}

组播沿用原生 /down 主题，删除 moteeui；两者同时存在时走单播。先在网关与所有目标终端配置相同组地址和两把组密钥，并确认终端按 Class C 接收。无线帧按组地址和组密钥发送，网页成员列表不是无线接收白名单。应用发布成功仅说明 Broker 接受消息，不表示网关解包成功、无线发送完成或终端收到；结合实时记录、队列、终端回复及实际动作验收。

图解：把业务 MQTT 配到哪里 ​

Edge MQTT 数据服务器配置（界面示例）：地址填主机名/IP，端口单独填；SSL 开关、用户名、密码、Client ID 分别配置。未测试连接或保存。
Edge MQTT 数据服务器配置（界面示例）：地址填主机名/IP，端口单独填；SSL 开关、用户名、密码、Client ID 分别配置。未测试连接或保存。 点击放大
Edge MQTT 数据服务器配置（界面示例）：地址填主机名/IP，端口单独填；SSL 开关、用户名、密码、Client ID 分别配置。未测试连接或保存。
Edge MQTT 数据服务器配置（界面示例）：地址填主机名/IP，端口单独填；SSL 开关、用户名、密码、Client ID 分别配置。未测试连接或保存。
页面项目示例 / 填写方法检查点
服务器地址broker.example.com 或现场 IP此输入框填主机，不填 /gateway/.../up 主题；示例域名需替换
服务器端口现场 Broker 的监听端口普通 MQTT 常用 1883；TLS 端口由服务提供方确认，不能只开 SSL 而不换配套端口
SSL按 Broker 要求开启，配置相应证书CA、客户端证书、私钥按 Broker 要求提供；当前配套实现中，填写 CA 内容的连接测试，以及加载自定义证书的正式连接，会跳过服务端证书链与主机名校验；不能仅凭测试成功认定服务器身份已验证
用户名 / 密码Broker 授予的账号不是网页管理账户；有发布/订阅权限
Client ID例如 site01-gw-data当前网页最多 23 字符，只允许字母、数字、下划线、短横线；同 Broker 内避免冲突

保存并重连后，应用先订阅上行主题，再触发一个已登记终端的正常上报。若没有消息，依次核对输出勾选、Broker 连接、主题开头斜杠、EUI 和 ACL；不要先改载荷倍率。

把同一包在三个位置对起来 ​

所在位置示例值怎样对应
终端实时页的应用 HEX31 32 33三个原始应用字节，教学样本非测量
MQTT payloadMTIzBase64 解码后应仍为 31 32 33
应用接收记录EUI、FPort=12、接收时间与同一终端同一条上行对应；不要把无线 PHY 帧当应用字节

下行也按“应用字节 → Base64 → JSON → 具体主题”处理。需要直接运行的订阅、编码和只读调用示例，见接入示例与联调。

G4 实机配置与接收 ​

G4 Edge 保存重启后的 MQTT 数据服务器回读。图中地址是本次测试电脑的局域网服务，现场使用时换成自己的 Broker；认证信息不展示。
G4 Edge 保存重启后的 MQTT 数据服务器回读。图中地址是本次测试电脑的局域网服务，现场使用时换成自己的 Broker；认证信息不展示。 点击放大
G4 Edge 保存重启后的 MQTT 数据服务器回读。图中地址是本次测试电脑的局域网服务，现场使用时换成自己的 Broker；认证信息不展示。
G4 Edge 保存重启后的 MQTT 数据服务器回读。图中地址是本次测试电脑的局域网服务，现场使用时换成自己的 Broker；认证信息不展示。
测试电脑接收端的真实 MQTT 上行记录：显示主题、FPort、上行计数和应用 HEX；不是网关管理页面中的新功能。
测试电脑接收端的真实 MQTT 上行记录：显示主题、FPort、上行计数和应用 HEX；不是网关管理页面中的新功能。 点击放大
测试电脑接收端的真实 MQTT 上行记录：显示主题、FPort、上行计数和应用 HEX；不是网关管理页面中的新功能。
测试电脑接收端的真实 MQTT 上行记录：显示主题、FPort、上行计数和应用 HEX；不是网关管理页面中的新功能。

本次已实际验证 DTU 的 FPort 40 心跳从网关到 MQTT 接收端，并与 HTTP 收到的同一条记录核对原始字节一致。没有验证无线下行或外接仪表采集。连续操作见MQTT 配置实录。

设备使用指南

© 2026 DeviceGuide