Dragino PB01 LoRaWAN 按钮对接文档
模型清单
可使用下列名称或 ID 在 ThinkLink 中搜索对应模型。
| 模型类型 | 名称 | id_name | 平台模型 ID |
|---|---|---|---|
| RPC | [PB01 GET] 21312 | pb01_get_21312 | 134020096518418432 |
| RPC | [PB01 SET] 21312 | pb01_set_21312 | 134020095729889280 |
| Template | PB01 | PB01_21312 | 134020093183946752 |
| Thing Model | [PB01] | pb01_21312 | 134020094186385408 |
| Parameter Thing Model | [PB01-PARA] | pb01_para_21312 | 134020094945554432 |
1. 设备简介
PB01 是 Dragino 的原生 LoRaWAN Class A 无线按钮，使用两节 AAA 电池供电。设备按键时立即上报按钮事件，并按周期上报电池电压、声音开关状态、温度和湿度。设备内置蜂鸣器，可远程设置按键音、服务器 ACK 音、按键防误触时长和提示音类型。
本项目只对接 LoRaWAN 版本，不包含 NB-IoT，也不使用 EdgeBus 或外接 DTU。
| 项目 | 值 |
|---|---|
| 项目名称 | DRAGINO-21312-PB01 |
| 业务编码 | 21312 |
| 厂商 / 型号 | Dragino / PB01 |
| 租户 | PUBLIC |
| 通信方式 | LoRaWAN 1.0.3, Class A |
| 默认区域 | CN470，部署时必须与设备频段一致 |
| 默认上报周期 | 1200 s |
| 默认下行 FPort | 2，可通过模板共享属性调整 |
2. 适用场景
- 物业、园区和公共区域的一键求助或人工事件上报。
- 仓储、设备间和作业节点的异常标记。
- 养老与无障碍场景的非医疗级辅助呼叫。
- 需要同时观察按钮事件和环境温湿度的低功耗场景。
按钮事件不能替代生命安全系统或医疗报警设备。部署方应结合现场流程配置通知、工单或告警策略。
3. LoRaWAN 上行协议
3.1 FPort 2 实时数据
FPort 2 为固定 8 字节：
| 字节位置 | 字段 | 编码 | 换算 |
|---|---|---|---|
| 0–1 | battery | uint16BE | mV ÷ 1000 = V |
| 2 bit0 | button_sound | bit | 1=开启，0=关闭 |
| 2 bit1 | ack_sound | bit | 1=开启，0=关闭 |
| 3 bit0 | button_alarm | bit | 1=按键触发，0=周期上报 |
| 4–5 | temperature | int16BE | ÷ 10 ℃ |
| 6–7 | humidity | uint16BE | ÷ 10 %RH |
官方样例：
FPort: 2
Payload: 0C EA 03 01 01 11 02 A8
Result: battery=3.306 V, button_sound=1, ack_sound=1,
button_alarm=1, temperature=27.3 ℃, humidity=68.0 %RH解析器还会从首个网关接收信息中提取 rssi 和 snr。空载荷、非 FPort 2 或非 8 字节载荷不会产生实时遥测。
声音位采用 PB01 最新设备手册定义：
button_sound=bit0、ack_sound=bit1。Dragino 旧版官方解码文件中的字段名称与手册相反，本项目以设备手册为准。
3.2 FPort 5 设备状态
下发状态读取命令后，设备通过 FPort 5 返回固定 7 字节：
| 字节位置 | 字段 | 编码 / 说明 |
|---|---|---|
| 0 | sensor_model | PB01 固定 0x35 |
| 1–2 | firmware_version | 版本号 nibbles |
| 3 | frequency_band | 频段枚举 |
| 4 | sub_band | 子频段；0xFF 表示不适用 |
| 5–6 | status_battery | uint16BE，mV ÷ 1000 |
示例：
FPort: 5
Payload: 35 01 00 0B FF 0C DE
Result: sensor_model=PB01, firmware_version=1.0.0,
frequency_band=CN470, sub_band=N/A, status_battery=3.294 V参数模型还会把 FPort 2 中的 button_sound 和 ack_sound 同步为共享属性。FPort 5 长度错误或型号字节不是 0x35 时会拒绝该帧。
3.3 未纳入的 FPort
PB01 的 FPort 3 用于历史补传，每条记录为 11 字节。本次按最常用日常能力对接，没有建立历史记录模型；需要离线补传展示时应单独扩展，避免与实时遥测混合。
4. 遥测字段
| 字段 | 类型 | 单位 | 说明 |
|---|---|---|---|
battery | number | V | 实时电池电压 |
button_sound | number | — | 按键音状态，0/1 |
ack_sound | number | — | ACK 音状态，0/1 |
button_alarm | number | — | 按钮触发状态，0/1 |
temperature | number | ℃ | 有符号环境温度 |
humidity | number | %RH | 环境相对湿度 |
rssi | number | dBm | 首个接收网关 RSSI |
snr | number | dB | 首个接收网关 SNR |
状态模型展示 sensor_model、firmware_version、frequency_band、sub_band 和 status_battery。
5. RPC
5.1 常用设置
pb01_set_21312 使用 setting 选项，每次只发送一种设置。Class A 设备通常只能在上行后的接收窗口接收下行，不建议在一次操作中连续排队多条配置。
| 设置项 | 参数 | 范围 | 下行载荷 |
|---|---|---|---|
| 上报周期 | period_up | 1–16777215 s | 01 + uint24BE |
| 声音开关 | button_sound, ack_sound | 各 0–1 | A1 BB AA |
| 按键防误触时长 | button_press_duration | 0–1000 ms | A2 + uint16BE |
| 提示音类型 | buzzer_music_type | 0–4 | A3 MM |
示例：
period_up=300 -> 01 00 01 2C
button_sound=0, ack_sound=1 -> A1 00 01
button_press_duration=1000 -> A2 03 E8
buzzer_music_type=3 -> A3 03协议没有为这些设置定义统一的即时回显，因此 RPC 成功仅代表平台已构造并提交下行，不能单独证明设备已经应用设置。声音状态可在后续 FPort 2 上行中核对。
5.2 读取设备状态
pb01_get_21312 固定发送：
26 01设备在后续 FPort 5 上行中返回固件、频段、子频段和电池信息。
6. 模板部署
在 PUBLIC 模型中选择：
- 模板：
PB01 - id_name：
PB01_21312 - 模板 ID：
134020093183946752
部署前核对以下项目：
standard必须与设备固件频段和 LoRaWAN 网络一致；模板默认 CN470。- 使用设备标签上的 DevEUI、JoinEUI/AppEUI 和 AppKey 注册 OTAA 设备，密钥不得写入项目文件。
downlink_port默认 2；若网络服务器或固件约定不同，可改为 1–223。- 确认设备已经入网并产生上行后，再执行 Class A 下行。
- 首次部署建议执行一次“读取设备状态”，核对返回的频段与固件版本。
模板默认共享属性：
| 属性 | 默认值 |
|---|---|
class_mode | ClassA |
standard | CN470 |
period_up | 1200 s |
downlink_port | 2 |
button_sound | 1 |
ack_sound | 1 |
button_press_duration | 0 ms |
buzzer_music_type | 3 |
7. 测试与故障排查
本地协议测试入口为 test/pb01.test.mjs，覆盖：
- 官方 FPort 2 样例和负温度解析。
- 声音位定义、错误端口和错误长度。
- FPort 5 状态帧及型号校验。
- 四类 SET 下行的精确字节。
- GET 状态命令
2601。 - 模型、RPC、模板引用和公共索引。
现场无数据时依次检查 DevEUI/JoinEUI/AppKey、区域频段、网关覆盖和上行 FPort。下行未生效时，先等待下一次设备上行，确认 Class A 接收窗口、下行 FPort 和网络服务器队列，再通过后续上行或状态帧核对结果。
8. 参考资料
- Dragino PB01 产品页：https://www.dragino.com/products/lorawan-nb-iot-door-sensor-water-leak/item/333-pb01-lorawan-button.html
- Dragino PB01 在线手册：https://wiki.dragino.com/docs/LoRaWAN-End-Node/trackers-buttons-beacons/pb01/
- Dragino PB01 官方解码器：https://github.com/dragino/dragino-end-node-decoder/tree/main/PB01