# LoRaWAN 节点 NFC 配置工具 — 现场使用说明书

> 适用产品：LoRaWAN 温湿度传感器（STM32WL，墨水屏显示，集成 NFC 标签 FM11NT082C）
> 适用 App：android_nfc（Android NFC 读写工具）
> 面向对象：运维 / 现场安装人员
> 文档版本：v1.1（对应 NFC 协议 v0x03）

---

## 1. 工具简介

本 App 通过手机的 NFC 功能，对现场的 LoRaWAN 传感器进行**读取状态**与**写入配置**，无需拆机、无需串口，适合批量安装、现场调试和故障排查。

App 共 4 个页面（底部 Tab）：

| 页面 | 用途 |
|------|------|
| **首页（概览）** | 快速入口与 NFC 状态提示 |
| **读取** | 感应设备，读取 PN/SN、入网状态、凭证、运行参数、温湿度补偿等 |
| **写入** | 修改入网方式、上传周期、温度单位、温湿度补偿、信道与频段（含频段选择）；点「开始写入」时一并完成授时 |
| **设备** | 查看已扫描设备列表、导出 CSV、删除记录 |

安装前提：
- Android 手机，支持 NFC（设置中可开启）。
- 设备 NFC 标签为 FM11NT082C（设备外壳上有 NFC 标贴区域）。

---

## 2. 第一次使用前

1. 在手机「设置 → 连接与共享（或更多连接）」中打开 **NFC**。
2. 安装本 App 并打开。
3. 若 App 顶部提示「NFC 不可用」，请确认手机 NFC 已开启且本机支持。
4. 默认进入「读取」页面，可直接开始操作。

> 提示：App 在前台时会自动接管 NFC。靠近设备前，请先点击页面上的「开始扫描」或「开始写入」按钮，App 才会处理标签。

---

## 3. 读取设备状态（现场核查）

适用场景：安装前核查设备身份、确认入网与否；安装后验证上报参数。

**步骤：**
1. 在「读取」页点击 **开始扫描**（按钮变为「停止」）。
2. 将手机背部 NFC 感应区**贴近设备 NFC 标贴**（通常在设备外壳 NFC 图标处），保持稳定约 1~2 秒。
3. 读取成功后页面显示设备信息，顶部提示「读取成功：<产品型号>」。

**读取内容字段说明：**

| 分组 | 字段 | 含义 / 现场关注点 |
|------|------|-------------------|
| 设备身份 | PN | 产品型号（如 ATU-TH-7788） |
| | SN | 设备序列号（唯一，导出与去重依据） |
| 入网方式 | 激活模式 | OTAA（默认）或 ABP |
| | 凭证来源 | PHONE（手机写入）/ AUTO（设备自派生） |
| 网络状态 | 入网点位 | YES=已入网 / JOINING=入网中 / 未入网 |
| | DevAddr | 设备地址 |
| | Class | 设备类型（默认 A） |
| | FCnt | 上行帧计数 |
| 凭证区 | OTAA | DevEUI / AppEUI / AppKey |
| | ABP | DevAddr / NwkSKey / AppSKey |
| 运行参数 | DR / TXPwr / ADR / 确认 | 数据速率、发射功率、自适应速率、是否需确认 |
| | 上传周期 | 两次上报间隔（秒） |
| 高级 | 区域 / RX2频率 / RX2 DR / NetID / 信道掩码 | 频段与接收参数（CN470 默认），一般无需改动 |
| | 密钥版本 / LoRaWAN 版本 / CRC | 配置完整性校验（CRC 失败 ✗ 表示配置可能损坏） |
| 温湿度 | 温度单位 / 补偿 | ℃/℉、温度与湿度补偿值 |
| 实时状态 | RSSI / SNR / 电池电压 | 信号强度、信噪比、电池电压（mV） |
| 芯片信息 | UID / ATQA / SAK | NFC 芯片标识（产测/去重溯源用） |

**常见提示：**
- 「未识别到设备数据，请重新感应」：贴卡不稳或标签无数据，重试。
- 「读取失败：…」：标签不支持 / 解析失败，重新贴卡；若反复失败，换一台设备对照排查。
- 单次读取超时 8 秒，读卡过程请保持贴合，不要移开手机。

---

## 4. 写入 / 修改配置（现场配置）

适用场景：切换温度显示单位、设置温湿度补偿、调整上报周期、指定 ABP/OTAA 身份，以及给设备授时。

**重要原则（避免写坏设备）：**
- **App 不暴露密钥输入框**，也不允许手动填密钥。
- **未选择设备时：只改你填过的字段，其余保持设备原值**（含密钥与凭证来源，绝不清空）。
  留空的文本框 = 保留原值；未点过的选项 = 保持原值。
- **从已有设备导入时：同步所选设备的全部信息，但入网身份保持每台设备自身。**
- 写入会将整块 128 字节配置重写，但**值层面只动应改动的字段**，安全。
- **贴卡后必须先读到有效配置（CRC 校验通过）才会写入**；CRC 失败会中止并提示，绝不用默认值覆盖。
- 写入期间**保持手机贴紧设备**，直到提示「写入成功，已回读校验一致」。若提前移开，设备可能读不到配置。
- **授时（时间同步）已合并进「开始写入」**：点「开始写入」时，App 会同时把手机当前的 UTC 时间写入设备，无需再单独操作。

**步骤：**
1. 在「写入」页点击 **开始写入**：App 先自动读取贴卡设备原值作为合并基线（身份字段会显示在表单上供核对），随后执行写入，**并同时把手机当前的 UTC 时间写入设备（授时）**——无需再单独点「时间同步」。
2. 观察进度到 100% 与回读校验结果，进度下方会显示「写入成功，已回读校验一致」以及本次授时时间。

**可配置项（5 张折叠卡片）：**

① **入网方式**（三态）
- **OTAA** / **ABP** / **保持原值**。默认「保持原值」= 不改设备的入网方式。
- 身份字段（DevEUI/JoinEUI 或 DevAddr）**只读，仅用于显示与核对**，不可编辑。
- 现场一般**不要改动**，除非平台要求固定身份。

② **上传周期**
- 单位：秒；范围 **60 ~ 86400 秒**（1 分钟 ~ 24 小时）。
- 留空 = 保留原值。

③ **温度单位**
- 摄氏度（℃）/ 华氏度（℉）/ 保持原值。
- 仅影响墨水屏本地显示；LoRaWAN 上报始终为摄氏。

④ **温湿度补偿**
- 补偿值单位：0.1（如填 `-1.5` 表示 -1.5℃），范围 **-10.0 ~ +10.0**。`0` 是合法补偿值。
- 留空 = 保留原值（含「不修改」哨兵 0x8000）。
- 同时影响墨水屏显示与 LoRaWAN 上报。

⑤ **信道与频段**（默认 CN470，一般无需改动）
- **频段 (Region)**：下拉按 LoRaMacRegion_t 顺序排列（AS923 / AU915 / CN470 / CN779 / EU433 / EU868 / KR920 / IN865 / US915 / RU864）；不选 = 保留设备原值。
- **信道掩码 (channel_mask)**：12 个 chip，每个对应 8 个信道，覆盖 CN470 全部 96 个信道（信道 0–7、8–15、…、88–95）；勾选 = 启用该 8 信道子组，**可多选**；不勾选任何 chip = 保留设备原信道配置。**不允许全部取消**（等于关闭设备全部信道，App 会拒绝写入）。
- 仅当现场需要切换频段或调整信道时填写；填错会导致设备无法入网，请务必核对。
- RX2 频率 / RX2 速率 / NetID / 密钥版本等高级字段**App 不暴露**，一律保留设备原值（或从所选设备同步）；**授时时间由「开始写入」统一写入手机 UTC 时间**（旧版独立的「时间同步」按钮已合并移除）。

3. 填好后点击 **开始写入**，观察进度到 100% 与回读校验结果。
4. 写完后回到「读取」页重新感应，确认修改生效。

**入网身份字段（DevEUI / JoinEUI / DevAddr）只读：**

- 身份字段**仅用于显示与核对**，不可手动编辑，也**不会**被所选设备覆盖。
- 写入时的取值**永远来自贴卡设备自身**（两种场景皆如此），保证每台设备的 DevEUI / DevAddr 保持自身不变，杜绝串号。
- 切换入网方式仅改变显示哪组身份字段，不影响写入时的实际身份取值。
- ABP 需要 DevAddr。若设备尚未入网、配置区没有 DevAddr，App 会提示先让设备完成一次 OTAA 入网获取 DevAddr。

---

### 两种写入场景（务必区分）

#### 场景一：未选择设备 —— 只改我填过的字段

- 不点任何设备选择按钮，直接在表单上改（或什么都不改）后点「开始写入」。
- **生效范围**：入网方式、上传周期、温度单位、温湿度补偿、信道与频段，以及由「开始写入」统一完成的授时。
- **其余一律保留设备原值 —— 包括 AppKey / NwkSKey / AppSKey 和凭证来源（PHONE / AUTO）都不会被清空。**
  这一点很关键：只改温度单位，不会让已注册到平台的密钥失效。

#### 场景二：从已读取设备选择 —— 同步全部信息（身份除外）

- 在「写入」页点击 **从已读取设备选择**，选一台后，其**入网方式、上传周期、温度单位、温湿度补偿、信道与频段，以及 DR / 发射功率 / ADR / 确认 / RX2 / NetID 等全部运行参数**都会同步过来。
- **身份（DevEUI / JoinEUI / DevAddr）保持贴卡设备自身**，不会复制所选设备。
- 顶部会出现「已同步 XXX」提示条，点 **×** 可清除同步、回到场景一。
- 适用于「把一台已配好设备的参数批量复制到其它同型号设备」。
- **ABP 特别注意**：NwkSKey / AppSKey 与 DevAddr 一一绑定。由于 DevAddr 保持贴卡设备自身，会话密钥也必须保持其自身，因此**不会**复制所选设备的 ABP 会话密钥（App 会给出提示）。若确需整机克隆 ABP 凭证，请在平台侧重新分配并注册。

| 维度 | 场景一（未选择设备） | 场景二（从已读取设备选择） |
|------|------------------|----------------------|
| 入口 | 直接点「开始写入」 | 「从已读取设备选择」→ 选设备 →「开始写入」 |
| 身份 (DevEUI/DevAddr) | 贴卡设备自身 | 贴卡设备自身 |
| 未手填的运行参数 | 保留贴卡设备原值 | 同步所选设备 |
| 密钥 / 凭证来源 | **保留原值，不清空** | OTAA 复用 AppKey；ABP 保持自身 |
| 是否需要同步来源 | 否 | 是（顶部提示条，可 × 清除） |

> 注：旧版的「直接用所选设备写入」（场景三）入口已移除。源设备 AppKey 复用需求可改用「从已读取设备选择 → 开始写入」完成（身份仍保持贴卡设备自身）。

---

## 5. 设备列表与导出（批量注册）

每次成功读取会自动保存一条设备快照（按 SN 更新）。

在「设备」页可以：
- 查看已扫描设备（品牌/SN/入网方式/凭证/芯片信息/读取时间）。
- **多选**后点击 **导出 CSV**：生成 `LoRaWAN_Devices_<时间>.csv`，保存到手机「Download」目录，含 `品牌,SN,入网方式,APP_KEY,DevEUI,AppEUI,DevAddr,芯片信息,读取时间`，UTF-8 BOM 可被 Excel 直接打开。
- **删除选中** / **清空全部** 本地记录。

> 导出用途：将 OTAA（DevEUI+AppEUI+AppKey）或 ABP（DevAddr+NwkSKey+AppSKey）清单提交后台，批量注册到 LoRaWAN 平台。DevAddr 可能重复，需后台去重后再注册（详见第 7 节）。

---

## 6. 现场常见问题排查

| 现象 | 可能原因 | 处理 |
|------|----------|------|
| 提示「NFC 不可用」 | 手机无 NFC 或系统未授权 | 换支持 NFC 的手机；确认系统 NFC 已开 |
| 点击扫描后贴卡无反应 | 未先点「开始扫描/写入」；或手机 NFC 关了 | 先点按钮；确认 NFC 开启；对准感应区 |
| 读取失败 / 反复重试 | 贴卡不稳、标签坏、超时 | 保持贴合 1~2 秒；换位置；重试 |
| 写入后参数没变 | 写入时贴卡过早移开；字段留空被视为保留 | 重新写入并保持贴合到成功；确认填了要改的值 |
| CRC 显示「失败 ✗」 | 配置可能损坏 | 重新读取；确认贴稳后若仍失败，联系厂商处理（App 会**拒绝**对 CRC 失败的设备写入，避免覆盖） |
| 写入被中止，提示「CRC 校验失败」 | 贴卡设备配置区读取不完整 | 回到「读取」页重新贴卡确认；保持贴合 1~2 秒后再写入 |
| 写入被中止，提示「贴卡设备无有效身份」 | 空标签或该设备从未被读取过 | 先到「读取」页贴一次该设备，再回来写入 |
| 想改 ABP 却提示「尚无 DevAddr」 | 设备尚未入网，配置区没有 DevAddr | 先让设备完成一次 OTAA 入网获取 DevAddr，再切 ABP |
| 提示「信道掩码不能全为 0」 | 勾过信道组后又全部取消 | 至少勾选一个信道组；或点顶部提示条的 × 清除同步，不勾选任何组即保留原值 |
| 导出的 CSV 在 Excel 中文乱码 | 未识别 UTF-8 | 用「数据→从文本」导入并选 UTF-8，或用 WPS 打开 |
| 入网点位长期 JOINING / 未入网 | 平台未注册该设备凭证，或频段不匹配 | 确认已按导出清单在平台注册；确认区域为 CN470 |
| 选了频段后读取页显示的频段不符 | 旧版本 App 的频段下拉顺序与协议枚举错位 | 升级到本版本（下拉已按 AS923 / AU915 / CN470 … 正确排序） |

---

## 7. 运维须知（平台注册与去重）

- 设备出厂默认 **AUTO 自派生**凭证，现场读取即可拿到 DevEUI/AppKey（OTAA）或 DevAddr/会话密钥（ABP），用于平台注册。
- **DevAddr 32 位空间有限，批量设备可能碰撞**。注册流程：
  1. 用本 App 逐台读取并导出 CSV；
  2. 后台汇总，**扫描 DevAddr 重复**；
  3. 重复的设备在平台侧重新分配 DevAddr，并通过 NFC 写回（cred_source=PHONE）后再注册。
- DevEUI / AppKey 空间极大，**无需去重**，放心批量注册。
- 区域默认 **CN470**，与国内平台一致；其它区域需固件支持，App 侧不改。

---

## 8. 安全与注意事项

- NFC 标签内密钥为明文可读（任何 NFC 读卡器贴近即可读），属已接受的设计假设；现场请勿将设备交由不可信第三方贴卡读取。
- 量产设备已开启 STM32WL 读保护（RDP），调试口无法读出 Flash 密钥。
- 写入以 CRC16 校验，校验失败设备会**拒绝更新并保留旧配置**，不会写坏失联。
- 温湿度补偿为**全链路一致**（显示+上报同时叠加），设置后请结合实际标准器复核读数。
- 授时以手机系统 UTC 时间为准；若手机系统时间异常（不在 2020~2100 范围），App 会中止授时并提示先校正手机时间。

---

## 9. 术语速查

| 术语 | 说明 |
|------|------|
| OTAA | 空中激活，需 DevEUI+AppEUI+AppKey 向网络服务器入网 |
| ABP | 个性化激活，直接写入 DevAddr+会话密钥，无入网过程 |
| PN / SN | 产品型号 / 序列号 |
| DevAddr | 设备短地址（32 位，需去重） |
| AppKey / NwkSKey / AppSKey | OTAA 根密钥 / ABP 网络会话密钥 / ABP 应用会话密钥 |
| CRC | 配置完整性校验和，失败表示配置可能损坏 |
| CN470 | 中国 470MHz 频段（默认） |
| 补偿哨兵 0x8000 | 「不修改」标志，App 中表现为补偿框留空 |
| 授时 | 将手机当前 UTC 时间写入设备，已并入「开始写入」动作 |

---

## 10. 网页功能演示（网站展示用）

为在官网上向客户展示 App 功能，仓库内含一个**纯前端、零依赖**的演示页面：`web_demo/index.html`。

- 用手机外框还原 App 四个 Tab（首页 / 读取 / 写入 / 设备），所有按钮均可点击操作。
- 「读取」模拟 NFC 读卡并展示完整字段；「写入」模拟贴卡，并**按 NFC 协议真实组包、计算 CRC16**，完成后弹出 128 字节十六进制 dump 与关键字段摘要；「设备」支持多选、删除、导出 CSV。
- 时间同步已合并进「开始写入」（写入结果会显示授时时间），与 App 当前行为一致。
- 无真实硬件，NFC 读写为模拟流程，仅用于界面与交互展示；直接用浏览器打开该文件即可。

---

*—— 现场使用说明结束 ——*