OpenRGB Matrix Portal M4 Plugin

This is an OpenRGB plugin for exposing an Adafruit Matrix Portal M4 as a 64x32 direct-color matrix device.

The OpenRGB plugin registers an RGBController with one matrix zone. When OpenRGB updates colors, the plugin streams a full RGB565 frame to the Matrix Portal over USB CDC data serial using this packet format:

MPF2
uint16_le width
uint16_le height
width * height * 2 bytes of little-endian RGB565 pixel data

Files

• src/: OpenRGB C++ plugin and RGB controller.
• circuitpython/boot.py: enables the separate USB CDC data serial endpoint.
• circuitpython/code.py: Matrix Portal receiver and RGB matrix renderer.
• scripts/build.sh: qmake build wrapper.

Build

The plugin needs OpenRGB source headers. By default the build script uses the OpenRGB submodule at OpenRGB/. To use another OpenRGB source tree:

OPENRGB_DIR=/path/to/OpenRGB ./scripts/build.sh

Otherwise:

git clone --recurse-submodules https://github.com/ikeroy/Matrix-M4-OpenRGB.git
cd Matrix-M4-OpenRGB
./scripts/build.sh

The output is:

build/libOpenRgbMatrixPortalPlugin.so

Select that file when installing a plugin through the settings menu, then restart.

Serial Port

The plugin defaults to /dev/ttyACM1. Override it when launching OpenRGB:

MATRIX_PORTAL_PORT=/dev/ttyACM0 openrgb

On Linux, the user running OpenRGB must have permission to open the serial device, usually through the dialout group or a udev rule.

Important: with boot.py enabling both console and data serial, CircuitPython usually exposes two /dev/ttyACM* devices. The REPL is the console endpoint. The receiver listens on usb_cdc.data, which is usually the other endpoint. If tio is connected to /dev/ttyACM1, try launching OpenRGB with MATRIX_PORTAL_PORT=/dev/ttyACM0.

Test Without OpenRGB

After copying the CircuitPython files and resetting the board, connect tio to the console endpoint. You should see:

Matrix Portal OpenRGB receiver starting
Listening for OpenRGB frames on usb_cdc.data

Then send frames to the other endpoint:

./scripts/send_test_frame.py /dev/ttyACM0

If the matrix updates and the REPL prints Displayed frame 1, the board side is working and OpenRGB is probably using the wrong serial port. If nothing happens, swap /dev/ttyACM0 and /dev/ttyACM1.

Install Receiver On The Matrix Portal

Copy circuitpython/boot.py and circuitpython/code.py to the CircuitPython drive. The board must reboot after boot.py is added because CircuitPython only changes USB CDC endpoints during boot.

code.py assumes a 64x32 RGB matrix wired through the standard Matrix Portal M4 matrix pins.

Current Limitations

• Linux serial support only.
• Matrix size is fixed at 64x32 in both the plugin and CircuitPython receiver.
• The plugin caps serial updates at about 20 fps to avoid building a stale frame queue.
• No plugin settings UI yet; serial port is configured by MATRIX_PORTAL_PORT.

Help with support for other operating systems and matrix sizes is appreciated :3