Node.js / Python 独立 SDK
直接访问 PicoXTools 的 IP,无需打开前端、安装 OpenOCD/GDB 或启动本地网络桥接。两套客户端沿用现有固件协议,没有修改固件。
安装与运行
当前配套发行包为 0.3.0(文档不表示已经发布到 npm/PyPI)。从维护者获取发行包,或下载本页随站点提供的快照:
0.3.0 新增主动 CMSIS-DAP 调试:pico.dap(),支持 SWD/JTAG、内存与 Cortex-M 控制;另见下方方法对照。
两个发行包均自带运行资源,可以在没有 PicoXTools 工程的电脑上安装:
# Node.js >= 22;无 npm 运行依赖
npm install ./picoxtools-sdk-0.3.0.tgz
# Python >= 3.10;pip 自动安装 websockets
python -m pip install ./picoxtools_sdk-0.3.0-py3-none-any.whlNode 导入 import { PicoXTools } from 'picoxtools-sdk';Python 导入 from picoxtools import PicoXTools。 Node 的 vendor/、Python 的 picoxtools/_engine/ 各自包含编译器、FlashRom、协议、转换器和 WASM;两包互不依赖,也不引用工程目录。
Python 的 Shell、UART、I2C、SPI、RTT 和上传/烧录只依赖 Python。C/PIO 编译、FLM/HEX/ELF 处理和 FlashRom 额外需要系统安装 Node.js >=22,以运行 wheel 内置的 WASM worker,不需要另装 npm SDK。Python 通过标准输入/输出调用 worker,WebSocket 仍由 Python 直接连接板子,不监听本地端口。可用 PICOXTOOLS_NODE 指定 Node 可执行文件。
可执行示例见各发行包 examples(源码树中也保留 sdk/examples/):version / shell / uart / i2c / spi / flashrom / compile / pio / flash / rtt。compile、pio 只生成本地镜像,flash 示例只探测 SWD 目标,flashrom 保存 backup.bin。
源码包也可以单独构建:Node 包目录执行 npm pack;Python 包目录执行 python -m build。无需资源复制脚本或父级工程。维护者更新引擎快照时才运行 sdk/tools/sync_vendors.py,它不是安装/构建的一部分。
接口与单位
| 模块 | Node.js | Python | 板端路径 |
|---|---|---|---|
| Shell 原始终端 | await pico.shell() | await pico.shell() | /ws/shell |
| UART 配置/收发 | await pico.uart(settings) | await pico.uart(**settings) | /api/setup?type=uart + /ws/uart |
| I2C 主机/从机/抓取 | await pico.i2c(settings) | await pico.i2c(**settings) | /api/setup?type=i2c + /ws/i2c |
| SPI 主机/从机/抓取 | await pico.spi(settings) | await pico.spi(**settings) | /api/setup?type=spi + /ws/spi |
| SPI FlashRom | await pico.flashrom(options) | await pico.flashrom(**options) | /ws/serprog |
| 本地 C/PIO 编译 | compileC / assemblePio / compilePio | compile_c / assemble_pio / compile_pio | 本地 WASM,不访问板子 |
| C 镜像运行/保存/停止 | runC / uploadC / stopC | run_c / upload_c / stop_c | /api/cc/run / upload / stop |
| SWD 目标探测 | probeTarget() | probe_target() | /api/swd_port |
| MCU 烧录/文件保存 | flash / uploadFile | flash / upload_file | /ws/flash |
| FLM 转换并保存算法 | uploadFlm(data, chipId, options) | upload_flm(data, chip_id, **options) | 本地转换 + /ws/flash?oper=upload |
| RTT 多通道 | await pico.rtt() | await pico.rtt() | /ws/rtt-control + /ws/rtt-channels |
| CMSIS-DAP 主动操作 | pico.dap() | pico.dap() | /ws/dap |
| DAP Monitor 原始记录 | await pico.dapMonitor() | await pico.dap_monitor() | /ws/swd,侦听 CMSIS-DAP 报文 |
| USB Sniffer 原始流 | await pico.usbSniffer() | await pico.usb_sniffer() | /ws/usb-fs |
| 逻辑分析仪原始流 | await pico.logicAnalyzer() | await pico.logic_analyzer() | /ws/la |
传输边界: 配置接口、目标探测、C 镜像执行在现有固件里仅提供 HTTP API,客户端直接调用这些接口,没有虚构 WebSocket 命令。若要求连配置也只能走 WebSocket,需要另行扩展固件协议。
常用频率:UART bit_rate 是波特率,I2C/SPI clock 和 RTT frequency 是 Hz,FlashRom speed 是 kHz,默认 20000。Node 的超时单位是 ms,Python 是 秒。PIO version=1 对应当前 RP2350,RP2040 可指定 version=0。
CMSIS-DAP 调试接口(0.3.0)
pico.dap() 创建延迟连接的会话,通过 /ws/dap?client=script 直接操作板子。 dapMonitor() / dap_monitor() 仍然只侦听,不会执行命令。设备需要支持 /ws/dap 的新版固件。
无暂停读取 SWD 目标
Node.js:
const dap = pico.dap();
try {
await dap.initSWD({ frequency: 1000000 });
console.log((await dap.read32(0xE000ED00)).toString(16)); // CPUID
console.log(await dap.readMemory(0x20000000, 16));
} finally { await dap.close(); }Python(这些 DAP 功能不需要安装 Node.js):
async with pico.dap() as dap:
await dap.init_swd(frequency=1000000)
print(hex(await dap.read32(0xE000ED00)))
print(await dap.read_memory(0x20000000, 16))initSWD / init_swd 初始化调试端口并上电 MEM-AP,不暂停或复位 MCU。 attach() 验证 Cortex-M 并默认暂停;如需保持应用运行,传入 {halt:false} / halt=False。 close() 释放端口,不隐式恢复一个已暂停的 CPU;需要继续运行时先调用 run()。
方法对照
| Node.js | Python | 作用 |
|---|---|---|
info(id=2) | info(id=2) | 产品信息,返回 text/data/value |
command(op, payload) | command(op, payload) | 命令号 + 载荷,返回含命令号的完整响应 |
connect(port=1) / disconnect() | 同名 | 1=SWD,2=JTAG;仅连接端口,不完成初始化 |
initSWD({frequency,powerTimeout}) | init_swd(frequency=..., power_timeout=...) | SWD 初始化,返回 dpidr |
initJTAG({frequency,irLengths}) | init_jtag(frequency=...,ir_lengths=...) | JTAG 初始化;IR 长度需匹配目标链 |
jtagConfigure(irLengths) / jtagIdcode(index=0) | jtag_configure(ir_lengths) / jtag_idcode(index=0) | JTAG 链配置和 IDCODE |
transfer(items,{dapIndex}) | transfer(items,dap_index=0) | DP/AP 寄存器访问列表 |
transferBlock(options) | transfer_block(**options) | 连续访问;块读≤15字,块写≤14字 |
readDP(address) / writeDP(address,value) | read_dp / write_dp | DP 访问 |
readAP(address,{ap,bank}) / writeAP(address,value,{ap,bank}) | read_ap(address,ap=0,bank=0) / write_ap(...) | 带 SELECT 的 AP 访问 |
read32(address,ap=0) / write32(address,value,ap=0) | 同名 | 对齐32位内存/MMIO访问 |
readMemory(address,length,ap=0) | read_memory(address,length,ap=0) | 最多65536字节 |
writeMemory(address,data,ap=0) | write_memory(address,data,ap=0) | 支持非对齐写入;返回字节数 |
readTargetMemory(address,length,options) / readTarget32(...) | read_target_memory(address,length,**options) / read_target32(...) | 共享当前 Web RTT 已连接目标的只读访问 |
attach({protocol,frequency,halt,ap,timeout}) | attach(protocol='swd',frequency=...,halt=True,ap=0,timeout=1) | Cortex-M 连接;protocol 为 swd/jtag |
halt() / run() / reset({halt:false}) | halt() / run() / reset(halt=False) | Cortex-M 暂停、运行、系统复位 |
reg(selector) / regs() | 同名 | 读取暂停的 Cortex-M 寄存器 |
swdSequence(segments) / jtagSequence(segments) | swd_sequence / jtag_sequence | 分段时钟、输出、采集 |
queueCommands(frames) / executeCommands(frames=[]) | queue_commands / execute_commands | 本地排队,再合成 ExecuteCommands 报文 |
close() | close() / async with | 等待当前操作完成并释放会话 |
寄存器 selector 为 R0–R15=0–15,xPSR=16、MSP=17、PSP=18、SPECIAL=20,19保留。 regs() 同时返回 sp/lr/pc 及 primask/basepri/faultmask/control。 writeMemory 的非对齐边缘使用字节写,避免读改写相邻 MMIO;失败时 bytesWritten / bytes_written 表示已确认写入数。它不替代 Flash 擦写算法。
其余 CMSIS-DAP 报文均有封装:hostStatus、transferConfigure、transferAbort、writeAbort、delay、resetTarget、swjPins、swjClock、swjSequence、swdConfigure、swoTransport/Mode/Baudrate/Control/Status/Data/ExtendedStatus、uartTransport/Configure/Transfer/Control/Status;Python 使用相应 snake_case 名称。命令常量导出为 DAP_COMMAND_IDS。封装存在不代表当前固件一定实现 SWO/UART 等可选能力;不支持时返回错误。
resetTarget / reset_target 是 CMSIS-DAP 0x0A 报文,返回 executed,与 Cortex-M reset() 的 AIRCR 系统复位不同。 JTAG 的原始报文和链操作支持 RISC-V TAP;attach/halt/run/reset/reg/regs 及 MEM-AP 内存方法只适用于 Cortex-M/ARM MEM-AP,不提供 RISC-V DMI 抽象,也不提供 RVSWD 原始 CMSIS-DAP。
共享读取和访问互斥
未调用初始化/原始端口操作时,read32/readMemory 默认共享当前 Web RTT 目标读取,不注入 Connect/SELECT/TAR。 它们不会偷偷选择另一个目标;未连接共享目标时返回 no_shared_target。 也可显式使用以下方法(共享目标可以是 SWD/JTAG/RVSWD,取决于板端驱动):
const dap = pico.dap();
try {
const bytes = await dap.readTargetMemory(0x20000000, 512, { protocol: 'current' });
console.log(bytes);
} finally { await dap.close(); }Python 对应 await dap.read_target_memory(0x20000000,512,protocol='current')。 按256字节分块,校验目标 revision;途中目标变化返回 target_changed。 只有显式 protocol:'swd', fallback:true(Python protocol='swd',fallback=True),且板端返回 no_shared_target、owner为none,才会独立初始化 SWD 读取并释放。忙碌或接口不匹配时不抢占。
同一会话的完整复合操作串行化;USB CMSIS-DAP、GDB、Web RTT、脚本等入口按板端仲裁规则使用调试接口。 忙时错误具有 code 和 owner 属性,例如 debugger_busy / gdb。 超时/取消关闭会话,不自动重发写入、擦除或复位。断开不能撤销已经执行的操作。 二进制单报文请求/响应仍受64字节限制,长内存访问由 SDK 分块。 Node 超时为毫秒、Python 为秒,频率为 Hz。硬件尚在运行时关闭会话不等同于停止目标程序。
RTT 目标复位并释放
已有 rtt.scan/attach/enable/disable/detach 与多通道收发保持兼容,新增:
await rtt.resetTarget(); // action 6,复位已连接目标并释放Python 使用 await rtt.reset_target();此操作影响目标运行状态,调用前先确认目标。
Node.js
import { PicoXTools } from 'picoxtools-sdk';
const pico = new PicoXTools('192.168.33.1', { timeout: 10000 });
try {
const bus = await pico.i2c({ sda_pin: 8, clk_pin: 9, clock: 400000 });
try {
console.log(await bus.scan());
// 首先写寄存器地址,再读。此固件会产生 STOP,不是 repeated START。
console.log(await bus.readRegister(0x68, [0x75], 1));
} finally { await bus.close(); }
} finally { pico.close(); }socket.send(string | Uint8Array):string 发 WebSocket 文本,字节数组发二进制。await socket.receive(timeout):返回 string 或 Buffer;for await (const data of socket.messages())持续接收。uart.write(data)/await uart.read(timeout)。串口数据始终二进制,字符串按 UTF-8 编码。bus.read(addr,n)/bus.write(addr,data):每次 1–64 字节。bus.onEvent = frame => ...接收请求过程中混入的 GPIO/从机事件。从机空闲事件可直接读取bus.socket.messages()并用导出的parseFrames解包,不与请求并发读取。- SPI:
spi.transfer([0x9f,0,0,0])同时收发;或spi.transfer([0x9f], {readLength:3,writeThenRead:true})在一次 CS 有效期间先写后读。addr=0且hwcs=0才由固件包围整次事务控制 CS。 - GPIO:
bus.gpioInit(pin,{direction:1,pull:3,edge:0})、gpioRead(pin)、gpioWrite(pin,level)。沿用总线 WS;不要重配当前总线正在使用的引脚。 - 捕获 I2C:
const b=await pico.i2c({i2c_type:2}); for await (const events of b.sniff()) console.log(events)。SPI 则spi_type:2,每条为{mosi,miso}。结束时await b.close()释放外设。
C / PIO:
const shell = await pico.shell(); // 需要看 printf 时再连接
const { image, info } = await pico.compileC('int main(){printf("Hello\\n");return 0;}');
console.log(info); // entry/text/data/calls/ccver
await pico.runC(image); // 交给 Shell 任务异步执行
console.log((await shell.receive()).toString());
await pico.uploadC(image); // 保存 /upload/cc.exe,不执行
await pico.stopC(); // 收回运行程序注册的回调
// const pio = await pico.compilePio(pioSource, {version:1});
// await pico.runC(pio.image);Shell 是连续终端流,一条命令的输出可能分成多条消息,也可能与提示符合并。SDK 不按“收到一条消息”推断命令完成,需要时由调用方识别提示符。
FlashRom
完整复用当前固件配套的 flashrom 芯片库:
const rom = await pico.flashrom({
speed: 20000,
onLog: (level, text) => process.stderr.write(text),
onMatch: model => console.log('匹配:', model),
onProgress: (stage, done, total) => console.log({stage, done, total}),
});
try {
const size = await rom.probe(); // 多型号匹配时指定日志中的完整型号再次 probe(name)
const backup = await rom.image('read');
// await rom.image('write', firmware); // 长度须等于 size;写入后自动校验
// await rom.image('verify', firmware);
// await rom.erase(); // 芯片驱动选择擦除策略
} finally { await rom.close(); }
// 正在操作时取消:await rom.stop(),之后须重新连接。RTT
const rtt = await pico.rtt();
try {
console.log(await rtt.scan('swd', 4000000)); // 'jtag' / 'swd' / 'rvswd'
await rtt.attach(1);
console.log((await rtt.enable({searchTimeout:15000})).channels);
rtt.write(0, 'hello\r\n'); // channel 0..15,单次 <=512 字节
const {channel, data} = await rtt.read(5000);
console.log(channel, data.toString());
await rtt.disable();
await rtt.detach();
} finally { rtt.close(); }rtt.status() 返回固件完整状态;启用 RTT 时禁止重新扫描。查找超时后会向板子发送 disable,释放目标可调用 detach,关闭控制连接也会触发固件清理。
Python
全部是 asyncio API;字节数据用 bytes,文本发送接受 str。对象支持 async with。
import asyncio
from picoxtools import PicoXTools
async def main():
async with PicoXTools('192.168.33.1', timeout=10) as pico:
async with await pico.uart(bit_rate=115200, data_bits=8, parity=0, stop_bits=1) as uart:
await uart.write('hello\r\n')
print(await uart.read(5))
async with await pico.i2c(sda_pin=8, clk_pin=9, clock=400000) as bus:
print(await bus.scan())
print(await bus.read_register(0x68, b'\x75', 1))
async with await pico.spi(clock=20000000, cpol_cpha=0, hwcs=0) as bus:
print(await bus.transfer(b'\x9f', read_length=3, write_then_read=True))
asyncio.run(main())Python 与 Node 的功能对应,方法名采用 snake_case:
# 本地编译,返回 {image: bytes, info: dict, log: str}
built = await pico.compile_c('int main(){return 0;}')
await pico.run_c(built['image'])
await pico.upload_c(built['image'])
await pico.stop_c()
pio = await pico.compile_pio(pio_source, version=1)
async with await pico.flashrom(speed=20000, on_log=print,
on_progress=lambda stage, done, total: print(stage, done, total)) as rom:
size = await rom.probe() # 或 await rom.probe('完整型号')
backup = await rom.read()
# await rom.write(image) # 自动写后校验
# await rom.verify(image)
# await rom.erase()
# await rom.stop() # 取消当前操作并关闭 WS/引擎
async with await pico.rtt() as rtt:
await rtt.scan('rvswd', 4000000)
await rtt.attach(1)
state = await rtt.enable(ram_start=0, ram_end=0, search_timeout=15)
print(state['channels'])
await rtt.write(2, b'hello\r\n')
packet = await rtt.read(5) # {channel: int, data: bytes}
print(packet)
await rtt.disable()
await rtt.detach()离线烧录与 FLM
const chip = await pico.probeTarget(); // 包含 core_cpuid / chip_id,保留原始固件字段
await pico.uploadFlm(flmBytes, chip.chip_id, {ramStart:0x20000000, ramSize:0x2000});
// 文件名 /upload/flash_10006412.algo;使用完整芯片 ID,不用 CPUID。
await pico.uploadFile('/upload/app.bin', firmwareBytes);
await pico.flash(firmwareBytes, {onProgress: p => console.log(p.done, p.total)});
// await pico.flash(firmwareBytes, {eraseOnly:true});chip = await pico.probe_target()
await pico.upload_flm(flm_bytes, chip['chip_id'], ram_start=0x20000000, ram_size=0x2000)
await pico.upload_file('/upload/app.bin', firmware_bytes)
await pico.flash(firmware_bytes, on_progress=lambda p: print(p['done'], p['total']))- 上传/烧录块为 4096 字节数据 + 4 字节小端偏移,最后一块可不足 4096,逐块确认偏移/长度/总数。
erase=true / erase=True在写之前请求固件擦除;eraseOnly / erase_only仅擦除。擦除范围按当前固件与图像长度处理,语义和前端一致,不承诺所有 MCU 都是整片擦除。FlashRom 的 SPI 芯片擦除是另一条路径。- 本地 HEX/ELF/BIN 解析:
await pico.loadFirmware(data, 'app.hex')返回bytes/base/...;Pythonawait pico.load_firmware(data,'app.hex')返回data/base/...。FLM 只用uploadFlm/upload_flm或引擎层convertFlm/convert_flm转换,不能把原始 FLM 当固件烧录。 /ws/flash目标烧录路径没有任意基地址参数,由板端已探测目标与烧录算法决定地址。HEX/ELF 的 base 只用于检查,不会自动通过不存在的参数传给板子。确认匹配再传入平坦二进制。- 取消 Node 烧录可关闭
pico.close();Python 取消当前 task 时 finally 会关闭该次烧录连接。取消不能撤销已完成的擦写。
其它原始流
usbSniffer / usb_sniffer、logicAnalyzer / logic_analyzer 返回 CaptureStream:
const capture = await pico.usbSniffer();
console.log(await capture.read()); // 板子主动发送 ready
capture.command('start', {pin:8}); // D+=8, D-=9
const message = await capture.read(); // {type:'status'|'data', data}
capture.stop(); capture.close();Python 为 await capture.command('start', pin=8) / await capture.read() / await capture.stop()。 逻辑分析仪 start 参数:{pin:2,ch:4,rate:100000,trig:0,tpin:4,limit:0},另有 status/trigger/stop。 这里保留原始采集数据,不实现前端渲染、USB 事务分组和波形 UI。USB 二进制记录可用包内独立模块 vendor/usb_fs.mjs(Python 包内为 _engine/vendor/usb_fs.mjs) 的 LitePackets 解包(板端已经完成 USB 解码);DAP Monitor 仅用于侦听,主动调试请使用 pico.dap()。
并发与错误
- 板子的多数 WS 端点只允许一个客户端。页面仍打开对应功能时,SDK 连接可能替换页面连接;使用同一功能时只保留一个操作者。RTT 还与 GDB 互斥。
- I2C/SPI 没有请求序号,客户端对同一总线的请求串行排队,按 oper/addr 匹配响应。超时会关闭该连接,防止迟到响应被误配;重新 open/connect 后再重试。
- 一个原始 socket 只允许一个接收消费者。不要同时
receive()、messages()和总线 request/sniff;使用独立应用任务处理分发。 bus.close()/uart.close()还会通过 HTTP 释放外设;pico.close()负责关闭其所有 WS。Node 用 try/finally,Python 用 async with 释放 bus 对象。- 目标/总线错误抛出异常;短读、无应答、上传确认异常不会被当作成功。Python RTT 查找超时会停用,Node 相同。错误不会被自动重放为可能重复的写入。
- 编译后的 C 程序与 USB Sniffer 共享板内 RAM,固件仍会执行互斥检查。SPI/FlashRom/DAP 等共用 GPIO,也需要先释放占用。
验证
python3 -m venv /tmp/picoxtools-sdk-test
/tmp/picoxtools-sdk-test/bin/pip install -e ./sdk/python
/tmp/picoxtools-sdk-test/bin/python sdk/tests/test_clients.py -v
# 仅本地 WASM / 帧格式,不需要模拟服务:
node --test sdk/tests/node.test.mjs综合测试启动回环地址上的独立 HTTP/WS 模拟设备,再让 Python 和 Node 客户端连接它。覆盖主模块协议、早到回复、串行请求、事件混入、分块偏移、RTT 通道、搜索超时、断线及真实 C/PIO/FlashRom WASM。FlashRom 测试模拟 Winbond NOR,经真实芯片库完成读取、写入校验与擦除。没有对实物目标执行测试烧录。
依赖与复用资源见 依赖与许可证。