This repo has been superseded by Depot and will no longer be updated. Depot contains all the functionality offered by the code in this repo and more. This repo with shortly be archived.

An I2C client for macOS and Linux. It is used as the basis for client apps to operate HT16K33-controlled matrix and segment LED displays.

It requires a Raspberry Pi Pico, Adafruit QTPy RP2040, Adafruit QT2040 Trinkey, SparkFun ProMicro RP2040 or Pimoroni Tiny 2040 connected via USB and running the included firmware. This is the I2C Host.

There’s more information in this blog post.

You can build the code from the accompanying Xcode project.

1. Archive the project.
2. Save the build products on the desktop.
3. Copy the binaries cli2c, matrix and segment to your preferred location listed in $PATH.

1. Navigate to the repo directory.
2. cd linux
3. cmake -S . -B build
4. cmake --build build
5. Copy the binaries cli2c, matrix and segment to your preferred location listed in $PATH.

Important WE STRONGLY RECOMMEND YOU BUILD THE FIRMWARE WITH PICO SDK 1.5.0 OR ABOVE.

1. Navigate to the repo directory.
2. cmake -S . -B firmwarebuild
3. cmake --build firmwarebuild
4. Write the firmware depending on which board you are using:
   • ./deploy.sh /path/to/device firmwarebuild/firmware/pico/firmware_pico_rp2040.uf2
   • ./deploy.sh /path/to/device firmwarebuild/firmware/qtpy/firmware_qtpy_rp2040.uf2
   • ./deploy.sh /path/to/device firmwarebuild/firmware/promicro/firmware_promicro.uf2
   • ./deploy.sh /path/to/device firmwarebuild/firmware/tiny/firmware_tiny2040.uf2
   • ./deploy.sh /path/to/device firmwarebuild/firmware/trinkey/firmware_trinkey2040.uf2

The deploy script tricks the RP2040-based board into booting into disk mode, then copies over the newly build firmware. When the copy completes, the RP2040 automatically reboots. This saves of a lot of tedious power-cycling with the BOOT button held down.

The contents of this repo are:

/cli2c
|
|___/cli2c                      // The macOS driver and related code
|   |___/cli2c                  // A generic CLI tool for any I2C device
|   |___/matrix                 // An HT16K33 8x8 matrix-oriented version of cli2c
|   |___/segment                // An HT16K33 4-digit, 7-segment-oriented version of cli2c
|   |___/common                 // Code common to all versions
|
|___/firmware                   // The RP2040 host firmware, written in C
|   |___/pico                   // The Raspberry Pi Pico version
|   |___/qtpy                   // An Adafruit QTPy RP2040 version
|   |___/promicro               // A SparkFun ProMicro RP2040 version
|   |___/tiny                   // A Pimoroni Tiny 2040 version
|   |___/trinkey                // An Adafruit QT2040 Trinkey version
|   |___/common                 // Code common to all versions
|
|___/examples                   // Demo apps
|   |___cpu_chart_matrix.py     // CPU utilization display for 8x8 matrix LEDs
|   |___cpu_chart_segment.py    // CPU utilization display for 4-digit segment LEDs
|   |___mcp9809_temp.py         // Periodic temperature reports from an MCP9808 sensor
|
|___/linux                      // Linux build settings (Cmake) for the driver and client apps
|
|___CMakeLists.txt              // Top-level firmware project CMake config file
|___pico_sdk_import.cmake       // Raspberry Pi Pico SDK CMake import script
|
|___firmware.code-workspace     // Visual Studio Code workspace for the RP2040 firmware
|___cli2c.xcodeproj             // Xcode workspace for cli2c, matrix and segment
|
|___deploy.sh                   // A .uf2 deployment script that saves pressing
|                               // RESET/BOOTSEL buttons.
|
|___README.md
|___LICENSE.md

Under macOS, RP2040-based boards will appear in /dev as cu.usbmodemXXXXX or cu.usbserialXXXXXX. You can use my dlist() shell function to save looking up and keying in these names, which can vary across boots.

Under Linux, specifically Raspberry Pi OS, boards appear as /dev/ttyACM0. You may need to add your user account to the group dialout in order to access the port:

1. Run sudo adduser smitty dialout
2. Log out and then back in again.

cli2c is a command line driver for the USB-connected RP2040-based I2C host, which must be pre-loaded with the firmware.

It is a generic I2C driver with 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 I2C host’s Unix device path, eg. /dev/cu.usbmodem-101.
• [command] is an optional command block, comprising a single-character command and any required data as described in the following table.

All message output is routed via stderr. All data read back from an I2C 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
A0FF123B5C5FAA5F010304

Devices marked with * have a STEMMA-QT port as well as pins. The values in brackets are the bus and pins used when the STEMMA-QT is set to be the default. This can be done uncommenting the

set(USE_STEMMA 1)

line in the board’s CMakeLists.txt file.

But don’t forget that you can use the c command to choose an alternative I2C bus and pins.

You can use cli2c to set a GPIO pin. Provide the GPIO number and its initial state (hi or lo) and its mode: whether it is an input or output (in or out).

Setting a pin to an output immediately sets its state to the provided value. To change the state, just pass in the opposite value. There’s no need to specify its mode again unless you wish to change it.

cli2c /dev/cu.usbmodem-101 10 hi out
cli2c /dev/cu.usbmodem-101 10 lo

Setting a pin to an input does nothing immediately, and the supplied state value is ignored unless it is r, for read. To read an input pin, pass r in place of a state: cli2c will output the pin’s current value as a two-digit hex number:

cli2c /dev/cu.usbmodem-101 10 lo in
cli2c /dev/cu.usbmodem-101 10 r
01

Again, you don’t need to restate the pin’s mode unless you’re changing it.

matrix is a specific driver for HT16K33-based 8x8 LED matrices. It embeds cli2c but exposes a different, display-oriented set of commands.

You use the driver with this command-line call:

matrix {device} [I2C address] [commands]

Note Again, arguments in braces {} are required; those in square brackets \[\] are optional.

• {device} is the path to the I2C Mini’s device file, eg. /dev/cu.usbserial-DO029IEZ.
• [I2C address] is an optional I2C address. By default, the HT16K33 uses the address 0x70, but this can be changed.
• [commands] are a sequence of command blocks as described below.

Multiple commands can be issued by sequencing them at the command line. For example:

matrix /dev/cu.usbserial-DO029IEZ 0x71 w r 3 p 0 0 p 1 1 p 2 2 p 3 3 p 4 4 p 5 5 p 6 6 p 7 7

Note The client-side display buffer is not persisted across calls to matrix, so building up an image across calls will not work. While the display retains its own image data, the local buffer is implicitly cleared with each new call. This may be mitigated in a future release.

Draw a dot at 1,1

matrix /dev/cu.usbserial-DO029IEZ p 1 1

Draw T, centred

matrix /dev/cu.usbserial-DO029IEZ c 123 true

Draw a smiley

matrix /dev/cu.usbserial-DO029IEZ g 0x3C,0x42,0xA9,0x85,0x85,0xA9,0x42,0x3C

Scroll “Hello, World!” across the display

matrix /dev/cu.usbserial-DO029IEZ t "Hello, World!    "

Note The four spaces (two matrix columns each) ensure the text disappears of the screen at the end of the scroll.

segment is a specific driver for HT16K33-based 4-digit, 7-segment LEDs. It embeds cli2c but exposes a different, display-oriented set of commands.

You use the driver with this command-line call:

segment {device} [I2C address] [commands]

Note Again, arguments in braces {} are required; those in square brackets \[\] are optional.

• {device} is the path to the I2C Mini’s device file, eg. /dev/cu.usbserial-DO029IEZ.
• [I2C address] is an optional I2C address. By default, the HT16K33 uses the address 0x70, but this can be changed.
• [commands] are a sequence of command blocks as described below.

Multiple commands can be issued by sequencing them at the command line. For example:

segment /dev/cu.usbserial-DO029IEZ 0x71 w f n 7777

Note The display buffer is not persisted across calls to segment, so building up an image across calls will not work. While the display retains its own image data, the local buffer is implicitly cleared with each new call. This may be mitigated in a future release.

Draw 42.4 degrees

segment /dev/cu.usbserial-DO029IEZ n 4240 d 1 c '*' 3

The examples folder contains Python scripts that make use the above apps.

• cpu_chart_matrix.py — A rudimentary side-scrolling CPU activity chart. Requires an HT16K33-based 8x8 matrix LED.
• cpu_chart_segment.py — A CPU activity numerical percentage readout. Requires an HT16K33-based 4-digit, 7-segment matrix LED.
• mcp9809_temp.py — Second-by-second temperature readout. Requires an MCP98008 temperature sensor breakout.

This work was inspired by James Bowman’s (@jamesbowman) i2ccl tool, which was written as a macOS/Linux/Windows command line tool to connect to his I2CMini board.

My own I2C driver code started out based on James’ but involves numerous changes and (I think) improvements. I also removed the non-macOS code removed and some unneeded functionality that I don’t need (I2C capture, monitoring). Finally, it targets fresh firmware I wrote from the ground up to run on an RP2040-based board, not the I2CMini.

Why? Originally I was writing an HT16K33 driver based directly on James’ code, but I accidentally broke the pins off my I2CMini — only to find it is very hard to find new ones. James’ firmware is written in a modern version of Forth, so I can no choice but to learn Forth, or write code of my own. I chose the latter.

Thanks are also due to Hermann Stamm-Wilbrandt (@Hermann-SW) for the basis for the deploy script.

• Fixed in 1.1.3 Under macOS, rapidly repeated calls to cli2c, matrix or segment (ie. the I2C driver they all depend upon) can cause the I2C Host firmware to crash. This has been experienced with the matrix and segment examples. This is being investigated.

• 1.1.3 17 February 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 I2C bus and pin selection.
  • Support building and running client apps on Linux (RPiOS).
  • Support firmware transfer to board on Linux (RPiOS).
  • Add LED control to cli2c.
• 1.0.1 18 October 2022
  • Behind-the-scenes fixes for the client apps.
• 1.0.0 18 October 2022
  • Initial public release.

cli2c, matrix and segment contain small code portions © 2019, James Bowman. All other code © 2023, Tony Smith (@smittytone). They are licensed under the terms of the BSD 3-Clause Licence.

The RP2040 firmware is © 2023, Tony Smith (@smittytone). It is licensed under the terms of the MIT Licence.