7. Command reference

The Pololu Isolated USB-to-I²C Adapter supports several different commands on its USB virtual serial port interface. This section describes the details of what each command does, and how the commands and their responses are encoded as serial bytes.

List of commands

• I²C write
• I²C read
• Set I²C mode
• Set I²C timeout
• Clear bus
• Set STM32 timing
• Digital read
• Enable VCC Out
• Get device info

I²C write

Arguments	address: a 7-bit I²C address between 0 and 127 data: a list of 0 to 255 bytes to write to the device
Serial encoding	byte 0: 0x91 byte 1: address (0 to 127) byte 2: number of bytes to write (0 to 255) bytes to write
Response	Error code (1 byte)
Python method	i2c.write_to(address, data)

This command writes a series of bytes to the I²C target identified by the given 7-bit address.

To send this command to the adapter’s virtual serial port, you must first send a 3-byte header consisting of 0x91 followed by I²C address (0 to 127) and then the number of bytes to write (0 to 255). After that, send the bytes that you want to write to the target device.

The adapter responds to this command by sending back a single byte. The response is either zero to indicate that the adapter wrote the data successfully and received all the expected acknowledgments from the target device, or the response is a non-zero error code (see Section 8). The most common error code returned by this command is 8, which indicates that no target device acknowledged the address byte that the adapter transmitted to the bus. This error can happen if the target device is not powered, if the target device is not properly connected to the I²C bus, or—for adapters that do not provide power to the bus—if the adapter’s VCC (IN) pin is not powered. See Section 8 for more information about the adapter’s error codes and how to troubleshoot them.

A zero-length I²C write is valid and allows you to check if a device is present at the given address without actually writing any data to it. You can use this to scan the bus for devices: this is how the Python library implements its scan() method.

I²C read

Arguments	address: a 7-bit I²C address between 0 and 127 count: the number of bytes to read, from 1 to 255
Serial encoding	byte 0: 0x92 byte 1: address (0 to 127) byte 2: number of bytes to read (1 to 255)
Response	Error code (1 byte), followed by the bytes read
Python method	i2c.read_from(address, count)

This command reads a series of bytes from the I²C target identified by the given 7-bit address.

This command consists of three bytes: 0x92, the I²C address (0 to 127), and the number of bytes to read (1 to 255).

The first byte of the response is either zero to indicate that the adapter read the data successfully or a non-zero error code (see Section 8). The length of the remainder of the adapter’s response is equal to the number of bytes specified in the command, regardless of whether an error occurred or not. The remainder of the response contains the data read from the device, or other bytes with unspecified values if there was an error.

Set I²C mode

Arguments	mode: one of four supported I²C modes
Serial encoding	byte 0: 0x94 byte 1: mode number (0 to 4)
Response	none
Python method	i2c.set_i2c_frequency(frequency_khz)

This command tells the adapter what I²C mode to operate in, which determines the clock speed and other settings. The mode number should be one of:

• 0: Standard-mode (100 kHz)
• 1: Fast-mode (400 kHz)
• 2: Fast-mode Plus (1000 kHz)
• 3: 10 kHz mode

The first three modes are defined in the I²C-bus specification and user manual by NXP. The 10 kHz mode is a slower version of Standard-mode that could be useful for systems with long wires or other issues preventing 100 kHz clock speeds from working.

By default, the adapter operates in Standard-mode (100 kHz). If you send this command with an invalid mode number, the adapter switches to Standard-mode.

The communication speed is not solely determined by the specified I²C mode: it is also determined by the rise and fall times of the signals on SDA and SCL. If you use Fast-mode (400 kHz) or Fast-mode Plus (1000 kHz), adding pull-up resistors to your bus’s SDA and SCL can potentially speed up data transfer significantly (see Section 4 for more information about pull-ups).

For direct control over the parameters set by this command, see the Set STM32 timing command.

Set I²C timeout

Arguments	timeout: a number of milliseconds from 1 to 65535
Serial encoding	byte 0: 0x97 bytes 1 and 2: timeout value in milliseconds, little endian
Response	none
Python method	i2c.set_i2c_timeout(timeout_ms)

This command sets the maximum time allowed for I²C write and I²C read commands. If the total time taken by I²C communication in one of those commands takes longer than the specified time, the adapter aborts the command and returns the timeout error code (3).

The default I²C timeout is 50 ms.

Clear bus

Arguments	none
Serial encoding	byte 0: 0x98
Response	none
Python method	i2c.clear_bus()

This command transmits 10 low pulses on the SCL line at a frequency of 10 kHz. These pulses allow the bus to recover from cases where one of the target devices is in the wrong state and driving the SDA line low.

Set STM32 timing

Arguments	timingr: 32-bit value for the STM32’s TIMINGR register gpio_fmp_mode: 0 or 1
Serial encoding	byte 0: 0xA1 bytes 1 to 4: timingr, with little endian encoding byte 5: gpio_fmp_mode
Response	none
Python method	i2c.set_stm32_timing(timingr, gpio_fmp_mode)

This command is another way to set the parameters set by the Set I²C mode command. It allows fine control over the I²C clock speed and enables the adapter to achieve speeds higher than 1000 kHz.

The timingr argument is a 32-bit unsigned integer. This parameter corresponds to the TIMINGR register of the I²C module on its STM32C071 microcontroller. You can use the STM32CubeIDE or STM32CubeMx software from ST to generate values for this register based on your desired I²C mode, clock speed, and rise and fall times.

The gpio_fmp_mode parameter should be 0 or 1. A value of 1 enables Fast-mode Plus driving capability on the I²C pins of adapter’s STM32C071 microcontroller. This parameter corresponds to the I2C1_FMP bit in the CFGR1 register of the SYSCFG module.

Digital read

Arguments	none
Serial encoding	byte 0: 0xA2
Response	1 byte: bit 0 is SCL, bit 1 is SDA
Python method	i2c.digital_read()

This command retrieves digital readings of the adapter’s internal SCL and SDA signals, which can be useful for troubleshooting. Normally the bus will be idle when the adapter executes this command, so both readings will be high (1). If the SDA reading is low (0), the Clear bus command might restore your bus to a working state.

Enable VCC Out

Arguments	enabled: 0 or 1
Serial encoding	byte 0: 0xA4 byte 1: enabled (0 or 1)
Response	Error code (1 byte)
Python method	i2c.enable_vcc_out(enabled)

On adapters that have a “VCC (OUT)” pin, this command enables or disables the isolated DC-DC power module responsible for supplying USB power to the I²C bus. The VCC power output is enabled by default whenever the adapter powers on, so disabling it with this command does not have a permanent effect. The voltage of the VCC power supply (3.3 V or 5 V) is determined by the position of the voltage selection switch and is latched when the power supply turns on.

The adapter responds to this command by either sending 0 to indicate success or by sending error code 13 to indicate that the command is not supported because the adapter does not supply power.

Get device info

Arguments	none
Serial encoding	byte 0: 0xA7
Response	see below
Python method	i2c.get_device_info()

This command returns identifying information about the adapter and the firmware running on it.

Byte 0 (the first byte) of the response data is the total size of the data, in bytes. This allows future versions of the firmware to add more information at the end of the data without breaking older software.

Byte 1 is a version number for format of the data. For now, this version number is always 0, and software parsing the data should raise an error if it is non-zero.

Bytes 2 through 5 are the USB vendor ID (VID) followed by the USB product ID (PID). Both numbers are 16-bit and little endian. This table shows the known VID/PID combinations you can expect:

Vendor ID	Product ID	Name
0x1FFB	0x2502	Pololu Isolated USB-to-I2C Adapter
0x1FFB	0x2503	Pololu Isolated USB-to-I2C Adapter with Isolated Power

Bytes 6 and 7 are the firmware version. It is a 16-bit little endian number and holds 4 digits of binary-coded decimal. For example, if bytes 5 and 6 are 0x02 and 0x01 respectively, that corresponds to 0x0102, which indicates firmware version 1.02. This is the same as the bcdDevice field from the device’s USB descriptor. See Section 9 for information about the different firmware versions.

The next 8 bytes (bytes 8 to 15) are a null-terminated ASCII string that describes any special modifications that were made to the firmware. A single hyphen (“-”) indicates no special modifications, and should not be displayed.

The final 12 bytes of the response (bytes 16 to 27) are the unique ID of the device. These are arbitrary binary bytes, and they are the same bytes that the adapter uses to generate its USB serial number.