HTTP / WebSocket 接口
客户端直接访问设备 IP。不是所有功能都只用 WebSocket:配置、目标探测和 C 执行目前还使用 HTTP。建议优先使用 独立 SDK;直接对接时遵循当前前端和固件协议。
端点总览
| 端点 | 载荷 / 用途 |
|---|---|
/api/setup?type=uart | HTTP POST,串口参数;oper=close 释放 |
/api/setup?type=i2c / type=spi | HTTP POST,总线配置;oper=close 释放 |
/api/pwm | HTTP GET 状态;POST 输出、占空比、停止与输入测量 |
/api/swd_port | HTTP,SWD 目标探测与识别信息 |
/api/cc/run / upload / stop | HTTP,C 镜像运行、保存、停止 |
/ws/shell | Shell stdio 连续终端流 |
/ws/uart | 裸字节串口透传 |
/ws/i2c / /ws/spi | 自定义二进制帧,总线与 GPIO 操作 |
/ws/serprog | FlashRom serprog 字节流 |
/ws/flash | 文件上传或 MCU 固件分块传输 |
/ws/target | 旧目标控制帧接口,与 /ws/dap 不同 |
/ws/swd | DAP Monitor 的 CMSIS-DAP 侦听记录 |
/ws/dap | 原始 CMSIS-DAP 请求/响应或受支持的共享读取 |
/ws/rtt-control | RTT 目标扫描、连接和控制 |
/ws/rtt-channels | RTT 多通道数据流 |
/ws/la | 逻辑分析仪控制与采样流 |
/ws/usb-fs | USB Sniffer 控制与解码结果流 |
/mcp/api(兼容 /mpc/api) | HTTP JSON-RPC MCP |
路径相同不表示数据格式相同。例如 /ws/swd 是侦听,不是发调试命令;/ws/dap 才是原始命令通道。
I2C / SPI 公共帧
小端 6 字节头,后面跟可选载荷,可在一次 WS 消息中出现多个帧:
| 偏移 | 长度 | 字段 |
|---|---|---|
| 0 | 2 | 本帧总长度 head_len(包含头) |
| 2 | 1 | addr,I2C 常为设备地址;其他操作可能复用 |
| 3 | 1 | oper 操作码 |
| 4 | 2 | size,不同操作可能为字节数或位域 |
| 6 | 可变 | 载荷 |
不能对所有 oper 都把 size 当成 payload 长度,也不能假设一次 WS 消息只有一帧。协议数值由工程 protocol/ws_proto.json 生成,SDK 的帧解析器与之配套,避免手写重复常量。
原始 DAP 最小例
const ws = new WebSocket('ws://192.168.33.1/ws/dap')
ws.binaryType = 'arraybuffer'
ws.onopen = () => ws.send(new Uint8Array([0x00, 0x02])) // 产品信息
ws.onmessage = event => {
if (typeof event.data === 'string') console.log(JSON.parse(event.data))
else console.log(Array.from(new Uint8Array(event.data)))
ws.close()
}请求和响应含命令号,单包最多 64 字节,命令布局先经固件校验。目标访问需完整 Connect/配置/操作/Disconnect 事务。多个原始连接按调度等待,错误会含 owner 或超时信息;不应并发向同一连接灌入多个未完成请求。
共享只读请求为文本 {"op":"readMemory","address":...,"length":...,"protocol":...,"revision":...},只适用于受支持的 Web RTT 目标,单次最多 256 字节。建议通过脚本 DAP.readTargetMemory 管理分块和目标版本,不要无视接口不匹配或目标变化错误。
文件与烧录数据块
/ws/flash 上传数据块为最多 4096 字节数据 + 4 字节小端偏移,每块等待 JSON 确认;最后一块可不足 4096。是否上传文件、应用镜像或算法取决于连接参数及操作流程,不要只向裸端点发文件。
Shell 是连续终端流,提示符和命令输出可能拆包或合包。UART 是字节流,不能默认 UTF-8 文本边界与 WS 消息边界一致。RTT/采集有自己的封装,不适用 I2C/SPI 六字节头。
连接与错误处理
总线端点通常只允许一个活动客户端,后连者可能替换旧连接。一个 socket 保持一个接收消费者,并按请求串行处理;超时后重新建立会话,避免迟到回复错配。不要重放结果未知的写入、擦除或复位。
PWM 输出与输入测量
GET /api/pwm 返回系统时钟、频率范围、各组运行状态、引脚占用及实际参数。POST /api/pwm 使用 JSON,gpio_a 始终为组内 A 脚,即使仅输出 B。基点 duty_*_bp 的 10000 对应 100%。
{"operation":"start","gpio_a":2,"frequency_hz":1000,"duty_a_bp":5000,"duty_b_bp":5000,"channel_mask":2}以上仅输出 GPIO3;channel_mask 为 1(A)、2(B)、3(双通道)。运行中更新占空比:
{"operation":"duty","gpio_a":2,"duty_a_bp":5000,"duty_b_bp":2500}在另一 Slice 测量 GPIO9(B 输入),每窗口 200 ms:
{"operation":"capture_start","gpio_a":8,"window_ms":200}停止指定组:
{"operation":"stop","gpio_a":2}GPIO8/9 测量任务需另发 gpio_a:8 停止。频率和占空比以成功响应的实际值为准。HTTP 400 表示配置无效;409 包括引脚占用或用户 C 任务冲突;503 capture_unavailable 表示测量所需计时器/IRQ 不可用。旧固件可能不支持该端点或单通道能力。