wymcg / matricks

A command-line tool for extensible LED matrix control with Raspberry Pi devices.

Matricks

"Teach an old matrix new tricks..."

Matricks is a WASM-based extensible LED matrix control tool intended for use on Raspberry Pi devices. LED matrix functionality is defined by user-developed plugins, or "tricks", which can be developed in any language that is supported by the Extism PDK. To simulate plugins while you're developing them, check out Simtricks!

Run Matricks

Installation on Raspberry Pi

• Install 64-bit Raspbian¹ on your Raspberry Pi²
• Install Rust and Cargo from the Rust website
• Run apt install libclang-dev libssl-dev
• Run cargo install matricks
• Configure your Raspberry Pi and reboot

Use a pre-compiled binary

For convenience, pre-compiled binaries are available in the releases tab.

• Configure your Raspberry Pi and reboot
• Run the following command to download and run Matricks:

MATRICKS_VERSION=0.3.1 && \
wget https://github.com/wymcg/matricks/releases/download/v$MATRICKS_VERSION/matricks_$MATRICKS_VERSION && \ 
chmod +x matricks_$MATRICKS_VERSION && \
./matricks_$MATRICKS_VERSION 

Cross-compilation

• On another device,
  • Install Rust and Cargo from the Rust website
  • Run rustup target add aarch64-unknown-linux-musl
  • Run cargo install cross
  • Clone this repository and build with cross build --release --target aarch64-unknown-linux-musl
  • Transfer the produced executable to your Raspberry Pi
• On your Raspberry Pi,
  • Install 64-bit Raspbian¹
  • Configure your Raspberry Pi and reboot
  • Run the executable

Usage

This section describes basic usage of Matricks. For general usage information, run matricks help. For a list of plugins to try, there are several example plugins listed in the examples README.

Manual configuration

You may manually provide a configuration to Matricks using matricks manual. To run a plugin (or a set of plugins in a directory), Matricks can be invoked as follows:

matricks manual [OPTIONS] --path <PLUGIN_PATH> --width <WIDTH> --height <HEIGHT>

This will run the plugin(s) at the given path on the connected matrix. Other matrix and plugin configuration options are also available; See matricks help manual for more information.

Saving a configuration

Once you have confirmed that everything is working with matricks manual, you can save your configuration to a file using the matricks save command. To save your configuration, Matricks can be invoked as follows:

matricks save <NEW_CONFIG_PATH> [OPTIONS] --path <PLUGIN_PATH> --width <WIDTH> --height <HEIGHT>

This is similar to matricks manual, but instead of running the plugin, Matricks will save the configuration information to a new TOML file at the given path. matricks save has the same matrix and plugin configuration options as matricks manual. See matricks help save for more information.

Automatic configuration

If you have a TOML configuration file (created either by hand or by running matricks save), you can use it using matricks auto. To run Matricks with a configuration file, Matricks can be invoked as follows:

matricks auto <CONFIG_PATH>

This command will use the configuration information in the given file to drive the matrix. See matricks help auto for more information.

Clearing the matrix

If for any reason you need to clear all LEDs on the matrix, Matricks can be invoked as follows:

matricks clear --width <WIDTH> --height <HEIGHT>

See matricks help clear for more information.

View Logs

To see logs from Matricks, prepend your command with RUST_LOG=matricks=info. For example:

RUST_LOG=matricks=info matricks auto your_config.toml

Raspberry Pi Configuration

Matricks requires some configuration before it can be used to drive a LED matrix. If these instructions are not followed, Matricks may not work as expected. This section paraphrases the instructions from the rpi_ws281x README.

Enable SPI

The easiest way to enable SPI on Raspberry Pi is with the raspi-config command line tool. Run sudo raspi-config and navigate to the SPI activation dialog by selecting Interface Options > SPI.

Change GPU Core Frequency

Add the following lines to /boot/config.txt:

Device	Lines to Add
Raspberry Pi 3	core_freq=250
Raspberry Pi 4	core_freq=500 core_freq_min=500

Change SPI Buffer Size (optional)

On some distributions, it may be necessary to increase the maximum SPI transfer size by editing /boot/cmdline.txt and adding the following line:

spidev.bufsiz=32768

Footnotes

1. At this time, Matricks can only be installed and run on 64-bit operating systems. ↩ ↩²

2. If you are using a Raspberry Pi with less than 1GB of RAM, installation using this method is not recommended. ↩

matricks's Issues

Remove Magnification Option

Remove the magnification command line argument. The argument is no longer necessary after #14.

Update Readme and GitHub Pages Site with new usage details

Several command line options have been added since v0.1.0. The usage page of the GitHub Pages site needs this information, and the main readme should be changed to reflect the added options as well.

Add Brightness Option

Add brightness command line option which allows users to set LED matrix brightness on non-simulated matrices.

Add LED controller options

Add command line options to change GPIO pin, DMA channel and signal frequency used by the matrix controller.

Plugin Update Lag Detection

Check and log if the plugin update loop is taking more time to generate an update than there is time between frames.

Add support for vertically wired matrices

Currently, Matricks expects that LED strips are wired horizontally, not vertically. Add a command line option that switches between horizontal and vertical matrix configurations.

Simplify build/install instructions

The existing build, install and/or download instructions are more complicated than is strictly necessary to get Matricks working on a Raspberry Pi. After some experimentation, it seems that this is all that is required:

1. Enable the SPI interface. This can be done using raspi-config.
2. Change the GPU core frequency. Specifics are available here.
3. Install or download Matricks

If building Matricks from scratch (i.e. using cargo install matricks or cross build --release --target aarch64-unknown-linux-musl), you must install Rust and install the required libraries using apt install libclang-dev libssl-dev.

Update the README and the website with these simplified installation instructions.

Better plugin input scheme

Currently, Matricks will accept a single path from the user to specify which plugin(s) to run. If the path is to a plugin, Matricks will run that plugin. If the path is to a directory, Matricks will play all plugins within that directory. This is not ideal, because a user may want to play a subset of plugins within a directory.

Replace the existing --path option with a --plugin that can be given several times, similar to how --allow-host works. For example, matricks manual -x 12 -y 12 --plugin a.wasm --plugin b.wasm --plugin c.wasm should play a.wasm, b.wasm, and c.wasm.

Upgrade Extism version

Upgrade Extism version to latest version. Doing so will probably require dealing with the new-ish Extism manifest and allowing the user to specify exactly which hosts plugins can communicate with for HTTPS requests.

Change `--map-path` to mount

Currently, to make a location on the host filesystem accessible at some location in the plugin filesystem, we have the --map-path option, host and plugin paths separated by a ">". For example, to map the path /host/example on the host filesystem to a path /example on the plugin filesystem, you could add the flag --map-path /host/example>/example. A few users have expressed some confusion with this option, partially due to the way this behavior is named, and partially because of its use.

Matricks calls this behavior "mapping", but a more universal term for this sort of behavior is "mounting". Other tools, such as dylibso's Hermit, do a similar task by separating the host and WASM locations with a ":" instead of a ">".

So, to keep more in line with what other tools are doing, instead of --map-path [HOST]>[PLUGIN], change it to --mount [HOST]:[PLUGIN]. Doing this will involve:

• Changing the map_path option in clargs.rs to mount
• Changing all usages of map_path in the code to mount
• Change the separator for the host and plugin path from '>' to ':'
• Changing the doc comment in clargs.rs to describe the new usage

Phase out PluginUpdate

Completely remove PluginUpdate as a requirement for plugin development. The replacement mechanism must allow the plugin to:

1. Make logs. The mechanism for logs from plugins has already been replaced, see #39.
2. Send LED color data from the plugin to the host.
3. Tell the host to stop requesting plugin updates.

Update usage information for v0.3.2

Update usage information in the README and on the website with the new options.

• Single-path plugin selection with --path changed to multi-path plugin selection with --plugin (#58)
• --map-path was renamed to --mount, with minor usage changes (#93)
• Several orientation and wiring options were added, including --vertical and the mirroring flags (#86, #87, #91)
• --gpio, --dma, and --frequency options were added (#83)

Add note about `rpi_ws281x` configuration to `README.md`

Users have had issues running Matricks due to missing certain important setup steps from the rpi_ws281x library, including enabling SPI and not blacklisting the snd_bcm2835 module. Add some notes about these steps to the readme.

Update installation instructions on website

The website's installation instructions are out of date and should be updated with the most recent instructions on the v0.2.2 README.

Quit on failure to push update to matrix

Currently, if a matrix controller is created successfully but it can't render the update on the matrix, Matricks produces the following output:

The warning message in this error probably shouldn't be a warning, it should be an error, and the plugin update thread should stop if this happens. Also, most of the time this error is a result of fewer LEDs being connected than expected (i.e. Matricks is attempting to drive a 10x10 matrix but only 50 LEDs are actually connected), so perhaps a more helpful error message is in order.

Move to env_logger

Right now, Matricks has a special thread specifically for writing logs to a file. This probably felt like a good idea at the time, but it's definitely a much better idea to use env_logger instead. All existing custom logging code should be completely removed and all logging should be done with env_logger.

Matrix Control Thread Lag Detection

Detect and log if the matrix control thread is updating the matrix slower than it is receiving matrix updates.

Config file for matrix setup

Right now, matrix config information can only be provided via the command line (i.e. matrix dimensions are set with the --width and --height flags). Most of the time, though, a user will be running Matricks with the same set of command line flags. Ideally, the user would be able to give Matricks a config file of some sort that would supply matrix configuration information instead.

Redundant log message for `matricks auto`

Running matricks auto results in two very similar and redundant logs:

Add default Serde values

Currently, all fields must be filled in a config file in order for matricks auto to accept it. Add default values for Serde in clargs.rs so that not all fields must be given in a config file.

Update documentation for v0.3.0

Update website where necessary to reflect new plugin development patterns.

• Using config::get() to get matrix configuration information
• Returning new matrix state from the update() function
• Halting a plugin
• Making logs from a plugin

Turn off LEDs on exit

Currently, LEDs stay set to the last color when the program quits. Ideally, the LEDs would turn off when the program exits.

Add logging instructions

Add logging instructions on the GitHub Pages site and the README. Matricks v0.2.2+ uses env_logger, so for more information on how to deal with logs in Matricks, check out the env_logger documentation here.

Stop Matricks if plugin update thread dies

Currently, Matricks does not quit if the plugin update thread stops. Make it so that if the plugin update thread stops for any reason, Matricks stops.

Plugin Time Limit Option

Add a command line flag that sets a time limit for how long a single plugin can run. If a plugin has been running for more than the specified time, move on to the next available plugin. There is no time limit by default, and the time limit is ignored if there is only one plugin available.

Revamp Plugin Logging

Currently, plugins can only send logs at the end of the update function. Ideally, plugins would be able to send logs at any time, including in the setup function. Extism does allow plugins to send logs to the host, but these logs can only be written to a file (see here). Add a way that plugins can send logs through the host, alongside the normal Matricks env_logger logs.

Fix Conditional Compilation for Non-Raspberry Pi ARM64 Targets

Currently, Matricks will use the target architecture to determine whether to include rs_ws281x to drive the matrix or opencv to simulate the matrix, and will switch between matrix control thread functionality accordingly. We need to switch away from using a blanket cfg(target_arch = "aarch64") because it presents issues when compiling for non-Raspberry Pi devices that also use ARM64, such as M1 Macs.

Move to Extism Configs

Use Extism's built-in config mechanism, replacing the MatrixConfiguration struct from matricks_plugin.

`env_logger` default log level

If possible, set a default log level for env_logger so that the user doesn't need to prepend their calls to Matricks with RUST_LOG=matricks=info.

Add cross-compilation instructions to the README

Compiling on Raspberry Pi boards takes a while, and may be impossible depending on the memory available to the board (i.e. Raspberry Pi 3 and earlier are known to run out of memory while compiling, see #14). Although there are workarounds for these memory issues, it would be much easier if we could just tell users how to cross compile Matricks instead.

Add `matricks auto` config override options

Add all matricks manual options to matricks auto, so that individual settings in a configuration file can be overridden by the user. For example given a config file example.toml:

[matrix]
width = 12
height = 12
fps = 30.0
serpentine = true
brightness = 255

[plugin]
path = "example_plugin.wasm"
loop_plugins = false

Running matricks auto example.toml --fps 60 should run the plugin at 60 FPS, instead of 30 FPS as specified in example.toml.

Add missing help text for `--allow-host` and `--map-path`

The "allow host" and "map path" options are missing help text (i.e. run matricks manual -h). Use doc comments to add that help text in clargs.rs.

Add ability to rotate matrix vertically

Add option to flip the entire matrix display vertically (i.e. with a --vertical/--landscape option)

Add Generic Plugin Examples

Currently, only Rust has a generic example plugin in the examples folder. Extism supports writing plugins in other languages, including Go, C, and JavaScript.

Choose one of the languages that Extism supports and write a generic plugin that does the following:

1. Gets matrix width and height from the config
2. Fades from black to white
3. Halts the plugin when the matrix finishes fading
4. Makes a few generic logs using the logging host functions, if host functions are supported by that language's PDK

Add matrix clear subcommand

Add a subcommand (i.e. matricks clear) that will turn off all LEDs in the matrix and quit.

Add GPIO Pin Argument

Add command line argument to change GPIO pin of LED strip.

Document new subcommands

Add information about the new subcommands to the GitHub Pages site.

• matricks manual drives a connected matrix like before, using command line arguments to configure everything
• matricks save is just like matricks manual, except it saves all options to a file instead of driving a connected LED matrix
• matricks auto drives a connected matrix using a file created by hand or by matricks save to configure everything

Plugin Loop Option

Add a boolean command line flag that makes the program loop plugins, instead of running each plugin once and then quitting.

Add your plugin to example list

Have you made a plugin that you want to show off? Add it to the README.md in the examples folder with a link to your plugin, the language you used, and a short description about what it does!

Add ability to mirror matrix

Add option to flip the entire matrix display horizontally (i.e. with a --mirror option)