设备使用指南

切换深色模式

API 接入示例与联调 ​

本章把“字段是什么”连成可执行的接入顺序。示例 EUI、地址、域名、密钥和数据均为虚构；先替换为项目参数。本章构造样例没有直接发送到现场；使用真实参数完成的 G4 界面操作另见实机视频。 MQTT 示例需要电脑安装 Mosquitto 客户端；Python 示例仅使用 Python 3 标准库。

先选正确的数据路径 ​

流程图加载中…

Std 的无线帧应先到外部 NS，本章 Edge 应用载荷样例不投递到 Std 的 command/down。管理 REST 与管理 MQTT 是维护接口，也不替代业务输出。

MQTT：先订阅，再等待真实上报 ​

在 Edge 勾选业务 MQTT 并保存后，电脑使用有权限的账号订阅同一个 Broker。以下无认证示例仅用于允许匿名访问的受控测试 Broker；生产环境按服务方提供的客户端配置加入认证/TLS，不把密码写入公共脚本。

sh
mosquitto_sub -h BROKER_HOST -p 1883 \
  -t '/gateway/1122334455667788/up' -v

1122334455667788 替换为网关 EUI，保持开头斜杠。然后让一个已登记终端上报；应看到主题和 app JSON。没数据时，先在本机终端实时页看是否有同一上行。需要兼容主题时，先确认 compatOpen 已启用，不能仅更换订阅主题。

验证 Base64 与应用字节 ​

sh
python3 - <<'PY'
import base64
raw = bytes.fromhex('01 02 03')
encoded = base64.b64encode(raw).decode('ascii')
print(encoded)                         # AQID
print(base64.b64decode(encoded, validate=True).hex(' '))  # 01 02 03
PY

这段只在电脑本地转换，不连接网关。真实数据按 FPort/型号协议解释；文本 010203、HEX 字节 01 02 03 与 Base64 AQID 是不同表示。

需要下行时再发布 ​

先按目标终端协议准备允许发送的应用字节和 FPort，再生成 JSON 文件。可下载原生单播 JSON 样例查看结构；示例 01 02 03 不是实际控制命令，替换前不要向运行设备发布。

sh
mosquitto_pub -h BROKER_HOST -p 1883 \
  -t '/gateway/1122334455667788/down' \
  -f verified-downlink.json

verified-downlink.json 是你已按终端协议核对的文件。不要加 retain；Class A 等下一次上行，Class C 也需正确接收参数。发布返回成功后，仍需检查网关记录和终端回复。

本地 HTTP 接收示例 ​

下载 Python 接收程序，在网关能访问的测试电脑运行：

sh
python3 http_receiver.py --bind 0.0.0.0 --port 8088

只在受控测试网络使用；示例无认证、无 TLS、无持久化。将 Edge 的 HTTP URL 填为 http://电脑局域网IP:8088/uplink，允许对应入站端口。这里的地址不是网关管理 IP，也不是电脑回环地址。

  1. 点 HTTP 测试，接收程序应打印 test-empty-object 并返回 200。
  2. 保存并重新连接后，让真实终端上报，程序应打印 native-uplink 或 compat-uplink、EUI、FPort 和解码后的 HEX。
  3. 非法 JSON 返回 400，未知路径返回 404，载荷格式不正确返回 400；检查日志修正后再测。
  4. 正式服务将处理结果写入业务系统，并自行设计鉴权、持久化、去重和错误处理，不能把这个演示接收器直接当生产服务。

原生 JSON 使用 app.userdata.payload，兼容 JSON 使用 data。若测试通过但业务失败，先看收到的完整 JSON 与程序错误，不能继续用空测试体证明业务接入成功。

管理 REST：登录与只读查询 ​

先设置你自己的登录 JSON，示例不内置账户：

sh
export GATEWAY_BASE='http://GATEWAY_IP'
# 替换下列占位符为你自己的网页账户；不要公开真实值。
export GATEWAY_LOGIN_JSON='{"username":"YOUR_ACCOUNT","password":"YOUR_PASSWORD"}'
curl --silent --show-error -c gateway.cookies \
  -H 'Content-Type: application/json' \
  --data "$GATEWAY_LOGIN_JSON" "$GATEWAY_BASE/api/user/login"
curl --silent --show-error -b gateway.cookies \
  "$GATEWAY_BASE/api/gateway/info"
curl --silent --show-error -b gateway.cookies \
  "$GATEWAY_BASE/api/gateway/config/get"

先检查登录 code=0 和 data.mode。Cookie 文件及配置响应含敏感信息，不放到说明书或公共仓库。网关重启后重新登录；如果响应为 HTML 或登录页，先检查地址、认证与软件版本。

Edge 分页与 RX2 ​

sh
curl --silent --show-error -b gateway.cookies --get \
  --data-urlencode 'search=example' --data-urlencode 'limit=10' \
  --data-urlencode 'offset=0' --data-urlencode 'alive=false' \
  "$GATEWAY_BASE/api/mote/list"
curl --silent --show-error -b gateway.cookies \
  "$GATEWAY_BASE/api/mote/rx2"

本机 Std 没有这些终端接口。RX2 返回 freq 为 MHz、sf 为下拉索引；单位转换表给出与原生下行 Hz/SF 的对应关系。

添加、更新与发送的调用合同 ​

动作方法 / 目标JSON 请求体返回后的核对
添加终端POST /api/mote/add终端对象code=0 后查列表及实际上报
批量添加POST /api/mote/add/batch同结构的对象数组检查条数、EUI/地址重复及每台入网
更新终端PUT /api/mote/update读取并修改的完整对象保留数字 ID 和会话配置；计数由服务器保留，重新查询确认
单播下发POST /api/mote/send与原生 MQTT 下行相同的 app 对象查队列、无线记录、终端回复
创建组播POST /api/group/add组对象查组记录，再配置终端组参数
组播下发POST /api/group/sendapp.groupAddr、userdata；不带 moteeui逐项核实终端实际结果
保存网关PUT /api/gateway/config/setconfig/get 响应中的完整 data.gc会重启；重连后回读和业务验收

这些调用会改变设备，不在本章只读步骤中自动执行。不能把一个“返回 0”的离线响应当作真实设备验证。

管理 MQTT：请求、ACK、结果分开 ​

  1. 使用远程管理 Broker，先订阅 gateway/{EUI}/event/ack 和对应结果主题。
  2. 构造 getInfo 请求，gatewayID 用 EUI 原始 8 字节的 Base64。
  3. 发布到 gateway/{EUI}/command/exec，不要加业务接口开头的斜杠。
  4. 收到 ACK 后核对 items[0].status；1 仅代表 JSON 解包通过。继续等 up/info 的同 token 结果。
  5. 将结果 stdout Base64 解码，再按对应 JSON 处理。

可以下载只读 getInfo 命令；token=1001 为教学关联号。不要把查询示例改成 reboot/config 后直接试发。

json
{
  "gatewayID": "ESIzRFVmd4g=",
  "token": 1001,
  "items": [{"status": 1}]
}

上面是构造的 ACK 结构示例，不是设备执行结果。管理 API 的 code、管理 MQTT 的 ACK status、Std 的 TX_ACK 和终端实际动作分属不同层次，不能互相替代。

RS485：先验证帧再接主站 ​

下载本地编码校验工具，运行 python3 protocol_check.py，核对 Base64、MHz/SF 转换和本册 Modbus/Private 示例 CRC。程序只在本地计算，不打开串口、不发网络数据。CRC 正确只说明帧编码自洽，实际寄存器序号、终端缓存和无线下行仍按RS485 章验收。

设备使用指南

© 2026 DeviceGuide