sim-dashboard 中的设备绑定¶

设备绑定是将模拟电子墨水屏设备关联到你的 Inklet 用户账户的过程。绑定后，你可以向设备发送命令并在仪表盘中查看其显示输出。

绑定方式¶

设备配对现在只支持 NFC 绑定。sim-hw 在启动时将 NFC v2 URI 载荷写入数据目录，模拟物理设备的 NFC 标签。

配对码已下线

旧的 6 位配对码方式（claim code）及 POST /api/devices/bind/code 接口已于 NFC v2 版本下线，永久返回 410 Gone。sim-dashboard 不再提供配对码绑定入口。

NFC 载荷绑定¶

sim-hw 启动时将 NFC v2 URI 载荷写入 {data-dir}/nfc-payload：

inklet://bind?v=2&kid=<keyId>&hw=<hwId>&cv=<credentialVersion>&p=<proof>

工作原理：

sim-hw 启动时生成 NFC v2 载荷，写入 {data-dir}/nfc-payload
你从文件中复制该 URI 字符串
在 sim-dashboard 的绑定对话框中粘贴
后端验证 proof 并将设备绑定到你的账户

分步绑定指南¶

第 1 步：启动 sim-hw¶

在单独的终端中启动模拟设备：

python -m eink_hw --data-dir devices/kitchen

启动时，sim-hw 将：

注册到 AWS IoT Core（首次运行时进行配网）
向后端发送心跳，后端据此创建设备记录
生成 NFC v2 载荷并写入 devices/kitchen/nfc-payload
将帧缓冲推送到 sim-dashboard

你应看到如下日志输出：

INFO  Connected as inklet-a1b2c3d4
INFO  Sending heartbeat...
INFO  NFC v2 payload written to devices/kitchen/nfc-payload
INFO  Framebuffer pushed to sim-dashboard

第 2 步：读取 NFC 载荷¶

cat devices/kitchen/nfc-payload
# inklet://bind?v=2&kid=k1&hw=a1b2c3d4e5f60708090a0b0c0d0e0f10&cv=1&p=AAAAAAAAAAAAAAAA

第 3 步：绑定设备¶

在 sim-dashboard 中（已登录 http://localhost:5173）：

点击仪表盘右上方区域的 "Bind Device" 按钮
在弹出对话框中选择 NFC Payload 标签
粘贴完整的 URI 字符串（例如 inklet://bind?v=2&kid=...）
点击 Bind

第 4 步：设备出现在仪表盘中¶

绑定成功后：

后端通过 MQTT 向设备发送 bound 命令
sim-hw 在显示屏上渲染"Device bound successfully"
设备出现在你的仪表盘中，带有实时电子墨水屏预览
设备现在可以接收 text 命令

第 5 步：发送命令¶

设备绑定后，你可以向其发送文本：

从仪表盘从 API

点击设备卡片打开详情视图。使用文本输入框向设备发送内容。

curl -X POST http://localhost:4000/api/devices/{id}/cmd \
  -H "Authorization: Bearer {accessToken}" \
  -H "Content-Type: application/json" \
  -d '{"kind": "text", "text": "Hello from the API!"}'

文本将以逼真的刷新动画渲染到模拟电子墨水屏上。

解绑设备¶

要解绑设备：

从仪表盘从 API

点击已绑定的设备打开详情视图
点击 "Unbind" 按钮
确认操作

curl -X POST http://localhost:4000/api/devices/{id}/unbind \
  -H "Authorization: Bearer {accessToken}"

解绑后发生的事情：

后端通过 MQTT 向设备发送 unbound 命令
sim-hw 接收命令并清除显示内容
设备从你的仪表盘绑定设备列表中消失
设备可以通过新的 NFC 扫描重新绑定（NFC 载荷文件不变，cv 不变时 proof 仍有效）

设备继续运行

解绑不会停止模拟设备。sim-hw 继续运行，发送心跳。你可以随时通过 NFC 载荷重新绑定。

绑定生命周期图¶

sim-hw starts
    │
    ├── Heartbeat → Backend creates device record
    │
    ├── NFC payload written to nfc-payload file
    │
    │              User reads nfc-payload and pastes in sim-dashboard
    │                          │
    │              POST /api/devices/bind/nfc (NFC v2)
    │                          │
    │              Backend verifies proof → binds device
    │                          │
    ├── bound received → Display shows "Bound successfully"
    │
    │              Device appears in dashboard
    │              User sends text commands
    │                          │
    ├── text received → Display renders content
    │
    │              User clicks "Unbind"
    │                          │
    │              POST /api/devices/{id}/unbind
    │                          │
    └── unbound received → Display clears

故障排除¶

绑定时出现"Device not found"错误¶

设备必须在绑定前至少发送过一次心跳。启动 sim-hw 后等待几秒再试。
确认该设备已在工厂控制台（factory-console）完成注册，并且已生成 NFC 凭证文件。

绑定时出现"Invalid NFC credential"错误¶

确认粘贴的是完整的 inklet://bind?... URI，没有截断。
确认 sim-hw 使用的 NFC_MASTER_KEYS 与后端配置一致。
如果设备凭证已被吊销并重发，NFC 载荷文件会随之更新，请重新读取。

出现"Device already bound"错误¶

设备已绑定到另一个用户账户。请先解绑，或使用拥有该设备的账户登录。

绑定后显示不更新¶

在浏览器开发者工具中检查 WebSocket 连接
确认 Fastify 服务器正在接收来自 sim-hw 的帧缓冲 POST 请求
尝试刷新页面