切换深色模式
LoRaWAN MQTT 业务接口
本文件只说明 LoRaWAN 数据订阅和下发；平台用户、授权和系统维护使用 平台管理 API。MQTT 是异步消息，连接成功不等于终端在线。
能力边界
| 任务 | Application MQTT 支持情况 | 应使用的入口 |
|---|---|---|
| 注册/删除/查询终端档案 | 无标准 CRUD 主题 | LoRaWAN API |
| 读取历史数据 | 无标准历史查询主题 | API 历史查询 |
| 订阅新上行和事件 | 支持 | event/up 等主题 |
| 单播下行 | 支持 | command/down |
| 创建/删除/查询组播组及成员 | 无标准管理主题 | MulticastGroupService |
| 组播下行 | 无对应标准 Application MQTT 组播提交主题 | MulticastGroupService/Enqueue |
网关远程管理的私有 command/exec 不是公共终端 CRUD 协议；不要向业务主题发布自造的 register、delete 或 list 消息。
连接准备
向部署管理员获取服务器地址、实际集成端口、应用账号密码及 TLS 要求。原生包集成端口默认 1885；使用安装实例的凭据，不照抄旧文档固定密码。Broker 是否对远端监听、防火墙是否放行也必须核对。
在业务系统配置唯一 Client ID，连接后订阅目标应用。不要让两个客户端共用 Client ID 导致互相挤下线。默认不承诺离线历史补发，重连后用业务时间/事件标识去重并按需查询历史。
事件订阅主题
application/{application_id}/device/{dev_eui}/event/{event}
| 订阅范围 | 主题 |
|---|---|
| 单个终端全部事件 | application/{application_id}/device/{dev_eui}/event/+ |
| 某应用全部终端上行 | application/{application_id}/device/+/event/up |
| 某应用全部事件 | application/{application_id}/device/+/event/+ |
application_id 使用应用 UUID；dev_eui 使用终端实际 EUI。+ 匹配一层，订阅后等待新的真实事件。
| event | 含义 |
|---|---|
| up | 应用上行 |
| join | OTAA 入网事件 |
| txack | 网关下行发送任务结果 |
| ack | confirmed 下行对应的终端协议确认 |
| log | 设备日志 |
| status | 设备状态 |
| location | 设备位置 |
上行数据字段
事件实际编码由部署配置决定，JSON / Protobuf 不可混用。JSON 字段大小写按实际序列化结果处理，不只对某一截图硬编码。
| 字段（protobuf JSON 常见形式） | 类型 | 说明 |
|---|---|---|
| deduplicationId | string | 上行去重标识 |
| time | Timestamp | 事件时间 |
| deviceInfo | object | DevEUI、应用、模版等资源信息 |
| devAddr | string | 会话短地址 |
| fPort | integer | 应用端口 |
| fCnt | integer | 帧计数 |
| data | Base64 string | 原始应用负载 |
| object | object | codec 解码结果，无 codec 或失败时不能假设有值 |
| rxInfo | array | 接收网关、信号等 |
| txInfo | object | 发射频率、数据率等 |
解码对象用于业务，原始 data 用于复核。相同空口帧可能涉及多个网关接收信息；不能把每个 rxInfo 项计成不同终端上报。
单播下行
业务系统发布：application/{application_id}/device/{dev_eui}/command/down。
| 字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| devEui / dev_eui | string | 是 | 与主题的终端一致 |
| fPort / f_port | integer | 是 | 按终端业务协议指定 |
| confirmed | boolean | 按业务选择 | 是否需要 LoRaWAN 确认 |
| data | Base64 string | 与 object 二选一 | 直接发送业务字节 |
| object | object | 与 data 二选一 | 需要模版的下行编码器 |
| id | UUID string | 否 | 请求的队列标识，按当前消息定义使用 |
| expiresAt / expires_at | Timestamp | 否 | 过期时间，使用未来时间 |
不要把 HEX 字符串直接填到 data，也不要将任意 JSON 对象当成终端必然支持的命令。发布后必须观察队列及 txack；confirmed 还需检查对应 ack，具体动作再看业务回复。
验收顺序
- 查询 API 确认应用、终端和会话存在。
- 订阅目标应用 up，并让终端发送真实上行。
- 比对 DevEUI、FPort、负载和接收时间。
- 按目标协议提交一条可恢复的单播下行。
- 关联队列 ID、txack、ack 和业务回复。
- 断线重连后检查重复消费和数据缺口；历史补查走 API。
本册不把“MQTT publish 成功”解释为“终端收到”。
G4 Edge 私有 MQTT：终端与组播管理
这一节操作的是 G4 Edge 网关本地的 LoRaWAN 档案与队列，不是服务器 Application MQTT。两套设备档案不能混为一谈；Std 转发模式不按 Edge 本地网络服务使用。
管理主题与消息外层
下表为默认主题，实际以网关和服务器管理 MQTT 配置为准。
| 方向 | 主题 | 内容 |
|---|---|---|
| 管理端 → 网关 | gateway/{gateway_id}/command/exec | 命令外层 |
| 网关 → 管理端 | gateway/{gateway_id}/event/ack | 命令处理确认 |
| 网关 → 管理端 | gateway/{gateway_id}/up/mote | 终端/组播操作结果 |
| 外层字段 | 类型 | 必填 | 说明 |
|---|---|---|---|
| gatewayID | Base64 string | 是 | 8 字节网关 EUI 的 Base64；不是直接填写 HEX 文本 |
| command | string | 是 | 下方命令名 |
| token | int32 | 是 | 请求关联编号；回复需匹配同一 token |
| environment | map<string,string> | 按命令 | 查询参数；数字、布尔也按字符串填写 |
| body | Base64 string | 按命令 | 命令体 JSON 的 UTF-8 字节再做 Base64 |
回复外层包含 gatewayID、token、stdout。stdout 同样为 Base64 字节内容，解码后才得到 {code,msg,data} 的 JSON；code 为 0 表示该处理成功，错误时可为 -1 并带 msg。ack、解码后的命令结果、无线实际接收分层判断。
网关本地终端命令
| command | environment | body（编码前的 JSON 类型） | 用途/结果 |
|---|---|---|---|
| mote:add | 无 | Mote 对象 | 注册一条本地终端 |
| mote:add:batch | 无 | Mote 对象数组 | 批量注册 |
| mote:get | id：完整本地 DevEUI | 无 | 查询一条；无 data 不能当成查到设备 |
| mote:list | search、alive、limit、offset、class、group、filterGroup | 无 | 查询列表；默认 limit=10、offset=0；返回 data.total / result |
| mote:update | 无 | Mote 对象 | 更新本地终端 |
| mote:delete | id：完整本地 DevEUI | 无 | 删除指定本地档案 |
| mote:delete:all | 无 | 无 | 清空全部本地终端；影响范围大 |
| mote:send | 无 | DataDownPayload | 本地单播下行 |
| mote:queue:len | id：8 位 DevAddr | 无 | 返回 data.len；这里 id 不是 DevEUI |
| mote:rx2 | 无 | 无 | 查询默认 RX2 的 bw、freq、sf |
Mote 对象的常用字段如下。入网方式、密钥和会话必须与实际终端匹配。
| 字段 | 类型 | 含义 |
|---|---|---|
| name | string | 显示名称 |
| isOtaa | bool | OTAA 或 ABP |
| devEUI | HEX string | 完整本地 DevEUI |
| devAddr | HEX string | ABP 短地址 |
| appKey | HEX string | OTAA 根密钥 |
| appSKey / nwkSKey | HEX string | ABP 会话密钥 |
| class | string | 接收 Class |
| fCntUp / fCntDown | uint32 | 会话计数器 |
| interval | uint32 | 网关在线判断用的预期上报间隔，不会修改终端发包周期 |
| rx1DelayMs / rx2DelayMs | uint32 | 数据接收窗口延时 |
| joinRx1DelayMs / joinRx2DelayMs | uint32 | 入网接收窗口延时 |
网关本地组播命令
| command | environment | body（编码前） | 用途 |
|---|---|---|---|
| group:add / group:update | 无 | MoteGroup 对象 | 创建/更新本地组 |
| group:get | addr：组播地址 | 无 | 查询组 |
| group:list | search、limit、offset | 无 | 查询组列表 |
| group:delete | addr：组播地址 | 无 | 删除组 |
| group:add:mote | addr、search、alive、allCheck、filterGroup | DevEUI 数组 | 添加指定或按筛选选定的成员；allCheck 使用字符串 true/false |
| group:remove:mote | eui：DevEUI | 无 | 移除终端的组关联 |
| group:remove:all:mote | addr：组播地址 | 无 | 移除该组所有成员 |
| group:send | 无 | DataDownPayload | 网关直接处理本地组播发送；不属于 Application MQTT |
MoteGroup 主要字段为 groupName、groupAddr、groupAppSKey、groupNwkSKey、fCntDown。组播地址/密钥必须同步到现场成员，更新服务器或网关列表不会自动写入终端。
私有单播/组播下行体
DataDownPayload 外层为 app 对象。单播填写 app.moteeui；组播填写 app.groupAddr，且不能同时填写 moteeui。app.userdata.port 为业务端口，app.userdata.payload 为应用字节的 Base64。其他可选字段包括 token、freq、sf、bandwidth，只有清楚实际接收配置时才指定。
从服务器 API 转发这些命令
也可以使用 AlinkwiseService/ExecuteGatewayRemoteCommand：填写 gateway_id、command、environment_json 和 body_json。此处 body_json 是普通 JSON 字符串，服务器会再编码为 MQTT 外层 body；调用方不要提前重复做 Base64。
服务器使用白名单。当前允许上述多数查询与增删操作及 mote:send，但不允许 group:send，也不允许 mote:timing:update。直接网关 MQTT 与服务器转发支持范围不同；不在白名单的命令会报 Unsupported gateway remote terminal command。服务器自身组播仍使用 MulticastGroupService/Enqueue。
本节私有协议结构已按网关与服务器实现核对；本次只实测了服务器远程信息/配置读取，没有向 Edge 实机执行批量删除、组播或下行。
Edge 私有业务数据订阅
网关本地网络服务的原生上行为 /gateway/{gatewayId}/up，原生下行为 /gateway/{gatewayId}/down，注意开头斜杠。业务上行包含 app.moteeui、app.userdata.port / payload、motetx 和 gwrx；payload 为 Base64 应用负载。原生 motetx.freq 单位为 MHz，不能与服务器接口的 Hz 直接混用。
可选兼容主题为 application/0/device/{DevEUI}/rx 和 /tx，仅在网关 compatOpen 启用时生效；不能将它与服务器 application/{UUID}/device/.../event/up 混写。原生私有主题、兼容主题、管理 up/mote 的方向和内容各不相同。完整网关业务字段见 Edge MQTT 数据接口。