cli2c

A command line tool to interact with I2C devices

Latest Release: 1.1.3

Important

cli2c has been superseded and will not be updated. Please see Depot for the latest and future versions.

About cli2c

cli2c is a command line tool that allows you to interact with I²C devices connected to your Mac or Linux box via a hardware bridge.

Connect a matrix display to your Mac

The bridge is a Raspberry Pi RP2040-based board, such as the Pico, running custom firmware. The bridge relays commands from cli2c to the I²C device, be it a sensor, a display, an actuator, a storage chip, or whatever.

The Mac or Linux box connects to the bridge over USB.

The firmware is documented in the documentation section.

Back to the Top

How to Use cli2c

cli2c has the the following syntax:

cli2c {device_port} [command] ... [command]

Note Arguments in braces { } are required; those in square brackets [ ] are optional.

device_port is the USB-connected I²C host’s Unix device path.
- On a Mac, this will be something like /dev/cu.usbmodem-101.
- On a Raspberry Pi, this will be /dev/ttyACM0.
[command] is an optional command block, comprising a single-character command and any required data as described in the following table.

Command	Args	Description
`c`	`{bus}` `{sda_pin}` `{scl_pin}`	Choose the host’s I²C bus (1-or-0) and the SDA and SCL pins by their RP2040 GPIO number. Defaults are board-specific and shown below. You must select a bus before initialising it
`f`	`{frequency}`	The I²C bus frequency in multiples of 100kHz. Supported values: 4-and-1
`z`		Initialise the target I²C bus. The bus is not initialised at startup
`w`	`{address}` `{data_bytes}`	Write the supplied data to the I²C device at `address`. `data_bytes` are comma-separated 8-bit hex values, eg. `0x4A,0x5C,0xFF`
`r`	`{address}` `{count}`	Read `count` bytes from the I²C device at `address` and issue an I²C STOP
`p`		Issue an I²C STOP. Usually used after one or more writes
`x`		Reset the I²C bus
`s`		Display devices on the I²C bus. Note This will initialise the bus if it is not already initialised
`i`		Display I²C host device information
`l`	`{on\|off}`	Turn the I²C Host LED on or off
`h`		Display help information

Error and Data Output

All message output is routed via stderr. All data read back from an I²C device is output to stdout so it can be captured to a file. Returned data is currently presented as hexadecimal strings. For example:

$ cli2c /dev/cu.usbmodem-0-r-101x18 16 > data.bin
$ cat data.bin
0AB3FF4A3C8A8EBAB3FF4A3C8A8E01

Device Defaults

Board	I²C Bus	SDA Pin	SCL Pin	QWIIC STEMMA I²C	QWIIC STEMMA SDA	QWIIC STEMMA SCL
Raspberry Pi Pico	1	2	3	—	—	—
Adafruit QTpy*	1	22	23	1	26	27
Adafruit QT2040 Trinkey	0	16	17	—	—	—
SparkFun ProMicro 2040*	1	2	3	0	16	17
Pimoroni Tiny 2040	1	6	7	—	—	—

Devices marked with * have a QWIIC/STEMMA-QT port as well as pins. The default bus and pins used when the QWIIC/STEMMA-QT port is set to be the default I²C pinout. This can be done by uncommenting the

set(USE_STEMMA 1)

line in the board’s CMakeLists.txt file.

Note Don’t forget that you can also use the c command to choose an alternative I²C bus and pins.

Back to the Top

Install cli2c

Mac users can build cli2c using Xcode. Select either the All scheme, or one of the individual app schemes, and select Archive. Save the build products to the desktop and then mv the apps to your preferred $PATH-accessible directory.

To build for Linux, clone the source code repo, then navigate to it.

cd linux
cmake -S . -B build
cmake --build build
sudo cp build/cli2c /usr/local/bin/cli2c
sudo cp build/matrix /usr/local/bin/matrix
sudo cp build/segment /usr/local/bin/segment

Back to the Top

Source Code

You can view Cli2c’s source code at GitHub.

Back to the Top

Release Notes

1.1.3 17 March 2023
- A major stability improvement thanks to Pico SDK 1.5.0.
- Fix connectivity issues with Linux clients.
- Fix matrix character parsing.
- Add v for version command to matrix and segment.
- Reorganise firmware code.
- Add to firmware the ability to report the most recent error.
1.1.2 11 February 2023
- A big data transfer speed improvement.
- Document GPIO usage.
- Better error messages.
- Internal changes and bug fixes.
1.1.1 27 October 2022
- Internal changes.
1.1.0 22 October 2022
- Support I²C bus and pin selection.
- Support LED control.
- Support building and running client apps on Linux (RPiOS).
- Support firmware transfer to board on Linux (RPiOS).
1.0.1 18 October 2022
- Initial public release with fixes.

Back to the Top

Related Software

Depot

Back to the Top