From 11a8d6d473409061e35e097be4404b7bdfe27eac Mon Sep 17 00:00:00 2001
From: waltem01 <simon.waltemathe@ptb.de>
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).
-- 
GitLab