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.
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.
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.
/dev/cu.usbmodem-101
./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 |
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
0AB3FF4A3C8A8EBAB3FF4A3C8A8E01
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.
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
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
You can view Cli2c’s source code at GitHub.