feat: integrate NFC infrared peripherals and orchestration

2026-08-25 11:45:45 +08:00
parent 9ac8fdface
commit 2529b4896a
19 changed files with 3818 additions and 117 deletions
@@ -43,8 +43,36 @@ make dev-lan

 自扩展接口统一位于 `/api/extension/*`，GSCU1B 默认以 TCP 模式监听
 `0.0.0.0:4444`。可通过 `GSCU_TRANSPORT=simulation` 使用演示学习器，或通过
-`GSCU_TRANSPORT=mqtt` 与 `GSCU_MQTT_*` 配置接入 MQTT。MQTT 依赖可通过
-项目的 `ir` 可选依赖安装。自扩展不再需要独立的 `8010` 前端服务。
+`GSCU_TRANSPORT=mqtt` 与 `GSCU_MQTT_*` 配置接入 MQTT。MQTT 依赖已包含在
+核心环境中；NFC 串口依赖通过 `ir` 可选依赖安装。自扩展不再需要独立的
+`8010` 前端服务。
+
+## NFC 玩具识别与红外学习
+
+统一页面的“外设与扩展能力”区域提供“感应玩具 NFC”入口。点击后将玩具上的
+NFC 卡片靠近 PCR532/PN532（CH340/CH341 串口）读卡器：新卡可建立或绑定
+玩具档案，并立即进入现有 GSCU1B 红外学习流程；已绑定卡片会自动识别玩具，
+展示全部已学习/待学习动作，并可直接发射已验证动作。
+
+安装串口支持并启动：
+
+```bash
+python -m pip install -e ".[ir]"
+make dev
+```
+
+服务会优先复用本机 `ir-toy-learning` 的 MQTT NFC 桥（默认
+`127.0.0.1:1883`），避免两个进程同时抢占同一个 `COM` 口；桥不可用时再自动选择
+唯一的 CH340/CH341、PN532 或 PCR532 串口。可通过 `NFC_PORT=COM5` 指定串口，
+或用 `NFC_MQTT_HOST`、`NFC_MQTT_PORT` 调整桥地址；`NFC_MQTT_DISABLED=true`
+强制只使用串口，`NFC_DISABLED=true` 可完全禁用读卡线程。
+
+首次加载时页面会从 `http://localhost:3001/n7web-profile-bridge.html` 安全迁移旧
+`ir-toy-learning` 浏览器档案，保留工牌 UID、玩具编号、动作名称和 GSCU1B 槽位。
+不同浏览器运行时，旧工作台会把不含红外原始波形的档案元数据同步到本机 MQTT
+保留主题 `toy/ir/profiles`，当前服务同样会自动导入。迁移按档案与槽位幂等合并，
+不会覆盖当前工程中已经建立的能力。NFC UID 与玩具档案的绑定保存在当前浏览器，
+红外波形仍保存在 GSCU1B 的 1–248 号物理槽位。

 TCP 模式下本服务是服务器，GSCU1B 是客户端：设备配网页中的“TCP服务器”
 必须填写运行本服务的主机地址，“TCP端口”必须与 `GSCU_TCP_PORT` 一致。