Skip to content

HTTP / WebSocket 接口 ​

客户端直接访问设备 IP。不是所有功能都只用 WebSocket:配置、目标探测和 C 执行目前还使用 HTTP。建议优先使用 独立 SDK;直接对接时遵循当前前端和固件协议。

端点总览 ​

端点载荷 / 用途
/api/setup?type=uartHTTP POST,串口参数;oper=close 释放
/api/setup?type=i2c / type=spiHTTP POST,总线配置;oper=close 释放
/api/pwmHTTP GET 状态;POST 输出、占空比、停止与输入测量
/api/swd_portHTTP,SWD 目标探测与识别信息
/api/cc/run / upload / stopHTTP,C 镜像运行、保存、停止
/ws/shellShell stdio 连续终端流
/ws/uart裸字节串口透传
/ws/i2c / /ws/spi自定义二进制帧,总线与 GPIO 操作
/ws/serprogFlashRom serprog 字节流
/ws/flash文件上传或 MCU 固件分块传输
/ws/target旧目标控制帧接口,与 /ws/dap 不同
/ws/swdDAP Monitor 的 CMSIS-DAP 侦听记录
/ws/dap原始 CMSIS-DAP 请求/响应或受支持的共享读取
/ws/rtt-controlRTT 目标扫描、连接和控制
/ws/rtt-channelsRTT 多通道数据流
/ws/la逻辑分析仪控制与采样流
/ws/usb-fsUSB Sniffer 控制与解码结果流
/mcp/api(兼容 /mpc/api)HTTP JSON-RPC MCP

路径相同不表示数据格式相同。例如 /ws/swd 是侦听,不是发调试命令;/ws/dap 才是原始命令通道。

I2C / SPI 公共帧 ​

小端 6 字节头,后面跟可选载荷,可在一次 WS 消息中出现多个帧:

偏移长度字段
02本帧总长度 head_len(包含头)
21addr,I2C 常为设备地址;其他操作可能复用
31oper 操作码
42size,不同操作可能为字节数或位域
6可变载荷

不能对所有 oper 都把 size 当成 payload 长度,也不能假设一次 WS 消息只有一帧。协议数值由工程 protocol/ws_proto.json 生成,SDK 的帧解析器与之配套,避免手写重复常量。

原始 DAP 最小例 ​

js
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%。

json
{"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(双通道)。运行中更新占空比:

json
{"operation":"duty","gpio_a":2,"duty_a_bp":5000,"duty_b_bp":2500}

在另一 Slice 测量 GPIO9(B 输入),每窗口 200 ms:

json
{"operation":"capture_start","gpio_a":8,"window_ms":200}

停止指定组:

json
{"operation":"stop","gpio_a":2}

GPIO8/9 测量任务需另发 gpio_a:8 停止。频率和占空比以成功响应的实际值为准。HTTP 400 表示配置无效;409 包括引脚占用或用户 C 任务冲突;503 capture_unavailable 表示测量所需计时器/IRQ 不可用。旧固件可能不支持该端点或单通道能力。

交互式使用步骤