From 3ffee1899d11283a8220b71fe5c5ed911c07dbc7 Mon Sep 17 00:00:00 2001 From: Codex Date: Wed, 27 May 2026 19:50:00 +0800 Subject: [PATCH] docs: clarify device-pod bench abstraction --- docs/reference/device-pod.md | 19 +++++++++++++++++-- 1 file changed, 17 insertions(+), 2 deletions(-) diff --git a/docs/reference/device-pod.md b/docs/reference/device-pod.md index c78fabe5..ce038e2c 100644 --- a/docs/reference/device-pod.md +++ b/docs/reference/device-pod.md @@ -1,6 +1,6 @@ # Device Pod 设备目标能力模型 -本文是 HWLAB `device-pod` 的长期参考口径。`device-pod` 是一个以单副本 k8s Pod 运行的设备目标代理单元，用于把一个可开发、可下载、可复位、可观测 I/O 的设备目标封装成统一 REST/job API。对外稳定身份由 Service/Deployment 承载，不依赖实际 Pod name。 +本文是 HWLAB `device-pod` 的长期参考口径。`device-pod` 是一个逻辑实验台抽象，用于把一个可开发、可编译、可下载、可复位、可观测 I/O 的设备目标封装成统一能力单元。进入 server 阶段后，该能力单元可以由单副本 k8s Pod 承载，并对外提供统一 REST/job API；对外稳定身份由 Service/Deployment 承载，不依赖实际 Pod name。 `device-pod` 不等同于裸物理设备，也不是泛化远程 shell。它是以下四个要素的运行时组合： @@ -12,6 +12,19 @@ device-pod + ioInterface ``` +## 设计抽象 + +`device-pod` 可以理解成云端可拥有和调度的一张嵌入式实验台。云端拥有的是 `device-pod` 这个逻辑能力单元，不是直接拥有某一块裸板、某一根探针或某一台用户 PC。只要 profile 能把 `deviceTarget`、`debugInterface`、`projectWorkspace` 和 `ioInterface` 四要素绑定清楚，code agent 就可以围绕同一个 `devicePodId` 完成源码修改、构建、下载、复位、状态读取和 I/O 观察，从而覆盖嵌入式开发的完整闭环。 + +四要素的物理落点可以不同，也可以复用同一个硬件实体的不同能力： + +- `deviceTarget` 是被调试和被验证的目标设备。 +- `debugInterface` 提供下载、烧录、复位、debug probe 状态和芯片识别等调试能力。 +- `projectWorkspace` 承载源码、工程、Keil/GCC 等工具链和编译产物。 +- `ioInterface` 提供 AI、AO、DI、DO、UART、截图、日志和其他实时或近实时观测/控制能力。 + +`device-pod` 因此是逻辑打包关系，而不是一对一物理设备关系。一个 DAPLink/MKLink 类探针可以同时拆出 `debugInterface` 的 SWD/CMSIS-DAP 能力和 `ioInterface` 的 UART 能力；同一个 `device-pod` 也可以把该探针与调试 box、USB 摄像头、串口工具或厂商上位机组合起来，共同形成对同一个 `deviceTarget` 的完整访问能力。 + ## 实施计划 长期模型以本文为准；分阶段实现计划单独维护，避免把一次性开发步骤写进长期参考： @@ -78,7 +91,7 @@ projectWorkspace.build ### `ioInterface` -`ioInterface` 是设备的实时或近实时 I/O 观测与控制接口，代表 UART、AI、AO、DI、DO、状态采样、日志抓取等能力。典型实现包括 DAPLink 自带串口、独立串口工具、USB/WiFi/厂商协议上位机或 `device-host-cli`。 +`ioInterface` 是设备的实时或近实时 I/O 观测与控制接口，代表 UART、AI、AO、DI、DO、状态采样、日志抓取、截图等能力。典型实现包括 DAPLink/MKLink 自带串口、独立串口工具、调试 box、USB 摄像头、USB/WiFi/厂商协议上位机或 `device-host-cli`。 MVP 推荐路径为： @@ -160,4 +173,6 @@ projectWorkspace: STM32F103 源码、Keil 工程和编译工具链 ioInterface: DAPLink UART 串口 ``` +最小真实闭环也可以表述为：STM32F103 最小系统板作为 `deviceTarget`，一只 MKLink/DAPLink 类探针同时提供 `debugInterface` 和第一版 `ioInterface`，其中 debug 侧负责下载、复位和芯片识别，I/O 侧先只开放 UART；`projectWorkspace` 映射到用户 PC 上的源码目录、Keil 工程和工具链，再通过 gateway/device-host-cli 暴露受控构建和 artifact 能力。这样四要素齐备后，云端 code agent 就能围绕同一个 `device-pod` 完成改源码、编译、下载、复位、读串口的最小嵌入式开发闭环。 + 该模型后续可以扩展到更多 target 或更复杂 I/O probe，但每个 `device-pod` 仍只代表一个明确的设备目标能力单元。