Update README.md

2024-12-02 19:24:36 +01:00 · 2024-12-02 19:24:36 +01:00 · 4ec8252534
commit 4ec8252534
parent d14985f63b
1 changed files with 106 additions and 0 deletions
--- a/README.md
+++ b/README.md
@ -0,0 +1,106 @@
+Introduction
+===
+
+Transform and display [telegraf](https://influxdata.com/telegraf) metrics on [VU1 dials](https://streacom.com/products/vu1-dynamic-analogue-dials/). 
+
+Equiped with a plugin system to avoid repeating common tasks like color transformation and mapping and a small YAML file for easy and flexible configuration.
+
+How does it work?
+===
+`telegraf_to_vu1` uses [vu1-py](https://git.geekify.de/sqozz/vu1-py) to talk and interface with the Streacom VU1 analog gauges. It can address multiple dials and sets properties like background image, color or gauge value regularly based on a users configuration and used plugins. Instead of collecting these values on its own, it relies on telegraf - a very flexible metric collection daemon - to collect and deliver them as JSON via stdin to `telegraf_to_vu1`. A user configures plugins to take these values, understand and transform them and apply all wanted settings to a configured dial.
+
+Requirements
+===
+1. [telegraf](https://influxdata.com/telegraf) (no database like influxdb or prometheus, etc required)
+2. https://git.geekify.de/sqozz/vu1-py needs to be installed - vu1.py can simply be (soft)linked into this repository
+3. A working and configured instance of the [VU Dials Server Application](https://github.com/SasaKaranovic/VU-Server)
+
+Configuration
+===
+
+VU Dials Server
+---
+1. Follow https://vudials.com/ and open your local http interface
+2. Go to "API Keys" and either take the "MASTER_KEY" (not recommended) or create a new one
+    * Ensure the key can access **all** dials you want to control later
+
+telegraf
+---
+First, create a output configuration which calls the `main.py`:
+
+```
+[[outputs.execd]]
+  command = ["/home/user/git/telegraf_to_vu1/main.py", "-c", "/home/user/git/telegraf_to_vu1/config.yaml"]
+  data_format = "json"
+```
+
+Second, create the according input sections you want to display on your dial. A plugin needs to exist which understands these inputs data. Existing plugins can be found in: https://git.geekify.de/sqozz/telegraf_to_vu1/src/branch/main/dial_configs - they are very easy to implement. A few generic plugins should work on any system like e.g. CPU utilization, RAM usage und fan speed (altough currently the fan speed plugin implements Lenovo ThinkPad details). According telegraf config entries are:
+
+```
+[[inputs.cpu]]
+  percpu = false
+  totalcpu = true
+  collect_cpu_time = false
+  report_active = false
+  core_tags = false
+  fieldpass = ["usage_idle"]
+  taginclude = [""]
+
+[[inputs.mem]]
+  fieldpass = ["used_percent"]
+  taginclude = [""]
+
+[[inputs.sensors]]
+  remove_numbers = false
+  taginclude = ["chip", "feature"]
+  [inputs.sensors.tagpass]
+    feature = [ "fan1", "fan2" ] # include fan speeds
+    chip = [ "BAT0-acpi-0" ] # include battery voltage and charge power
+```
+
+`taginclude`, `fieldpass` or `tagpass` are used to further reduce collected values to only interesting data. The less `telegraf_to_vu1` is called, the less it needs to waste resources in filtering out unneeded metrics.
+
+The "GPULoad"-plugin demonstrated how telegraf can be (ab)used to even just follow a value in some file and display it on the gauge:
+
+```
+[[inputs.file]]
+  files = ["/sys/class/drm/card0/device/gpu_busy_percent"]
+  name_override = "gpu_busy_percent"
+  data_format = "value"
+  data_type = "integer" # required
+```
+(this works on an AMD system with APU and amdgpu kernel driver)
+
+telegraf_to_vu1
+---
+Lastly you can link everything together to your liking. Start with the connection to the VU1 server by editing the `vuserver`-section:
+
+```
+vuserver:
+  api:
+    url: "http://localhost:5340" # default if you didn't change it
+    password: "" # the API key previously created
+```
+
+The `assets`-key defines a folder where assets are stored. Currently these are not public but based on the [starter VU1 images](https://vudials.com/download/image_pack):
+
+```
+assets: "/home/user/Downloads/image_pack"
+```
+
+Each plugin decides on its own which image it looks for in this folder.
+
+In the `dials`-section, you define the UIDs of each of your dial and optionally give them a nice alias to reference them later with. Each dial has to have its unique id (taken from the VU1 server application) and can have one or multiple aliases:
+
+```
+dials:
+  "0123456789ABCDEFGHIJKLMN":
+    aliases:
+      - "my_dial"
+  "RIBAILOFEE2CHOONGUVAHCAE":
+    aliases:
+      - "outside"
+      - "my_dial2"
+```
+
+At last, configure your `config_sets`. A config set has a name (e.g. "notebook") and contains several dials and a plugin attached to this specific dial. When running, `telegraf_to_vu1` will match each received metric against the configured plugin, transform the data (if needed), generate a color based on a schema (e.g. spectrum) and set it to the hardware dial.