improve and update documentation

This commit is contained in:
waltem01 2024-03-15 09:18:35 +01:00
parent fb6aba75d7
commit 11a8d6d473
3 changed files with 41 additions and 18 deletions

View File

@ -1,20 +1,28 @@
## About ## About
REST API to access the Raspberry PI RGB LED Matrix over HTTP. 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 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). **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).
## How to run ## 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
**Note:** Once run, you should not simply kill the process. Graceful shutdown is work-in-progress. **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: - Attached mode:
```python ```python
sudo python3 main.py sudo python3 main.py
``` ```
- Running as daemon: - Running as daemon:
1. Create a system.d service file in `/etc/systemd/system/`:
1. Create a system.d service file:
``` ```
[Unit] [Unit]
@ -58,12 +66,13 @@ The script will host a `waitress` webserver on port `8080` of the machine it's r
**Note**: All POST Endpoints require to receive form data to function. **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`: Display text on buffer
- text: string - 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 - `/pixel`: Set a single pixel on buffer
- x: int - x: int
- y: int - y: int
@ -76,13 +85,22 @@ The script will host a `waitress` webserver on port `8080` of the machine it's r
- y: int - y: int
- w: int - w: int
- h: 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 ## 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`. 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: ### Example:
```bash ```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 sudo python main.py --led-slowdown-gpio=5 --led-gpio-mapping=regular
``` ```

View File

@ -2,7 +2,7 @@
## Description ## Description
This project is a two-part software solution designed to drive LED matrices. It leverages a [specific library](./API/deps/librgbmatrix.so), which is originally designed for controlling LED matrices. The project adds an additional layer of abstraction to this library, making it more accessible and easier to use. This project is a two-part software solution designed to drive LED matrices. It leverages a [specific library](./API/deps/librgbmatrix.so), which was originally uploaded by Github user [`hzeller`](https://github.com/hzeller/). The project adds an additional layer of abstraction to this library, making it more accessible and easier to use.
### REST API ### REST API
@ -14,4 +14,8 @@ The second part of the project is a [webserver](./Webserver/). This server inter
## Project Structure ## Project Structure
The project is divided into two main directories, each containing the necessary files for the [REST API](./API/) and the [webserver](./Webserver/) respectively. You might've noticed the links to these directories whenever they were mentioned. The setup instructions for each part are provided within their respective directories. The project is divided into two main directories, each containing the necessary files for the [REST API](./API/) and the [Webserver](./Webserver/) respectively. You might've noticed the links to these directories whenever they were mentioned. The setup instructions for each part are provided within their respective directories.
## Environment Variables
The project is configured using optional environment variables. You will find project-wide variables here in [`.env.example`](./.env.example) that both the [REST API](./API/) and the [Webserver](./Webserver/) use to configure your hardware configuration.

View File

@ -1,6 +1,6 @@
## About ## About
This is a Webserver to host a Website on the same machine as the Matrix API. This allows users to access its functions and developers to implement new features and interfaces such as games as demos. This is a Webserver to host a Website on the same machine as the Matrix API. It allows users to access the functions provided by the [API](../API/) and developers to implement new features and interfaces such as games as demos.
## Installation ## Installation
@ -29,10 +29,11 @@ You can preview the production build with `npm run preview`.
## Running ## Running
1. Navigate into the production environment with `cd build/` 1. After finishing the [build process](#Building):
2. Install dependencies with `npm ci --omit dev` 2. Navigate into the production environment with `cd build/`
3. Start the production server with `node .` 3. Install dependencies with `npm ci --omit dev`
4. Start the production server with `node .`
## Note ## Note
If the Matrix API is executed on a separate device, although this has been explicitly advised against, you will need to point the Webserver to it by setting the environment variables shown in [`.env.example`](.env.example). If the Matrix API is executed on a separate device, although this is explicitly advised against, you will need to point the Webserver to it by setting the optional environment variables shown in [`.env.example`](.env.example).