From 11a8d6d473409061e35e097be4404b7bdfe27eac Mon Sep 17 00:00:00 2001 From: waltem01 Date: Fri, 15 Mar 2024 09:18:35 +0100 Subject: [PATCH] improve and update documentation --- API/README.md | 40 +++++++++++++++++++++++++++++----------- README.md | 8 ++++++-- Webserver/README.md | 11 ++++++----- 3 files changed, 41 insertions(+), 18 deletions(-) diff --git a/API/README.md b/API/README.md index 9b979b8..f16723b 100644 --- a/API/README.md +++ b/API/README.md @@ -1,20 +1,28 @@ ## 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. +- 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: + 1. Create a system.d service file in `/etc/systemd/system/`: ``` [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. +- `/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 -- `/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 @@ -76,13 +85,22 @@ The script will host a `waitress` webserver on port `8080` of the machine it's r - 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`. +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-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 ``` diff --git a/README.md b/README.md index b198073..84c29dd 100644 --- a/README.md +++ b/README.md @@ -2,7 +2,7 @@ ## 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 @@ -14,4 +14,8 @@ The second part of the project is a [webserver](./Webserver/). This server inter ## 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. diff --git a/Webserver/README.md b/Webserver/README.md index 5c7eccd..2905bbb 100644 --- a/Webserver/README.md +++ b/Webserver/README.md @@ -1,6 +1,6 @@ ## 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 @@ -29,10 +29,11 @@ You can preview the production build with `npm run preview`. ## Running -1. Navigate into the production environment with `cd build/` -2. Install dependencies with `npm ci --omit dev` -3. Start the production server with `node .` +1. After finishing the [build process](#Building): +2. Navigate into the production environment with `cd build/` +3. Install dependencies with `npm ci --omit dev` +4. Start the production server with `node .` ## 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).