# Was ist der MQTT-Collector?

> Der MQTT-Collector abonniert Topics eines MQTT-Brokers, verarbeitet die empfangenen Werte und schreibt sie in die InfluxDB.

Der **MQTT-Collector** sammelt Messwerte über einen MQTT-Broker ein und schreibt diese in die InfluxDB.

Im Gegensatz zu den spezialisierten Kollektoren (z.B. für SENEC oder Shelly) ist das ein Allzweckwerkzeug, das Messwerte aus verschiedenen Quellen verarbeitet.

Voraussetzung für diesen Collector ist ein funktionsfähiger MQTT-Broker. Dieser kann entweder im lokalen Netzwerk laufen (ioBroker oder Mosquitto sind gängige MQTT-Broker) oder auch ein Cloud-Service sein (z.B. HiveMQ).

Üblicherweise bindet der Collector Geräte an SOLECTRUS an, die SOLECTRUS nicht direkt unterstützt. Ein ioBroker-Adapter fragt das Gerät ab und stellt die Werte per MQTT bereit. Der MQTT-Collector holt sie dort ab.

So lassen sich auch exotische Wallboxen, Wärmepumpen, Batteriespeicher, Wechselrichter oder E-Autos in SOLECTRUS einbinden.

## Empfang von Messwerten

Der MQTT-Collector abonniert Topics bei einem MQTT-Broker, verarbeitet die empfangenen Werte und schreibt sie in eine InfluxDB. Prinzipiell ist das unabhängig von SOLECTRUS, aber üblicherweise läuft der Collector in einer SOLECTRUS-Umgebung. SOLECTRUS bedient sich dann der Werte aus der InfluxDB.

Für jedes abonnierte Topic legt ein eigenes **Mapping** fest, was mit den Werten geschieht und wohin sie gespeichert werden.

Ab Version 0.8.0 gibt es außerdem Mappings ohne Topic. Sie berechnen ihren Wert aus anderen Mappings, etwa den Hausverbrauch ohne Wallbox und Wärmepumpe. Näheres unter [Berechnete Werte](/docs/referenz/mqtt-collector/topics/#berechnete-werte).

```mermaid
flowchart LR
  MQTTCollector[MQTT-Collector]
  MQTTMapping((MQTT-Mapping))
  InfluxDB

  MQTTCollector -->|Topic + Payload| MQTTMapping
  MQTTMapping -->|Measurement + Field + Value| InfluxDB
```

Der Collector muss sich an kein vorgegebenes Namensschema halten. Die Messwerte lassen sich inhaltlich strukturieren, etwa nach ihrer Quelle. Die Bezeichnungen von Measurements und Fields in der InfluxDB sind also frei wählbar.

Auch Messwerte, die SOLECTRUS nicht verarbeitet, lassen sich mit dem MQTT-Collector sammeln, etwa der Kilometerstand eines E-Autos oder die Außentemperatur. Sie liegen dann in der InfluxDB, ohne im Dashboard aufzutauchen.

Wie das Mapping im Detail zu definieren ist, wird in der [Konfiguration](/docs/referenz/mqtt-collector/konfiguration/) beschrieben.

> **Hinweis**
>
>
> Messwerte müssen **kontinuierlich** über den MQTT-Broker eintreffen. Lücken im Datenempfang führen später in SOLECTRUS zu Problemen. Gängiges Negativ-Beispiel ist eine Wallbox, die nur bei Ladevorgängen den Verbrauch sendet. Sie muss auch außerhalb von Ladevorgängen kontinuierlich einen Verbrauch von 0 Watt senden, damit keine Lücken entstehen.
>
> Falls der MQTT-Broker eine Einstellung wie „Publish only on change" anbietet, ist diese zu **deaktivieren**.
>

## Weiterverarbeitung in SOLECTRUS

Das Dashboard von SOLECTRUS holt sich die Werte aus der InfluxDB, ohne zu wissen, woher sie kommen. Es ist also unabhängig von der Quelle der Messwerte. SOLECTRUS definiert dazu Sensoren, über die es die Werte abruft. Die Sensoren sind die Schnittstelle zwischen SOLECTRUS und der InfluxDB. Für den MQTT-Collector sind sie irrelevant.

```mermaid
flowchart LR
  InfluxDB
  SensorMapping((Sensor-Mapping))
  Dashboard

  InfluxDB -->|Measurement + Field + Value| SensorMapping
  SensorMapping -->|Sensor + Value| Dashboard
```

## Verhalten bei Ausfällen

Empfangene Nachrichten wandern zunächst in eine Warteschlange und gehen von dort an die InfluxDB. Verfügbar ab Version 0.8.0. Der Empfang hängt damit nicht mehr am Tempo der Datenbank: Auch eine langsame InfluxDB hält den Collector nicht davon ab, weiter Nachrichten anzunehmen.

Schlägt ein Schreibvorgang fehl, weil die InfluxDB gerade nicht erreichbar ist, bleiben die Messwerte in der Warteschlange. Der Collector versucht es alle 5 Sekunden erneut, und zwar mit dem Zeitpunkt, an dem die Nachricht eintraf. Nach der Störung landen die Messwerte also dort in der Zeitreihe, wo sie hingehören.

Messwerte, die InfluxDB inhaltlich ablehnt, verwirft der Collector sofort, statt sie zu wiederholen. Das passiert etwa, wenn ein Feld einen anderen Datentyp bekommen soll als den, den es in der Datenbank bereits hat. Das Protokoll nennt den Fall.

Die Warteschlange fasst 100.000 Nachrichten, also mehr als einen Tag bei einer Nachricht pro Sekunde. Ist sie voll, macht die älteste Nachricht der neuesten Platz. Sie überlebt keinen Neustart: Wird der Collector während einer Störung neu gestartet, sind die gesammelten Messwerte verloren.

## Logging

Der Collector schreibt ein Protokoll ins Docker-Log, das im Normalfall so aussieht:

```log
MQTT collector for SOLECTRUS, Version v0.8.0, built at 2026-08-19T15:24:07.512Z
https://github.com/solectrus/mqtt-collector
Copyright (c) 2023-2026 Georg Ledermann and contributors, released under the MIT License

Using Ruby 4.0.6 on platform aarch64-linux-musl
Subscribing from MQTT broker at mqtt://192.168.178.31:1883
Pushing to InfluxDB at http://influxdb:8086, bucket solectrus

Subscribing to 2 topics:
- MODBUS/HousePower   => PV:house_power (integer, named 'house_power')
- MODBUS/WallboxPower => PV:wallbox_power (integer, named 'wallbox_power', expiring after 300s)

Calculating 1 virtual mapping(s):
- Household:base_load (integer) = {house_power} - {wallbox_power}

# Message from 2026-08-19 10:05:12 +0200
  topic = MODBUS/HousePower
  message = 1420
  => PV:house_power = 1420
  => Household:base_load = 1020
...
```

Fehler protokolliert der Collector ebenfalls, etwa wenn der MQTT-Broker oder die InfluxDB nicht erreichbar ist.

## Quelltext

Der MQTT-Collector ist in Ruby implementiert, der Quelltext ist auf GitHub verfügbar: \
[github.com/solectrus/mqtt-collector](https://github.com/solectrus/mqtt-collector)