https://github.com/wymcg/matricks
A command-line tool for extensible LED matrix control with Raspberry Pi devices.
https://github.com/wymcg/matricks
extism raspberrypi rust wasm ws2812b ws281x
Last synced: about 2 months ago
JSON representation
A command-line tool for extensible LED matrix control with Raspberry Pi devices.
- Host: GitHub
- URL: https://github.com/wymcg/matricks
- Owner: wymcg
- License: mit
- Created: 2023-04-11T03:28:58.000Z (over 2 years ago)
- Default Branch: main
- Last Pushed: 2024-01-22T22:30:11.000Z (over 1 year ago)
- Last Synced: 2025-07-07T12:16:30.710Z (3 months ago)
- Topics: extism, raspberrypi, rust, wasm, ws2812b, ws281x
- Language: Rust
- Homepage: https://wymcg.github.io/matricks/
- Size: 364 KB
- Stars: 6
- Watchers: 1
- Forks: 3
- Open Issues: 16
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# 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](https://extism.org/docs/category/write-a-plug-in).
To simulate plugins while you're developing them, check out [Simtricks](https://github.com/wymcg/simtricks)!
## Run Matricks
### Installation on Raspberry Pi
- Install 64-bit Raspbian[^1] on your Raspberry Pi[^2]
- Install Rust and Cargo from [the Rust website](https://rustup.rs)
- Run `apt install libclang-dev libssl-dev`
- Run `cargo install matricks`
- [Configure your Raspberry Pi](#raspberry-pi-configuration) and reboot
### Use a pre-compiled binary
For convenience, pre-compiled binaries are available in the releases tab.
- [Configure your Raspberry Pi](#raspberry-pi-configuration) 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](https://rustup.rs)
- 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[^1]
- [Configure your Raspberry Pi](#raspberry-pi-configuration) 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](./examples/README.md).
### 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 --width --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 [OPTIONS] --path --width --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
```
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 --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
```
[^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.
## 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](https://github.com/jgarff/rpi_ws281x#spi).
### 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
```