出厂 provisioning 串口协议

固件接收后台分发的设备私钥与序列号，写进一次性可编程存储区，读回确认。 读侧（应用启动时从 OTP 读身份，记录格式与判定）见 docs/otp-read.md；本文档只写写侧协议。 固件不再自己产生密钥对：密钥对由后台生成、绑定序列号，写入工具登录后取密钥， 经串口发给固件。旧的“现场产生、人工登记”流程已作废。

角色与流程

1. 出发前，现场实施人员从管理后台批量领号（发号系统去重、标记已领出）。
2. 写入工具用操作员账号（用户名密码）登录管理后台，联网向后台取该设备的密钥对； 取密钥时上报设备序列号、型号等，后台把密钥对绑定到该序列号，并记操作时间、 操作人等审计。
3. 写入工具经串口（DAPLink 自带虚拟串口）把私钥和序列号发给固件，固件写进 一次性可编程存储区，读回确认。
4. 写入工具确认 OK PROVISIONED 后，该台完成；写不进或读回不符的台隔离处理， 不重试写入（存储区写一次即不可改）。

传输

• 一行一条命令，\n 结尾；结尾的 \r 允许（即 \r\n 也行）。
• 命令是纯 ASCII，大小写敏感（全大写）；空行不回复（串口噪声直接忽略）。
• 单行最长 128 字节；超长直接回 ERR BAD_COMMAND。
• 回复一行，含结尾 \n；调用方回复缓冲至少 64 字节，不足时不写半截回复。
• 私钥只以 64 位十六进制字符（大小写均可）出现在 PROV KEY 这一行里； 设备在任何回复里都不输出私钥（原值、十六进制、指纹一律不输出），只回序列号。

命令

状态机

IDLE --BEGIN--> READY --COMMIT--> 已写入
  ^              |
  +--- ABORT ----+

• SERIAL 与 KEY 在 READY 下可按任意顺序送，提交前重发可覆盖纠错。
• BEGIN 在 READY 下可重复送（不清空待提交值）；已写入后送 BEGIN 回 ERR ALREADY_PROVISIONED。
• STATUS 在任何状态下都可用；未写入时回 OK UNPROVISIONED。
• SERIAL、KEY、COMMIT 在 IDLE 下（未 BEGIN）回 ERR BAD_COMMAND。
• COMMIT 后待提交值从内存清掉（私钥清零，不只是遗忘）。

提交检查顺序

COMMIT 按以下顺序检查，任一步失败即停：

1. 已写入 → ERR ALREADY_PROVISIONED。
2. 不在 READY → ERR BAD_COMMAND。
3. 序列号或私钥缺失 → ERR INCOMPLETE。
4. 写存储区失败 → ERR OTP。
5. 读回与写入值不符 → ERR VERIFY。此时存储区已经写了、但没通过确认， 该台必须隔离处理，不能重新写入（写一次即不可改），也不能靠重试蒙过去。
6. 全过 → OK PROVISIONED。

字段规则

• 序列号：1–32 字节，可见 ASCII（0x21–0x7E），不含空格（空格是命令分隔符）。 序列号格式本身由后台发号系统定，固件这里只做长度与字符检查，不硬编码格式。
• 私钥：恰好 64 位十六进制字符，对应 32 字节 X25519 私钥；长度不对或含非十六进制 字符回 ERR BAD_KEY。
• 未知命令、多余参数、缺参数回 ERR BAD_COMMAND；序列号非法回 ERR BAD_SERIAL。

错误码一览

写入工具对话示例

-> PROV STATUS
<- OK UNPROVISIONED
-> PROV BEGIN
<- OK PROV READY
-> PROV SERIAL GW202611020001
<- OK SERIAL
-> PROV KEY 808182838485868788898a8b8c8d8e8f909192939495969798999a9b9c9d9e9f
<- OK KEY
-> PROV COMMIT
<- OK PROVISIONED
-> PROV STATUS
<- OK PROVISIONED GW202611020001

相关文档

• 固件分发全流程（主本）：sign 仓 docs/固件分发全流程.md（https://github.com/ffffxxxjjj/sign/blob/main/docs/固件分发全流程.md）——开发出原始固件 → 运营上传管理后台（后端签名＋加密出共用包）→ 现场下载 → 写入工具分发取密钥 → 本协议写进一次性可编程存储区 → 现场安装验在线 → 空中升级。
• 服务端端点：sign 仓 docs/sign-server-api.md（https://github.com/ffffxxxjjj/sign/blob/main/docs/sign-server-api.md）——领号（POST /devices/allocate）、操作员登录与分发（POST /operator/login、POST /devices/issue）、包密钥包（GET /key-package）、手动推送（POST /devices/{序列号}/push、POST /devices/push-batch）、状态接入。
• 写入工具设计：firmware-tool 仓 docs/固件写入工具设计.md（https://github.com/ffffxxxjjj/firmware-tool/blob/main/docs/固件写入工具设计.md）——工具侧单台流程、界面、服务端接口。
• 包格式：sign 仓 docs/package-format.md（https://github.com/ffffxxxjjj/sign/blob/main/docs/package-format.md）——GWPK v3 共用包（包头 312 字节、格式 3）与 80 字节包密钥包。

注意：本协议只覆盖出厂写入（私钥与序列号进一次性可编程存储区）。空中升级的设备端处理（收 firmware_update 命令、解包密钥、解固件、验签、安装、回执）待固件侧实现，不在本协议内；回执配对跟踪与管理台推送按钮界面同样待后续。

实现位置与测试

• 实现：bootloader/src/provision.rs（Provisioner + OtpStore 抽象），no_std、 无堆、无外设依赖；板上应用层把串口收到的行喂给 handle_line，把返回的回复行 写回串口即可（串口接线本身不在本批内）。
• 存储抽象：OtpStore 只有读、写、查已写入三项，没有擦除与覆盖；芯片实现接 芯片的一次性可编程区，主机测试用内存模拟（同样写一次即不可改）。
• 主机测试：cargo test 里的 provision::tests（13 项），覆盖正常写入读回、 顺序可换、重复写入拒绝、缺字段、会话外命令、非法字段、未知命令、空行、 中止、读回不符、存储失败、重发覆盖、回复缓冲不足。