Matrix/API/README.md

## About

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, please make sure you set up a firewall or other kinds of access rules to **forbid any connections** from outside of this machine (localhost).

## How to run

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

- Attached mode:
  ```python
  sudo python3 main.py
  ```
- Running as daemon:

  1. Create a system.d service file:

     ```
     [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.

- `/text`: Display text on buffer
  - text: string
- `/color`: Specify a color to be used by dispaly methods
  - r: int
  - g: int
  - b: int
- `/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

## 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`.

### Example:

```bash
sudo python main.py --led-rows=64 --led-cols=64 --led-slowdown-gpio=5 --led-parallel=3 --led-chain=3 --led-gpio-mapping=regular
```