new readme

README.org

@@ -1,27 +1,54 @@
 * README
 Welcome welcome...
-This is a personal project to display the current playing Spotify track on a small LCD screen connected to a Raspberry Pi.
+This is a personal project to have a small screen to show hardware stats and currently playing track
-
+[[https://photos.barrys.cloud/api/assets/90056fad-36ad-4de4-9133-0d6262d63a1f/thumbnail?size=preview&key=llUU6Y5rliO27GQo6lanGlLt_zsIT7AjDhC-s1f0NQVOlSNsgbP8ezh2hfLDm6uBeLs][Final Results]]
 ** What it does:
+*** How did it start
+This project started from a spare 2" LCD display from [[https://www.waveshare.com/2inch-lcd-module.htm][waveshare]], the display is a 320 x 240 pixel, inexpensive diplay, good as a cheap Pi stats monitor.
+Initially I just wanted to show the currently playing song from Spotify, with a simple clock idle screen, then I started playing around with adding features to the idle screen, until I realized I started to get more use out of the idle screen than the track display feature, so the scope of the project broadened.
 *** Project's scope
-This project aims to act as a view only display to showcase the current playing song on Spotify, it is built to support only one specific display and the Pi 5 hardware, no other platforms are intended to be supported soon.
+This project aims to display your raspberry pi homelab stats on the supported LCD screen.
+To provide something like a 'mini htop' for your Pi homelab.
+This is still pretty vague but feature by feature I decide if the information showed is worth the space that it takes.
 *** Features & Functionality
+[[./imgs/output_warm_50.gif]]
+*Idle Screen*
+
 This project uses the Spotify API to authenticate the user and pull live information about currently playing song, the information is then displayed in the screen.
 *Features:*
+- Idle Screen:
+  - dynamically rendered CPU temperature through time, with customizable color map.
+  - CPU utilization %, displays smooothened CPU % values through time
+  - RAM usage, displays a box plot of RAM used through time
 - Track Display: displays the track name, artists and album cover.
-- Dynamic Progress bar: displays the track progress dynamically, to reduce API calls the bar assumes the track continues playing in-between requests, to smoothly contine updating the bar every =refresh_interval=
+  - Dynamic Progress bar: displays the track progress dynamically, to reduce API calls the bar assumes the track continues playing in-between requests, to smoothly contine updating the bar every =refresh_interval=
-- Standby Screen: displays current time and QR code, the QR code can be set by the user to connect to a Spotify Speaker.
+  - Standby Screen: displays current time and QR code, the QR code can be set by the user to connect to a Spotify Speaker.
 - Easy Config: all the parameters needed by the app running can be set in =config.yaml=, including the API polling rate interval, the display refresh interval, Spotify's app credential and the color scheme. The colors of all the UI components are exposed and controllable in this configuration file.
 ** Get Started:
 *** Hardware Requirements
 This project is build for [[https://www.waveshare.com/wiki/2inch_LCD_Module][this]] specific screen, a 2" LCD SPi Display, compatible with different models of Raspberry Pi, this code is tested on a Pi 3b+ and a Pi 5.
+To get the screen connected to the Pi follow [[https://www.waveshare.com/wiki/2inch_LCD_Module#Raspberry_Pi_hardware_connection][this]] guide, the code assumes the following wiring:
+| LCD | color  | Pi   | Pi 5 PIN nr |
+|-----+--------+------+-------------|
+| VCC | purple | 3.3  |          17 |
+| GND | white  | GND  |          20 |
+| DIN | green  | MOSI |          19 |
+| CLK | orange | SCL  |          23 |
+| CS  | yellow | CE0  |          24 |
+| DC  | blue   | GPIO |         22* |
+| RST | brown  | GPIO |         13* |
+| BL  | gray   | GPIO |         12* |
+where the pins marked with an asterisk are arbitrarily set to those pins, but any available GPIO pin can do, in the case where you make changes to the wiring, change the =__init__= parameters of the =RaspberryPi= class in =spotiplayer_pi/lcdconfig.py=.
+The pinout can be seen here:
+[[./imgs/pi_pinout.png]]
+The PIN number in the table corresponds to the number written inside the pin circle, and if you change the pinout, for example of the RST from pin 13 (GPIO 27), to pin 33 (GPIO 13), then rst=13 in the init of the RaspberryPi class in =lcdconfig.py=
 *** Software Requirements
 This project uses python3.11 and assumes you have it already installed.
 For development poetry is used to create a virtualenv and handle dependencies, ultimately the code must be run as =sudo= so the dependencies must be installed on the root python interpreter anyways, so the poetry virtualenv is for developement only.
 *** Install
 To install, start by cloning this repo with
 #+begin_src shell
-git clone http://192.168.1.244:8080/barry/spotiplayer-pi.git
+git clone https://git.barrys.cloud/barry/spotiplayer-pi.git
 cd spotiplayer-pi
 #+end_src
 Then make sure you have poetry installed, to install on the Pi run: =curl -sSL https://install.python-poetry.org | python3 -=
@@ -41,13 +68,15 @@ To run the script there are two options, either from a CLI, with:
 #+begin_src shell
 sudo python -m spotiplayer_pi.main
 #+end_src
-or as a systemd service, which guarantees that the script will be restarted if it fails, to activate it do:
+Once you ran the script and verified that it works, you can run the app as a systemd service, which guarantees that the script will be autostarted and it will be restarted if it fails, to activate it do:
 #+begin_src shell
-# TODO
+cp spotiplayer.service /etc/systemd/system
+systemctl daemon-reload
+systemctl enable --now spotiplayer
 #+end_src
 *** Configure
 To configure the app's settings go to =spotiplayer_pi/config.yaml=, it contains all user modifiable settings, there you can set the progress bar refresh rate, the API polling rate and the color scheme of the play screen.
-*** Develop
+*** Contribute
 To contribute to the developement you will find some dev tools already implemented, to use them first install the extra dependencies with:
 #+begin_src shell
 poetry install --with dev
@@ -56,6 +85,10 @@ Now you have access to pre-commit with the following hooks:
 - *ruff*: format and lint .py files
 - *tests*: run all tests in =tests/=
 - *requirements*: checks if the output of =poetry export= matches =requirements.txt=
-Only if all checks pass it is possible to make a commit
+Only if all checks pass it is possible to make a commit.
-** Code Philosophy / Style
+** Project's Philosophy / Code Style
-# TODO
+This project is built on one display, so all the layout is hardcoded for its dimensions, no other dimensions are planned to be supported soon.
+The display must remain minimalistic, since its small size, to keep readability. So screen space is our most important resource that we have to optimize, if you want to implement a feature first ask yourself: "Do I need to see that information 24/7?" this will exclude most features that might be nice to have but unnecessary, here we want only the necessary.
+
+The code style is to reduce as much as possible the layers of abstraction, to have code that can be read from top to bottom in a natural way without having to jump around many different files multiple time to understand what is the purpose and functionality of a function.
+The only times when creating a function is allowed is to remove duplicate code and when the atomic scope of some code is fundamentally different from the function it resides in.