UTools-SI104 Docs

What problem is solved?

In board-level debugging, module testing, and production fixtures, host software often needs to access multiple I2C devices at the same time, emulate an I2C slave register area, or quickly verify SPI transfers. UTools-SI104 unifies these access paths into one USB device:

How data flows

Core Capabilities

Quick specs

Which applications are suitable?

Delivery Features

Typical workflow

Directory and reading path

Quick access

1. Read Product Positioning, USB Enumeration and Interface Layout first.
2. Windows host computer reads WinUSB access first; Linux system integration reads Linux I2C driver first.
3. Read Python CLI usage when you need to debug scripts.

Protocol Development

1. Read Private Protocol Frame Format, Status Code, Command Set first.
2. I2C master/slave function reading I2C functional model.
3. Please read SPI Function Model for SPI; OTA is only described as a host-managed maintenance capability.

Testing and Maintenance

1. Production line fixture reading Hardware self-test.
2. Read Debugging and Diagnosis for problem location.
3. Firmware maintenance is handled by the host application.

1. Product positioning

UTools-SI104 is a USB multi-bus bridge device. The current project default firmware uses the USB Vendor Bulk private protocol, which is targeted at the following scenarios:

• The host computer directly accesses 4 independent I2C buses.
• The host computer accesses 1 SPI bus.
• Configure any I2C channel as a slave, providing three types of behaviors: raw, mailbox, and register.
• Emulates a register-based device using 8KB I2C slave cache and virtual address page mapping.
• Application firmware maintenance through an independent OTA function.
• Automatic binding of WinUSB via MS OS 2.0 descriptor on Windows side.
• Map to standard i2c_adapter on Linux side via private Bulk I2C driver.

2. System architecture

2.1 Runtime data path

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

The USB interrupt side is only responsible for collecting packets into the queue and remounting the endpoint. The protocol execution is completed in the RTOS task to avoid executing time-consuming bus transactions in the interrupt context.

3. USB enumeration and interface layout

3.1 Device identification

3.2 Interfaces and endpoints

The default I2C/SPI interfaces are Vendor Specific classes with private subclasses for I2C/SPI and protocol field 0x04. OTA is managed by the host application, and this document does not define its protocol details.

3.3 Windows WinUSB

Firmware releases MS OS 2.0 descriptors and Windows should automatically bind MI_00 to MI_05 as WinUSB:

If Windows still shows Code 28, run:

.\tools\windows_driver\refresh_si104_winusb.ps1

Then reseat the device.

4. External connector

The external connector of the device is 24PIN double row horn socket (2x12), divided from left to right:

• SPI0
• I2C3
• I2C2
• I2C1
• I2C0

Description:

• Each I2C channel occupies 2 columns: signal column SCL/SDA and power column GND/VCC.
• The SPI0_ prefix is ​​omitted for the SPI signals in the table, and the I2C signals distinguish the channels through partitions.
• The I2C VCC output is controlled by firmware protection logic and detects external voltage before turning on.

5. Private protocol frame format

All multibyte fields are little-endian. USB OUT requests and USB IN responses use the same frame header.

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;

Agreement restrictions:

• PRIVATE_PROTO_MAX_DATA = 512
• The maximum frame length is 12 + 512 = 524 bytes.
• The I2C_MASTER_XFER request payload contains an 8-byte transaction header, so a master write can carry up to 504 bytes of data.
• When VCC telemetry is enabled, the I2C_MASTER_XFER response reserves a 6-byte tail; a master read can return up to 506 bytes. With VCC telemetry disabled, a master read can return 512 bytes.
• I2C_REG_WRITE request payload contains a 4-byte offset/length header, so a maximum of 508 bytes of cached data can be written at a time.
• The SPI_XFER request payload contains an 8-byte transaction header, so SPI TX can carry up to 504 bytes and SPI RX can return up to 512 bytes.

6. Status code

7. Command set

7.1 Common commands

7.2 I2C commands

7.3 SPI commands

8. I2C functional model

8.1 Channel configuration

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;

The reserved field bitwise encodes the slave behavior:

Rate recommendations:

8.2 Host transmission

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;

When firmware detects a lack of available pull-up power on the I2C bus, the transfer may return NO_POWER. The host computer should query or set VCC first.

8.3 Slave mode

Register mode supports:

• 8-bit or 16-bit register address.
• 8-bit or 16-bit data width hint.
• little/big endian data tips.
• The event queue records external host writes, pointer settings, and host-side cache writes.

8.4 Virtual address cache

Each I2C channel has 8KB cache divided into 32 256B pages:

• page0 is fixedly mapped to logical address 0x00xx.
• page1..page31 can be bound to the virtual high byte 0x01..0xFE.
• The unbinding value is 0xFF.
• Unmapped virtual page reads return 0x00, writes are ignored.

Logical address mapping:

addr = (hi << 8) | lo

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

8.5 Event Polling

I2C_EVENT_POLL response:

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;

The host computer can know which logical address, length and sampling data are written by the external I2C host through event polling, and observe whether packet loss occurs in the event queue.

8.6 VCC control

I2C VCC is a device-level shared rail for all four I2C connectors, so enabling it affects CH0..CH3 and is not CH0-only. The host CLI routes VCC commands through the CH0 private endpoint by default to keep the tool entry stable; the effect still applies to all I2C channels:

• I2C_VCC_SET: Turn on/off output, optionally save status.
• I2C_VCC_THRESHOLD: Query or set the external voltage protection threshold.

Response fields include output status, persistence status, threshold, ADC voltage, failure reason, operation result, and measured voltage. Common reasons for failure:

9. SPI functional model

9.1 SPI configuration

SPI supports master mode and single-I/O slave mode. The standard use case is master mode; slave mode is intended for external SPI master fixture verification.

Notes:

• In master mode, sclk values above 40 MHz are rejected by the CLI/client library or by firmware as a parameter error.
• For master single-I/O transfers larger than the peripheral FIFO capacity, firmware automatically prefers DMA when DMA is available.
• Slave mode supports single-I/O only and requires an external SPI master to provide SCLK for verification.

9.2 SPI transmission

SPI_XFER supports:

• tx-only.
• rx-only.
• full-duplex.
• Single transfer payload is subject to the protocol limit of 512 bytes.
• DMA options can be overridden on a single transfer. The no-DMA option can force the FIFO path for comparison.

Typical read 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 Function

The standard firmware keeps an independent OTA maintenance capability for host application firmware upgrade and maintenance. This document does not define OTA operation flows, script interfaces, or upgrade parameters; public protocol scripts only cover I2C/SPI private protocol functions.

11. Python CLI usage

11.1 Install dependencies

pip install pyusb

11.2 Global parameters

11.3 Parameter list

Type convention:

Global parameters:

I2C parameters:

i2c-ping, i2c-version, i2c-status, i2c-event-poll, i2c-vaddr-get, i2c-reset only requires --ch. i2c-vcc-status/set/threshold routes through CH0 by default, usually with no need to specify --ch; VCC output affects CH0..CH3 at the same time.

SPI parameters:

11.4 I2C Master Example

# Connectivity test
python si104_cli.py i2c-ping --ch 0

# Configure 400kHz I2C master
python si104_cli.py i2c-config --ch 0 --role master --mode fast --timeout 1000

# Write register
python si104_cli.py i2c-write --ch 0 --addr 0x50 --data "00 01 A5"

# Read after writing
python si104_cli.py i2c-wr --ch 0 --addr 0x50 --tx "00" --rx-len 8

# Disable the VCC telemetry tail when reading the full 512 bytes
python si104_cli.py i2c-read --ch 0 --addr 0x50 --rx-len 512 --monitor-vcc 0

# Scan address
python si104_cli.py i2c-scan --ch 0 --start 0x03 --end 0x77

11.5 I2C Slave Buffer Example

# Configure CH0 as a register slave with 16-bit address + 8-bit data
python si104_cli.py i2c-config --ch 0 --role slave --slave-addr 0x30 --slave-mode reg --reg-addr-width 16 --data-width 8

# Bind slot1 to virtual high byte 0x12
python si104_cli.py i2c-vaddr-set --ch 0 --slot 1 --vaddr 0x12

# Write cache
python si104_cli.py i2c-reg-write --ch 0 --offset 0x1200 --data "11 22 33 44"

# Read cache
python si104_cli.py i2c-reg-read --ch 0 --offset 0x1200 --len 16

# Polling events
python si104_cli.py i2c-event-poll --ch 0

11.6 VCC Example

# Query VCC status
python si104_cli.py i2c-vcc-status

# Request to open VCC without saving
python si104_cli.py i2c-vcc-set --enable 1

# Set the threshold to 1000mV and save
python si104_cli.py i2c-vcc-threshold --set-mv 1000 --save 1

12. Linux I2C driver

kernel_driver/si104_i2c.c is the first stage out-of-tree Linux kernel module, which aims to register the 4-way SI104 private Bulk I2C interface as a standard Linux I2C adapter.

Realized scope:

• Bind I2C interface 0..3 of 34b7:e481.
• CH0..CH3 use 0x01/0x81 to 0x04/0x84 respectively.
• Supports writing one message, reading one message, and reading two messages after writing repeated-start.
• Supports common SMBus access through I2C core emulation, but does not support SMBus quick yet.
• The shared VCC output under firmware protection can be requested via module parameters or sysfs. VCC affects CH0..CH3 at the same time.

Loading example:

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>

Runtime shared VCC control:

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

Module parameters:

Unimplemented scope:

• SI104 private slave/register/mailbox/vaddr control plane.
• SPI controller driver.
• OTA maintenance capability is provided by the host application.

13. Hardware self-test

Self-test script path:

test_scripts/si104_self_test.py

Default fixture wiring:

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

Commonly used commands:

# Default smoke test
python test_scripts/si104_self_test.py

# Private protocol non-destructive matrix
python test_scripts/si104_self_test.py --suite private --report-json reports/si104_self_test_private.json

# Complete matrix
python test_scripts/si104_self_test.py --suite all --report-json reports/si104_self_test_all.json

# Performance test
python test_scripts/si104_self_test.py --suite perf --perf-iterations 1000 --perf-payload-len 256

Test suite:

By default, --vcc auto will first request the firmware VCC protection logic to turn on the I2C pull-up power supply; if it detects that the external voltage has exceeded the threshold, the firmware will refuse to turn on the output, and the script will continue to use the external power supply.

14. Debugging and Diagnostics

14.1 Device not found

Check:

• Whether the VID/PID is 34b7:e481.
• Whether Windows has bound WinUSB.
• Whether --serial is required in multi-device scenarios.
• Whether the current user has USB access rights under Linux.

14.2 I2C returns NO_POWER

Possible reasons:

• The target I2C bus does not have an external pull-up supply.
• SI104 Internal VCC is not open.
• The external voltage exceeds the protection threshold and the firmware refuses to turn on the VCC output.

suggestion:

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

14.3 I2C read and write timeout

Check:

• Whether the target address exists.
• Whether --mode and --bus-hz are suitable for the target device.
• I2C line sequence, pull-up, and level are correct.
• If the slave mode is not reset and the channel status remains, you can execute i2c-reset.

14.4 Abnormal SPI reading

Check:

• Whether the CPOL/CPHA matches the target device.
• Whether the MISO/MOSI/CLK/CS line sequence is correct.
• Is sclk above 40 MHz or beyond the fixture signal-integrity margin?
• Whether it is necessary to turn off or turn on DMA for comparison.

15. Technical specifications

16. Release material index

17. Revision History

Copyright (c) 2026 LanMotion.