Zum Hauptinhalt springen
Inhalt

EnergyOS vereint zwei Aufgaben: die Fernverwaltung Ihrer Energiesysteme und die Verwaltung der Geräte, die alles verbinden. Diese Anleitung erklärt, was jeder Teil leistet, wie die Teile miteinander sprechen und wie Sie sie einrichten.

Erste Schritte

  1. Legen Sie ein Konto an und melden Sie sich an. Der Gratis-Tarif braucht keine Kreditkarte.
  2. Fügen Sie Ihre Energiesysteme hinzu unter Energiemanagement aus der Ferne → Energiesysteme (Wärmepumpe, PV, Batterie, Ladestation) oder erstellen Sie zuerst Demo-Systeme zum Ausprobieren.
  3. Verbinden Sie ein Gerät unter Geräteverwaltung → Gerät hinzufügen. Es führt den EnergyOS-Agenten neben Ihren Systemen aus und meldet deren Status (siehe den Agenten).
  4. Verknüpfen Sie jedes System mit seinem Gerät. Die Übersicht zeigt dann, ob es online ist.
Die EnergyOS-Übersicht mit den zwei Bereichen: Energiemanagement aus der Ferne und Geräteverwaltung aus der Ferne
Die Übersicht zeigt die zwei Bereiche in dieser Reihenfolge: Energiemanagement, Geräteverwaltung.

Wie EnergyOS zusammenspielt

EnergyOS spricht nie direkt mit Ihren Anlagen. Ein kleines Programm bei Ihnen vor Ort, das Gateway oder der Agent, spricht mit den Anlagen und hält eine ausgehende, verschlüsselte Verbindung zum EnergyOS-Message-Broker. Alles Weitere läuft über diese Verbindung.

Wie EnergyOS sich mit Ihren Anlagen verbindet Die Anlagen sprechen mit einem Gateway oder dem EnergyOS-Agenten bei Ihnen vor Ort. Das Gateway verbindet sich ausgehend per MQTT mit TLS zum QLines-Broker, der die Nachrichten an EnergyOS weitergibt. Sie nutzen EnergyOS im Browser über HTTPS. Bei Ihnen vor Ort QLines Anlagen WärmepumpePV-WechselrichterBatterieLadestationEnergiezähler Gateway oder Agent Home Assistantevcc · Node-REDEnergyOS agent(rc-agent) MQTT-Broker TLS, Port 8883ein Zugang pro Gerätnur eigene Topics EnergyOS Dashboards, RegelnBerichte, AlarmeDatenspeicher Sie Browseroder Smartphone MQTT über TLSnur ausgehend HTTPS Kein offener Port, kein VPN, keine feste IP Das Gateway wählt sich nur zum Broker nach außen ein. Jedes Gerät hat seinen eigenen Zugang und darf nur seine eigenen Topics nutzen: rc/account/device/…
Alles bei Ihnen vor Ort verbindet sich nach außen. Nichts muss in Ihr Netzwerk hineinreichen.
TeilWo es läuftWas sie tut
AnlagenBei Ihnen vor OrtWärmepumpe, PV-Wechselrichter, Batterie, Ladestation, Zähler, Sensoren. Spricht ein eigenes Protokoll (Modbus, OCPP, KNX, Matter, eine Hersteller-API).
GatewayBei Ihnen vor Ort: ein Raspberry Pi, Mini-PC, NAS oder ServerÜbersetzt zwischen dem Protokoll der Anlage und EnergyOS-Nachrichten. Home Assistant, evcc, Node-RED, zigbee2mqtt oder ein kleines Skript können alle das Gateway sein.
EnergyOS-AgentAuf einem Linux-Gerät bei Ihnen vor OrtMeldet den Zustand des Geräts (CPU, Speicher, Festplatte, Temperatur), führt Netzwerktests aus und führt Befehle aus, die Sie von der Seite senden.
MQTT-BrokerQLinesNimmt Nachrichten entgegen und verteilt sie. Jedes Gerät hat seinen eigenen Zugang und darf nur seine eigenen Topics nutzen.
EnergyOSQLinesZeigt die Daten, sendet Befehle, führt Regeln und Alarme aus und zeigt die Wetterprognose und die Strompreise.

Was brauche ich? Um Energiesysteme zu lesen und zu steuern, brauchen Sie ein Gateway, das MQTT spricht (siehe Anlagen verbinden). Um einen Computer zu beobachten und zu verwalten (Status, Diagramme, Netzqualität, Fernbefehle), installieren Sie den Agenten (siehe Der Agent). Ein Gerät kann beides: Der Agent und Home Assistant können nebeneinander auf demselben Raspberry Pi laufen.

Energiemanagement aus der Ferne

Ein Energiesystem ist ein Anlagenteil: Wärmepumpe, PV-Anlage, Batterie, Ladestation, Heizkessel, Energiezähler. Zu jedem geben Sie einen Namen, den Typ, die Nennleistung, die Anbindung und das Gerät (das Gateway) an, mit dem es verknüpft ist.

  • Übersicht: eine Kachel pro System mit seinem Hauptwert und einem Live-/Keine-Daten-Status. Melden PV, ein Netzzähler oder eine Batterie Werte, wird der Energiefluss gezeigt: PV, Netz (Bezug oder Einspeisung), Batterie, Hausverbrauch und der Anteil, den Sie selbst decken.
  • Systemseite: alle aktuellen Werte, ein Verlaufsdiagramm (6 Stunden, 24 Stunden, 7 Tage, jeder Kanal), Steuerungen und die Liste der letzten Befehle.
  • Demo-Systeme: Demo-Systeme erstellen legt fünf Systeme mit zwei Tagen simulierter Messwerte und simulierten Befehlen an, zum Ausprobieren oder für ein Video.
Energiefluss: PV 5,2 kW, Netzeinspeisung 4,7 kW, Batterie 0 W, Haus 505 W, 100 Prozent Eigenversorgung
Der Energiefluss oben auf der Seite.
Formular „Energiesystem hinzufügen“ und eine Kachel pro System: Wärmepumpe, Dach-PV, Heimspeicher, Wallbox und Netzzähler
Fügen Sie ein System hinzu oder erstellen Sie Demo-Systeme. Jede Kachel zeigt den Hauptwert und ob das System live ist.
Eine Wärmepumpen-Systemseite mit den aktuellen Werten und einem 24-Stunden-Leistungsverlauf
Eine Systemseite: aktuelle Werte und ein Verlaufsdiagramm für jeden Kanal.

Steuerungen

Die Steuerungen hängen vom Typ ab. Wärmepumpe: Betriebsart (gesperrt, normal, Einschaltempfehlung, Zwangsbetrieb, wie bei SG Ready), Warmwasser-Solltemperatur, Leistungsgrenze. Ladestation: Laden erlaubt, Stromgrenze, Leistungsgrenze. Batterie: Modus, maximale Ladeleistung. PV: Einspeisegrenze. Heizkessel: Vorlauftemperatur-Sollwert.

Was passiert, wenn Sie eine Steuerung ändern EnergyOS prüft den Wert und sendet den Befehl an das Gateway. Das Gateway antwortet mit einer Bestätigung, einer Ablehnung oder gar nicht. Das Ergebnis wird als bestätigt, fehlgeschlagen oder keine Bestätigung angezeigt, und die Einstellung wird erst nach einer Bestätigung gemerkt. Sie stellen es einModus, Grenze, Zielwert EnergyOS prüftWert und Bereich Gesendet: …/setan das Gateway Gateway bestätigt: …/ack okWird als bestätigt angezeigt. Die Einstellung wird gemerkt. Gateway lehnt ab: ack mit einem FehlerWird als fehlgeschlagen angezeigt, mit dem Grund, den das Gateway nennt. Keine Antwort in der ZeitWird als „keine Bestätigung“ angezeigt. Es wird nicht angenommen, dass es funktioniert.
Eine Einstellung wird erst gemerkt, wenn das Gateway sie bestätigt. Ohne Antwort wird „keine Bestätigung“ angezeigt, nie „erledigt“.
Steuerungen einer Demo-Wärmepumpe: Betriebsart, Warmwasser-Solltemperatur und Leistungsgrenze, jeweils mit einer Senden-Schaltfläche
Steuerungen einer Wärmepumpe. Befehle an Demo-Systeme werden simuliert.

Anlagen verbinden (MQTT)

EnergyOS spricht MQTT. Ein Gateway steht neben Ihrer Anlage, spricht deren eigenes Protokoll und tauscht flache JSON-Nachrichten mit EnergyOS aus. Jedes Programm, das MQTT spricht, kann das Gateway sein: Home Assistant, Node-RED, evcc, zigbee2mqtt, ein Matter-Server oder ein kleines Skript. Nutzen Sie den MQTT-Zugang des Geräts, mit dem das System verknüpft ist: Die Geräte-ID ist der Benutzername und der Geräte-Token das Passwort, über TLS auf Port 8883 (Server mqtt.qlines.net).

publish   rc/{account}/{device}/energy/{system_id}        {"power_w": 4200, "soc_pct": 63}
listen    rc/{account}/{device}/energy/{system_id}/set    {"cmd_id": "...", "control": "mode", "value": "eco"}
confirm   rc/{account}/{device}/energy/{system_id}/ack    {"cmd_id": "...", "ok": true, "message": ""}

Die Systemseite zeigt diese Topics mit Ihren echten IDs. Messwerte sind nur Zahlen (bis zu 40 Kanäle pro Nachricht), werden höchstens alle 10 Sekunden gespeichert und 90 Tage aufbewahrt; sie zählen zum täglichen Nachrichtenlimit des Geräts.

KanalBedeutung
power_wLeistung in W (Batterie: positiv beim Laden)
grid_wNetzzähler: positiv = Bezug, negativ = Einspeisung
soc_pctLadezustand der Batterie in %
temp_flow_c, temp_return_c, temp_outdoor_c, temp_dhw_c, copWärmepumpenwerte
energy_kwh, energy_import_kwh, energy_export_kwhZähler in kWh
grid_limit_active1, solange der Netzbetreiber steuerbare Geräte begrenzt (§14a EnWG)

Protokolle

Sie wählen, wie ein System angebunden ist, damit die Einrichtung dokumentiert ist. EnergyOS selbst spricht MQTT; das Gateway übersetzt:

Die Anlage sprichtGateway
Modbus TCP / SunSpec (Wechselrichter, Batterien, Zähler)Home Assistant, evcc, Node-RED oder eine MQTT-Option des Herstellers
OCPP (Ladestationen)evcc oder die eigene MQTT-Schnittstelle der Ladestation
EEBUS, SG Ready (Wärmepumpen)Home Assistant oder das Gateway der Wärmepumpe; SG Ready sind zwei Relaiskontakte
KNX, Matter / Thread, Zigbee / Z-Wave (Sensoren, Schalter, Steckdosen)Home Assistant (KNX, Matter) oder zigbee2mqtt, beide veröffentlichen auf MQTT
Hersteller-Cloud oder HTTP-APIEin kleines Skript oder ein Node-RED-Flow

EnergyOS spricht nicht selbst mit den Anlagen. Bestätigt ein Gateway einen Befehl nicht, zeigt die Seite keine Bestätigung, und die Einstellung gilt nicht als übernommen.

Wetterprognose

Geben Sie auf der Energieseite einmal den Standort Ihrer Systeme ein (Ort, Postleitzahl oder Adresse). EnergyOS lädt dann die Wettervorhersage für die nächsten 48 Stunden: die MOSMIX-Prognose des Deutschen Wetterdienstes (DWD) für den nächstgelegenen Prognosepunkt, über den Dienst Bright Sky: Außentemperatur, Sonneneinstrahlung und Bewölkung, stündlich aktualisiert. Daraus zeigt EnergyOS:

  • Kälteste und wärmste Stunde der nächsten 24 Stunden.
  • Erwarteter PV-Ertrag: Sonneneinstrahlung × installierte kWp Ihrer PV-Systeme × 80 % Performance Ratio. Eine einfache Schätzung ohne Dachneigung und Ausrichtung, gut genug, um einen sonnigen Tag von einem grauen zu unterscheiden.
  • Heizbedarf: Gradstunden unter 15 °C Außentemperatur. Mehr Gradstunden bedeuten mehr benötigte Wärme.
  • PV heute, erwartet gegenüber gemessen: die Prognoseenergie seit Mitternacht neben der Energie, die Ihre PV-Systeme gemeldet haben. Deutlich unter der Prognose (unter 70 %) deutet auf Verschattung, Verschmutzung oder einen Fehler hin.
Wetterprognose-Karte für München mit kältester und wärmster Stunde, erwartetem PV-Ertrag, Heizbedarf und einem 48-Stunden-Diagramm von Temperatur und Sonneneinstrahlung
Die Prognosekarte mit dem 48-Stunden-Diagramm.

Die Prognose steuert auch zwei Regeln unter Automatisierung (siehe unten). Demo-Systeme verwenden München als Standort; ihre PV-Messwerte sind simuliert, daher wird die Zeile „erwartet gegenüber gemessen“ nur für echte PV-Systeme angezeigt.

Automatisierung und Preise

Unter Automatisierung sehen Sie den deutschen Day-Ahead-Strompreis für die nächsten Stunden: jetzt, niedrigster, höchster und das günstigste 3-Stunden-Fenster. Der Preis ist der Marktpreis ohne Steuern, Netzentgelte und Lieferantenmarge: gut zum Vergleichen von Stunden, keine Rechnung. Er kommt von aWATTar, mit Energy-Charts als Ausweichquelle.

Balkendiagramm des Day-Ahead-Strompreises mit aktuellem, niedrigstem und höchstem Preis und dem günstigsten Drei-Stunden-Fenster
Der Day-Ahead-Preis für die nächsten Stunden.

Regeln schalten eine Steuerung, wenn eine Bedingung beginnt, und stellen sie zurück, wenn sie endet. Eine Regel ändert höchstens alle 5 Minuten. Verfügbare Regeln:

  • PV-Überschuss für die Wärmepumpe nutzen: Exportiert der Netzzähler mehr als die Schwelle, wird die Wärmepumpe auf empfohlen ein gestellt; danach zurück auf normal.
  • Das Auto mit PV-Überschuss laden: Laden erlauben, solange der Überschuss anhält.
  • Warmwasser heizen, wenn Strom günstig ist: Zwangsbetrieb, solange der Marktpreis unter der Schwelle liegt (ct/kWh).
  • Vor einer Kältewelle vorheizen (Wetterprognose): Liegt die niedrigste für die nächsten 12 Stunden vorhergesagte Außentemperatur an oder unter der Schwelle (°C), wird die Wärmepumpe auf empfohlen ein gestellt, damit das Gebäude Wärme speichert, bevor die Kälte kommt; danach zurück auf normal.
  • Warmwasser der Sonne überlassen, wenn ein sonniger Tag vorhergesagt ist: Erreicht die PV-Ertragsprognose für die nächsten 24 Stunden die Schwelle (kWh), wird die Warmwasser-Solltemperatur auf 45 °C gesenkt, damit die Sonne es später erwärmen kann; sonst 55 °C. Braucht mindestens ein PV-System mit seiner kWp-Angabe.
  • Netzbetreiber-Begrenzung (§14a EnWG): Meldet das Gateway grid_limit_active = 1, werden Wärmepumpen und Ladestationen auf 4,2 kW begrenzt; die Begrenzung wird aufgehoben, wenn das Signal endet.
Die Karte „Regeln“ mit Regeltyp-Auswahl, Schwellenfeld und Schaltfläche „Hinzufügen“
Eine Regel hinzufügen: Typ und Schwelle wählen.

Regeln brauchen Daten: Eine Regel, die die benötigten Werte nicht sieht, tut nichts (zum Beispiel eine Prognoseregel ohne Standort oder Prognose). Sie können jede Regel pausieren oder löschen.

Förderrechner für Wärmepumpen

Die Bundesförderung für eine Wärmepumpe in Deutschland (BEG EM, ausgezahlt von KfW und BAFA) ist nicht Teil des EnergyOS-Dashboards. Es ist ein kostenloser Rechner auf qlines.net, der kein Konto braucht und nichts speichert: Wärmepumpen-Förderrechner für Deutschland.

Nur für Deutschland. Der Rechner nutzt das deutsche Bundesprogramm und gilt für Gebäude in Deutschland. Förderungen in anderen Ländern folgen anderen Regeln.

Der Förderrechner für Wärmepumpen in Deutschland: ein Hinweis, dass er nur für Deutschland gilt, und ein Ergebnis mit 80 Prozent Satz, 28.000 Euro förderfähigen Kosten und 22.400 Euro höchster Förderung
Der Rechner zeigt den Satz, die Obergrenze, die höchste Förderung und Ihren Eigenanteil.

Sie geben die Gebäudeart, das Antragsdatum, die Heizung, die Sie ersetzen, und ihr Alter, ob Sie selbst im Gebäude wohnen, Ihr Haushaltseinkommen und die geplanten Kosten ein (oder die Wärmepumpengröße für eine Kostenschätzung). Sie erhalten den Fördersatz, wie er sich aus Grundförderung und Boni zusammensetzt, die höchste Förderung, Ihren Eigenanteil und, wenn Sie Ihren Brennstoffverbrauch angeben, die jährliche Ersparnis und die Amortisation.

Das Ergebnis ist eine Schätzung mit den veröffentlichten Regeln, kein Förderbescheid. Über den Antrag entscheiden KfW (private Eigentümer) oder BAFA.

Geräteverwaltung aus der Ferne

Fügen Sie ein Gerät hinzu, um Status, Verbindungsqualität, Netzwerktests und Fernbefehle zu erhalten. Die Flottenübersicht zeigt alle Geräte auf einen Blick: wie viele es im Vergleich zu Ihrem Tarif sind, wie viele online und offline sind und wie viele Alarme offen sind. Jede Karte zeigt den Status, wann das Gerät zuletzt gesehen wurde, CPU-, Speicher- und Festplattenauslastung und den letzten Ping. Mit Filterfeld und Sortiermenü finden Sie ein Gerät.

Die Flottenübersicht mit Zählern für Geräte insgesamt, online, offline und Alarme sowie einer Karte pro Gerät mit CPU, RAM und Festplatte
Die Flottenübersicht.

Status und zuletzt gesehen

Gerätestatus Ein Gerät ist „Nie verbunden“, bis sich sein Agent registriert. Es ist „Online“, solange Heartbeats ankommen. Nach 2 Minuten ohne Heartbeat wird es „Offline“ und ein Alarm wird geöffnet. Der nächste Heartbeat macht es wieder „Online“. Nie verbunden Online Offline der Agent registriert sich kein Heartbeat seit 2 Minuten nächster Heartbeat

Ein Alarm wird geöffnet: Er wird an der Glocke und auf der Flottenübersicht gezählt.

Ein Gerät ist nach zwei Minuten ohne Heartbeat offline. Die Prüfung läuft alle zwei Minuten, daher kann die Anzeige etwas länger dauern.

Zuletzt gesehen sagt, wie lange das Gerät zuletzt gemeldet hat, zum Beispiel vor 5 Min. oder vor 3 Tagen, und aktualisiert sich selbst, solange die Seite offen ist. Fahren Sie mit der Maus darüber, um die genaue Zeit in Ihrer Zeitzone zu sehen. Unter einer Minute steht gerade eben; nach einem Tag wird der Text bernsteinfarben, damit ein vergessenes Gerät auffällt.

Die Geräteseite

  • Übersicht: aktuelle CPU, Speicher, Festplatte und Temperatur sowie die Systemdetails: Geräte-ID, Hostname, Betriebssystem, Architektur, Agent-Version, Registrierungsdatum, zuletzt gesehen und Betriebszeit.
  • Telemetrie: Diagramme für CPU, Speicher, Festplatte und Temperatur für 1 Stunde, 6 Stunden, 24 Stunden oder 7 Tage.
  • Befehle: Führen Sie einen Befehl auf dem Gerät aus und sehen Sie das Ergebnis (siehe Fernbefehle).
  • Netzwerktests: Ping, Download- und Upload-Geschwindigkeit, DNS-Abfragezeit und HTTP-Prüfungen, nach Zeitplan oder auf Abruf mit Test jetzt ausführen.
  • Einstellungen: Name und Notizen, das Heartbeat-Intervall (15, 30 oder 60 Sekunden), das Telemetrie-Intervall (30 Sekunden bis 15 Minuten), der Zeitplan der Netzwerktests und die aktivierten Funktionen. Speichern und Refresh Config senden die neuen Einstellungen an den Agenten.
Geräteseite, Reiter Übersicht: aktuelle CPU, RAM, Festplatte und Temperatur sowie die Systemdetails des Geräts
Der Reiter Übersicht eines Geräts.
Geräteseite, Reiter Telemetrie: vier Diagramme für CPU, RAM, Festplatte und Temperatur
Der Reiter Telemetrie: ein Diagramm pro Messwert.
Geräteseite, Reiter Netzwerktests: letzte Ping-, Geschwindigkeits- und DNS-Werte, Verlaufsdiagramme und die Testhistorie
Netzwerktests: letztes Ergebnis, Verläufe und Historie.

Alarme

EnergyOS öffnet einen Alarm, wenn ein Wert seine Schwelle überschreitet. Offene Alarme werden an der Glocke oben rechts und auf der Flottenübersicht gezählt. Ein Alarm schließt sich von selbst, wenn der Wert wieder normal ist.

AlarmÖffnet sich, wenn
Gerät offlineKein Heartbeat seit 2 Minuten
Hohe CPU-LastCPU über 90 %
Hohe TemperaturTemperatur über 80 °C
Hohe FestplattenauslastungFestplatte über 90 %
Hohe LatenzPing-Durchschnitt über 200 ms im letzten Netzwerktest
PaketverlustJeder Paketverlust im letzten Netzwerktest

Alarme erscheinen in der App. E-Mail-Benachrichtigungen sind standardmäßig aus; kontaktieren Sie uns, wenn Sie sie für Ihr Konto möchten.

Der Agent: Installation und Voraussetzungen

Der EnergyOS-Agent ist ein kleines Python-Programm für Linux-Geräte (Raspberry Pi, Mini-PCs, Server). Er hält eine ausgehende MQTT-Verbindung zu EnergyOS, meldet den Zustand des Geräts und führt die Netzwerktests und Befehle aus, die Sie von der Seite starten. Zum Anbinden von Energieanlagen wird er nicht gebraucht; das ist die Aufgabe des Gateways (siehe Wie EnergyOS zusammenspielt).

Voraussetzungen

WasErforderlich
BetriebssystemLinux. systemd wird empfohlen, um ihn als Dienst auszuführen. Raspberry Pi OS, Debian und Ubuntu sind die üblichen Wahlen; ARM und x86 funktionieren beide.
PythonVersion 3.9 oder neuer
pipWird vom Installer installiert, falls es fehlt (über apt, dnf, yum, pacman, apk oder das offizielle get-pip-Skript)
Bibliothekenpaho-mqtt, psutil, PyYAML, speedtest-cli, requests und schedule. Der Installer holt sie.
RechteKeine, wenn Sie als eigener Benutzer installieren und ausführen. sudo nur für rc-agent install-service und, falls gewünscht, zum Installieren von pip.
NetzwerkNur ausgehend: HTTPS (Port 443) zu www.qlines.net für die Installation und das einmalige init, danach MQTT über TLS (Port 8883) zu mqtt.qlines.net. pip erreicht außerdem PyPI. Die Uhr muss stimmen, sonst schlägt die TLS-Prüfung fehl.
Für die NetzwerktestsDer Befehl ping und ausgehender Zugriff auf 8.8.8.8, google.com und cloudflare.com
GrößeEin leichter Hintergrundprozess; ein Raspberry Pi reicht völlig aus

Installation

  1. Wählen Sie in EnergyOS Gerät hinzufügen, geben Sie ihm einen Namen und registrieren Sie es. Kopieren Sie den Token; er wird einmal angezeigt.
  2. Führen Sie auf dem Gerät den Installer mit Ihrem Token aus:
    curl -sSL https://www.qlines.net/install/rc-agent | bash -s -- --token tok_xxxxxxxx
  3. Den Agenten starten:
    rc-agent start
  4. Damit der Agent nach dem Abmelden und nach einem Neustart weiterläuft, installieren Sie ihn als Dienst:
    sudo rc-agent install-service
    sudo systemctl start remotecontrol-agent
Das Formular „Neues Gerät registrieren“ mit Gerätename und Notizen
Registrieren Sie zuerst das Gerät. Der Token erscheint, nachdem Sie es registriert haben.
Installation des EnergyOS-Agenten: fünf Schritte und wo jeder seine Dateien ablegt Registrieren Sie das Gerät in EnergyOS, führen Sie den Installer auf dem Gerät aus, initialisieren Sie mit dem Token, starten Sie den Agenten als Programm oder Dienst, und das Gerät wird online. Jeder Schritt nennt, was er auf dem Gerät oder auf dem Server anlegt. 1 Gerät registrieren

Flottenübersicht, Gerät hinzufügen. Sie erhalten einen Token (wird einmal angezeigt).

Auf dem Server

Ein Geräteeintrag, der Token (gehasht gespeichert) und ein Broker-Zugang für genau dieses Gerät.

2 Installer ausführen

Ein Befehl auf dem Gerät: Er prüft auf Python 3.9+, installiert pip, falls es fehlt, und installiert den Agenten.

Auf dem Gerät

Der Befehl rc-agent (in ~/.local/bin oder /usr/local/bin), das Python-Paket und 6 Bibliotheken.

3 Initialisieren

rc-agent init sendet den Token über HTTPS (443) und erhält die Geräteidentität zurück.

Auf dem Gerät

config.yaml mit den IDs, dem Token und der Serveradresse, in ~/.config/remotecontrol/ oder /etc/remotecontrol/.

4 Start

rc-agent start führt ihn im Vordergrund aus; sudo rc-agent install-service macht ihn zum Dienst.

Auf dem Gerät

Ein systemd-Dienst, remotecontrol-agent, der als Benutzer remotecontrol läuft.

5 Online

Der Agent meldet sich beim Broker an, sendet seine Angaben und berichtet dann alle 30 s.

Auf dem Server

Status Online, Live-Telemetrie, Befehle und Netzwerktests für dieses Gerät.

Netzwerkbedarf

Ausgehend HTTPS (443) für die Installation und Schritt 3, danach ausgehend MQTT über TLS (8883). Nichts eingehend.

Der Installer arbeitet in fünf Schritten. Die Kästen zeigen, was jeder Schritt wo anlegt.

Unter Debian 12 und Raspberry Pi OS ist das System-Python „extern verwaltet“. Der Installer fügt dann die pip-Option --break-system-packages hinzu. Wenn Sie den Agenten getrennt halten möchten, legen Sie zuerst eine virtuelle Umgebung an (python3 -m venv ~/rc-agent-env), installieren Sie das Paket mit dem pip dieser Umgebung hinein (https://www.qlines.net/install/remotecontrol-agent.tar.gz) und starten Sie ~/rc-agent-env/bin/rc-agent.

Was wo installiert wird

WasWo
Befehl rc-agent~/.local/bin (Benutzerinstallation) oder /usr/local/bin (als root installiert)
Python-Paket und BibliothekenDer Ordner site-packages des Python, das der Installer verwendet hat
Einstellungen (ID, Token, Server)~/.config/remotecontrol/config.yaml; als Dienst /etc/remotecontrol/config.yaml (nur für den Dienstbenutzer lesbar)
Dienst/etc/systemd/system/remotecontrol-agent.service, läuft als Systembenutzer remotecontrol (ohne Login, ohne Home-Verzeichnis)
Marker für den laufenden Prozess/tmp/remotecontrol-agent.pid
ProtokollDas Terminal; als Dienst journalctl -u remotecontrol-agent

Die Einstellungsdatei enthält den Geräte-Token im Klartext. Schützen Sie sie: chmod 600 ~/.config/remotecontrol/config.yaml. Wird ein Token offengelegt, nutzen Sie Regenerate Token in den Geräteeinstellungen: Der alte funktioniert dann nicht mehr.

Was Agent und EnergyOS einander sagen

Alle Nachrichten sind kleine JSON-Dokumente auf Topics unter rc/{account}/{device}/. Der Agent beginnt jedes Gespräch: Er verbindet sich, abonniert drei Topics (config, cmd/request, nettest/trigger) und veröffentlicht, was er hat. EnergyOS antwortet auf den Topics, auf die der Agent lauscht.

Nachrichten zwischen Agent, Broker, EnergyOS und Ihnen Der Agent verbindet sich mit dem Broker, abonniert seine Topics, registriert sich und erhält seine Konfiguration. Danach sendet er alle 30 Sekunden einen Heartbeat, alle 60 Sekunden Telemetrie und nach Zeitplan Netzwerktests. Wenn Sie einen Befehl ausführen, sendet EnergyOS ihn an den Agenten, der ihn ausführt und das Ergebnis zurückschickt. Agent MQTT-Broker EnergyOS Sie Start connect: TLS + der eigene Zugang des Geräts subscribe: config, cmd/request, nettest/trigger register: Agent-Version, Hostname, System config: Intervalle, Funktionen, Zeitplan der Netzwerktests Dann, die ganze Zeit Heartbeat alle 30 s: „noch da“ telemetry alle 60 s: CPU, Speicher, Festplatte, Temperatur, Betriebszeit Netzwerktest nach Zeitplan (standardmäßig stündlich) oder auf Anforderung Wenn Sie einen Befehl ausführen Ausführen: der Befehlstext cmd/request (nur wenn das Gerät online ist)

führt das Programm aus, als Benutzer des Agenten

cmd/response: Ausgabe, Fehlertext, Exit-Code, Dauer Ergebnis im Verlauf
Eine Verbindung, vom Agenten gestartet. Ein Befehl nimmt denselben Weg zurück: EnergyOS fragt, der Agent führt aus und antwortet.
Topic (unter rc/{account}/{device}/)RichtungInhalt
registerAgent → EnergyOSAgent-Version, Hostname, System, Architektur, Python-Version
configEnergyOS → AgentHeartbeat- und Telemetrie-Intervall, aktivierte Funktionen, Zeitplan der Netzwerktests
heartbeatAgent → EnergyOS„Noch da“, standardmäßig alle 30 Sekunden
telemetry/systemAgent → EnergyOSCPU, Speicher, Festplatte, Temperatur, Betriebszeit, Last; standardmäßig alle 60 Sekunden
nettest/trigger und nettest/resultbeideEinen Netzwerktest jetzt starten; sein Ergebnis (Ping, DNS, HTTP-Prüfungen, Geschwindigkeit)
cmd/request und cmd/responsebeideDer auszuführende Befehl; seine Ausgabe, Fehlertext, Exit-Code und Dauer

Befehle des Agenten

BefehlWas sie tut
rc-agent init --token … --server mqtt.qlines.netPrüft den Token bei EnergyOS und schreibt die Einstellungsdatei
rc-agent startFührt den Agenten im Vordergrund aus
rc-agent statusZeigt, ob er läuft, und eine Zusammenfassung der Einstellungen
rc-agent test-nettestFührt einen Netzwerktest aus und gibt das Ergebnis aus
sudo rc-agent install-serviceLegt den Dienstbenutzer an, kopiert die Einstellungen nach /etc/remotecontrol und installiert und aktiviert den systemd-Dienst

Den Agenten entfernen

  1. Den Dienst stoppen und entfernen, falls Sie ihn installiert haben: sudo systemctl disable --now remotecontrol-agent und /etc/systemd/system/remotecontrol-agent.service löschen.
  2. python3 -m pip uninstall remotecontrol-agent und löschen Sie den Einstellungsordner.
  3. Löschen Sie das Gerät in EnergyOS. Dadurch wird auch sein Zugang beim Broker entfernt.

Fernbefehle

Auf dem Reiter Befehle eines Geräts können Sie einen Befehl auf dem Gerät ausführen und die Antwort lesen. Befehle laufen über den Agenten, nur solange das Gerät online ist, und jeder Befehl wird protokolliert: wer ihn gesendet hat, wann, Exit-Code und Dauer.

Geräteseite, Reiter Befehle: Schnellbefehle, ein Eingabefeld und der Verlauf der Befehle mit Exit-Code, Dauer und Status
Der Reiter Befehle: Schnellbefehle, das Eingabefeld und der Verlauf.

Wie ein Befehl abläuft

Der Agent startet keine Shell. Er zerlegt Ihren Text wie eine Shell in Wörter (Anführungszeichen funktionieren) und startet das Programm direkt, als der Benutzer, unter dem der Agent läuft. Das ist sicherer und erklärt, warum nur manches so funktioniert, wie es getippt wird.

Wie der Agent einen Fernbefehl ausführt Der Befehlstext wird in Wörter zerlegt, und das Programm wird direkt gestartet, ohne Shell, als der Benutzer, unter dem der Agent läuft. Der Agent wartet bis zum Timeout, sammelt die Ausgabe und sendet Exit-Code, Ausgabe und Fehlertext zurück. Pipes und Umleitungen brauchen eine ausdrücklich angeforderte Shell wie bash -c. Ihr Befehldf -h /

auf der Geräteseite eingegeben

In Wörter zerlegen

wie eine Shell, daher funktionieren Anführungszeichen: ls "my dir"

Programm starten

direkt, ohne Shell, als der Benutzer des Agenten; keine Eingabe (stdin geschlossen)

Warten und sammeln

Bis zu 30 Sekunden; dann werden das Programm und alles, was es gestartet hat, gestoppt.

Ergebnis zurück

Exit-Code, Ausgabe und Fehlertext (je bis zu 64.000 Zeichen).

Funktioniert so uname -adf -h /systemctl status evcc/usr/bin/python3 /opt/x.py Braucht eine Shell

Pipes, Umleitungen, &&, Platzhalter, $VARIABLEN, cd, export:

/bin/bash -c 'df -h | head -2'

Ein Befehl, von bash ausgeführt.

Umgebung

Derselbe Benutzer, dieselbe PATH-Variable und dieselben Variablen wie beim Agent-Prozess. Als Dienst ist das eine kleine, saubere Umgebung, nicht Ihre Login-Shell.

Geben Sie im Zweifel den vollen Pfad an.

Der Agent führt das Programm selbst aus. Dazwischen liegt keine Shell, es sei denn, Sie fordern eine an.
Sie geben einErgebnis
df -h /, uname -a, uptimeFunktioniert: ein Programm und seine Argumente
df -h | head -2, a && b, ls > file, ls *.logFunktioniert so nicht: Pipes, &&, Umleitungen und Platzhalter gehören zu einer Shell
cd /tmp, export X=1, echo $HOMEFunktioniert nicht: Das sind Shell-Befehle und Variablenersetzungen
/bin/bash -c 'df -h | head -2'Funktioniert: Sie fordern selbst eine Shell an, und sie führt die ganze Zeile aus
sudo rebootFunktioniert nur, wenn der Benutzer des Agenten es ohne Passwort ausführen darf (siehe unten)
Ein Programm, das auf Eingaben wartet oder länger als 30 Sekunden läuftNach 30 Sekunden gestoppt, zusammen mit allem, was es gestartet hat. Die Eingabe ist geschlossen, daher kann nichts eine Frage stellen.
Eine sehr lange AusgabeBei 64.000 Zeichen pro Strom abgeschnitten, mit einem Hinweis

Kurz gesagt: Ein Befehl nutzt den eigenen Benutzer und die Umgebung des Agenten. Als Dienst ist das der Benutzer remotecontrol mit einem minimalen PATH und ohne Login-Profil.

Um Ihre eigene Umgebung zu nutzen, führen Sie /bin/bash -lc '…' für eine Login-Shell aus, rufen Sie Programme mit ihrem vollen Pfad auf (zum Beispiel dem Pfad venv/bin/python) oder fügen Sie dem Dienst Environment=-Zeilen hinzu.

Welche Umgebung ein Befehl sieht

Ein Befehl läuft als der Benutzer, unter dem der Agent läuft, mit der Umgebung des Agent-Prozesses: dessen PATH, dessen HOME, dessen Arbeitsordner und dessen Variablen. Er liest weder .bashrc noch .profile, weil keine Login-Shell beteiligt ist.

  • Von Hand gestartet (rc-agent start): die Umgebung dieses Terminals, einschließlich einer aktivierten virtuellen Umgebung.
  • Als Dienst gestartet (install-service): der Systembenutzer remotecontrol mit der minimalen Umgebung, die systemd einem Dienst gibt (ein kurzer PATH wie /usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin). Er ist nicht Ihr Login-Benutzer, hat kein Home-Verzeichnis und ist nicht in der Gruppe sudo.

Die eigene Umgebung nutzen

Sie möchtenTun Sie dies
Um zu sehen, was der Agent siehtFühren Sie env und whoami als Befehle aus
Ihre Login-Umgebung (.profile, Ergänzungen von PATH)/bin/bash -lc 'your command' (eine Login-Shell des Agent-Benutzers)
Ein Programm aus einer virtuellen UmgebungGeben Sie den vollen Pfad an: /home/pi/venv/bin/python /home/pi/check.py
Dauerhafte Variablen für jeden BefehlAls Dienst: sudo systemctl edit remotecontrol-agent, [Service] und Environment="NAME=value" hinzufügen (oder EnvironmentFile=/etc/remotecontrol/env), dann den Dienst neu starten. Von Hand: vor rc-agent start setzen.
Befehle als anderer BenutzerLassen Sie den Agenten unter diesem Benutzer laufen (User= im Dienst ändern) oder erlauben Sie genau die benötigten Befehle mit einer sudoers-Regel für den Benutzer remotecontrol
Ein Neustart des GerätsDie Schaltfläche Reboot Agent sendet sudo reboot. Erlauben Sie es mit einer sudoers-Datei wie remotecontrol ALL=(root) NOPASSWD: /usr/sbin/reboot, /usr/bin/systemctl reboot

Jeder, der sich in Ihrem EnergyOS-Konto anmelden kann, kann auf jedem Gerät darin Befehle ausführen. Geben Sie dem Benutzer des Agenten nur die nötigen Rechte, machen Sie ihn nie aus Bequemlichkeit zu root und schützen Sie das Konto mit einem starken Passwort.

Sicherheit und Datenschutz

  • Verschlüsselt: Der gesamte MQTT-Verkehr nutzt TLS (Port 8883), und der Agent prüft das Zertifikat des Servers. Die Website und die einmalige Token-Prüfung des Agenten nutzen HTTPS.
  • Ein Zugang pro Gerät: Die Geräte-ID ist der Benutzername und der Token das Passwort. Ein Gerät kann nur auf seinen eigenen Topics veröffentlichen und lauschen, daher kann kein Gerät ein anderes lesen oder steuern.
  • Keine eingehenden Verbindungen: Die Anlagen bleiben hinter Ihrem Router. Gateway und Agent verbinden sich nach außen.
  • Tokens: werden bei EnergyOS gehasht gespeichert. Ein verlorener oder offengelegter Token wird in den Geräteeinstellungen mit Regenerate Token ersetzt (der Agent trennt sich, bis er neu eingerichtet ist); beim Löschen eines Geräts wird sein Zugang sofort entfernt.
  • Privat pro Konto: Energiesysteme, Messwerte, Geräte und Befehle gehören nur zu Ihrem Konto.
  • Wetter und Ortssuche: An die Wetter- und Ortsdienste werden nur der eingegebene Ortstext und die daraus gefundenen Koordinaten gesendet; keine Kontodaten.
  • Backups: Die Daten werden jede Nacht gesichert. Gelöschte Daten verschwinden mit dem Rotieren der Backups, innerhalb von sechs Monaten.

Konto, Tarife und Grenzen

Unter Einstellungen sehen Sie Ihren Tarif und wie viel davon Sie nutzen (Geräte und die heutigen Nachrichten), ändern Passwort und E-Mail-Adresse, vergleichen Tarife und können, wenn Sie möchten, Ihr Konto löschen.

Die Seite „Einstellungen“ mit Kontoübersicht, Passwort ändern, E-Mail-Adresse ändern, Tarifen und Konto löschen
Einstellungen: Tarifnutzung, Passwort, E-Mail-Adresse, Tarife und Kontolöschung.
WasGrenze
Geräte, Nachrichten pro Gerät und Tag, DatenaufbewahrungHängen von Ihrem Tarif ab; siehe Preise und die Tarifkarten in den Einstellungen
Energiesysteme pro Konto30
Automatisierungsregeln pro Konto20
Energiemesswerte1 pro System alle 10 s, 90 Tage gespeichert; Befehle 180 Tage gespeichert

Die Daten werden jede Nacht gesichert.

Fragen und Fehlersuche

Ich habe mein Passwort vergessen. Was nun?

Wählen Sie auf der Anmeldeseite Passwort vergessen? und geben Sie Ihre E-Mail-Adresse ein. Der Link in der E-Mail ist eine Stunde gültig und funktioniert einmal. Angemeldet ändern Sie das Passwort unter Einstellungen → Passwort ändern. Ein neues Passwort meldet Sie auf allen anderen Geräten ab.

Wie ändere ich meine E-Mail-Adresse?

Unter Einstellungen → E-Mail-Adresse ändern, mit Ihrem aktuellen Passwort. Wir senden einen Link an die neue Adresse; sobald Sie ihn anklicken (innerhalb von 24 Stunden), melden Sie sich mit der neuen Adresse an, und alle E-Mails gehen dorthin. Die alte Adresse erhält eine Mitteilung. Geräte, Systeme und Daten bleiben wie sie sind, installierte Agenten brauchen keine Änderung.

Wie lösche ich mein Konto?

Unter Einstellungen → Konto löschen, mit Ihrem aktuellen Passwort. Alles wird sofort gelöscht: Geräte werden getrennt und entfernt, zusammen mit Energiesystemen, Messwerten, Regeln, Einstellungen und dem Aktivitätsprotokoll. Kopien in unseren Backups werden gelöscht, sobald die Backups rotieren, innerhalb von sechs Monaten. Ihr UtilityControl-Konto, falls Sie eines haben, ist getrennt.

Der Installer meldet „Python 3.9+ not found“.

Installieren Sie ein aktuelles Python 3 (sudo apt install python3 python3-pip auf Debian-basierten Systemen) und starten Sie den Installer erneut.

Der Agent startet, aber das Gerät bleibt „Nie verbunden“ oder „Offline“.

  • Prüfen Sie das Protokoll (journalctl -u remotecontrol-agent -f oder das Terminal). „MQTT connect refused“ bedeutet, dass der Token nicht zu diesem Gerät passt: Nutzen Sie Regenerate Token in den Geräteeinstellungen und führen Sie rc-agent init mit dem neuen Token erneut aus.
  • Prüfen Sie, ob das Gerät mqtt.qlines.net auf Port 8883 (ausgehend) erreicht und ob seine Uhr stimmt.
  • Manche Firmennetzwerke blockieren Port 8883; bitten Sie den Netzwerkverantwortlichen, ihn ausgehend freizugeben.

Ein Befehl meldet „Executable not found“.

Das Programm liegt nicht im PATH des Agenten. Geben Sie den vollen Pfad an oder lesen Sie Die eigene Umgebung nutzen.

Eine Steuerung meldet „keine Bestätigung“.

Das Gateway hat nicht rechtzeitig geantwortet. Prüfen Sie, ob es läuft und auf dem Topic …/set dieses Systems lauscht und ob es auf …/ack veröffentlicht. EnergyOS nimmt nicht an, dass die Einstellung gewirkt hat.

Ist das Ergebnis des Förderrechners verbindlich?

Nein. Es ist eine Berechnung mit den veröffentlichten Regeln. Über die Bewilligung entscheiden KfW oder BAFA.

Die Förderregeln haben sich geändert. Was nun?

Die Regeln sind als Daten gespeichert und werden von uns aktualisiert; die Ergebnisseite zeigt das Datum der letzten Prüfung.

Sie brauchen eine Funktion oder ein Tarif-Upgrade?

Kontaktieren Sie uns.