matrix API README

API/README.md

@@ -0,0 +1,78 @@
+## About
+
+REST API to access the Raspberry PI RGB LED Matrix over HTTP.
+
+## 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.
+
+**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. For this reason, please make sure you set up a firewall or other kinds of access rules to **forbid any connections** from outside of this machine (localhost).
+
+### 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