Introduction

Transform and display telegraf metrics on VU1 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 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 (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

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:

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.