Was ist der MQTT-Collector?

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.

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

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

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

Logging

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

MQTT collector for SOLECTRUS, Version v0.7.6, built at 2026-06-08T05:06:38.669Z
https://github.com/solectrus/mqtt-collector
Copyright (c) 2023-2026 Georg Ledermann and contributors, released under the MIT License

Using Ruby 4.0.5 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 1 topics:
- MODBUS/BatteryLevel => SUNGROW:battery_soc (float)

# Message from 2026-07-14 10:05:12 +0200
  topic = MODBUS/BatteryLevel
  message = 42
  => SUNGROW:battery_soc = 42.0
...

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