Matrix/API/README.md

107 lines
3.2 KiB
Markdown
Raw Normal View History

2023-11-30 14:16:07 +00:00
## About
2024-03-15 08:18:35 +00:00
This is a REST API to access the Raspberry PI RGB LED Matrix over HTTP.
2023-11-30 14:16:07 +00:00
2024-03-15 08:18:35 +00:00
**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).
2024-01-11 13:39:17 +00:00
2024-03-15 08:18:35 +00:00
## Installation
1. 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.
2. 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
3. Download repository with `git clone https://gitlab1.ptb.de/waltem01/Matrix.git`
4. Navigate to the API directory with `cd API/`
## Running
2023-11-30 14:16:07 +00:00
**Note:** Once run, you should not simply kill the process. Graceful shutdown is work-in-progress.
2024-03-15 08:18:35 +00:00
- 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
2023-11-30 14:16:07 +00:00
- Attached mode:
```python
sudo python3 main.py
```
- Running as daemon:
2024-03-15 08:18:35 +00:00
1. Create a system.d service file in `/etc/systemd/system/`:
2023-11-30 14:16:07 +00:00
```
[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.
2024-03-15 08:18:35 +00:00
- `/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
2023-11-30 14:16:07 +00:00
- `/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
2024-03-15 08:18:35 +00:00
- `/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
2023-11-30 14:18:44 +00:00
## Flags and Arguments
2024-03-15 08:18:35 +00:00
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.
2023-11-30 14:18:44 +00:00
### Example:
```bash
2024-03-15 08:18:35 +00:00
sudo python main.py --led-slowdown-gpio=5 --led-gpio-mapping=regular
2023-11-30 14:18:44 +00:00
```