ioBroker JavaScript – Systemfunktionen

Zuletzt aktualisiert: 16. September 2026

Wer in ioBroker eigene JavaScript-Automationen erstellt, stößt schnell auf Funktionen wie getState(), setState(), on() oder schedule(). Damit lassen sich Datenpunkte lesen, Geräte schalten, Änderungen überwachen und zeitgesteuerte Abläufe erstellen.

In dieser Übersicht zeige ich die wichtigsten ioBroker JavaScript-Funktionen anhand kleiner Beispiele. Der Artikel eignet sich damit sowohl als Einstieg als auch als Nachschlagewerk für eigene Skripte.

getState(): Datenpunkt in ioBroker auslesen

Mit getState() lesen wir einen Datenpunkt aus. Die Funktion liefert dabei mehr als nur den eigentlichen Wert.

const state = getState('0_userdata.0.Wohnzimmer.Temperatur');

log(state.val);

Der aktuelle Wert befindet sich in val. Deshalb kann man ihn auch direkt auslesen:

const temperatur = getState('0_userdata.0.Wohnzimmer.Temperatur').val;

log('Temperatur: ' + temperatur);

Neben val enthält ein State unter anderem Informationen darüber, wann er zuletzt aktualisiert oder geändert wurde.

Optional Chaining verwenden

Wenn nicht sicher ist, ob der Datenpunkt existiert, kann modernes JavaScript mit ?. helfen:

const temperatur = getState('0_userdata.0.Wohnzimmer.Temperatur')?.val;

if (temperatur !== undefined) {
    log('Temperatur: ' + temperatur);
}

setState(): Datenpunkt setzen

Mit setState() verändern wir einen vorhandenen Datenpunkt. Damit kann beispielsweise ein Licht eingeschaltet werden.

setState('0_userdata.0.Test.Licht', true);

Auch Zahlen und Texte können gesetzt werden:

setState('0_userdata.0.Test.Helligkeit', 50);

setState('0_userdata.0.Test.Status', 'Automatik aktiv');

Was bedeutet ack bei setState?

Bei ioBroker taucht häufig der Parameter ack auf. Vereinfacht gesagt unterscheidet ioBroker damit zwischen einem neuen Steuerbefehl und einem bereits bestätigten Zustand.

setState('0_userdata.0.Test.Status', true, false);

ack=false bedeutet normalerweise, dass ein neuer Wert beziehungsweise Befehl gesetzt wird. ack=true wird typischerweise verwendet, wenn ein Wert als bestätigter Zustand gespeichert wird.

Bei normalen Geräteaktionen wird der Parameter häufig nicht angegeben. Dann arbeitet setState() standardmäßig als Steuerbefehl.

on(): Auf Änderungen eines Datenpunkts reagieren

Viele Smart-Home-Automationen sollen erst starten, wenn sich ein bestimmter Zustand ändert. Dafür verwenden wir on().

on({
    id: '0_userdata.0.Test.Bewegung',
    change: 'ne'
}, (obj) => {
    log('Neuer Wert: ' + obj.state.val);
});

change: 'ne' bedeutet, dass das Skript nur reagiert, wenn sich der Wert tatsächlich verändert hat.

Der vorherige Wert steht ebenfalls zur Verfügung:

on({
    id: '0_userdata.0.Test.Bewegung',
    change: 'ne'
}, (obj) => {
    log('Alt: ' + obj.oldState.val);
    log('Neu: ' + obj.state.val);
});

Beispiel: Licht bei Bewegung einschalten

Damit lässt sich bereits eine einfache Automation erstellen:

on({
    id: '0_userdata.0.Flur.Bewegung',
    change: 'ne'
}, (obj) => {

    if (obj.state.val === true) {
        setState('0_userdata.0.Flur.Licht', true);
    }

});

Sobald der Bewegungsdatenpunkt auf true wechselt, wird der Licht-Datenpunkt eingeschaltet.

setStateDelayed(): Datenpunkt verzögert setzen

Für viele Automationen ist eine Verzögerung praktisch. Ein Licht soll beispielsweise nach fünf Minuten automatisch wieder ausgeschaltet werden.

setState('0_userdata.0.Flur.Licht', true);

setStateDelayed(
    '0_userdata.0.Flur.Licht',
    false,
    300000
);

Die Zeit wird in Millisekunden angegeben. 300.000 Millisekunden entsprechen fünf Minuten.

Damit können wir unser Bewegungsmelder-Beispiel erweitern:

on({
    id: '0_userdata.0.Flur.Bewegung',
    change: 'ne'
}, (obj) => {

    if (obj.state.val === true) {

        setState('0_userdata.0.Flur.Licht', true);

        setStateDelayed(
            '0_userdata.0.Flur.Licht',
            false,
            300000
        );
    }

});

schedule(): JavaScript nach Zeitplan ausführen

Mit schedule() lassen sich Aktionen zu bestimmten Uhrzeiten oder nach einem Cron-Zeitplan starten.

Dieses Beispiel wird jeden Tag um 22 Uhr ausgeführt:

schedule('0 22 * * *', () => {
    log('Es ist 22 Uhr');
});

Damit können beispielsweise Beleuchtungen ausgeschaltet, Geräte kontrolliert oder tägliche Berechnungen durchgeführt werden.

createState(): eigenen Datenpunkt erstellen

Für eigene Skripte sind Datenpunkte unter 0_userdata.0 praktisch. Sie lassen sich unter anderem mit createState() anlegen.

createState(
    '0_userdata.0.MeineAutomation.Status',
    false,
    {
        name: 'Status meiner Automation',
        type: 'boolean',
        read: true,
        write: true
    }
);

Danach lässt sich dieser Datenpunkt wie jeder andere State mit getState() lesen oder mit setState() verändern.

existsState(): Prüfen, ob ein Datenpunkt existiert

Vor dem Zugriff auf dynamische Datenpunkte kann eine Prüfung sinnvoll sein:

const id = '0_userdata.0.Wohnzimmer.Temperatur';

if (existsState(id)) {
    log('Temperatur: ' + getState(id).val);
} else {
    log('Datenpunkt nicht gefunden', 'warn');
}

Damit vermeidest du unnötige Warnungen im ioBroker-Protokoll.

log(): Meldungen ins ioBroker-Protokoll schreiben

log() gehört für mich zu den wichtigsten Funktionen beim Entwickeln und Testen eines Skripts.

log('Skript wurde gestartet');

Zusätzlich kann ein Log-Level angegeben werden:

log('Normale Information', 'info');

log('Hier stimmt etwas nicht', 'warn');

log('Es ist ein Fehler aufgetreten', 'error');

Beim Aufbau einer Automation würde ich an wichtigen Stellen zunächst zusätzliche Log-Ausgaben einbauen. So lässt sich schnell erkennen, ob ein Trigger überhaupt ausgelöst wird und welche Werte verarbeitet werden.

Async-Funktionen in ioBroker JavaScript

Viele ioBroker-Funktionen stehen inzwischen zusätzlich als asynchrone Variante zur Verfügung. Dazu gehören beispielsweise getStateAsync() und setStateAsync().

const state = await getStateAsync(
    '0_userdata.0.Wohnzimmer.Temperatur'
);

log('Temperatur: ' + state.val);

Beim Schreiben sieht es entsprechend so aus:

await setStateAsync(
    '0_userdata.0.Test.Licht',
    true
);

Async-Funktionen werden vor allem interessant, wenn mehrere Aktionen nacheinander zuverlässig abgearbeitet werden sollen.

getState oder getStateAsync?

Für viele kleine ioBroker-Skripte ist das normale getState() weiterhin die einfachste Lösung.

Bei moderneren Skripten mit mehreren aufeinanderfolgenden Aktionen können die Promise-basierten Async-Funktionen den Ablauf übersichtlicher machen.

Häufige Fehler in ioBroker JavaScript

Falsche Datenpunkt-ID

Die vollständige ID muss exakt stimmen. Am einfachsten kopierst du sie direkt aus der ioBroker-Objektansicht.

.val vergessen

getState() liefert ein Objekt zurück. Wer nur den eigentlichen Wert benötigt, verwendet normalerweise .val.

const wert = getState('0_userdata.0.Test.Wert').val;

Trigger reagiert zu oft

Ohne passende Bedingung kann ein Trigger auch auf Aktualisierungen reagieren, bei denen sich der eigentliche Wert gar nicht geändert hat. Mit change: 'ne' lässt sich das in vielen Fällen verhindern.

Skript läuft nicht

Prüfe zuerst, ob das Skript aktiviert ist und ob im ioBroker-Protokoll Fehler angezeigt werden.

Welche Funktionen sollte ein Einsteiger zuerst lernen?

Für die meisten Automationen reichen am Anfang bereits vier Funktionen:

1. getState() zum Lesen
2. setState() zum Schreiben
3. on() als Trigger
4. log() zur Fehlersuche

Danach würde ich mich mit setStateDelayed(), Zeitplänen und eigenen Datenpunkten beschäftigen.

Blockly oder JavaScript?

Wer gerade mit ioBroker beginnt, kann viele dieser Funktionen zunächst über Blockly kennenlernen. Hinter den grafischen Blöcken stehen letztlich sehr ähnliche Abläufe: Ein Trigger reagiert auf ein Ereignis, Bedingungen werden geprüft und anschließend werden Datenpunkte verändert.

Unsere ausführliche Einführung findest du hier: ioBroker Blockly Anleitung: Blöcke, Beispiele und Funktionen.

Fazit

Mit wenigen ioBroker JavaScript-Funktionen lassen sich bereits viele Smart-Home-Automationen umsetzen. getState() liest Werte, setState() verändert Datenpunkte und on() reagiert auf Änderungen. Mit Zeitplänen, verzögerten Aktionen und eigenen States können daraus schnell umfangreichere Abläufe entstehen.

Gerade beim Einstieg würde ich Automationen klein aufbauen und mit zusätzlichen log()-Ausgaben testen. Sobald der Ablauf zuverlässig funktioniert, können die einzelnen Teile Schritt für Schritt erweitert werden.

Häufige Fragen

Wie lese ich einen ioBroker-Datenpunkt in JavaScript aus?

Mit getState('Datenpunkt-ID').val kannst du den aktuellen Wert eines Datenpunkts auslesen.

Wie setze ich einen Wert in ioBroker?

Mit setState('Datenpunkt-ID', Wert) kann ein vorhandener Datenpunkt verändert werden.

Wie reagiere ich auf eine Änderung?

Dafür wird normalerweise on() verwendet. Über change: 'ne' lässt sich beispielsweise nur auf tatsächliche Wertänderungen reagieren.

Wie schalte ich etwas zeitverzögert?

Mit setStateDelayed() lässt sich ein Datenpunkt nach einer vorgegebenen Zeit verändern.