{"id":29323824,"url":"https://github.com/wymcg/matricks","last_synced_at":"2025-08-16T22:33:56.564Z","repository":{"id":153098212,"uuid":"626224211","full_name":"wymcg/matricks","owner":"wymcg","description":"A command-line tool for extensible LED matrix control with Raspberry Pi devices.","archived":false,"fork":false,"pushed_at":"2024-01-22T22:30:11.000Z","size":373,"stargazers_count":6,"open_issues_count":16,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-07-07T12:16:30.710Z","etag":null,"topics":["extism","raspberrypi","rust","wasm","ws2812b","ws281x"],"latest_commit_sha":null,"homepage":"https://wymcg.github.io/matricks/","language":"Rust","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/wymcg.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2023-04-11T03:28:58.000Z","updated_at":"2024-05-12T06:45:22.000Z","dependencies_parsed_at":"2023-06-03T16:30:14.093Z","dependency_job_id":"2ffd786f-63b7-45f1-a0fc-a0be3b294f72","html_url":"https://github.com/wymcg/matricks","commit_stats":null,"previous_names":[],"tags_count":8,"template":false,"template_full_name":null,"purl":"pkg:github/wymcg/matricks","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wymcg%2Fmatricks","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wymcg%2Fmatricks/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wymcg%2Fmatricks/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wymcg%2Fmatricks/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/wymcg","download_url":"https://codeload.github.com/wymcg/matricks/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/wymcg%2Fmatricks/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":270781200,"owners_count":24643805,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-08-16T02:00:11.002Z","response_time":91,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["extism","raspberrypi","rust","wasm","ws2812b","ws281x"],"created_at":"2025-07-07T16:02:30.209Z","updated_at":"2025-08-16T22:33:56.551Z","avatar_url":"https://github.com/wymcg.png","language":"Rust","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Matricks\n\n\u003e _\"Teach an old matrix new tricks...\"_\n\nMatricks is a WASM-based extensible LED matrix control tool intended for use on Raspberry Pi devices.\nLED matrix functionality is defined by user-developed plugins, or \"tricks\", which can be developed in any language that \nis supported by the [Extism PDK](https://extism.org/docs/category/write-a-plug-in). \nTo simulate plugins while you're developing them, check out [Simtricks](https://github.com/wymcg/simtricks)!\n\n## Run Matricks\n\n### Installation on Raspberry Pi\n- Install 64-bit Raspbian[^1] on your Raspberry Pi[^2]\n- Install Rust and Cargo from [the Rust website](https://rustup.rs)\n- Run `apt install libclang-dev libssl-dev`\n- Run `cargo install matricks`\n- [Configure your Raspberry Pi](#raspberry-pi-configuration) and reboot\n\n### Use a pre-compiled binary\nFor convenience, pre-compiled binaries are available in the releases tab.\n- [Configure your Raspberry Pi](#raspberry-pi-configuration) and reboot\n- Run the following command to download and run Matricks:\n\n```\nMATRICKS_VERSION=0.3.1 \u0026\u0026 \\\nwget https://github.com/wymcg/matricks/releases/download/v$MATRICKS_VERSION/matricks_$MATRICKS_VERSION \u0026\u0026 \\ \nchmod +x matricks_$MATRICKS_VERSION \u0026\u0026 \\\n./matricks_$MATRICKS_VERSION \n```\n\n### Cross-compilation\n- On another device,\n  - Install Rust and Cargo from [the Rust website](https://rustup.rs)\n  - Run `rustup target add aarch64-unknown-linux-musl`\n  - Run `cargo install cross`\n  - Clone this repository and build with `cross build --release --target aarch64-unknown-linux-musl`\n  - Transfer the produced executable to your Raspberry Pi\n- On your Raspberry Pi,\n  - Install 64-bit Raspbian[^1]\n  - [Configure your Raspberry Pi](#raspberry-pi-configuration) and reboot\n  - Run the executable\n\n## Usage\nThis section describes basic usage of Matricks. For general usage information, run `matricks help`.\nFor a list of plugins to try, there are several example plugins listed in the [examples README](./examples/README.md).\n\n### Manual configuration\nYou may manually provide a configuration to Matricks using `matricks manual`.\nTo run a plugin (or a set of plugins in a directory), Matricks can be invoked as follows:\n\n```\nmatricks manual [OPTIONS] --path \u003cPLUGIN_PATH\u003e --width \u003cWIDTH\u003e --height \u003cHEIGHT\u003e\n```\n\nThis will run the plugin(s) at the given path on the connected matrix.\nOther matrix and plugin configuration options are also available; See `matricks help manual` for more information.\n\n### Saving a configuration\nOnce you have confirmed that everything is working with `matricks manual`, you can save your configuration to a file using the `matricks save` command.\nTo save your configuration, Matricks can be invoked as follows:\n\n```\nmatricks save \u003cNEW_CONFIG_PATH\u003e [OPTIONS] --path \u003cPLUGIN_PATH\u003e --width \u003cWIDTH\u003e --height \u003cHEIGHT\u003e\n```\n\nThis 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.\n`matricks save` has the same matrix and plugin configuration options as `matricks manual`. \nSee `matricks help save` for more information.\n\n### Automatic configuration\nIf you have a TOML configuration file (created either by hand or by running `matricks save`), you can use it using `matricks auto`.\nTo run Matricks with a configuration file, Matricks can be invoked as follows:\n\n```\nmatricks auto \u003cCONFIG_PATH\u003e\n```\n\nThis command will use the configuration information in the given file to drive the matrix.\nSee `matricks help auto` for more information.\n\n### Clearing the matrix\nIf for any reason you need to clear all LEDs on the matrix, Matricks can be invoked as follows:\n\n```\nmatricks clear --width \u003cWIDTH\u003e --height \u003cHEIGHT\u003e\n```\n\nSee `matricks help clear` for more information.\n\n### View Logs\nTo see logs from Matricks, prepend your command with `RUST_LOG=matricks=info`.\nFor example:\n```\nRUST_LOG=matricks=info matricks auto your_config.toml\n```\n\n[^1]: At this time, Matricks can only be installed and run on 64-bit operating systems.\n[^2]: If you are using a Raspberry Pi with less than 1GB of RAM, installation using this method is not recommended.\n\n## Raspberry Pi Configuration\nMatricks requires some configuration before it can be used to drive a LED matrix. \nIf these instructions are not followed, Matricks may not work as expected.\nThis section paraphrases the instructions from the [rpi_ws281x README](https://github.com/jgarff/rpi_ws281x#spi).\n\n### Enable SPI\nThe easiest way to enable SPI on Raspberry Pi is with the `raspi-config` command line tool.\nRun `sudo raspi-config` and navigate to the SPI activation dialog by selecting `Interface Options \u003e SPI`.\n\n### Change GPU Core Frequency\nAdd the following lines to `/boot/config.txt`:\n\n| Device         | Lines to Add                                    |\n|----------------|-------------------------------------------------|\n| Raspberry Pi 3 | ```core_freq=250```                             |\n| Raspberry Pi 4 | ```core_freq=500```\u003cbr/\u003e```core_freq_min=500``` |\n\n### Change SPI Buffer Size (optional)\nOn some distributions, it may be necessary to increase the maximum SPI transfer size by editing `/boot/cmdline.txt` and adding the following line:\n\n```\nspidev.bufsiz=32768\n```","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwymcg%2Fmatricks","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fwymcg%2Fmatricks","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fwymcg%2Fmatricks/lists"}