A command line tool to interact with I2C devices

Latest Release: 1.1.1


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.

Connect a matrix display to your Raspberry Pi 400

The firmware is documented in the documentation section.

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 (0 or 1) 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: 1 and 4
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-101 r 0x18 16 > data.bin
$ cat data.bin

Device Defaults

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


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.

Install cli2c

Mac users can install cli2c using Homebrew. In Terminal, just run:

brew tap smittytone/homebrew-smittytone
brew install --cask cli2c

cli2c will be installed in /usr/local/bin.

You can also install the matrix and segment cli tools this same way:

brew install --cask matrix segment

Connect a matrix display to your Mac

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

  1. cd linux
  2. cmake -S . -B build
  3. cmake --build build
  4. sudo cp build/cli2c /usr/local/bin/cli2c
  5. sudo cp build/matrix /usr/local/bin/matrix
  6. sudo cp build/segment /usr/local/bin/segment

Connect a matrix display to your Mac

Source Code

You can view Cli2c’s source code at GitHub.

Release Notes

  • 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.

Related Software

The Seal of RassilonThe Seal of Rassilon
Site and software copyright © 2023, Tony Smith