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.

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

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

Back to the Top

---

Source Code

You can view Cli2c’s source code at GitHub.

Back to the Top

---

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.

Back to the Top

---

Related Software

• Unicoder
• XBeeParser
• ASCII
• HighlighterSwift
• MNU

Back to the Top

---