157 lines
5.7 KiB
Markdown
157 lines
5.7 KiB
Markdown
# BlockyGrapher v0.9b
|
|
|
|
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:
|
|
|
|
|
|
|
|
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.
|
|
|
|
|
|
|
|
In this example we will look at Orange PI Zero 3.
|
|
|
|
|
|
|
|
We need I2C pins here. We also need 5V (Which is VCC) pin and GND. Connect these to the display.
|
|
|
|
|
|
|
|
### 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.
|
|
|
|
|
|
|
|
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 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/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.
|
|
```
|
|
~$ 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 BlockyGrapher.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 BlockyGrapher.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)
|
|
After succssesful install, you probably want to install it as service.
|
|
|
|
Edit `BlockyGrapher.service`. The only lines you really want to change are `User`, `Group`, `WorkingDirectory`, `ExecStart`. Also uncomment and change `After` with service name if you have one.
|
|
|
|
Copy file.
|
|
```
|
|
sudo cp BlockyGrapher.service /etc/systemd/system/
|
|
```
|
|
Start service.
|
|
```
|
|
sudo systemctl start BlockyGrapher
|
|
```
|
|
## 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
|