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](../Webserver/) to serve a GUI. Although it can still be run in standalone (more on this [here](../Webserver/README.md)), 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](https://www.raspberrypi.com/software/).
2. Make sure you have Python version 3.9.* installed, as the [library](https://github.com/hzeller/rpi-rgb-led-matrix) 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](https://github.com/hzeller/rpi-rgb-led-matrix/blob/master/bindings/python/README.md).

## Installation

1. Download the main [library](https://github.com/hzeller/rpi-rgb-led-matrix)'s repository and follow the installation [instructions](https://github.com/hzeller/rpi-rgb-led-matrix/blob/master/bindings/python/README.md) 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](https://github.com/hzeller/rpi-rgb-led-matrix/blob/master/bindings/python/samples/).

## 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`](../.env.example) in the project root
- Attached mode:
  ```python
  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:

     ```bash
     sudo systemctl daemon-reload
     ```

  4. Enable and start service:

     ```bash
     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](https://github.com/hzeller/rpi-rgb-led-matrix/blob/master/README.md) documentation.

### Example:

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