# Konfiguration des Shelly-Collectors

> Die Umgebungsvariablen des Shelly-Collectors, für den lokalen Zugriff oder den Weg über die Shelly-Cloud, auch für mehrere Geräte gleichzeitig.

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.

```properties title="Beispiel für zwei lokale Geräte"
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`<span class="badge optional"></span>

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.

```properties title="Beispiel"
SHELLY_HOST=192.168.178.5
```

> **HELIOS**
>
>
> HELIOS fragt die Adresse jedes Geräts ab: unter _Konfiguration → Sensoren_ beim zugehörigen Sensor, unter _Konfiguration → Datenquellen → Shelly-Geräte_ bei allen übrigen. Aus diesen Adressen baut HELIOS die Liste. Steht die Verbindungsart auf **Über Shelly Cloud**, lässt HELIOS die Variable weg.
>

### `SHELLY_PASSWORD`<span class="badge optional"></span>

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.

```properties title="Beispiel"
SHELLY_PASSWORD=my-shelly-password
```

> **HELIOS**
>
>
> HELIOS fragt das Passwort je Gerät ab, zusammen mit dessen Adresse. Bleibt das Feld überall leer, lässt HELIOS die Variable weg.
>

### `SHELLY_CLOUD_SERVER`<span class="badge optional"></span>

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](https://control.shelly.cloud) unter _Settings / User Settings / Authorization cloud key_. Das Gerät muss dort registriert sein und seine Daten in die Cloud senden.

```properties title="Beispiel"
SHELLY_CLOUD_SERVER=https://shelly-42-eu.shelly.cloud
```

> **HELIOS**
>
>
> HELIOS fragt die Server-URL unter _Konfiguration → Datenquellen → Shelly-Collector_ ab, sobald die Verbindungsart auf **Über Shelly Cloud** steht. Ein Knopf daneben prüft, ob die Cloud antwortet.
>

### `SHELLY_AUTH_KEY`<span class="badge optional"></span>

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](https://control.shelly.cloud) unter _Settings / User Settings / Authorization cloud key / Get Key_.

```properties title="Beispiel"
SHELLY_AUTH_KEY=ABCDEFGHIJKLMNOPQRSTUVWXYZ1234567890
```

> **HELIOS**
>
>
> HELIOS fragt den Schlüssel unter _Konfiguration → Datenquellen → Shelly-Collector_ ab, sobald die Verbindungsart auf **Über Shelly Cloud** steht.
>

### `SHELLY_DEVICE_ID`<span class="badge optional"></span>

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](https://control.shelly.cloud) beim jeweiligen Gerät unter _Settings / Device information_.

```properties title="Beispiel"
SHELLY_DEVICE_ID=12345abcdef0
```

> **HELIOS**
>
>
> HELIOS fragt die Cloud-ID jedes Geräts ab: unter _Konfiguration → Sensoren_ beim zugehörigen Sensor, unter _Konfiguration → Datenquellen → Shelly-Geräte_ bei allen übrigen. Steht die Verbindungsart auf **Lokal**, lässt HELIOS die Variable weg.
>

### `SHELLY_INTERVAL`<span class="badge optional"></span>

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.

```properties title="Beispiel"
SHELLY_INTERVAL=10
```

> **HELIOS**
>
>
> HELIOS fragt das Intervall unter _Konfiguration → Datenquellen → Shelly-Collector_ ab, vorbelegt mit `5`.
>

### `SHELLY_INVERT_POWER`<span class="badge optional"></span>

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.

```properties title="Beispiel"
SHELLY_INVERT_POWER=true
```

> **HELIOS**
>
>
> HELIOS bietet dafür je Gerät einen Schalter **Leistung invertieren**, standardmäßig aus. Invertiert kein Gerät, lässt HELIOS die Variable weg.
>

### `INFLUX_HOST`<span class="badge required"></span>

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`.

```properties title="Beispiel"
INFLUX_HOST=influxdb
```

> **HELIOS**
>
>
> HELIOS setzt den Hostnamen automatisch: normalerweise `influxdb`, bei aktivem [Ingest-Dienst](/docs/referenz/ingest/) stattdessen `ingest`. Nur bei einer externen InfluxDB fragt HELIOS ihn unter _Konfiguration → Grundeinstellungen → InfluxDB_ ab.
>

### `INFLUX_SCHEMA`<span class="badge optional"></span>

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

```properties title="Beispiel"
INFLUX_SCHEMA=https
```

> **HELIOS**
>
>
> HELIOS setzt `http`, denn innerhalb des Docker-Netzwerks wird nicht verschlüsselt. Nur bei einer externen InfluxDB fragt HELIOS das Protokoll ab.
>

### `INFLUX_PORT`<span class="badge optional"></span>

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

```properties title="Beispiel"
INFLUX_PORT=443
```

> **HELIOS**
>
>
> HELIOS setzt den Port automatisch: `8086` für InfluxDB, `4567` beim Umweg über den [Ingest-Dienst](/docs/referenz/ingest/). Nur bei einer externen InfluxDB fragt HELIOS ihn ab.
>

### `INFLUX_TOKEN`<span class="badge required"></span>

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.

```properties title="Beispiel"
INFLUX_TOKEN=my-super-secret-write-token
```

> **HELIOS**
>
>
> HELIOS gibt dem Collector den Schreib-Token, siehe [`INFLUX_TOKEN_WRITE`](/docs/referenz/helios/konfiguration/#influx_token_write). Lese- oder Admin-Zugriff bekommt er nicht.
>

### `INFLUX_ORG`<span class="badge required"></span>

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](/docs/referenz/influxdb/konfiguration/) 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.

```properties title="Beispiel"
INFLUX_ORG=solectrus
```

> **HELIOS**
>
>
> HELIOS gibt `solectrus` vor, einzustellen gibt es nichts. Nur bei einer externen InfluxDB fragt HELIOS den Namen der vorhandenen Organisation ab.
>

### `INFLUX_BUCKET`<span class="badge required"></span>

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](/docs/referenz/influxdb/konfiguration/) 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.

```properties title="Beispiel"
INFLUX_BUCKET=solectrus
```

> **HELIOS**
>
>
> HELIOS gibt `solectrus` vor, einzustellen gibt es nichts. Nur bei einer externen InfluxDB fragt HELIOS den Namen des vorhandenen Buckets ab.
>

### `INFLUX_MEASUREMENT`<span class="badge optional"></span>

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](/docs/anleitungen/mehrere-shelly/).

```properties title="Beispiel"
INFLUX_MEASUREMENT=Heatpump
```

> **HELIOS**
>
>
> HELIOS fragt das Measurement je Gerät ab und setzt die Namen zu einer Liste zusammen. Beim Sensor eines benutzerdefinierten Verbrauchers trägt HELIOS es selbst ein.
>

### `INFLUX_MODE`<span class="badge optional"></span>

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.

```properties title="Beispiel"
INFLUX_MODE=essential
```

> **HELIOS**
>
>
> HELIOS bietet dafür keine Einstellung. Nur beim Übernehmen einer vorhandenen Installation liest HELIOS einen bereits gesetzten Wert ein und behält ihn bei.
>

### `INFLUX_POWER_DATA_TYPE`<span class="badge optional"></span>

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.

```properties title="Beispiel"
INFLUX_POWER_DATA_TYPE=Integer
```

> **HELIOS**
>
>
> HELIOS bietet dafür keine Einstellung. Nur beim Übernehmen einer vorhandenen Installation liest HELIOS einen bereits gesetzten Wert ein und behält ihn bei.
>

### `TZ`<span class="badge optional"></span>

Zeitzone gemäß [Liste](https://en.wikipedia.org/wiki/List_of_tz_database_time_zones). 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.

```properties title="Beispiel"
TZ=Europe/Berlin
```

> **HELIOS**
>
>
> HELIOS fragt die Zeitzone unter _Konfiguration → Grundeinstellungen → PV-Anlage_ ab, vorbelegt mit `Europe/Berlin`.
>