carrot-io (cio) - 极简硬件抽象层与总线通信库

极简、零顶层强依赖、优雅静默降级的高性能 Python 3.12+ 硬件抽象层与设备验证库。

carrot-io（导入包名：cio）为串口（UART）、工业仪器（VISA / 示波器 / SCPI）、总线外设（I2C / SPI / GPIO）、网络管道（TCP / UDP）及 CH347 多协议硬件底座提供了统一的标准 RFC 3986 URL 访问模型与纯异步核心 + 统一同步调度双模架构。

📖 权威文档导航：

• 📘 用户态 API 参考与速查手册 (API.md)：包含全部 URL 语法、总线方法签名、断言验证测试模板。
• 📄 下位机 ASCII 协议规范 (CARROT_PROTOCOL.md)：MCU 下位机固件与协议桥交互格式。
• 🛠️ 架构规范与 AI Agent 开发者手册 (AGENTS.md)：分层解耦、并发锁与底层红线设计原则。

目录

• 一、安装与可选依赖
• 二、5 秒极速上手
• 三、典型硬件场景 (由浅入深)
  • 1. 串口与以太网通信 (Serial / TCP)
  • 2. 示波器与工业仪器控制 (VISA / SCPI)
  • 3. I2C 传感器与 SPI 外设读写
  • 4. GPIO 引脚电平控制
  • 5. 沁恒 CH347 高速 USB 多协议底座
• 四、生产力工程特性
  • 1. 实时通信抓包高亮与故障历史 (trace / dump_history)
  • 2. 环境变量单例注入 (from cio import dev)
  • 3. 芯片与硬件 DSL 验证断言 (check / verify)
  • 4. 跨网络透明 RPC 代理 (rpc://)
• 五、核心类与 API 极速速查 (Cheat Sheet)
  • 1. 物理流传输类 (AsyncStreamTransport / VisaTransport)
  • 2. I2C 主机总线类 (AsyncI2cTransport / AsyncI2cBridge)
  • 3. SPI 主机总线类 (AsyncSpiTransport / AsyncSpiBridge)
  • 4. GPIO 引脚控制类 (AsyncGpioPin / AsyncGpioBridge)
  • 5. 协议编解码器 (dev.bind(codec))
  • 6. 测试验证断言与记分板 (cio.testing.verify)
  • 7. 顶层入口与快捷构造 (cio.*)
• 六、自动化测试
• 七、开源协议

一、安装与可选依赖

核心库保持零第三方强依赖，仅使用 Python 3.12+ 标准库。外部驱动按需延迟加载：

# 使用 uv (推荐)
uv add carrot-io                  # 核心库 (支持 TCP/UDP/RPC/Mock，零额外依赖)
uv add "carrot-io[serial]"        # 串口支持 (pyserial)
uv add "carrot-io[visa]"          # 示波器与工业仪表支持 (pyvisa)
uv add "carrot-io[ftdi]"          # FTDI 芯片支持 (pyftdi)
uv add "carrot-io[all]"           # 全量依赖安装

# 使用 pip
pip install "carrot-io[serial,visa]"

二、5 秒极速上手

无论是自动化脚本还是交互式终端，cio 支持统一的 URL 连接与无缝同步/异步自动切换：

import cio

# 1. 一键静默扫描系统在线设备（自动跳过未安装驱动的后端）
print(cio.scan())

# 2. 同步模式：直接使用 with 上下文（常规测试脚本最爱，零异步心智负担）
with cio.connect("serial://COM3?baud=115200") as dev:
    dev.write(b"PING\n")
    print(dev.read_until(b"\n"))

# 3. 异步模式：使用 async with 保持原生高性能协程调度
# async with cio.connect("serial://COM3?baud=115200") as dev:
#     await dev.write(b"PING\n")
#     print(await dev.read_until(b"\n"))

三、典型硬件场景 (由浅入深)

1. 串口与以太网通信 (Serial / TCP)

支持精确字节读取、定界符截取与超时控制：

import cio

# 串口设备
with cio.serial("COM3", baud=115200, timeout=2.0) as dev:
    dev.write(b"AT+GMR\r\n")
    response = dev.read_until(b"OK\r\n")
    print("AT Response:", response)

# 以太网 TCP 设备 (例如网口仪表或嵌入式设备端口)
with cio.tcp("192.168.1.100", 5025, timeout=3.0) as dev:
    dev.write(b"*IDN?\n")
    print("TCP Reply:", dev.read_until(b"\n"))

2. 示波器与工业仪器控制 (VISA / SCPI)

支持 USB-TMC、GPIB、TCPIP 等符合 VISA 规范的仪器设备。兼容系统已安装的 NI-VISA、Keysight VISA 驱动与纯 Python 后端：

import cio

# 扫描连接的所有 VISA 仪器 (自动列出示波器、万用表等)
instruments = cio.scan("visa")
print("Found Instruments:", instruments)

# 原生字符串重载：直接传入 SCPI 字符串，自动补齐换行并解码返回 str
with cio.visa("USB0::0x2A8D::0x9007::MY63160152::INSTR", timeout=5.0) as scope:
    # 问答式查询
    idn = scope.query("*IDN?")
    print("示波器型号与版本:", idn)

    # 发送配置控制指令
    scope.write("*CLS")
    scope.write(":AUToscale")

    # 若需要读取波形数据块等原始二进制，直接传入 bytes 即可获取原始 bytes
    # raw_wave = scope.query(b":WAV:DATA?\n")

3. I2C 传感器与 SPI 外设读写

通过标准 URL 语法直连单片机/测试桥底座（默认串口通讯，下位机运行 CarrotBridge 固件）：

import cio

# I2C 总线操作 (自动推导为串口底层通信)
with cio.connect("i2c://COM3?baud=2000000&reg_len=2") as i2c:
    # 扫描在线从机地址
    slaves = i2c.scan()
    print("Online I2C Slaves:", [hex(s) for s in slaves])

    # 读写 16 位寄存器 (支持直接传入 int、列表或 bytes)
    i2c.write_reg(addr=0x57, reg=0x0100, data=[0xAA, 0x55])
    val = i2c.read_reg(addr=0x57, reg=0x0100, nbytes=2)
    print("Reg 0x0100:", val.hex())

# SPI 总线全双工收发 (例如读取 SPI Flash JEDEC ID)
with cio.connect("spi://COM3?baud=2000000&cs=0") as spi:
    # 发送 0x9F 命令，同时读回 3 字节厂商与设备 ID
    rx = spi.transfer([0x9F, 0x00, 0x00, 0x00])
    print(f"SPI Flash ID: 0x{rx[1]:02X}{rx[2]:02X}{rx[3]:02X}")

4. GPIO 引脚电平控制

import cio

with cio.connect("gpio://COM3?pin=1") as gpio:
    gpio.set_high()
    print("Current Level:", gpio.read_level())
    gpio.toggle()

5. 沁恒 CH347 高速 USB 多协议底座

支持利用单一 CH347 芯片同时进行原生硬件 I2C/SPI 操作与双串口全双工收发：

import cio

# 打开 CH347 硬件原生 I2C 主机 (400kHz)
with cio.connect("i2c://0?transport=ch347&frequency=400000") as i2c:
    i2c.write(0x44, [0x24, 0x00])
    data = i2c.read(0x44, 6)
    print("Sensor Data:", data.hex())

四、生产力工程特性

1. 实时通信抓包高亮与故障历史 (trace / dump_history)

无需任何第三方抓包器，在任意 URL 尾部追加 ?trace=on 即可在控制台实时微秒级高亮打印 TX/RX 报文：

import cio

# 开启实时报文跟踪
with cio.connect("serial://COM3?baud=115200&trace=on") as dev:
    dev.write(b"HELLO")
    dev.read(5)

    # 任何时候可调取最近通讯历史（用于错误报告或记录日志）
    print(dev.dump_history(limit=10))

2. 环境变量单例注入 (from cio import dev)

通过 .env 或环境变量 CIO_DEVICE 声明设备，脚本内直接调用，彻底消除测试脚本中的硬编码端口：

# 在当前目录 .env 文件中声明
CIO_DEVICE="visa://USB0::0x2A8D::0x9007::MY63160152::INSTR"

from cio import dev

# 无需手动 connect，开箱即用，进程退出时由 atexit 自动安全释放句柄
idn = dev.query("*IDN?")
print("Auto-injected device:", idn)

3. 芯片与硬件 DSL 验证断言 (check / verify)

专为芯片寄存器回归测试与产测冒烟脚本打造，提供掩码过滤、Hex 对齐比对与记分板看板：

import cio
from cio import check, require, verify

with cio.connect("i2c://COM3") as i2c:
    verify.reset()

    # 1. check 记录断言结果并不中断执行；支持掩码比对
    check(i2c.read_reg(0x57, 0x00, 1), 0x07, mask=0x07, name="STATUS_REG")

    # 2. require 遇到错误立即中断并输出现场 Hex Diff
    require(i2c.read_reg(0x57, 0x01, 1), 0x10, name="CHIP_ID")

    # 3. 打印本次测试看板
    verify.summary()

4. 跨网络透明 RPC 代理 (rpc://)

远端主机启动服务，本地直接透明控制远端硬件，协议自动解包转发：

# 远端主机一行启动网关
python -c "import asyncio, cio; asyncio.run(cio.start_rpc_server('0.0.0.0', 8000))"

# 本地透明代理调用
with cio.connect("rpc://192.168.1.50:8000/COM1?baud=115200") as dev:
    dev.write(b"HELLO")

5. 多通道数据采集与实时落盘 (cio.Collector)

测试中散落在各处的测量值，通过统一单一方法 collect(...) 汇聚，每个 Tag 天然作为独立 1D 向量存储：

import cio

# 打开收集器 (指定文件则实时流式追加落盘，Crash-Safe 防断电数据丢失)
with cio.Collector("run.csv") as col:
    # 1. 关键字多通道同时打点 (最直观)
    col.collect(CH1=5.01, CH2=3.32, TEMP=25.4)
    # 2. 单点打点带单位
    col.collect(5.05, tag="CH1", unit="V")
    # 3. 连续波形向量直接注入
    col.collect([1.1, 1.2, 1.3], tag="WAVE")
    # 4. 直接获取 1D 向量与切片
    print(col["CH1"][:2])  # [5.01, 5.05]
    # 5. 抗毛刺中位数与均值
    print("中位数:", col.median("CH1"))
    # 6. 一键终端看板
    col.print_summary()

五、核心类与 API 极速速查 (Cheat Sheet)

无需每次翻阅底层源码与完整手册，核心类名、方法签名与极简用法速查：

1. 物理流传输类 (AsyncStreamTransport / VisaTransport)

适用于：串口、TCP、VISA 示波器与工业仪器、FTDI

2. I2C 主机总线类 (AsyncI2cTransport / AsyncI2cBridge)

适用于：I2C 传感器、EEPROM、外设配置芯片

3. SPI 主机总线类 (AsyncSpiTransport / AsyncSpiBridge)

适用于：SPI Flash、高速 ADC/DAC、外置通信芯片

4. GPIO 引脚控制类 (AsyncGpioPin / AsyncGpioBridge)

适用于：硬件复位引脚、片选 CS 控制、电平检测与边沿中断

5. 协议编解码器 (dev.bind(codec) -> ProtocolTransport)

适用于：为底层生肉字节管道绑定强类型结构化帧收发

6. 测试验证断言与记分板 (cio.testing.verify)

适用于：芯片寄存器冒烟测试、产测判断看板

7. 顶层入口与快捷构造 (cio.*)

8. 多通道时序数据收集器 (cio.Collector)

适用于：电压/电流/温度巡检、示波器波形捕获、抗毛刺中位数统计与实时 CSV 写入

六、自动化测试

cio 拥有完备的自动化测试矩阵。常规单元测试与真实硬件在环测试实现了严格的物理隔离：

# 运行常规单元测试与边界测试 (CI 默认模式，秒级全量执行，零硬件依赖)
uv run pytest -m "not hardware" -v

# 运行真实物理示波器/硬件在环测试 (需连接实际硬件)
uv run pytest tests/test_visa_hardware.py -m hardware -v

七、开源协议

本项目采用 MIT License 许可开源。