UTools-SI104 文档

解决什么问题

在板级调试、模块测试和产线夹具里，上位机经常需要同时访问多个 I2C 器件、模拟一个 I2C 从机寄存器区，或者对 SPI 器件做快速收发验证。UTools-SI104 把这些访问统一到一台 USB 设备里：

数据如何流动

核心能力

规格速览

适合哪些应用

交付特色

典型工作流程

目录与阅读路径

快速接入

1. 先阅读 产品定位、USB 枚举与接口布局。
2. Windows 上位机优先阅读 WinUSB 接入；Linux 系统集成优先阅读 Linux I2C 驱动。
3. 需要脚本调试时阅读 Python CLI 使用。

协议开发

1. 先阅读 私有协议帧格式、状态码、命令集。
2. I2C 主机/从机功能阅读 I2C 功能模型。
3. SPI 功能阅读 SPI 功能模型；OTA 仅作为上位机维护能力说明。

测试与维护

1. 产线夹具阅读 硬件自测试。
2. 问题定位阅读 调试与诊断。
3. 固件维护由上位机软件承载。

1. 产品定位

UTools-SI104 是一款 USB 多总线桥接设备。当前工程默认固件采用 USB Vendor Bulk 私有协议，面向以下场景：

• 上位机直接访问 4 路独立 I2C 总线。
• 上位机访问 1 路 SPI 总线。
• 将任意一路 I2C 配置为从机，提供 raw、mailbox、register 三类行为。
• 使用 8KB I2C 从机缓存和虚拟地址页映射，模拟寄存器型器件。
• 通过独立 OTA 功能进行应用固件维护。
• 在 Windows 侧通过 MS OS 2.0 描述符自动绑定 WinUSB。
• 在 Linux 侧通过私有 Bulk I2C 驱动映射为标准 i2c_adapter。

2. 系统架构

2.1 运行时数据路径

Host CLI / app
    |
    | USB Bulk frame
    v
SI104 USB RX task
    |
    +--> I2C task --> private_i2c.c --> i2c_port.c
    |
    +--> SPI task --> private_spi.c --> spi_port.c
    |
    +--> Host-managed OTA maintenance path
    |
    v
USB TX lane --> Host response

USB 中断侧只负责收包入队和重新挂载端点，协议执行放在 RTOS 任务中完成，以避免在中断上下文中执行耗时总线事务。

3. USB 枚举与接口布局

3.1 设备标识

3.2 接口与端点

默认 I2C/SPI 接口为 Vendor Specific 类，使用私有子类区分 I2C/SPI，协议字段为 0x04。OTA 功能由上位机软件管理，本文档不展开其协议细节。

3.3 Windows WinUSB

固件发布 MS OS 2.0 描述符，Windows 应自动将 MI_00 到 MI_05 绑定为 WinUSB：

如果 Windows 仍显示 Code 28，可运行：

.\tools\windows_driver\refresh_si104_winusb.ps1

然后重新插拔设备。

4. 外部连接器

设备外部连接器为 24PIN 双排牛角座（2x12），按从左到右分区：

• SPI0
• I2C3
• I2C2
• I2C1
• I2C0

说明：

• I2C 每路占 2 列：信号列 SCL/SDA 和电源列 GND/VCC。
• 表中 SPI 信号省略 SPI0_ 前缀，I2C 信号通过分区区分通道。
• I2C VCC 输出受固件保护逻辑控制，打开前会检测外部电压。

5. 私有协议帧格式

所有多字节字段均为 little-endian。USB OUT 请求和 USB IN 响应使用相同帧头。

typedef struct __attribute__((packed)) {
    uint16_t magic;       // 0xA55A
    uint8_t  version;     // 0x01
    uint8_t  cmd;         // command id
    uint8_t  channel;     // i2c: 0..3, spi: 0
    uint8_t  reserved;    // 0
    uint16_t seq;         // host sequence id
    uint16_t payload_len; // payload bytes
    uint16_t status;      // response status, request=0
} private_proto_hdr_t;

协议限制：

• PRIVATE_PROTO_MAX_DATA = 512
• 最大帧长为 12 + 512 = 524 字节。
• I2C_MASTER_XFER 请求负载包含 8 字节事务头，因此主机写方向单次最多携带 504 字节数据。
• I2C_MASTER_XFER 开启 VCC 监测时响应尾部占用 6 字节，因此读方向单次最多返回 506 字节数据；关闭 VCC 监测时可返回 512 字节。
• I2C_REG_WRITE 请求负载包含 4 字节偏移/长度头，因此单次最多写入 508 字节缓存数据。
• SPI_XFER 请求负载包含 8 字节事务头，因此 SPI 写方向单次最多携带 504 字节数据，读方向最多返回 512 字节。

6. 状态码

7. 命令集

7.1 通用命令

7.2 I2C 命令

7.3 SPI 命令

8. I2C 功能模型

8.1 通道配置

typedef struct __attribute__((packed)) {
    uint8_t  role;        // 0 master, 1 slave
    uint8_t  i2c_mode;    // 0 standard, 1 fast, 2 fast-plus, 3 custom
    uint8_t  addr_10bit;  // 0/1
    uint8_t  reserved;    // slave mode and register flags
    uint32_t bus_hz;
    uint16_t slave_addr;
    uint16_t timeout_ms;
} private_i2c_cfg_req_t;

reserved 字段按位编码从机行为：

速率建议：

8.2 主机传输

typedef struct __attribute__((packed)) {
    uint16_t addr;
    uint16_t flags;
    uint16_t tx_len;
    uint16_t rx_len;
    uint8_t  data[];
} private_i2c_master_xfer_req_t;

当固件检测到 I2C 总线缺少可用上拉供电时，传输可能返回 NO_POWER。上位机应先查询或设置 VCC。

8.3 从机模式

寄存器模式支持：

• 8-bit 或 16-bit 寄存器地址。
• 8-bit 或 16-bit 数据宽度提示。
• little/big endian 数据提示。
• 事件队列记录外部主机写入、指针设置、主机侧缓存写入。

8.4 虚拟地址缓存

每个 I2C 通道拥有 8KB 缓存，划分为 32 个 256B 页：

• page0 固定映射到逻辑地址 0x00xx。
• page1..page31 可绑定到虚拟高字节 0x01..0xFE。
• 解绑值为 0xFF。
• 未映射虚拟页读返回 0x00，写入被忽略。

逻辑地址映射：

addr = (hi << 8) | lo

if hi == 0x00:
    physical = lo
else if hi is mapped:
    physical = mapped_page * 256 + lo
else:
    unmapped

8.5 事件轮询

I2C_EVENT_POLL 响应：

typedef struct __attribute__((packed)) {
    uint8_t  type;       // 0 no event, 1 master write, 2 pointer set, 3 host reg write
    uint8_t  sample_len; // 0..32
    uint16_t addr;
    uint16_t len;
    uint16_t dropped;
    uint8_t  sample[32];
} private_i2c_event_poll_rsp_t;

上位机可通过事件轮询知道外部 I2C 主机写入了哪个逻辑地址、长度和采样数据，并观察事件队列是否发生丢包。

8.6 VCC 控制

I2C VCC 是设备级共享电源轨，对 CH0..CH3 四路 I2C 连接器同时生效，并不是 CH0 专用电源。上位机 CLI 默认通过 CH0 私有端点路由 VCC 命令，以保持工具入口稳定；命令效果仍作用于全部 I2C 通道：

• I2C_VCC_SET：开启/关闭输出，可选择保存状态。
• I2C_VCC_THRESHOLD：查询或设置外部电压保护阈值。

响应字段包括输出状态、持久化状态、阈值、ADC 电压、失败原因、操作结果和测量电压。常见失败原因：

9. SPI 功能模型

9.1 SPI 配置

SPI 支持主机模式和 single-I/O 从机模式。标准使用场景以主机模式为主；从机模式用于外部 SPI master 夹具验证。

说明：

• 主机模式下 sclk 超过 40 MHz 会被 CLI/客户端库拒绝，或由固件返回参数错误。
• 主机 single-I/O 传输长度超过外设 FIFO 容量时，固件会在 DMA 可用时自动优先使用 DMA。
• 从机模式仅支持 single-I/O，实际验证需要外部 SPI master 提供 SCLK。

9.2 SPI 传输

SPI_XFER 支持：

• tx-only。
• rx-only。
• full-duplex。
• 单次传输负载受 512 字节协议上限约束。
• 可在单次传输上覆盖 DMA 选项，也可用 no-DMA 选项强制走 FIFO 路径用于对比。

典型读取 JEDEC ID：

python si104_cli.py spi-config --cpol 0 --cpha 0 --bit-order msb --data-bits 8 --sclk 1000000
python si104_cli.py spi-xfer --tx "9F" --rx-len 3

10. OTA 功能

标准固件保留独立 OTA 维护能力，用于上位机软件执行固件升级和维护。本文档不定义 OTA 操作流程、脚本接口或升级参数；对外协议脚本仅覆盖 I2C/SPI 私有协议能力。

11. Python CLI 使用

11.1 安装依赖

pip install pyusb

11.2 全局参数

11.3 参数总表

类型约定：

全局参数：

I2C 参数：

i2c-ping、i2c-version、i2c-status、i2c-event-poll、i2c-vaddr-get、i2c-reset 仅需 --ch。i2c-vcc-status/set/threshold 默认通过 CH0 路由，通常不需要指定 --ch；VCC 供电效果对 CH0..CH3 同时生效。

SPI 参数：

11.4 I2C 主机示例

# 连通性测试
python si104_cli.py i2c-ping --ch 0

# 配置 400kHz I2C 主机
python si104_cli.py i2c-config --ch 0 --role master --mode fast --timeout 1000

# 写寄存器
python si104_cli.py i2c-write --ch 0 --addr 0x50 --data "00 01 A5"

# 写后读
python si104_cli.py i2c-wr --ch 0 --addr 0x50 --tx "00" --rx-len 8

# 读取完整 512 字节时关闭 VCC 尾部监测
python si104_cli.py i2c-read --ch 0 --addr 0x50 --rx-len 512 --monitor-vcc 0

# 扫描地址
python si104_cli.py i2c-scan --ch 0 --start 0x03 --end 0x77

11.5 I2C 从机缓存示例

# 配置 CH0 为 16-bit 地址 + 8-bit 数据的寄存器从机
python si104_cli.py i2c-config --ch 0 --role slave --slave-addr 0x30 --slave-mode reg --reg-addr-width 16 --data-width 8

# 绑定 slot1 到虚拟高字节 0x12
python si104_cli.py i2c-vaddr-set --ch 0 --slot 1 --vaddr 0x12

# 写入缓存
python si104_cli.py i2c-reg-write --ch 0 --offset 0x1200 --data "11 22 33 44"

# 读取缓存
python si104_cli.py i2c-reg-read --ch 0 --offset 0x1200 --len 16

# 轮询事件
python si104_cli.py i2c-event-poll --ch 0

11.6 VCC 示例

# 查询 VCC 状态
python si104_cli.py i2c-vcc-status

# 请求打开 VCC，不保存
python si104_cli.py i2c-vcc-set --enable 1

# 设置阈值为 1000mV 并保存
python si104_cli.py i2c-vcc-threshold --set-mv 1000 --save 1

12. Linux I2C 驱动

kernel_driver/si104_i2c.c 是第一阶段 out-of-tree Linux kernel module，目标是把 4 路 SI104 私有 Bulk I2C 接口注册为标准 Linux I2C adapter。

已实现范围：

• 绑定 34b7:e481 的 I2C 接口 0..3。
• CH0..CH3 分别使用 0x01/0x81 到 0x04/0x84。
• 支持一条消息写、一条消息读、两条消息写后读 repeated-start。
• 支持常见 SMBus 访问通过 I2C core emulation，暂不支持 SMBus quick。
• 可通过模块参数或 sysfs 请求固件保护下的共享 VCC 输出，VCC 对 CH0..CH3 同时生效。

加载示例：

sudo insmod si104_i2c.ko enable_vcc=1 bus_hz=400000 i2c_timeout_ms=1000 usb_timeout_ms=3000
i2cdetect -l
sudo i2cdetect -y -r <bus>

运行时控制共享 VCC：

find /sys/bus/usb/drivers/si104_i2c -name vcc_enable -print
echo 1 | sudo tee /sys/bus/usb/drivers/si104_i2c/<usb-interface>/vcc_enable
echo 0 | sudo tee /sys/bus/usb/drivers/si104_i2c/<usb-interface>/vcc_enable

模块参数：

未实现范围：

• SI104 私有从机/register/mailbox/vaddr 控制面。
• SPI controller driver。
• OTA 维护能力由上位机软件承载。

13. 硬件自测试

自测试脚本路径：

test_scripts/si104_self_test.py

默认夹具接线：

• I2C CH0 <-> CH1
• I2C CH2 <-> CH3
• SPI MOSI <-> MISO

常用命令：

# 默认 smoke 测试
python test_scripts/si104_self_test.py

# 私有协议非破坏性矩阵
python test_scripts/si104_self_test.py --suite private --report-json reports/si104_self_test_private.json

# 完整矩阵
python test_scripts/si104_self_test.py --suite all --report-json reports/si104_self_test_all.json

# 性能测试
python test_scripts/si104_self_test.py --suite perf --perf-iterations 1000 --perf-payload-len 256

测试套件：

默认 --vcc auto 会先请求固件 VCC 保护逻辑打开 I2C 上拉供电；若检测到外部电压已超过阈值，固件会拒绝打开输出，脚本继续使用外部供电。

14. 调试与诊断

14.1 设备未找到

检查：

• VID/PID 是否为 34b7:e481。
• Windows 是否已绑定 WinUSB。
• 多设备场景是否需要 --serial。
• Linux 下当前用户是否具备 USB 访问权限。

14.2 I2C 返回 NO_POWER

可能原因：

• 目标 I2C 总线没有外部上拉电源。
• SI104 内部 VCC 未打开。
• 外部电压超过保护阈值，固件拒绝打开 VCC 输出。

建议：

python si104_cli.py i2c-vcc-status
python si104_cli.py i2c-vcc-set --enable 1

14.3 I2C 读写超时

检查：

• 目标地址是否存在。
• --mode 与 --bus-hz 是否适合目标器件。
• I2C 线序、上拉、电平是否正确。
• 从机模式是否未复位导致通道状态残留，可执行 i2c-reset。

14.4 SPI 读数异常

检查：

• CPOL/CPHA 是否与目标器件匹配。
• MISO/MOSI/CLK/CS 线序是否正确。
• sclk 是否超过 40 MHz 或超出夹具信号完整性能力。
• 是否需要关闭或开启 DMA 做对比。

15. 技术规格

16. 发布资料索引

17. 修订历史

Copyright (c) 2026 LanMotion.