mirror of
https://gitlab1.ptb.de/waltem01/Matrix
synced 2024-11-15 01:13:49 +00:00
117 lines
4.1 KiB
Markdown
117 lines
4.1 KiB
Markdown
## 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).
|
|
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](https://raspberrypi-guide.github.io/networking/create-wireless-access-point).
|
|
|
|
## 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:
|
|
- library/fonts -> ./API/deps/fonts
|
|
- library/bindings/python/samples/samplebase.py -> ./API/deps/samplebase.py
|
|
|
|
**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
|
|
```
|