docs(devices): publish ILX MultiPad first case

devices/CHANGELOG.md

@@ -4,6 +4,10 @@ This file records changes to public protocol behavior, shared vectors, SDK surfa
 
 ## Unreleased
 
+- Add the first ILX MultiPad case guide with pinned upstream source, public
+  adapter integration, key mapping, build separation, and SWD/serial evidence
+  rules.
+
 ### Added
 
 - A source-first ILX MultiPad USB CDC developer binding that reuses the portable

devices/README.md

@@ -23,6 +23,7 @@ The device does not run the Agent session and does not receive Agent credentials
 | Get ideas for what to build                  | [Browse the use cases](docs/use-cases.md)                                                                                                                  |
 | Build and flash a supported board            | [Run the first approval](docs/first-approval.md), then use the [reference-board track](docs/implementation-tracks.md#track-1-run-a-reference-board)        |
 | Prepare an ILX MultiPad USB device           | Read the [MultiPad USB guide](docs/multipad-usb.md); confirm the PCB before any flash write                                                                |
+| Reproduce the first public hardware case     | Follow the [ILX MultiPad case](docs/cases/multipad-first-case.md); build the upstream firmware before adding Nexting                                       |
 | Add a physical control surface to a Host/App | [Browse every public interface](docs/interfaces.md), then use the [Host integration track](docs/implementation-tracks.md#track-2-integrate-a-host-or-app)  |
 | Port a new MCU, RTOS, or chip family         | [Build the public foundation](docs/foundation-development.md), then use the [MCU port track](docs/implementation-tracks.md#track-3-port-a-new-mcu-or-rtos) |
 | Implement another language SDK               | Use the [language SDK track](docs/implementation-tracks.md#track-4-maintain-a-new-language-sdk)                                                            |

devices/SHA256SUMS

@@ -1,30 +1,31 @@
 5e79c3b2a9dc997d6faa762fa3d420da27243c27a60726a5b4d94dabfdfcfb17  AGENTS.md
-b2e88419dcda506677dd44af32faca468de0f852305eb6c6b3892f1bd10b0f86  CHANGELOG.md
+362a3eea47663c7cb770739dba81e86818624b0874d448b6136873156521a2eb  CHANGELOG.md
 0905c822fd9d85cb05d05539ca0b41ce807109621f06e5d18792505a78fc270f  CONTRIBUTING.md
 f0e5a3b3fc8d8d664d76be452f1631a296ef89566acb58440354da31af2074bd  docs/board-verification.md
+06a0f796634a47af9fb8628b11206a91120505e0a0d0fd6757915ef44f961f47  docs/cases/multipad-first-case.md
 bdfc3ae27b547003179322577ca28a03e8d06bb46815625ec1270ff3142b50da  docs/conformance.md
 92b35fee2f0ae4195fc31614a01b1aeba3b2bdc24b8f59c38e46a2c0c537dcc2  docs/development.md
 b6b2a3bc464d167d920f143c71ffde52c51d264f5cc71c0e8928f95986fa0e2b  docs/first-approval.md
 e27b38c5b92c32d3f0028996516b027fb842183730dae8c7ba3c87e5be882329  docs/foundation-development.md
 253e7aff8894704a280e9a588e0181da98a9bd825fd506625b9325e357f6e419  docs/hardware-support.md
-8436fcbbfb8554f5c2549d06b329f6f3f7631ed3437ec51f1bb7454798491b00  docs/implementation-tracks.md
+1cb75f130268edcf545e5525a08c948f2f470a6cdc23a0734dc0766d0f1e932b  docs/implementation-tracks.md
 16815c4d5e0ae09b8502f0109a0a4e38b64b467a4b0a82b029905093b63310af  docs/interfaces.md
 026b3ce7d5970d2a34d64862de12882f8da9e014d2ef9ab4a9c3d5e99af31b1b  docs/migration-0.1-to-0.2.md
-18c71c1d3da6a2a9bb66912832916594c672d268fa1c014b66c4decdce9fe11a  docs/multipad-usb.md
+74f60bf30d5940a6cb2f71b208abb48196249a0f1195eb7ac7f6eeb125c3e573  docs/multipad-usb.md
 36f7151ddbf307f8ff4cf5487d094930882b78b7ee91d241adf2eff53753ac55  docs/porting-guide.md
-8ba7a254ecd348f19215dedc11eeb561f22c74cf3417b47d414dfaab5675c4ed  docs/project-status.md
-dc9e38145477ae5c9f9818ad3567d7d57f9bd31f264279014b30ffec097b22e7  docs/README.md
+e0200e8dbcd3d758ae6fea3b608a3e648291877f7c5de284ea902ca1170062bf  docs/project-status.md
+dd62331e63b11b15874989474836fdff06b0282eca3340555554e0614ba266ef  docs/README.md
 5b04ce5083234a4137fad6eee987946b55bfe7a758220394eb127b804aa4f873  docs/use-cases.md
 cddf6aec5d4750dc34c9a6f642c604c8786ba89018082b96db8a7b6fe716b7b5  examples/macos-device-simulator/main.swift
 85a7b0f0976f7b43099629335e9b61be625a77ce548e438956dbf3a5e1de2e27  examples/macos-device-simulator/README.md
-3f56b901400960503a304e6c0f8f4a6aa0ab5467b8f097737b3a2d99dda6e5d0  firmware/multipad/bringup-status.md
+445fd02928f57ec5cb23b15c6fd4617cff6348e2df991736d04bad5d4ae8ec90  firmware/multipad/bringup-status.md
 e93dad280dad39b252d5d0edaf549cf9db8a8833eb009bc2b089da8ebfb181d2  firmware/multipad/CMakeLists.txt
-e86c924b3b6cdd85fcf311dba4d85804cdf70a3fbeb554c4215d4617e37b9850  firmware/multipad/hw-review-findings.md
+58edf13b1bbc8c855432f921eab5ac74befe9a78ac8254c9040eeef4b0704c52  firmware/multipad/hw-review-findings.md
 d40be2000fae5697e0d40abebfc833d31c8568679c66c3f1b1cbb85744dac7d4  firmware/multipad/nexting_multipad_adapter.c
 f4bab39e2320ae1f171eca78005cdfd355848dda5690020f2201de4a96d37587  firmware/multipad/nexting_multipad_adapter.h
 55e8c889cfe9b62dcc62c591880aba2f9826a6a1353d7a89213916efd27c0bce  firmware/multipad/nexting-multipad-device-info.template.json
-b077373089e8bc8100b9dbb003fafb6e9bd97b2d471df84c0dc8a990e4e2c680  firmware/multipad/pin-function-map.md
-38103d0b2ed11139f1a1d3cfae91daccc6c57514086621a1ef49ca9e8d1d0270  firmware/multipad/README.md
+732ad9fa55a9055e2d8c1c701489fa09608634bda4b89a2e1d601dff5e75e013  firmware/multipad/pin-function-map.md
+2c743c98200d48a611fc9cb5994e11372b9daa3dc944570c3d48e55bf88be7ba  firmware/multipad/README.md
 49d3bf8fc0756bf4c69eb6d5af3b7cfe788c2c56822f000ba05adcad8d16e7c7  firmware/multipad/tests/test_adapter.c
 a111d8e0484745a126069df990273171181a61caa5a3a751043974cc52f43f00  firmware/multipad/tools/flash-multipad.sh
 4c27437ae7b7c5555a8a21eb763785e8600682ad71f0b12f29304e56cf132d5f  firmware/multipad/tools/multipad-cdc-smoke.py
@@ -45,7 +46,7 @@ faab06a4630dfc7b7e5c1fc7ecef24ae6ca0c0040f3b71f3d112d1a816a410b9  NOTICE
 af1ea5c4627d67b21afd238f48b7eb4931655894bd899450b16fc802d8cdcf68  protocol/vectors/approval-v1.json
 eb2a6b125d123a5644a0773593c2eee730339f2809e51605f2f82eb518dde1d4  protocol/vectors/device-info-v1.json
 3523ce906d597735ed9de66d79923b12de284595566c556725c10bf726ba84b0  protocol/vectors/status-v1.json
-e568a17b0b64eb50fd147981ad6d58127127022774075acdc8d07f93df14d895  README.md
+7ed0ffa1a546c198a2008f9fc9a1325035248c3fd4ccad3cce667790e579ddb9  README.md
 83c03d7b5779aaf86471945890b5e699cba1171fe3064b58942a3784c4efa9d6  reference/js/package.json
 18374cf8708c75abce5a22d6d445cf5ab48b6b62774ecf3af8f780693d1cf45e  reference/js/README.md
 d1daccb45aebdf6a6ff524abe07ba34833a83266c433178596840c00a7fb3ee8  reference/js/src/device-info.mjs
@@ -63,8 +64,8 @@ dd94f6782ad7f3f8ab102806ac2b32555a8f61ef6da04eca504250591f43d697  reference/js/t
 707046c2762b923fcc0add6465f23a504a93f48502c55c24155c7367fcbfe4ae  scripts/check-naming.mjs
 e3f347b6e98e6a1ca3f9f842a6c2f1245f0f6953680a685ecbdd42d17dd1e1ed  scripts/check-public-boundary.mjs
 8d7aad1d02044e2762835d765a6bad5fc41c454e15d75111f957db45bc72348c  scripts/check-public-boundary.test.mjs
-2ff5e27e3ce3c7d4e0623d1b66d5ff7fb24c2edf8308e35ba7b5fcdb59e76e4d  scripts/documentation-contract.test.mjs
-222cee57ac6ec97208cea67a6e3e7cf8672000f10acfd60a09d6f21af4b0b10f  scripts/export-manifest.json
+72e5a1d62ee49c9ca32dc026cf1d16bd1b55269cd10d00d0ad8c67efa01eb99a  scripts/documentation-contract.test.mjs
+2e6e8e0d3577700cc2e68aab5b034cffca7598474d54250ab9536eef25a7c6ad  scripts/export-manifest.json
 f461f2683632c7fb38a5c04b2fa03a0293fe791571b1b173982514530cc793d6  scripts/export-nexting-devices.mjs
 85f681344b04754999e17a4ec472dfae1ed1c2daa49f065d77bacdb223ea57fe  scripts/export-nexting-devices.test.mjs
 a7120b95b63f5c7004f5099fcd9bf073fd34e167cef6e6382258d869f6faa2ac  scripts/public-workflows/nexting-devices-ci.yml

devices/docs/README.md

@@ -27,6 +27,7 @@ Choose the task you are trying to complete.
 - [JavaScript reference](../reference/js/README.md): readable protocol, framing, and relay behavior.
 - [Zephyr reference firmware](../firmware/zephyr/README.md): shared Nordic and Espressif adapter.
 - [MultiPad USB CDC guide](multipad-usb.md): open-source STM32 adapter, board variant check, and fail-closed flash preparation.
+- [First case: ILX MultiPad](cases/multipad-first-case.md): reproduce the upstream build, add the public adapter, map the first two keys, and verify the flash path.
 - [Port a chip](porting-guide.md): platform contract and adapter rules.
 
 ## Verify and make claims

devices/docs/cases/multipad-first-case.md

@@ -0,0 +1,147 @@
+# 第一个案例：ILX MultiPad 接入 Nexting Devices
+
+ILX MultiPad 是 Nexting Devices 的第一个完整硬件案例。它不是一块
+Nexting 量产板，而是一块已经开源、已经能作为键盘使用的 STM32F103VET6
+USB HID + CDC 设备。这个案例的目标是说明：如何保留原作者的键盘功能，
+只增加一层可验证的 Nexting 设备协议适配。
+
+## 这个案例到底交付什么
+
+| 层             | 案例交付物                                                           | 证据等级           |
+| -------------- | -------------------------------------------------------------------- | ------------------ |
+| 上游固件       | `iLx11/multi-pad`，固定到 `78c1ee533a7f513e9f390741c4f5eed1e0aa91b3` | 源码可审计         |
+| Nexting 设备核 | `sdk/c` 的固定缓冲 C99 协议、流式拼帧和审批状态机                    | Core tested        |
+| MultiPad 适配  | `firmware/multipad/nexting_multipad_adapter.c/.h`                    | CMake 合约测试通过 |
+| 兼容入口       | 原有 `AA BB xx` 保留，只有换行 JSON 帧进入 Nexting 适配器            | 主机测试通过       |
+| 烧录路径       | Module 版走串口路径（仅当看到 SERIAL/BOOT/RESET）；FPC 版走 SWD      | 由拆机证据决定     |
+| Host 边界      | Host 负责授权、Agent 路由和最终回答；固件不保存凭证                  | 公开契约           |
+
+当前公开 SDK 不提供一个可以误称为“已经适配所有版本”的 HEX。上游工程中
+的 `leden.hex` 是原版固件（原作者固件）；接入 Nexting 适配器后必须重新构建并单独保存
+新的 HEX。不能把原固件误当作 Nexting 固件烧进去。
+
+## 上游工程与版本
+
+使用下面两个公开仓库，不要把上位机仓库当成下位机固件：
+
+- 下位机固件：[iLx11/multi-pad](https://github.com/iLx11/multi-pad)
+- 上位机：[iLx11/key-pad-application](https://github.com/iLx11/key-pad-application)
+
+本案例只接入下位机仓库。上游工程本身已经证明了这些事实：
+
+- `STM32F103VET6`、Cortex-M3；
+- USB HID + USB CDC composite；
+- 2 × 4 矩阵按键和 3 个旋钮模块；
+- `PA13 = SWDIO`、`PA14 = SWCLK`；
+- `PA9/PA10 = USART1_TX/RX`；
+- 工程没有 DFU、IAP 或应用侧 USB bootloader；
+- 上游许可证为 GPL-3.0。
+
+烧录配置在上游的 `Config/stlink.cfg`，不是 Nexting App 的配置。普通 Type-C
+枚举出来的 CDC 端口只能证明应用正在运行，不能证明它已经进入 bootloader。
+Type-C 不能直接烧录，除非先确认对应的 bootloader 路径。
+
+## 第一个可运行映射
+
+这个案例只承诺一个小而明确的映射，不把未来能力提前写成已支持：
+
+| MultiPad 控件     | Nexting 公共接口                   | 案例行为                                        |
+| ----------------- | ---------------------------------- | ----------------------------------------------- |
+| 第一个矩阵键      | `approval/1` → Allow               | 批准当前唯一待决请求                            |
+| 第二个矩阵键      | `approval/1` → Deny                | 拒绝当前唯一待决请求                            |
+| 现有 CDC 接收回调 | `nexting_multipad_receive()`       | 接收 `present`、`resolved`、`status`            |
+| 现有 CDC 发送函数 | `nexting_multipad_write_frame()`   | 回传 `answer`                                   |
+| 板上屏幕/指示器   | `render_approval`、`render_status` | 只渲染回调收到的状态                            |
+| 其他按键和旋钮    | 保留原厂行为                       | 等 `keys/1`、`rotary/1` 等 profile 发布后再映射 |
+
+适配器不会解析 Agent 会话，也不会把 Claude Code、Codex、账户或云地址写入
+设备。显示摘要、倒计时和状态的具体排版属于板级回调，不属于协议核。
+
+## 从上游源码到案例固件
+
+### 1. 固定上游源码并先构建原版
+
+```sh
+git clone https://github.com/iLx11/multi-pad.git
+cd multi-pad
+git checkout 78c1ee533a7f513e9f390741c4f5eed1e0aa91b3
+
+# 上游工程要求 arm-none-eabi-gcc、CMake 和 STM32 工具链
+cmake -S . -B build
+cmake --build build
+sha256sum build/leden.hex
+```
+
+先保存这个原版产物和哈希。它只用于恢复原厂功能，不能标记为 Nexting 固件。
+
+### 2. 加入公开 Nexting 源码
+
+从 `Nexting-ai/nexting/devices/` 取下面的公开文件，复制到上游工程的独立
+目录（例如 `USER/Nexting/`），不要修改公共 SDK 的语义：
+
+```text
+devices/sdk/c/include/nexting_device.h
+devices/sdk/c/src/nexting_device.c
+devices/firmware/multipad/nexting_multipad_adapter.h
+devices/firmware/multipad/nexting_multipad_adapter.c
+```
+
+把这四个文件加入上游 CMake target，并把 `sdk/c/include` 加入 include path。
+上游 `USER/Usb/usb_user.c` 的 CDC 回调先判断 Nexting 帧，再落回原有分支：
+
+```c
+if (nexting_multipad_accepts(&nexting_adapter, Buf, *Len)) {
+    (void)nexting_multipad_receive(&nexting_adapter, Buf, *Len);
+    return USBD_OK;
+}
+
+/* 原有 AA BB CC / AA BB AA / AA BB DD / AA BB EE / AA BB FF 分支继续保留。 */
+```
+
+初始化时提供四个板级回调：单调时钟、CDC 发送、审批渲染、状态渲染。主循环
+调用 `nexting_multipad_tick()`；USB 断连调用
+`nexting_multipad_disconnect()`；前两个审批键分别调用
+`nexting_multipad_choose(...ALLOW)` 和
+`nexting_multipad_choose(...DENY)`。回调失败时不要伪造成功 UI。
+
+### 3. 构建、备份、烧录
+
+重新构建后，对新的 `leden.hex` 计算哈希，并把原版备份、Nexting 版本和日志
+放在不同文件名下。根据硬件版本选择路径：
+
+| 版本       | 写入方式                   | 关键条件                                   |
+| ---------- | -------------------------- | ------------------------------------------ |
+| Module PCB | 上游串口路径（待实板确认） | 必须看到 SERIAL、BOOT、RESET 路径          |
+| FPC PCB    | ST-Link/J-Link SWD         | `3V3`、`GND`、`SWDIO(PA13)`、`SWCLK(PA14)` |
+
+在确认 bootloader 之后，才可以使用本目录的
+`firmware/multipad/tools/flash-multipad.sh`。脚本要求显式的端口、HEX、
+`--confirm --allow-write`，且不会覆盖原始备份。
+
+### 4. 一次只验证一个行为
+
+1. 先用 `multipad-cdc-smoke.py` 验证原有 `AA BB CC` 回显。
+2. 发送一个 `present`，确认屏幕或指示器只显示当前请求。
+3. 按 Allow，确认收到同一个 `id` 的 `answer`。
+4. 确认 Host 成功后发送 `resolved`，设备清掉待决状态。
+5. 单独测试超时和 USB 断连；两者都必须清空审批和状态，不能留下旧提示。
+
+在没有这些逐项证据前，只能写“适配器测试通过”，不能写“MultiPad 真板已
+兼容”或“Type-C 可直接烧录”。
+
+## 这个案例与 Nexting App 的关系
+
+MultiPad USB 是公开的开发者案例，不是现有 BLE App 自动支持的 USB 变体。
+Host 必须自己拥有 USB 权限、端口选择、授权状态和 Agent 最终回答操作；
+设备只接收有界的公共消息。未来如果 Nexting App 开放 USB transport，需要
+另行发布 Host 支持、授权测试和断连策略，不能由这份固件文档推断出来。
+
+## 完成定义
+
+- 上游工程能在固定 commit 上复现构建；
+- 原版 HEX 已备份并有哈希；
+- Nexting HEX 由明确的适配源码生成并有哈希；
+- `npm run test:multipad`、C99 合约测试和 CDC smoke 通过；
+- `present → answer → resolved`、超时、断连分别有记录；
+- `Device Info` 只声明实际存在的按键、旋钮、显示和电量能力；
+- GitHub README 只链接本案例，不把实验性 USB 路径写成量产承诺。

devices/docs/implementation-tracks.md

@@ -127,6 +127,11 @@ and not automatic Nexting App USB enrollment.
 The Host still owns USB authorization, Agent routing, and final action sinks.
 The device sees only bounded public frames and never receives credentials.
 
+The [first MultiPad case](cases/multipad-first-case.md) is the reproducible
+walkthrough for this track. It pins the upstream commit, separates the original
+HEX from the Nexting build, maps the first two keys to Allow/Deny, and records
+the evidence required before calling the board compatible.
+
 ## Track 5: Maintain a new language SDK
 
 This is the language SDK route formerly listed as **Track 4: Maintain a new language SDK**;

devices/docs/multipad-usb.md

@@ -5,6 +5,9 @@
 通道接收配置和 Nexting JSON。它不直接连接 Claude Code、Codex 或 Nexting
 云；Host/App 仍然负责授权、会话和最终动作。
 
+如果这是你第一次把公开硬件接入 Nexting，请先读[第一个案例：ILX MultiPad](cases/multipad-first-case.md)。
+本页是硬件路径和风险清单；案例页是从上游源码到新 HEX 的完整开发顺序。
+
 ## 先知道你手上的硬件是哪一版
 
 先看[上游仓库](https://github.com/iLx11/multi-pad)与
@@ -19,6 +22,11 @@ Nexting 适配层，不复制上游 GPL 固件。
 | FPC PCB        | 移除串口和按键                       | 需要 SWD/J-Link               |
 | App bootloader | 上游源码没有 DFU/IAP/应用 bootloader | 烧错后不能指望 USB 自救       |
 
+上游工程的烧录配置是 `Config/stlink.cfg`：ST-Link 使用 SWD，目标是 STM32F1。
+`leden.ioc` 明确把 `PA13` 配为 `SWDIO`、`PA14` 配为 `SWCLK`，但上游仓库没有
+原理图或焊盘坐标文件，所以不能从仓库臆造物理焊盘顺序。看到焊盘后按丝印或
+万用表确认 `3V3/GND/SWDIO/SWCLK`，不要把 Type-C CDC 当作烧录器。
+
 拆机前不要猜显示屏、电池、序列号或开关位置。请先拔掉 Type-C，拆下四个
 背面螺丝，拿起后盖时不要拉扯屏幕排线，并拍下 MCU、PCB 版本、BOOT/RESET
 和 SERIAL 标记。本目录的