Skip to content

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 工程的电脑上安装:

sh
# 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.whl

Node 导入 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.jsPython板端路径
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 FlashRomawait pico.flashrom(options)await pico.flashrom(**options)/ws/serprog
本地 C/PIO 编译compileC / assemblePio / compilePiocompile_c / assemble_pio / compile_pio本地 WASM,不访问板子
C 镜像运行/保存/停止runC / uploadC / stopCrun_c / upload_c / stop_c/api/cc/run / upload / stop
SWD 目标探测probeTarget()probe_target()/api/swd_port
MCU 烧录/文件保存flash / uploadFileflash / 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:

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):

python
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.jsPython作用
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_dpDP 访问
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,取决于板端驱动):

js
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 与多通道收发保持兼容,新增:

js
await rtt.resetTarget(); // action 6,复位已连接目标并释放

Python 使用 await rtt.reset_target();此操作影响目标运行状态,调用前先确认目标。

Node.js ​

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:

js
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 芯片库:

js
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 ​

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

python
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:

python
# 本地编译,返回 {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 ​

js
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});
python
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/...;Python await 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:

js
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,也需要先释放占用。

验证 ​

sh
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,经真实芯片库完成读取、写入校验与擦除。没有对实物目标执行测试烧录。

依赖与复用资源见 依赖与许可证。