API 总览
PicoXTools 有多层 API,它们面向不同运行环境。名称相似不表示可以直接互换。
| 入口 | 运行位置 | 用途 | 文档 |
|---|---|---|---|
| 浏览器脚本 | Web 工作台「脚本」(当前固定浏览器执行) | GPIO/总线、原始 DAP、Cortex-M 控制 | 脚本入门、DAP API |
| 板上 JavaScript | QuickJS,Shell js file.js | 无浏览器运行的板上自动化 | 板上 JS |
| Node.js / Python SDK | 电脑程序,直连板子 | 测试、采集、烧录、FlashRom、RTT、CMSIS-DAP | 独立 SDK |
| 设备 MCP | AI 客户端,Streamable HTTP | GPIO/I2C/SPI/UART 与 DAP 工具 | MCP API |
| 原始 HTTP / WebSocket | 自行实现的客户端 | 对接现有协议 | 协议与端点 |
| PIO/C 导出函数 | 板上用户程序 | GPIO/PIO/DMA 等受支持的本地能力 | C 函数、PIO 语法 |
单位和数据格式
| 参数 | 单位 / 格式 |
|---|---|
UART bit_rate(SDK)/ bitrate(MCP) | 波特率 |
SPI/I2C clock、RTT frequency | Hz |
FlashRom speed | kHz,默认 20000 |
| Node.js timeout / Python timeout | 毫秒 / 秒 |
I2C addr | 7 位地址 |
| SDK bytes / MCP 普通总线写 data | Uint8Array/bytes / Base64 |
| MCP DAP writeMemory data | 数字字节数组,不是 Base64 |
| JSON address / value | 十进制数字,JSON 不支持 0x 数字字面量 |
资源与错误
调试器的原始会话以事务互斥,USB CMSIS-DAP、GDB、Web RTT、脚本 DAP、MCP 和 Shell Flash 需要共享它。受支持的只读访问可以在 Web RTT 上分时调度,不代表能随意接管已运行的 GDB 会话。
debugger_busy / queue_timeout 返回占用方时先释放对应功能,不要不断重试具有副作用的写入或复位。MCP 使用 result.isError,SDK 使用异常,原始 DAP 还需检查命令状态、ACK 和已完成传输数。
I2C/SPI/SWD/JTAG/FlashRom 可能复用引脚;关闭连接和释放外设是不同层次,使用 SDK 时遵循 close() / async with,使用原始命令时结束完整事务。单条终端消息不代表一条 Shell 命令已经执行完毕。
从哪里开始
- 浏览器控制目标:先读 DAP 快速示例。
- Python/Node 自动化:先读 SDK 安装与示例。
- AI 直接操作:从 MCP 的 initialize / tools/list 开始。