Matrix/API/README.md

About

This is a REST API to access the Raspberry PI RGB LED Matrix over HTTP.

Note: This webserver should never be exposed to the outside of the system it's running on, since it's meant to be combined with the provided SvelteKit Webserver to serve a GUI. Although it can still be run in standalone (more on this here), please make sure you set up a firewall or other kinds of access rules to forbid any connections from outside of this machine (localhost).

Prerequisites

1. Install Raspberry PI OS Lite using the official installer.
2. Make sure you have Python version 3.9.* installed, as the library uses a now deprecated module and as it is the only version proven to work.
3. Install all necessary dependencies shown within this library's documentation.
4. It is recommended to access the UI and SSH-Connection to the RPI using an access point. To see how to set one up, see this guide.

Installation

1. Download the main library's repository and follow the installation instructions for the python binding
2. Download repository with git clone https://gitlab1.ptb.de/waltem01/Matrix.git
3. Install and copy the following dependencies of the library to this project:

Note: For further instructions and examples, especially for further development, please refer to the documentation of the library.

Running

Note: Once run, you should not simply kill the process. Graceful shutdown is work-in-progress.

• Setup / Configuration:
  • In case the default Matrix options are not suitable for your configuration, please infer them from the .env.example in the project root
• Attached mode:

  sudo python3 main.py
  

• Running as daemon:

  1. Create a system.d service file in /etc/systemd/system/:

     [Unit]
     After=network.target
     
     [Service]
     Restart=always
     WorkingDirectory=/path/to/project
     ExecStart=/usr/bin/python3 /path/to/project/main.py
     
     [Install]
     WantedBy=multi-user.target
     

  2. Place file in /etc/systemd/system/

  3. Reload system.d daemon:

     sudo systemctl daemon-reload
     

  4. Enable and start service:

     sudo systemctl enable <filename>
     sudo systemctl start <filename>
     

Usage

Webserver

The script will host a waitress webserver on port 8080 of the machine it's running on.

GET Endpoints

• /clear: Clear the buffered canvas
• /update: Swap buffered canvas on VSync

POST Endpoints

Note: All POST Endpoints require to receive form data to function.

• /upload: Upload image to api to be placed in the future
  • url: string
• /image: Position and display image on buffer at full size
  • x: int
  • y: int
• /text: Display text on buffer
  • text: string
• /pixel: Set a single pixel on buffer
  • x: int
  • y: int
• /circle: Display a circle on buffer
  • x: int
  • y: int
  • r: int
• /rectangle: Display a rectangle on buffer
  • x: int
  • y: int
  • w: int
  • h: int
• /line: Display a line on buffer
  • x1: int
  • y1: int
  • x2: int
  • y2: int
• /color: Specify a color to be used by dispaly methods
  • r: int
  • g: int
  • b: int

Flags and Arguments

You may need to specify all kinds of different flags or arguments to run the matrix correctly. For usage, please refer to any of the scripts, followed by the flag --help or directly to the main library documentation.

Example:

sudo python main.py --led-slowdown-gpio=5 --led-gpio-mapping=regular