Integrationen
Loxone Miniserver direkt einrichten
Heartbeat, Firmware-Version, Uptime und ausgewählte Statuswerte direkt über den kompatiblen Loxone-HTTPS-Ingress an Werklio senden.
Voraussetzungen
- Loxone Config ab 16.1
- Internetzugang und DNS-Auflösung am Miniserver
- Werklio-Loxone-Integration mit aktivem API-Key
Schritt für Schritt
- Erzeuge in Werklio eine Loxone-Integration und lade die aktuelle XML-Vorlage herunter.
- Ersetze in der XML vor dem Import LOXONE-FIRMWARE-VERSION durch die installierte Miniserver-Version, zum Beispiel 17.1.7.27.
- Markiere in Loxone Config Virtuelle Ausgänge und wähle Vordefinierte Geräte → Vorlage importieren.
- Kontrolliere bei jedem Befehl den HTTP-Header: Er enthält ausschließlich X-Werklio-Key mit dem Integrations-Key. Den Content-Type setzt der Miniserver selbst; Gen. 1 kann dabei auch text/xml senden, was Werklio unterstützt.
- Verbinde Firmware-Version mit Zeiten → Startimpuls, damit sie nach jedem Neustart einmal gesendet wird.
- Füge einen Analogspeicher ein: Zeiten → Sekunden seit Boot an Eingang V, Minutenimpuls an Set und den Ausgang V an Heartbeat + Uptime. Den Fallback-Heartbeat dann nicht zusätzlich verbinden.
- Verbinde die Systemvariable Systemstatus über einen Vergleich Systemstatus > 0 mit Sammelstörung. Damit wird bei einer aktiven Systemstatusmeldung true und nach der Entwarnung false gesendet.
- Verbinde optional den niedrigsten relevanten Batteriestand.
- Speichere die Konfiguration im Miniserver und prüfe den ersten Aufruf im HTTP-Monitor sowie danach in Werklio.
Beispielkonfiguration
<?xml version="1.0" encoding="utf-8"?>
<VirtualOut Title="Werklio Direkt" Comment="Healthcheck-Daten direkt per HTTPS an den Loxone-Ingress senden" Address="https://loxone.werkl.io" CmdInit="" HintText="Vor dem Import LOXONE-FIRMWARE-VERSION durch die installierte Miniserver-Version ersetzen." CloseAfterSend="true" CmdSep="">
<Info templateType="3" minVersion="16010630"/>
<VirtualOutCmd Title="Heartbeat (Fallback)" Comment="Nur verwenden, wenn keine Uptime gesendet wird; mit Minutenimpuls verbinden" CmdOnMethod="POST" CmdOffMethod="POST" CmdOn="/api/v1/ingest/loxone/direct" CmdOnHTTP="X-Werklio-Key: wk_live_DEIN_EINMALIGER_KEY" CmdOnPost="{"signal":"heartbeat"}" CmdOff="" CmdOffHTTP="" CmdOffPost="" CmdAnswer="" HintText="Eine steigende Flanke pro Minute senden. Nicht parallel zu Heartbeat + Uptime verwenden." Analog="false" Repeat="0" RepeatRate="0"/>
<VirtualOutCmd Title="Heartbeat + Uptime" Comment="Sekunden seit Boot minütlich über einen Analogspeicher zuführen" CmdOnMethod="POST" CmdOffMethod="POST" CmdOn="/api/v1/ingest/loxone/direct" CmdOnHTTP="X-Werklio-Key: wk_live_DEIN_EINMALIGER_KEY" CmdOnPost="{"signal":"uptime","value":<v>}" CmdOff="" CmdOffHTTP="" CmdOffPost="" CmdAnswer="" HintText="Zeiten/Sekunden seit Boot auf Analogspeicher V, Minutenimpuls auf Set, Ausgang V hier anschließen." Analog="true" Repeat="0" RepeatRate="0" SourceValHigh="1000000000" DestValHigh="1000000000"/>
<VirtualOutCmd Title="Firmware-Version" Comment="Beim Start einmal senden; Platzhalter vor Import ersetzen" CmdOnMethod="POST" CmdOffMethod="POST" CmdOn="/api/v1/ingest/loxone/direct" CmdOnHTTP="X-Werklio-Key: wk_live_DEIN_EINMALIGER_KEY" CmdOnPost="{"signal":"version","value":"LOXONE-FIRMWARE-VERSION"}" CmdOff="" CmdOffHTTP="" CmdOffPost="" CmdAnswer="" HintText="LOXONE-FIRMWARE-VERSION vor dem Import ersetzen und den Befehl mit Startimpuls verbinden." Analog="false" Repeat="0" RepeatRate="0"/>
<VirtualOutCmd Title="Sammelstörung" Comment="Systemstatus > 0 bedeutet Störung, 0 bedeutet in Ordnung" CmdOnMethod="POST" CmdOffMethod="POST" CmdOn="/api/v1/ingest/loxone/direct" CmdOnHTTP="X-Werklio-Key: wk_live_DEIN_EINMALIGER_KEY" CmdOnPost="{"signal":"system-fault","value":true}" CmdOff="/api/v1/ingest/loxone/direct" CmdOffHTTP="X-Werklio-Key: wk_live_DEIN_EINMALIGER_KEY" CmdOffPost="{"signal":"system-fault","value":false}" CmdAnswer="" HintText="Systemvariable Systemstatus über Vergleich > 0 verbinden. Bei Entwarnung sendet der AUS-Befehl automatisch false." Analog="false" Repeat="0" RepeatRate="0"/>
<VirtualOutCmd Title="Niedrigster Batteriestand" Comment="Optionaler Prozentwert 0 bis 100" CmdOnMethod="POST" CmdOffMethod="POST" CmdOn="/api/v1/ingest/loxone/direct" CmdOnHTTP="X-Werklio-Key: wk_live_DEIN_EINMALIGER_KEY" CmdOnPost="{"signal":"battery-minimum","value":<v>}" CmdOff="" CmdOffHTTP="" CmdOffPost="" CmdAnswer="" HintText="Optional mit dem niedrigsten relevanten Batteriestand verbinden." Analog="true" Repeat="0" RepeatRate="0" SourceValHigh="100" DestValHigh="100"/>
</VirtualOut>Testschritt
Im LiveView Firmware-Version einmal auslösen und Heartbeat + Uptime über den Analogspeicher senden. Der HTTP-Monitor soll eine erfolgreiche HTTPS-Antwort zeigen.
Erwartetes Ergebnis
Werklio zeigt einen aktuellen Loxone-Heartbeat mit Firmware-Version und steigender Uptime. Standort und Integration wurden allein aus dem API-Key ermittelt.
Signalzuordnung
| Loxone | Auslösung | Werklio |
|---|---|---|
| Firmware-Version | Startimpuls | Heartbeat · Version |
| Sekunden seit Boot | minütlich per Analogspeicher | Heartbeat · Uptime |
| Sammelstörung | bei Zustandswechsel | Service · online/warning |
| Niedrigster Batteriestand | bei Wertänderung | Sensor · batteryPercent |
Fehlerbehebung
- HTTP 401: Im HTTP-Header darf nur X-Werklio-Key mit dem Key stehen. Einen als Text sichtbaren XML-Zeilenumbruch sowie einen zusätzlich eingetragenen Content-Type entfernen oder die aktuelle XML neu importieren.
- HTTP 400: Signal, Wertebereich und unveränderten JSON-POST-Inhalt prüfen.
- Als Version erscheint noch LOXONE-FIRMWARE-VERSION: Platzhalter in der XML ersetzen und erneut importieren.
- Uptime fehlt oder sendet jede Sekunde: Sekunden seit Boot über einen Analogspeicher mit Minutenimpuls abtasten.
- SSL Write Error: Prüfen, dass der virtuelle Ausgang exakt https://loxone.werkl.io verwendet und die aktuelle Vorlage importiert wurde. Ein Miniserver-Neustart ist nicht erforderlich.
- Keine Verbindung: DNS, Gateway, Internetzugang und Uhrzeit des Miniservers kontrollieren.
- Doppelte Heartbeats: entweder Heartbeat + Uptime oder den Fallback-Heartbeat verbinden, nicht beide.
Sicherheitshinweise
- Der integrationsbezogene API-Key wird bewusst in der Loxone-Konfiguration gespeichert und nur als HTTPS-Header gesendet.
- Bei Weitergabe einer ungeschützten Projektdatei den Key in Werklio widerrufen und eine neue XML erzeugen.
- Keine Anwesenheits-, Tür- oder Bewegungswerte übertragen; die Vorlage beschränkt sich auf technische Healthcheck-Daten.