v0.9

Complete README, Blocked queries graph, Lightsoff mode
2024-12-11 22:52:36 +04:00
parent 841e320fe8
commit 47824edc51
8 changed files with 244 additions and 26 deletions
--- a/README.md
+++ b/README.md
@@ -1,15 +1,145 @@
-# BlockyGrapher
-Query grapher for Blocky DNS Server
+# BlockyGrapher v0.9b
+![Example setup using this software](./images/displaydemo.jpg)
+Physical display query grapher for Blocky DNS Server.
+
+I2C SSD1306 Displays with resolution 128x64 and 128x32 are supported.
+Note that this software in beta, and akward bugs may occur.
+## Preparation
+### Prometheus Metrics endpoint
+Open your Blocky DNS Server configuration. Include HTTP server port and enable Prometheus metrics endpoint.
+```
+ports:
+  dns: 53
+  http: 4500
+
+prometheus:
+  enable: true
+  path: /metrics
+```
+Restart server. Open your HTTP port in browser and head into metrics. You shoud see something like this:
+
+![Prometheus Metrics endpoint](./images/endpoint.png)
+
+You should not open HTTP port to the public (Unless you know what you are doing). Open your config again and edit the ports:
+```
+ports:
+  dns: 53
+  http: 127.0.0.1:4500
+```
+Restart server again.
+### Display Installation
+Both supported SSD1306 displays has 4 I2C pins that we need to connect - VCC, GND, SCL/SCK, SDA.
+
+![SSD1306 128x64/128x32 I2C Displays](./images/ssd1306.jpg)
+
+In this example we will look at Orange PI Zero 3. 
+
+![Orange PI Zero 3 pinout](./images/zero3pinout.png)
+
+We need I2C pins here. We also need 5V (Which is VCC) pin and GND. Connect these to the display.
+
+![Connection](./images/zero3pinoutcut.png)
+
+### Enabling I2C support in SoC Board settings
+On most SoC Boards you need to enable I2C devices support.
+In this example, we have Orange PI4 LTS with Armbian OS.
+We need to open armbian configuration utility `sudo armbian-config` and proceed to System > Hardware.
+Note that Orange PI4 LTS has RK3399 SoC. We need to select RK3399 I2C entries. Apply the changes and reboot.
+
+![Armbian Config GUI](./images/rk3399i2c.png)
+
+In some cases GUI Hardware configuration tool may not be available (Like Orange PI Zero 3 with DietPI OS). In that case you need to edit startup environment file in `/boot` directory.
+```bash
+~$ nano /boot/dietpiEnv.txt
+
+rootdev=UUID=XXXXXXXX-XXXX-XXXX-XXXX-XXXXXXXXXXXX
+rootfstype=ext4
+consoleargs=console=ttyS0,115200 console=tty1
+usbstoragequirks=
+extraargs=net.ifnames=0
+docker_optimizations=off
+overlay_path=allwinner
+overlay_prefix=sun50i-h616
+# We need to insert hardware I2C name in overlays. In case of Orange PI Zero 3 this is i2c3. 
+overlays=i2c3
+user_overlays=
+```
+Save and reboot.
+
 ## Install python packages
 Debian-based:
 ```bash
 # install system packages
+apt update
 apt install i2c-tools python3-dev python3-pip python3-numpy libfreetype6-dev libjpeg-dev build-essential
-# Give user permission to use i2c interface (Replace user with your name). Remember that you need re-login to user after this (You can reboot too if it didn't work for some reason).
+# Give user permission to use i2c interface (Replace user with your username). Remember that you need re-login to user after this (You can reboot too if it didn't work for some reason).
 usermod -a -G i2c user
 # install python packages
 pip install -r requirements.txt --break-system-packages
 ```
-## Finding right port
+## Finding right port/address and starting the program
+*In most cases pysical I2C port can differ from system I2C port binding!* It's better to double-check the ports before proceeding.
+
 `i2cdetect -l` can help to find port you need to use.
-Schematics for your adapter/board can also help. 
+```
+~$ sudo i2cdetect -l
+i2c-0   i2c             mv64xxx_i2c adapter                     I2C adapter
+i2c-1   i2c             DesignWare HDMI                         I2C adapter
+i2c-2   i2c             mv64xxx_i2c adapter                     I2C adapter
+```
+In this example we can see that ether port 0 or port 2 is needed. Let's pick port 2.  
+SSD1306 128x64 and 128x32 displays usually have 0x3C/0x30 address. 
+```
+~$ sudo i2cdetect -y 2
+     0  1  2  3  4  5  6  7  8  9  a  b  c  d  e  f
+00:                         -- -- -- -- -- -- -- --
+10: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+20: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+30: -- -- -- -- -- -- -- -- -- -- -- -- 3c -- -- --
+40: -- -- -- -- -- -- -- -- -- -- -- -- -- -- -- --
+```
+We found our display! Now we can start the grapher.
+```
+python3 dnsmonitor.py --i2c-port 2 --i2c-address 0x3C
+```
+Note that during first successful startup, you will need to edit newly created `config.ini` configuration file.
+```
+[F] [16:54:12] config.ini does not exist. Please edit newly created file and start the program.
+```
+You can see all available startup options using `python3 dnsmonitor.py -h`.
+## Cofiguration
+Unedited `config.ini` will look like this:
+```
+[source]
+url = http://127.0.0.1:4500/metrics
+[appearance]
+points = 14
+pointsDistance = 10
+dots = True
+[lightsoff]
+enabled = False
+start = 23
+stop = 06
+```
+### `[source]`
+`url` - Contains Prometeus endpoint URL.
+### `[appearence]`
+`points` - Amount of points on the graph. Each point pepresents each hour passed. Note that points can can render out of display bounds.
+
+`pointsDistance` - Distance between the points.
+
+`dots` - Renders small dots on each hour. Improves graph readability.
+### `[lightsoff]`
+`enabled` - Enables Lights OFF mode. During set up period in `start` and `stop` values, turns display off completely. May be useful during the nighttime, where *you are sleeping and not paying attention at all* (OLED displays are VERY bright during night as well).
+
+`start` - Hour, when Lights OFF mode starts.
+
+`stop` - Hour, when Lights OFF mode ends.
+## Install as service (Autorun)
+### TODO
+## Credits
+[Terminus Font](https://files.ax86.net/terminus-ttf/) - Font used by numbers in graph.
+
+[Font Awesome V4](https://fontawesome.com/v4/) - Icons
+
+[luma.oled](https://github.com/rm-hull/luma.oled) - SSD1306 Display Driver