切换深色模式
LoRaWAN UDP 网关接入
本文件说明 Semtech UDP Packet Forwarder 与服务器 Gateway Bridge 的连接。它是网关传输协议，不是普通业务 CRUD API，也不是终端应用负载的直接 UDP 入口。
能力边界
| 任务 | Semtech UDP 是否提供 | 正确入口 |
|---|---|---|
| 注册、删除、查询终端档案 | 不提供 | LoRaWAN API |
| 注册、删除、查询服务器网关档案 | 不提供资源管理接口 | GatewayService |
| 业务系统订阅解码数据/查询历史 | 不提供 | Application MQTT / API |
| 网关转发无线包、状态 | 提供 | PUSH_DATA |
| 网关保持下行通路 | 提供 | PULL_DATA |
| 网络服务器向网关发射下行 | 提供传输 | PULL_RESP / TX_ACK |
| 建组、维护组播成员、提交组播任务 | 不提供 | MulticastGroupService |
收到 UDP 包可以触发已启用的受信任自动登记逻辑，但自动登记属于服务器业务规则，不是 UDP register 接口。单播/组播由网络服务器生成有效无线帧，不能把任意应用字节放入 UDP 就替代队列。
原生包启用
在 server.toml 启用对应 UDP Profile，同时启用区域：
toml
[lorawan]
enabled_regions = ["cn470_0"]
[gateway]
udp_profiles = ["cn470_0"]检查 [gateway.udp_ports]，当前示例模板的 cn470_0 为 4700/udp。重启后用 status 和 Bridge 日志确认实际端口。旧文档常见 1700 是其他部署配置，不是所有 Profile 的统一端口。
网关配置步骤
- 先在“网关管理”添加网关，核对真实 EUI 和区域。
- 在网关中选择 Packet Forwarder / UDP 接入方式。
- Server Address 填服务器可达 IP，不能填网页 URL 或带路径地址。
- Up / Down 端口填写该 Profile 的实际端口。
- 网关射频信道与服务器区域及终端发射信道匹配。
- 保存并等待转发服务重新建立连接。
- 服务器查看该网关的新 stats 和实时数据，再让终端上报验证。
报文方向与确认层级
| 报文 | 方向 | 作用 | 不能据此证明 |
|---|---|---|---|
| PUSH_DATA | 网关 → Bridge | 无线接收帧 rxpk 或状态 stat | 业务解析成功 |
| PUSH_ACK | Bridge → 网关 | 对上送报文的传输确认 | 终端档案/会话有效 |
| PULL_DATA | 网关 → Bridge | 维持供下行使用的路径 | 已收到终端上行 |
| PULL_ACK | Bridge → 网关 | 下行通路的传输确认 | 有下行任务 |
| PULL_RESP | Bridge → 网关 | 网络服务器安排的发送内容 | 终端收到 |
| TX_ACK | 网关 → Bridge | 网关发射调度结果 | 终端业务动作成功 |
协议报文包含版本、令牌和类型；网关上送类型携带网关标识。rxpk.data / txpk.data 是 Base64 编码的完整无线物理帧，与 Application MQTT 的应用 FRMPayload data 不同，不能互换。rxpk 还携带频率、数据率、信号和硬件计时信息；下行时间戳不能用普通系统墙钟替代。
单播与组播
业务系统先调用设备队列或组播队列 API，由网络服务器进行会话、计数、加密与调度，再经 Bridge 生成 UDP 下行。组播要另外核对终端本地组播会话与接收参数；UDP TX_ACK 不是每个成员的接收确认。
诊断
只有 PULL_ACK 而无 up 时，检查终端和射频；有 rxpk 而无应用 up 时，检查会话、MIC、计数和 codec；PULL_RESP 后 TX_ACK 报错误时，检查过早/过晚调度、频率、功率与发射冲突。UDP 本身不保证可靠传输，不承诺离线补发或业务历史持久化。
Semtech UDP 本身不提供用户 token 认证；生产网络应按部署方案限制入口，或采用受控网络/支持的安全接入方式。不要将开放 UDP 端口理解为已实现设备权限管理。
协议报文定义参考 Semtech UDP Packet Forwarder 协议；本安装启用哪些 Profile、端口与区域，以本机配置为准。