sim-dashboard 中的设备绑定¶

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

绑定方式¶

有两种方式绑定设备：

方式一：配对码¶

配对码方式使用设备电子墨水屏上显示的 6 位字母数字码。

工作原理：

未绑定的设备启动时，向后端请求配对码
后端生成一个配对码（例如 A3X9K2）并发送给设备
设备将配对码渲染到电子墨水屏上
你在 sim-dashboard 中输入该码，将设备绑定到你的账户

方式二：NFC 载荷¶

NFC 载荷方式使用 sim-hw 生成的经 HMAC 签名的硬件标识符。

工作原理：

sim-hw 启动时将 NFC 载荷写入 {data-dir}/nfc-payload
载荷格式为 inklet:1:{hwId}:{signature}
你在 sim-dashboard 的绑定对话框中粘贴该字符串
后端验证 HMAC 签名并绑定设备

该选哪种方式？

日常使用模拟器时，配对码方式更简单，因为配对码直接显示在模拟屏幕上。NFC 载荷方式适用于专门测试 NFC 绑定流程或自动化测试脚本。

分步绑定指南¶

第 1 步：启动 sim-hw¶

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

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

启动时，sim-hw 将：

注册到 AWS IoT Core（首次运行时进行配网）
向后端发送心跳，后端据此创建设备记录
向后端请求配对码
将配对码渲染到模拟电子墨水屏上
将帧缓冲推送到 sim-dashboard

你应看到如下日志输出：

INFO  Connected as inklet-a1b2c3d4
INFO  Sending heartbeat...
INFO  Received claim_code command: A3X9K2
INFO  Rendering claim code to display...
INFO  Framebuffer pushed to sim-dashboard

第 2 步：查看配对码¶

配对码可在两处查看：

sim-dashboard 显示 --- 如果你正在查看设备的公开 URL（/device/{hwid}），配对码会渲染在模拟电子墨水屏上
sim-hw 日志 --- 配对码会打印在终端输出中

第 3 步：绑定设备¶

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

点击仪表盘右上方区域的 "Bind Device" 按钮
弹出对话框包含两个标签页：Claim Code 和 NFC Payload

使用配对码使用 NFC 载荷

选择 Claim Code 标签页
输入设备屏幕上的 6 位配对码（例如 A3X9K2）
点击 Bind

选择 NFC Payload 标签页
从 sim-hw 数据目录读取载荷：
```
cat devices/kitchen/nfc-payload
```
粘贴完整的载荷字符串（例如 inklet:1:a1b2c3d4-...:3f7a8b2c1d9e0f4a）
点击 Bind

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

绑定成功后：

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

第 5 步：发送命令¶

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

从仪表盘从 API

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

curl -X POST http://localhost:4000/api/devices/inklet-a1b2c3d4/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/inklet-a1b2c3d4/unbind \
  -H "Authorization: Bearer {accessToken}"

解绑后发生的事情：

后端通过 MQTT 向设备发送 unbound 命令
sim-hw 接收命令并清除显示内容
sim-hw 自动发布 request_claim 消息
后端生成新的配对码并发送给设备
设备显示新的配对码，准备重新配对
设备从你的仪表盘绑定设备列表中消失

设备继续运行

解绑不会停止模拟设备。sim-hw 继续运行，发送心跳并显示配对码。你可以随时重新绑定。

绑定生命周期图¶

sim-hw starts
    │
    ├── Heartbeat → Backend creates device record
    │
    ├── request_claim → Backend generates code
    │
    ├── claim_code received → Display shows "A3X9K2"
    │
    │              User enters code in sim-dashboard
    │                          │
    │              POST /api/devices/bind/code
    │                          │
    │              Backend binds device to user
    │                          │
    ├── 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/{thing}/unbind
    │                          │
    ├── unbound received → Display clears
    │
    └── request_claim → Cycle repeats

故障排除¶

配对码未出现¶

确认 sim-hw 正在运行并已连接（检查日志中是否有 Connected as inklet-...）
确认后端运行在 http://localhost:4000
确认 sim-dashboard 的 Fastify 服务器运行在 http://localhost:3001
确认 sim-hw 配置了 --sim-url http://localhost:3001

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

设备必须在绑定前至少发送过一次心跳。启动 sim-hw 后等待几秒再试。
确认配对码未过期。如果已过期，设备会自动请求新的配对码。

出现"Device already bound"错误¶

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

绑定后显示不更新¶

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