Konfiguration des Shelly-Collectors

Der Shelly-Collector wird über Umgebungsvariablen konfiguriert.

Lokal oder Cloud

Der Collector erreicht die Geräte auf zwei Wegen. Welcher gilt, entscheidet SHELLY_CLOUD_SERVER:

Lokal: Die Variable bleibt leer. Der Collector fragt jedes Gerät direkt im Heimnetz ab, adressiert über SHELLY_HOST.
Cloud: Die Variable ist gesetzt. Der Collector holt die Messwerte aus der Shelly-Cloud, adressiert über SHELLY_DEVICE_ID und SHELLY_AUTH_KEY.

Sind SHELLY_HOST und SHELLY_CLOUD_SERVER gleichzeitig gesetzt, bricht der Collector beim Start ab. Lokale und Cloud-Geräte lassen sich nicht mischen.

Mehrere Geräte

Ein einziger Collector bedient alle Shelly-Geräte. Dafür nehmen SHELLY_HOST (lokal) bzw. SHELLY_DEVICE_ID (Cloud) und INFLUX_MEASUREMENT eine Komma-getrennte Liste auf. Jedes Gerät schreibt in sein eigenes Measurement.

SHELLY_HOST=192.168.178.5,192.168.178.6
INFLUX_MEASUREMENT=Heatpump,Fridge

Geräteabhängige Optionen (SHELLY_PASSWORD, SHELLY_INVERT_POWER, INFLUX_MODE, INFLUX_POWER_DATA_TYPE) nehmen entweder einen einzelnen Wert für alle Geräte oder eine gleich lange Komma-getrennte Liste.

Für alle Geräte gemeinsam gelten SHELLY_INTERVAL, SHELLY_CLOUD_SERVER, SHELLY_AUTH_KEY und die InfluxDB-Einstellungen.

Umgebungsvariablen

`SHELLY_HOST`

Hostname des Shelly-Geräts. Pflicht beim lokalen Zugriff. Beim Cloud-Zugriff bleibt die Variable leer, dort tritt SHELLY_DEVICE_ID an ihre Stelle.

Üblich ist die IP-Adresse, ein lokaler Gerätename tut es auch. Hier gehört nur der Host hin, kein http:// oder https:// und keine Portnummer.

SHELLY_HOST=192.168.178.5

`SHELLY_PASSWORD`

Passwort des Shelly-Geräts. Nötig ist es nur, wenn das Gerät passwortgeschützt ist. Festgelegt wird der Schutz in der Web-Oberfläche des Shelly unter Settings / Device Settings / Authentication. Ohne die Variable fragt der Collector das Gerät ohne Zugangsdaten ab.

Der Benutzername steht fest auf admin, dafür gibt es keine Variable. Verwendet wird das Passwort nur beim lokalen Zugriff, beim Cloud-Zugriff ignoriert der Collector es.

SHELLY_PASSWORD=my-shelly-password

`SHELLY_CLOUD_SERVER`

Adresse des Shelly-Cloud-Servers, samt https://. Pflicht beim Cloud-Zugriff. Beim lokalen Zugriff bleibt die Variable leer.

Sie ist der Schalter zwischen beiden Zugriffsarten: Ist sie gesetzt, holt der Collector die Messwerte aus der Cloud statt aus dem Heimnetz. Welcher Server der richtige ist, steht in der Shelly-Cloud unter Settings / User Settings / Authorization cloud key. Das Gerät muss dort registriert sein und seine Daten in die Cloud senden.

SHELLY_CLOUD_SERVER=https://shelly-42-eu.shelly.cloud

`SHELLY_AUTH_KEY`

Schlüssel für den Zugriff auf die Shelly-Cloud. Pflicht beim Cloud-Zugriff. Beim lokalen Zugriff ignoriert der Collector die Variable.

Der Schlüssel muss das Recht haben, die Daten der angegebenen Geräte abzurufen. Erstellen und ablesen lässt er sich in der Shelly-Cloud unter Settings / User Settings / Authorization cloud key / Get Key.

SHELLY_AUTH_KEY=ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890

`SHELLY_DEVICE_ID`

ID, unter der die Shelly-Cloud das Gerät führt. Pflicht beim Cloud-Zugriff. Beim lokalen Zugriff ignoriert der Collector die Variable, dort adressiert SHELLY_HOST das Gerät.

Abzulesen ist die ID in der Shelly-Cloud beim jeweiligen Gerät unter Settings / Device information.

SHELLY_DEVICE_ID=12345abcdef0

`SHELLY_INTERVAL`

Abstand zwischen zwei Abfragen in Sekunden, eine Ganzzahl. Standardwert ist 5, das ergibt eine gute Auflösung. Kleinere Werte als 2 hebt der Collector auf 2 an.

Beim Cloud-Zugriff fragt der Collector bis zu zehn Geräte in einer Anfrage ab. Läuft er in das Rate-Limit der Shelly-Cloud, wartet er und versucht es erneut.

SHELLY_INTERVAL=10

`SHELLY_INVERT_POWER`

Dreht das Vorzeichen der Leistung um, aus negativen Werten werden positive und umgekehrt. Erlaubt sind true und false, jeder andere Wert gilt als false. Standardwert ist false. Nötig ist true, wenn der Shelly eine Erzeugung misst, etwa an einem Balkonkraftwerk.

Betroffen ist nur das Feld power. Die Einzelwerte power_a bis power_d schreibt der Collector unverändert.

SHELLY_INVERT_POWER=true

`INFLUX_HOST`

Hostname des InfluxDB-Servers. Läuft InfluxDB im selben Docker-Netzwerk, ist das der Name des Docker-Services, also influxdb. Es kann aber auch ein externer Server sein, etwa influxdb.example.com.

INFLUX_HOST=influxdb

`INFLUX_SCHEMA`

Schema für die Verbindung zu InfluxDB, http oder https. Standardwert ist http. Bei einer externen InfluxDB mit TLS gehört hier https hin.

INFLUX_SCHEMA=https

`INFLUX_PORT`

Port für die Verbindung zu InfluxDB, eine Ganzzahl. Standardwert ist 8086. Bei einer externen, per TLS abgesicherten InfluxDB ist es oft 443.

INFLUX_PORT=443

`INFLUX_TOKEN`

Token, mit dem sich der Collector bei InfluxDB anmeldet. Er muss dort existieren und das Recht haben, in den angegebenen Bucket zu schreiben. Mehr braucht der Collector nicht: Er schickt Messwerte hin und liest nie etwas zurück.

Passt der Token nicht, weist InfluxDB jeden Schreibzugriff ab. Der Collector läuft dann weiter, protokolliert aber Fehler, und im Dashboard bleiben die Kurven leer.

INFLUX_TOKEN=my-super-secret-write-token

`INFLUX_ORG`

Organisation in InfluxDB, unter der die Messwerte gespeichert werden. Eine Organisation ist der Mandant, dem Benutzer, Buckets und Tokens gehören. InfluxDB legt sie beim ersten Start an. In einer SOLECTRUS-Installation heißt sie solectrus, mehr als eine braucht es nicht.

Der Name muss zu der Organisation passen, die in InfluxDB tatsächlich existiert. Ein anderer Wert benennt sie nicht um, er lässt den Collector nur ins Leere schreiben.

INFLUX_ORG=solectrus

`INFLUX_BUCKET`

Bucket in InfluxDB, in den der Collector die Messwerte schreibt. Ein Bucket ist das, was anderswo die Datenbank wäre: ein benannter Speicher mit eigener Aufbewahrungsdauer. Auch ihn legt InfluxDB beim ersten Start an. Eine SOLECTRUS-Installation kommt mit einem einzigen aus, er heißt solectrus.

Der Name muss zu dem Bucket passen, der in InfluxDB existiert, und zu dem, aus dem das Dashboard liest. Gibt es ihn nicht, lehnt InfluxDB die Schreibzugriffe ab.

INFLUX_BUCKET=solectrus

`INFLUX_MEASUREMENT`

Measurement in InfluxDB, in das der Collector die Messwerte schreibt. Ein Measurement ist das, was anderswo die Tabelle wäre. Standardwert ist Consumer.

Bei mehreren Geräten steht hier ein Name je Gerät, in derselben Reihenfolge wie in SHELLY_HOST bzw. SHELLY_DEVICE_ID. Stimmt die Anzahl nicht überein, bricht der Collector beim Start ab. Mehr dazu unter Zusätzliche Shelly-Verbrauchszähler.

INFLUX_MEASUREMENT=Heatpump

`INFLUX_MODE`

Bestimmt, welche Messwerte in InfluxDB landen. Erlaubt sind default und essential, jeder andere Wert lässt den Collector beim Start abbrechen. Standardwert ist default.

Im default-Modus schreibt der Collector jeden gelesenen Messwert. Im essential-Modus schreibt er nur, solange Leistung fließt. Das spart Speicherplatz bei Geräten, die selten laufen, etwa Waschmaschine oder Geschirrspüler. Die Ränder schreibt er trotzdem mit: beim Abschalten einmalig 0 Watt, beim Wiedereinschalten den zuletzt verworfenen 0-Watt-Wert. Die Kurve beginnt und endet damit auf null, und InfluxDB rechnet die Verbrauchsmenge weiterhin richtig aus.

INFLUX_MODE=essential

`INFLUX_POWER_DATA_TYPE`

Datentyp der Leistungswerte in InfluxDB. Erlaubt sind Float und Integer, jeder andere Wert lässt den Collector beim Start abbrechen. Standardwert ist Float.

Mit Integer speichert der Collector power und power_a bis power_d als Ganzzahlen. Nötig ist das bei der Migration von einem System, das diese Werte bereits als Ganzzahlen abgelegt hat, denn InfluxDB lässt den Datentyp eines Feldes nachträglich nicht mehr ändern.

INFLUX_POWER_DATA_TYPE=Integer

`TZ`

Zeitzone gemäß Liste. Standardwert ist UTC.

Sie betrifft ausschließlich die Zeitstempel im Protokoll des Collectors. Die Messwerte selbst speichert InfluxDB immer in UTC, daran ändert TZ nichts.

TZ=Europe/Berlin