# Konfiguration des SENEC-Collectors

> Umgebungsvariablen des SENEC-Collectors – Betriebsmodus, Zugang zum Stromspeicher oder zur SENEC-Cloud und InfluxDB-Zugang.

Der SENEC-Collector wird über Umgebungsvariablen konfiguriert.

Welche Variablen nötig sind, hängt am Betriebsmodus: `SENEC_ADAPTER=local` fragt den Stromspeicher im Heimnetz ab, `SENEC_ADAPTER=cloud` holt die Messwerte bei `mein-senec.de`. Jeder Modus hat seine eigenen Pflichtvariablen, die des anderen Modus ignoriert der Collector.

## Umgebungsvariablen

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

Betriebsmodus des Collectors. Erlaubt sind `local` für den direkten Zugriff auf den Stromspeicher und `cloud` für den Abruf über die SENEC-Cloud. Standardwert ist `local`.

Jeder andere Wert bricht den Start ab. Der Home 4 hat keine lokale Schnittstelle, für ihn kommt nur `cloud` in Frage.

```properties title="Beispiel"
SENEC_ADAPTER=cloud
```

> **HELIOS**
>
>
> HELIOS fragt die Zugriffsart unter _Konfiguration → Datenquellen → SENEC-Collector_ ab, vorbelegt mit dem lokalen Zugriff. Bei einem Home 4 entfällt die Frage, HELIOS setzt dann `cloud`.
>

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

Hostname des SENEC-Stromspeichers, üblicherweise eine IP-Adresse. Pflicht, solange `SENEC_ADAPTER` auf `local` steht. Im Cloud-Modus wird die Variable ignoriert.

Hier gehört nur der Host hin, **kein** `http://` oder `https://`. Das Protokoll steht getrennt in `SENEC_SCHEMA`. Fehlt der Host im lokalen Modus, bricht der Collector beim Start mit einer Fehlermeldung ab.

```properties title="Beispiel"
SENEC_HOST=192.168.178.29
```

> **HELIOS**
>
>
> HELIOS fragt die IP-Adresse unter _Konfiguration → Datenquellen → SENEC-Collector_ ab und prüft auf Knopfdruck, ob das Gerät antwortet. Die Frage erscheint nur beim lokalen Zugriff.
>

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

Protokoll für die Verbindung zum SENEC-Stromspeicher, `http` oder `https`. Standardwert ist `https`. Im Cloud-Modus wird die Variable ignoriert.

Ältere Geräte sprechen mitunter nur `http`. Passt das Protokoll nicht, kommt keine Verbindung zustande.

```properties title="Beispiel"
SENEC_SCHEMA=http
```

> **HELIOS**
>
>
> HELIOS fragt das Protokoll unter _Konfiguration → Datenquellen → SENEC-Collector_ ab, vorbelegt mit `https`. Die Frage erscheint nur beim lokalen Zugriff.
>

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

Sprache der Status-Texte, die der Collector vom Gerät liest. Erlaubt sind `de`, `en` und `it`, andere Sprachen liefert das SENEC-Gerät nicht aus. Standardwert ist `de`. Im Cloud-Modus wird die Variable ignoriert.

Der Collector liest die Namen der Betriebszustände aus der Weboberfläche des Geräts und schreibt sie als `current_state` in die InfluxDB. Die Sprache entscheidet also, in welcher Sprache dieses Feld gefüllt wird.

```properties title="Beispiel"
SENEC_LANGUAGE=en
```

> **HELIOS**
>
>
> HELIOS fragt die Sprache unter _Konfiguration → Datenquellen → SENEC-Collector_ ab, vorbelegt mit Deutsch. Die Frage erscheint nur beim lokalen Zugriff.
>

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

E-Mail-Adresse für die Anmeldung bei `mein-senec.de`. Pflicht, sobald `SENEC_ADAPTER=cloud` gesetzt ist. Im lokalen Modus wird die Variable ignoriert.

Der Collector prüft beim Start, ob der Wert ein `@` enthält, und bricht sonst ab.

```properties title="Beispiel"
SENEC_USERNAME=mail@example.com
```

> **HELIOS**
>
>
> HELIOS fragt die E-Mail-Adresse unter _Konfiguration → Datenquellen → SENEC-Collector_ ab. Die Frage erscheint nur beim Cloud-Zugriff.
>

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

Passwort für die Anmeldung bei `mein-senec.de`. Pflicht, sobald `SENEC_ADAPTER=cloud` gesetzt ist. Im lokalen Modus wird die Variable ignoriert.

```properties title="Beispiel"
SENEC_PASSWORD=my-secret-password
```

> **HELIOS**
>
>
> HELIOS fragt das Passwort unter _Konfiguration → Datenquellen → SENEC-Collector_ ab. Die Frage erscheint nur beim Cloud-Zugriff.
>

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

URI für die Multi-Faktor-Authentifizierung (MFA) bei `mein-senec.de`. Nötig ist sie nur im Cloud-Modus und auch dort nur, wenn das Konto MFA verlangt. Im lokalen Modus wird die Variable ignoriert.

Anzugeben ist der vollständige String in Anführungszeichen. Er muss mit `otpauth://` beginnen und einen `secret`-Parameter enthalten, sonst bricht der Collector beim Start ab. Aus dem QR-Code von SENEC oder dem Eintrag im Google Authenticator lässt sich die URI mit dem [QR Code Secret Decoder](https://marq24.github.io/qr-code-decoder/) ermitteln.

```properties title="Beispiel"
SENEC_TOTP_URI="otpauth://totp/SENEC:mail%40example.com?secret=XXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX&digits=6&algorithm=SHA1&issuer=SENEC&period=30"
```

> **HELIOS**
>
>
> HELIOS fragt die TOTP-URI unter _Konfiguration → Datenquellen → SENEC-Collector_ ab, als optionales Feld beim Cloud-Zugriff. Ohne Eintrag lässt HELIOS die Variable weg.
>

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

ID des SENEC-Systems, dessen Messwerte der Collector aus der Cloud holt. Nötig ist sie nur, wenn am Konto mehr als ein System hängt. Im lokalen Modus wird die Variable ignoriert.

Ohne die Variable listet der Collector die verfügbaren IDs im Protokoll auf und verwendet die **erste**. Für eine andere als die erste ID sind drei Schritte nötig:

1. Die Variable leer lassen und den Collector starten.
2. Die gewünschte ID aus dem Protokoll ablesen.
3. Die ID hier eintragen und den Collector neu starten.

```properties title="Beispiel"
SENEC_SYSTEM_ID=12345
```

> **HELIOS**
>
>
> HELIOS fragt die System-ID unter _Konfiguration → Datenquellen → SENEC-Collector_ ab, als optionales Feld beim Cloud-Zugriff. Ohne Eintrag lässt HELIOS die Variable weg.
>

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

Intervall in Sekunden, in dem der Collector die Messwerte abfragt, eine Ganzzahl. Standardwert ist `5` im lokalen Modus und `60` im Cloud-Modus.

Diese Werte sind zugleich die Untergrenze: Ein kleinerer Wert wird stillschweigend angehoben. Häufigeres Abfragen brächte ohnehin nichts, denn die Cloud liefert neue Werte nur alle 5 Minuten, beim Home 4 jede Minute.

```properties title="Beispiel"
SENEC_INTERVAL=10
```

> **HELIOS**
>
>
> HELIOS fragt das Intervall unter _Konfiguration → Datenquellen → SENEC-Collector_ ab. Vorbelegt ist es passend zum Zugriff: 5 Sekunden lokal, 60 Sekunden beim Home 4 in der Cloud, sonst 300 Sekunden.
>

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

Messwerte, die der Collector **nicht** an InfluxDB sendet. Nötig, wenn ein Messwert aus einer anderen Quelle stammt, etwa die Wallbox-Leistung von einem Shelly. Erlaubt ist eine komma-getrennte Liste von [Feldnamen](/docs/referenz/senec-collector/#erfasste-messwerte) ohne Leerzeichen. Ohne die Variable sendet der Collector alle Messwerte.

Ein unbekannter Feldname bricht den Start ab. Der Collector nennt ihn dann im Protokoll.

```properties title="Beispiel"
SENEC_IGNORE=wallbox_charge_power,grid_power_minus
```

> **HELIOS**
>
>
> HELIOS leitet die Liste selbst ab: Es trägt jedes Feld ein, das ein anderer Collector in dasselbe Measurement schreibt. Einzustellen gibt es nichts.
>

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

Umfang der Abfrage in der Cloud. Erlaubt sind `minimal` und `full`, jeder andere Wert bricht den Start ab. Standardwert ist `minimal`. Im lokalen Modus wird die Variable ignoriert.

Mit `minimal` fragt der Collector nur einen Endpunkt mit den wichtigsten Feldern ab. Mit `full` holt er zusätzlich `case_temp`, `application_version`, `current_state` und `current_state_ok`. Die letzten beiden liefert der Home 4 allerdings nicht. Das kostet eine zweite Anfrage pro Durchlauf und erzeugt entsprechend mehr Last auf den SENEC-Servern.

```properties title="Beispiel"
SENEC_REQUEST_MODE=full
```

> **HELIOS**
>
>
> HELIOS fragt den Abfragemodus unter _Konfiguration → Datenquellen → SENEC-Collector_ ab, mit den Optionen _Minimal (empfohlen)_ und _Voll_. Die Frage erscheint nur beim Cloud-Zugriff.
>

### `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, unter dem die Messwerte des Collectors landen. Standardwert ist `SENEC`.

Der Name muss zu dem passen, den das Dashboard für die SENEC-Sensoren erwartet. Eine nachträgliche Änderung ist heikel: Bereits geschriebene Messwerte bleiben dauerhaft an den alten Namen gebunden.

```properties title="Beispiel"
INFLUX_MEASUREMENT=power_storage
```

> **HELIOS**
>
>
> HELIOS fragt den Namen unter _Konfiguration → Datenquellen → SENEC-Collector_ ab, vorbelegt mit `SENEC`.
>

### `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/Rome
```

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