Logikbaustein: Worx Landroid

Getting started

Geschätzte Lektüre: 11 Minuten 5 Ansichten

Funktion und Voraussetzungen

Der Logikbaustein verbindet einen Gira X1/L1 mit der WORX Cloud. Er liest den Zustand eines Landroid-Mähers und sendet Standard- oder Expertenbefehle. Erforderlich sind eine Internetverbindung, ein eingerichtetes WORX-Konto, ein diesem Konto zugeordneter Mäher und eine gültige TerraBytes-Lizenz.

Einrichtung und Lizenzparameter

Parameter Beispielwert Verwendung
Email max.mustermann@example.org E-Mail-Adresse der WORX-App; immer erforderlich.
Password MeinSicheresPasswort Kennwort der WORX-App; immer erforderlich.
SerialNumber 20231234567890123456 Seriennummer des WORX-Mähers. Bei mehreren Geräten unbedingt setzen.
DeviceIndex 0 Ersatzweise Geräteauswahl: 0 = erster, 1 = zweiter Mäher. Wird nur benutzt, wenn SerialNumber leer ist.
PollIntervalSeconds 300 Automatische Statusabfrage; mindestens 30 Sekunden, 0 deaktiviert das Polling.
ActivationCode ABCD1234-EFGH-5678-IJKL Von TerraBytes gelieferter Aktivierungscode.
LicenseSerialNumber X1-12345678 Optionale Seriennummer des Gira X1/L1 für die Lizenzzuordnung.
OfflineToken vollständiger gelieferter Token Optionaler signierter Offline-Lizenznachweis; unverändert einfügen.
OfflineProfile private Profil des Offline-Tokens: private, business oder partner.
ReleaseChannel stable Updatekanal; normalerweise stable, optional beta oder rc.

Wichtig: SerialNumber bezeichnet den WORX-Mäher. LicenseSerialNumber bezeichnet den Gira X1/L1. Diese Werte dürfen nicht vertauscht werden.

Der Baustein ist an die MAC-Adresse des X1/L1 gebunden. TerraBytes benötigt zur Bereitstellung Bestellnummer, Lizenznehmer, X1/L1-MAC-Adresse und optional die X1/L1-Seriennummer. WORX-E-Mail und WORX-Kennwort werden dafür nicht benötigt und dürfen nicht an TerraBytes übermittelt werden.

Was muss vor einer Aktion anliegen?

Vor jedem Aktionsimpuls müssen diese Voraussetzungen erfüllt sein:

gültige TerraBytes-Lizenz
  + Email und Password
  + SerialNumber oder DeviceIndex
  + vorbereitende Expertenwerte (nur bei Expertenaktionen)
  + Aktionsimpuls 0 → 1 → 0

Ohne gültige Lizenz setzt der Baustein Success=0 und Diagnostics="Keine gueltige Lizenz.". Ein dauerhaftes Signal auf 1 ersetzt keinen neuen Impuls.

Normale Aktionen

Aktion Vorher einstellen Auslösen Kein Kommandocode nötig
Status laden Konto- und Geräteparameter Refresh: 0 → 1 → 0 ja
Mähvorgang starten Konto- und Geräteparameter Start: 0 → 1 → 0 ja
Pausieren Konto- und Geräteparameter Pause: 0 → 1 → 0 ja
Zur Ladestation fahren Konto- und Geräteparameter Home: 0 → 1 → 0 ja

Beispiel Home:

Email        = max.mustermann@example.org
Password     = <WORX-Kennwort>
SerialNumber = 20231234567890123456
Home         = Impuls 0 → 1 → 0

Ergebnis:
Success      = 1
Diagnostics  = Heimfahrt gesendet

Nach etwa 5 bis 15 Sekunden Refresh auslösen, damit der inzwischen von WORX gemeldete Zustand übernommen wird.

Expertenaktionen

Aktion Zuerst setzen Danach auslösen
Freier Kommandocode CommandCode, z. B. 9 Impuls an SendCommand
Freie MQTT-Payload RawCommandJson, z. B. {"rd":120} Impuls an SendRawCommand
WORX-REST-Aufruf RestTarget, RestMethod, RestSuffix, RestBodyJson Impuls an ExecuteRest

Die vorbereitenden Werte lösen allein keine Aktion aus. Im GPA sollten sie zuerst stabil gesetzt und der Sendetrigger in einem folgenden Logikzyklus ausgelöst werden. Aktionsimpulse gegenseitig verriegeln, damit pro Zyklus nur eine Aktion startet.

Basis-Eingangsmatrix

Eingang Beispiel Wirkung
Refresh 0 → 1 → 0 Lädt Gerät und aktuellen Status. Beispiel: Success=1, BatteryPercent=78, Diagnostics=OK.
Start 0 → 1 → 0 Sendet Kommando 1; Beispiel: Diagnostics=Start gesendet.
Pause 0 → 1 → 0 Sendet Kommando 2; Beispiel: Diagnostics=Pause gesendet.
Home 0 → 1 → 0 Sendet Kommando 3; Beispiel: Diagnostics=Heimfahrt gesendet.
RainDelayMinutes 120 Bereitet eine Regenverzögerung von 120 Minuten vor; zulässig sind 0 bis 300 Minuten.
SetRainDelay 0 → 1 → 0 Sendet die zuvor gesetzte Regenverzögerung protokollgerecht an den Mäher.
CommandCode 9 Bereitet einen Kommandocode vor; sendet noch nichts. Experteneingang.
SendCommand 0 → 1 → 0 Sendet den zuvor gesetzten CommandCode. Experteneingang.
RawCommandJson {"rd":120} Bereitet eine modellabhängige Roh-Payload vor. Experteneingang.
SendRawCommand 0 → 1 → 0 Sendet RawCommandJson. Experteneingang.
RestTarget 0 0 = ausgewählter Mäher, 1 = Produktkatalog. Experteneingang.
RestMethod 0 0=GET, 1=POST, 2=PUT, 3=DELETE. Experteneingang.
RestSuffix firmware-upgrade Relativer Geräte-Unterpfad; für das Gerät selbst leer lassen. Experteneingang.
RestBodyJson {} JSON-Body für POST/PUT/DELETE; bei GET unbenutzt. Experteneingang.
ExecuteRest 0 → 1 → 0 Führt den vorbereiteten REST-Aufruf aus; Antwort in ApiResponse. Experteneingang.

Sind Start, Pause und Home gleichzeitig aktiv, gilt intern Start vor Pause vor Home. Für eindeutiges Verhalten immer nur einen Impuls senden.

Erweiterte Eingänge ab Version 0.5.0

Bereich Datenports Auslöser
Sperre LockEnabled SetLock
Partymodus PartyModeEnabled SetPartyMode
ACS AcsEnabled SetAcs
Off-Limits OffLimitsEnabled SetOffLimits
Off-Limits-Abkürzung OffLimitsShortcutEnabled SetOffLimitsShortcut
Drehmoment TorquePercent (-50…50) SetTorque
Schnitthöhe CuttingHeightMm (20…70) SetCuttingHeight
nächste Legacy-Zone Zone SetZone
Zeitplanstatus ScheduleEnabled SetScheduleEnabled
vollständiger Zeitplan ScheduleJson ApplyScheduleJson
einmaliges Mähen OneTimeRuntimeMinutes (10…120), OneTimeBoundary StartOneTimeSchedule
Kantenschnitt StartEdgeCut
automatische Planung AutoScheduleEnabled SetAutoScheduleEnabled
automatische Firmwareupdates FirmwareAutoUpgradeEnabled SetFirmwareAutoUpgrade
Rasendaten LawnSize, LawnPerimeter (0…100000) ApplyLawn
erweiterte Produkteinstellungen ProductItemPatchJson ApplyProductItemPatch
Mäher-Firmwareinfo GetMowerFirmwareInfo
Mäher-Firmwareupdate StartMowerFirmwareUpgrade
Akku-Zählerreset ResetBatteryCounter
Messer-Zählerreset ResetBladeCounter

Alle Datenports müssen vor dem zugehörigen positiven Auslöseimpuls stabil anliegen. Firmwareupdate und Zählerresets sind wartungsrelevante Aktionen.

Kommandocodes

Code Aktion
0 Status anfordern
1 Mähvorgang starten
2 Pausieren
3 Heimfahrt
4 Zonentraining
5 Mäher sperren
6 Mäher entsperren
7 Neustart
8 Pause auf Begrenzungsdraht
9 Sichere Heimfahrt, Messer aus

Nicht jedes Modell unterstützt jeden Code. Success=1 bestätigt zunächst die technische Annahme durch den Cloud-Kanal, nicht die tatsächliche Bewegung des Mähers.

Basis-Ausgangsmatrix

Ausgang Beispielwert Bedeutung
Success 1 Letzter Transport-/API-Aufruf war erfolgreich.
Name Landroid Garten Gerätename aus der WORX-App.
Serial 20231234567890123456 Seriennummer des tatsächlich ausgewählten WORX-Mähers.
StatusCode 1 Numerischer WORX-Zustand aus dat.ls; modellabhängig.
ErrorCode 0 WORX-Fehlercode aus dat.le; 0 bedeutet üblicherweise kein gemeldeter Fehler.
BatteryPercent 78 Akkuladestand in Prozent.
Online 1 1 = Mäher wird von WORX als online gemeldet.
LastUpdate 2026-07-14T10:42:18.000Z Zeitpunkt der letzten WORX-Statusmeldung, normalerweise UTC.
Diagnostics OK Ergebnis oder Fehlerursache, z. B. Start gesendet oder Der Mäher ist offline.
RawJson {"name":"Landroid Garten",...} Vollständiger Gerätedatensatz; standardmäßig ausgeblendet.
ApiResponse {"version":"3.32",...} Antwort des Experten-REST-Aufrufs; standardmäßig ausgeblendet.
RainDelayConfiguredMinutes 120 Im Mäher eingestellte Regenverzögerung aus cfg.rd.
RainDelayActive 1 Regensensor beziehungsweise Regenpause ist aktuell aktiv (dat.rain.s).
RainDelayRemainingMinutes 37 Noch verbleibende Regenpause in Minuten (dat.rain.cnt).
Latitude 51.234567 Breitengrad, wenn das Modell GPS/RTK-Positionen meldet; sonst 0.
Longitude 7.123456 Längengrad, wenn das Modell GPS/RTK-Positionen meldet; sonst 0.
RainDelayConfiguredMinutes 120 Im Mäher eingestellte Regenverzögerung aus cfg.rd.
RainDelayActive 1 Regensensor beziehungsweise Regenpause ist aktuell aktiv (dat.rain.s).
RainDelayRemainingMinutes 37 Noch verbleibende Regenpause in Minuten (dat.rain.cnt).
Latitude 51.234567 Breitengrad, wenn das Modell GPS/RTK-Positionen meldet; sonst 0.
Longitude 7.123456 Längengrad, wenn das Modell GPS/RTK-Positionen meldet; sonst 0.
RainDelayConfiguredMinutes 120 Im Mäher eingestellte Regenverzögerung aus cfg.rd.
RainDelayActive 1 Regensensor beziehungsweise Regenpause ist aktuell aktiv (dat.rain.s).
RainDelayRemainingMinutes 37 Noch verbleibende Regenpause in Minuten (dat.rain.cnt).
Latitude 51.234567 Breitengrad, wenn das Modell GPS/RTK-Positionen meldet; sonst 0.
Longitude 7.123456 Längengrad, wenn das Modell GPS/RTK-Positionen meldet; sonst 0.
RainDelayConfiguredMinutes 120 Im Mäher eingestellte Regenverzögerung aus cfg.rd.
RainDelayActive 1 Regensensor beziehungsweise Regenpause ist aktuell aktiv (dat.rain.s).
RainDelayRemainingMinutes 37 Noch verbleibende Regenpause in Minuten (dat.rain.cnt).
Latitude 51.234567 Breitengrad, wenn das Modell GPS/RTK-Positionen meldet; sonst 0.
Longitude 7.123456 Längengrad, wenn das Modell GPS/RTK-Positionen meldet; sonst 0.
LicenseStatus Lizenz: OK • bis 31.12.2027 23:59 Ergebnis der Lizenzprüfung beziehungsweise Aktivierungshinweis.
LicenseOwner Max Mustermann Im TerraBytes LicenseServer hinterlegter Lizenznehmer.
UpdateAvailable 1 Eine neuere Version ist im gewählten Releasekanal verfügbar.
LatestVersion 0.5.11 Vom Lizenzdienst gemeldete aktuelle Produktversion.
DownloadUrl https://…/Worx-0.5.11.zip Vom Lizenzdienst gelieferte Downloadadresse; kann leer sein.
OfflineExpiresAt 28.07.2026 12:00 Ablaufzeitpunkt des Offline-Nachweises; ohne Offline-Token leer.

Erweiterte Ausgänge ab Version 0.5.0

Zusätzlich stehen Modell, Mäher-UUID/MAC, Protokoll, Mäher-Firmware, Verbindungsart, Signalstärke, Sperre, Ladezustand, Akkutemperatur/-spannung/-zyklen, Messer- und Gesamtlaufzeit, Strecke, Neigung/Roll/Ausrichtung, aktuelle Zone, Drehmoment, Schnitthöhe, ACS-, Off-Limits-, Zeitplan-, Auto-Schedule- und Firmware-Auto-Status zur Verfügung.

Komplexe Strukturen werden verlustarm über CapabilitiesJson, ScheduleStatusJson, AutoScheduleJson, ZonesJson, ModulesJson, StatisticsJson und MowerFirmwareJson ausgegeben.

Positionen werden modellabhängig aus dat.modules.4G.gps.coo oder dat.rtk.pos gelesen. Viele klassische Landroid-Modelle besitzen kein GPS und liefern deshalb keine Position.

Positionen werden modellabhängig aus dat.modules.4G.gps.coo oder dat.rtk.pos gelesen. Viele klassische Landroid-Modelle besitzen kein GPS und liefern deshalb keine Position.

Positionen werden modellabhängig aus dat.modules.4G.gps.coo oder dat.rtk.pos gelesen. Viele klassische Landroid-Modelle besitzen kein GPS und liefern deshalb keine Position.

Positionen werden modellabhängig aus dat.modules.4G.gps.coo oder dat.rtk.pos gelesen. Viele klassische Landroid-Modelle besitzen kein GPS und liefern deshalb keine Position.

Fahr- und Fehlerzustände ab Version 0.5.1

Ausgang Bedeutung
StatusText Klartext wie Mäht, Fährt zur Ladestation oder Pause.
ErrorText Fehlerursache wie Angehoben oder Außerhalb Begrenzungsdraht.
IsMoving Bekannter Fahr-, Mäh-, Such-, Zonen-, Kanten- oder Erkundungszustand.
IsMowing Mähzustand 7 oder 8.
IsGoingHome Sucht oder fährt zur Ladestation.
IsDocked Mäher steht in der Ladestation.
IsPaused Mäher meldet Pause.
HasError ErrorCode ist nicht null.
IsLifted Mäher wurde angehoben.
IsTrapped Mäher ist festgefahren oder meldet entsprechenden Timeout.
IsOutsideBoundary Mäher befindet sich außerhalb des Begrenzungsdrahts.
WireMissing Begrenzungsdraht wird nicht erkannt.
BladeBlocked Messer oder Messermotor ist blockiert.
WheelBlocked Radmotor ist blockiert.
IsUpsideDown Mäher liegt auf dem Kopf.
BatteryLow Akku ist zu schwach.
IsLockedError Betrieb wird durch Sperre verhindert.
ExcessiveSlope Zulässige Steigung überschritten.
ZoneUnreachable Zielzone ist nicht erreichbar.
ChargingStationUnreachable Ladestation ist nicht erreichbar.
DigitalFenceEscape Digitaler Zaun wurde verlassen.
CameraError Vision-Kamerafehler.
MapError Kartenfehler bei Vision/RTK.

Beispiel: IsMoving=0, HasError=1, IsLifted=1 und ErrorText=Angehoben bedeutet, dass der Mäher wegen des Hebesensors nicht fährt.

Praxisbeispiele

Typen, Pflichtangaben und vorgeschlagene KNX-Adressen

Die folgende Zuordnung gilt für jeden Port des Bausteins. Pflicht bedeutet, dass der Baustein ohne den Wert nicht sinnvoll arbeiten kann; optional bedeutet, dass der Port leer bzw. unverdrahtet bleiben darf. Die Gruppenadressen sind Vorschläge und können im Projekt angepasst werden.

Portgruppe Ports Typ Pflicht KNX-DPT Adressbereich (Vorschlag)
Parameter Konto Email, Password Text/String Pflicht kein KNX-DPT (Parameter) keine GA
Parameter Auswahl SerialNumber Text/String optional* kein KNX-DPT (Parameter) keine GA
Parameter Auswahl DeviceIndex, PollIntervalSeconds Ganzzahl optional kein KNX-DPT (Parameter) keine GA
Parameter Lizenz ActivationCode, LicenseSerialNumber, OfflineToken, OfflineProfile, ReleaseChannel Text/String optional** kein KNX-DPT (Parameter) keine GA
Basis-Trigger Refresh, Start, Pause, Home, SetRainDelay Bool/Impuls Refresh Pflicht, übrige optional 1.001 10/0/1–10/0/5
Regenverzögerung RainDelayMinutes Ganzzahl optional 7.001 10/1/1
Experten-Trigger SendCommand, SendRawCommand, ExecuteRest Bool/Impuls optional 1.001 10/0/10–10/0/12
Experten-Daten CommandCode, RestTarget, RestMethod Ganzzahl optional 7.001 10/1/10–10/1/12
Experten-Daten RawCommandJson, RestSuffix, RestBodyJson Text/String optional 16.001 10/2/10–10/2/12
Erweiterte Bool-Eingänge LockEnabled, SetLock, PartyModeEnabled, SetPartyMode, AcsEnabled, SetAcs, OffLimitsEnabled, SetOffLimits, OffLimitsShortcutEnabled, SetOffLimitsShortcut, ScheduleEnabled, SetScheduleEnabled, OneTimeBoundary, StartOneTimeSchedule, StartEdgeCut, AutoScheduleEnabled, SetAutoScheduleEnabled, FirmwareAutoUpgradeEnabled, SetFirmwareAutoUpgrade, ApplyLawn, ApplyProductItemPatch, GetMowerFirmwareInfo, StartMowerFirmwareUpgrade, ResetBatteryCounter, ResetBladeCounter Bool optional 1.001 10/0/20–10/0/45
Erweiterte Zahlen-Eingänge TorquePercent, CuttingHeightMm, Zone, OneTimeRuntimeMinutes, LawnSize, LawnPerimeter Ganzzahl optional 7.001 10/1/20–10/1/25
Erweiterte Text-/JSON-Eingänge ScheduleJson, ProductItemPatchJson Text/String optional 16.001 10/2/20–10/2/21
Ausgangsgruppe Ports Typ Pflicht KNX-DPT Adressbereich (Vorschlag)
Ergebnis/Identität Success, Online Bool Ausgang immer vorhanden 1.001 10/3/1–10/3/2
Status/Fehler StatusCode, ErrorCode, Protocol, SignalStrength, CurrentZone, CurrentTorquePercent, CurrentCuttingHeightMm, RainDelayConfiguredMinutes, RainDelayRemainingMinutes, BatteryChargeCycles, BladeRuntimeMinutes, TotalRuntimeMinutes Ganzzahl Ausgang immer vorhanden 7.001 10/4/1–10/4/12
Messwerte BatteryPercent, BatteryTemperature, BatteryVoltage, DistanceMeters, Pitch, Roll, Yaw, Latitude, Longitude Gleitkomma Ausgang immer vorhanden 9.001 10/5/1–10/5/9
Zustands-Bools IsMoving, IsMowing, IsGoingHome, IsDocked, IsPaused, HasError, IsLifted, IsTrapped, IsOutsideBoundary, WireMissing, BladeBlocked, WheelBlocked, IsUpsideDown, BatteryLow, IsLockedError, ExcessiveSlope, ZoneUnreachable, ChargingStationUnreachable, DigitalFenceEscape, CameraError, MapError, Locked, Charging, AcsAvailable, AcsActive, OffLimitsAvailable, OffLimitsActive, OffLimitsShortcutActive, ScheduleActive, AutoScheduleActive, FirmwareAutoUpgradeActive, RainDelayActive, UpdateAvailable Bool Ausgang immer vorhanden 1.001 10/3/10–10/3/41
Textausgänge Name, Serial, StatusText, ErrorText, LastUpdate, Diagnostics, LicenseStatus, LicenseOwner, LatestVersion, DownloadUrl, OfflineExpiresAt, Model, MowerUuid, MowerMacAddress, MowerFirmwareVersion, ConnectionType Text/String Ausgang immer vorhanden 16.001 10/6/1–10/6/16
JSON-Ausgänge RawJson, ApiResponse, CapabilitiesJson, ScheduleStatusJson, AutoScheduleJson, ZonesJson, ModulesJson, StatisticsJson, MowerFirmwareJson Text/String optional sichtbar 16.001 10/7/1–10/7/9

* SerialNumber ist bei nur einem Mäher optional; bei mehreren Geräten sollte sie gesetzt werden. DeviceIndex wird nur verwendet, wenn SerialNumber leer ist. ** Mindestens eine gültige Online- oder Offline-Lizenzkonfiguration muss vorhanden sein; welche Parameter benötigt werden, hängt vom Lizenzweg ab. Bool-Impulse werden als 0 → 1 → 0 verdrahtet. KNX-DPT 16.001 ist für Diagnose-/JSON-Text nur eine Übergabeempfehlung; sehr lange JSON-Werte sollten nicht direkt als KNX-Text übertragen werden.

Statusabfrage

Parameter: Email, Password und SerialNumber gesetzt
Refresh = Impuls 0 → 1 → 0

Success        = 1
Name           = Landroid Garten
Serial         = 20231234567890123456
StatusCode     = 1
ErrorCode      = 0
BatteryPercent = 78
Online         = 1
LastUpdate     = 2026-07-14T10:42:18.000Z
Diagnostics    = OK

Firmwareinformationen lesen

RestTarget   = 0
RestMethod   = 0
RestSuffix   = firmware-upgrade
RestBodyJson = {}
ExecuteRest  = Impuls 0 → 1 → 0

Ergebnis:
Success      = 1
Diagnostics  = REST-Aufruf erfolgreich
ApiResponse  = <Firmwareantwort von WORX>

Lizenzaktivierung

ActivationCode, LicenseSerialNumber und – falls vereinbart – OfflineToken/OfflineProfile in die gleichnamigen Parameter kopieren. Beim Start prüft der Baustein die Lizenz. Die Online-Lizenz wird alle drei Stunden aktualisiert; für aktive Sitzungen wird alle acht Minuten ein Heartbeat gesendet. Details stehen in WORX_KUNDENANLEITUNG_LIZENZDATEN.md.

Sicherheit

Arbeitsbereich räumen, Personen und Tiere fernhalten und den Mäher bei ersten Tests beaufsichtigen. Zuerst Refresh, danach Pause oder Home testen; erst anschließend Start. Experten-, Firmware- und Zählerfunktionen nur durch den Administrator freischalten.

Fehlerbehebung

Meldung/Situation Maßnahme
Keine gueltige Lizenz. ActivationCode, X1/L1-MAC-Zuordnung und LicenseStatus prüfen.
Anmeldung fehlgeschlagen WORX-E-Mail und Kennwort prüfen; Anmeldung in der WORX-App testen.
Seriennummer nicht gefunden Mäher-SerialNumber prüfen oder leer lassen und DeviceIndex=0 testen.
Mäher offline WLAN- und Cloud-Verbindung des Mähers prüfen.
HTTP 429 Abfrageintervall vergrößern und einige Minuten warten.
cURL konnte nicht gestartet werden X1/L1-Firmware und Paketinstallation durch den Administrator prüfen.
Befehl angenommen, aber keine Bewegung WORX-App auf Sperre, Fehler, Regenpause oder Sicherheitszustand prüfen.

Empfohlenes Statusintervall: 60 bis 300 Sekunden.

Kommentieren Sie den Artikel

Bitte geben Sie Ihren Kommentar ein!
Bitte geben Sie hier Ihren Namen ein

Antimanual

Ask our AI support assistant your questions about our platform, features, and services.

You are offline
Chatbot Avatar
What can I help you with?
WeCreativez WhatsApp Support
Unser Team ist hier, um auf Deine Fragen zu antworten! Gebe Deine Telefon Nr. inkl. Landesvorwahl ohne + ein. Beispiel: 49152999999
👋 Hi, wie können wir helfen?