{"id":28066033,"url":"https://github.com/jeremynoesen/matrixdisplay","last_synced_at":"2025-05-12T14:36:00.239Z","repository":{"id":42023238,"uuid":"435257842","full_name":"jeremynoesen/MatrixDisplay","owner":"jeremynoesen","description":"A program to control a Raspberry Pi with a Unicorn HAT from a web interface","archived":false,"fork":false,"pushed_at":"2025-05-10T22:06:37.000Z","size":583,"stargazers_count":2,"open_issues_count":0,"forks_count":1,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-12T14:35:53.354Z","etag":null,"topics":["images","led-matrix","python","raspberry-pi","unicorn-hat"],"latest_commit_sha":null,"homepage":"https://youtu.be/zxgAzgMzVN0","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"gpl-3.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/jeremynoesen.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,"zenodo":null},"funding":{"github":"jeremynoesen"}},"created_at":"2021-12-05T19:22:00.000Z","updated_at":"2025-05-10T22:06:40.000Z","dependencies_parsed_at":"2025-05-10T04:32:49.692Z","dependency_job_id":null,"html_url":"https://github.com/jeremynoesen/MatrixDisplay","commit_stats":null,"previous_names":[],"tags_count":14,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremynoesen%2FMatrixDisplay","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremynoesen%2FMatrixDisplay/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremynoesen%2FMatrixDisplay/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/jeremynoesen%2FMatrixDisplay/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/jeremynoesen","download_url":"https://codeload.github.com/jeremynoesen/MatrixDisplay/tar.gz/refs/heads/main","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":253755779,"owners_count":21959080,"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","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":["images","led-matrix","python","raspberry-pi","unicorn-hat"],"created_at":"2025-05-12T14:35:59.396Z","updated_at":"2025-05-12T14:36:00.216Z","avatar_url":"https://github.com/jeremynoesen.png","language":"Python","funding_links":["https://github.com/sponsors/jeremynoesen"],"categories":[],"sub_categories":[],"readme":"\u003cimg src=\"img/Logo.svg\" alt=\"Logo\" title=\"Logo\" align=\"right\" width=\"72\" height=\"72\" /\u003e\n\n# MatrixDisplay\n\n## About\n\nMatrixDisplay is a Python program used to display images on the Pimoroni Unicorn HAT for Raspberry Pi through a web\ninterface.\n\n## Purpose\n\nThis project exists mainly as a way for me to try a new programming language, as well as to create a project that has\nboth software and hardware aspects in it. I also just wanted to make my own smart home gadget.\n\n## Usage\n\n### Web Interface\n\nOn the same network as the Raspberry Pi, open your browser to `http://yourpihostname.local:8080/ui`. From there, you can\ncontrol the display output from a web interface. Note that this page does not automatically refresh; it only updates\nwhen you click something or manually refresh the page.\n\n\u003cdiv align=\"center\" \u003e\u003cimg src=\"img/webinterface.png\" alt=\"Example Web Interface\" title=\"Example Web Interface\" /\u003e\u003c/div\u003e\n\n### API\n\nThis API is used by the web interface, but can also be used by other programs to control the display.\n\n#### GET\n\n- `http://DISPLAY-IP:8080/ui`: Get web interface HTML\n- `http://DISPLAY-IP:8080/api`: Get device state as JSON\n\n#### POST\n\n- `http://DISPLAY-IP:8080/api`: Set device state with JSON\n\n#### JSON Format\n\n```json\n{\n  \"mode\": \"off\",\n  \"image\": \"image.png\",\n  \"display_time\": 0,\n  \"color\": \"000000\",\n  \"brightness\": 100,\n  \"warmth\": 0\n}\n```\n\n- `mode`: `image`, `slideshow`, `color`, or `off`\n- `image`: Image file name\n- `display_time`: Display time for slideshow in seconds\n- `color`: Color for color mode in hex\n- `brightness`: Display brightness as a percent\n- `warmth`: Display warmth as a percent\n\n## Requirements\n\n### Software:\n\n- Python 3\n- [unicorn-hat](https://github.com/pimoroni/unicorn-hat) library\n- [Pillow](https://pypi.org/project/Pillow/) library\n\n### Hardware:\n\n- Raspberry Pi with the 40-pin header\n- [Pimoroni Unicorn HAT](https://shop.pimoroni.com/products/unicorn-hat)\n- [Pibow Ninja](https://shop.pimoroni.com/products/pibow-for-raspberry-pi-3-b-plus?variant=2601126395914) case (\n  optional)\n- [Pibow Ninja diffuser](https://shop.pimoroni.com/products/pibow-modification-layers?variant=1047619725) Pibow\n  modification layer (optional)\n- Micro USB cable for power\n- Micro SD card\n\n## Installation\n\n1. Install Python 3.\n2. Clone or download this repository onto the Raspberry Pi.\n3. Run `pip3 install -r requirements.txt`.\n4. If using Systemd to auto-start the program, Create the following `matrixdisplay.service` file\n   in `/etc/systemd/system/`, making sure to change the `WorkingDirectory` and `ExecStart`, as well as the `User`:\n\n```ini\n[Unit]\nDescription = MatrixDisplay Program\nAfter = network-online.target\n\n[Service]\nWorkingDirectory = /path/to/MatrixDisplay/\nExecStart = /usr/bin/sudo /usr/bin/python3 /path/to/main.py\nUser = set_user_here\nType = simple\nRestart = on-failure\n\n[Install]\nWantedBy = multi-user.target\n```\n\n## Running\n\n### Manual\n\nRun `sudo python3 /path/to/main.py`.\n\n### Systemd\n\nRun `sudo systemctl enable matrixdisplay \u0026\u0026 sudo systemctl start matrixdisplay` to start the service and set it to run\nat boot.\n\n## Configuration\n\nThere are two configurable values located in `config.py`:\n\n- `pictures_dir`: The location of the directory where images are stored. This directory should only contain images and\n  no hidden files.\n    - When adding images to this directory, you must refresh the web interface for the images list to\n      update.\n    - If running the slideshow, you must restart the slideshow mode for the new images to show up.\n- `cache_dir`: The location of the directory where cached images will be saved.\n    - If an image is ever modified in the\n      pictures directory, remove the corresponding file from this directory to have it be regenerated.\n\n## Updating\n\n1. Re-download or git pull (if you cloned) this repository.\n2. Run `pip3 install -r requirements.txt` to install any new requirements.\n3. Restart the program. (If using systemd, run `sudo systemctl restart matrixdisplay`).\n\n## Home Assistant\n\nThis project can be added to Home Assistant using the RESTful Switch integration. The following is an example entry\nin `configuration.yaml` to add a switch to Home Assistant that turns the display on to slideshow mode with set\nbrightness and warmth, as well as turn it off:\n\n```yaml\nswitch:\n  - platform: rest\n    resource: http://DISPLAY-IP:8080/api\n    body_on: '{\"mode\": \"slideshow\", \"display_time\": 60, \"brightness\": 40, \"warmth\": 20}'\n    body_off: '{\"mode\": \"off\"}'\n    is_on_template: '{{ value_json.mode != \"off\" }}'\n    headers:\n      Content-Type: application/json\n    verify_ssl: false\n    name: matrix_display\n```\n\n## Demonstration\n\n[Watch on YouTube](https://youtu.be/zxgAzgMzVN0)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeremynoesen%2Fmatrixdisplay","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fjeremynoesen%2Fmatrixdisplay","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fjeremynoesen%2Fmatrixdisplay/lists"}