Erste Schritte

Erste Schritte mit der API des nomos system Controllers, in JavaScript und mit curl

Dieses Beispiel meldet sich am Controller an, liest alle Komponenten, schaltet eine Komponente ein und wieder aus, verfolgt die Änderung mit und führt eine Szene aus. Zuerst in JavaScript über Socket.io, danach dieselben Schritte mit curl über HTTP.

Alle Aufrufe im Beispiel darf auch ein normaler Benutzer verwenden (siehe Rechte).

Was Sie brauchen

• die Adresse des Controllers im lokalen Netz, hier <controller-ip>
• einen Benutzer, hier USERNAME und PASSWORD
• die CID einer Komponente, die sich gefahrlos schalten lässt, etwa einer Leuchte. Wie Sie die CID finden, steht unter Datenmodell. Das Beispiel verwendet C5.
• optional die ID einer Szene, die Sie ausführen möchten

JavaScript (Socket.io)

Sie brauchen Node.js 18 oder neuer und socket.io-client ab Version 4.6:

mkdir nomos-quickstart && cd nomos-quickstart
npm init -y
npm install socket.io-client@4

Speichern Sie das Programm als quickstart.js:

// quickstart.js - Node.js 18 or later, npm install socket.io-client@4
const { io } = require('socket.io-client');

const HOST = process.env.NOMOS_HOST;          // address of the controller, e.g. 192.168.1.10
const USERNAME = process.env.NOMOS_USER;
const PASSWORD = process.env.NOMOS_PASSWORD;
const CID = process.env.NOMOS_CID;            // component to switch, e.g. C5
const SCENE_ID = process.env.NOMOS_SCENE;     // optional: scene to execute

const socket = io(`http://${HOST}/api/v1`, { path: '/socket.io-v4' });

// Sends an event and waits for the controller's answer
const call = (event, params = {}) => socket.timeout(15000).emitWithAck(event, params);
const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// Live values: an array of {cid, property, value, content, unit}
socket.on('onComponentUpdate', (updates) => {
    for (const update of updates) {
        if (update.cid === CID) console.log('onComponentUpdate:', update);
    }
});

// The controller asks for a login on every new connection. Only then is auth accepted.
socket.on('stateChange', async (state) => {
    if (state.part !== 'app' || state.state !== 'User Authorization needed') return;
    try {
        // 1. Log in, then initialise the connection
        const auth = await call('auth', { username: USERNAME, password: PASSWORD });
        if (auth.errorCode) throw new Error(`auth: ${auth.errorCode} ${auth.errorText}`);
        await call('init', { language: 'en', appName: 'quickstart' });

        // 2. Read all components
        const components = await call('getAllComponents', { withProperties: false, withMappings: false });
        for (const c of components) console.log(c.cid, c.name, c.category);

        // 3. Switch a component on and off again
        console.log('on:', await call('componentUpdate', { cid: CID, property: 'state', value: true }));
        await sleep(3000);
        console.log('off:', await call('componentUpdate', { cid: CID, property: 'state', value: false }));
        await sleep(3000);

        // 4. Execute a scene
        if (SCENE_ID) console.log('scene:', await call('executeScene', { id: Number(SCENE_ID) }));
    } catch (err) {
        console.error(err.message);
    } finally {
        socket.close();
    }
});

socket.on('connect_error', (err) => console.error('connect_error:', err.message));

Starten Sie es mit Ihren Angaben:

NOMOS_HOST=<controller-ip> NOMOS_USER=USERNAME NOMOS_PASSWORD=PASSWORD NOMOS_CID=C5 node quickstart.js

Die Ausgabe sieht etwa so aus (gekürzt):

native_scene Scenes Automation
...
C5 Switch Switches
C6 Dimmer Lighting
C7 Temperatur Sensors
...
on: { C5: true }
onComponentUpdate: { cid: 'C5', property: 'state', content: 1, value: true }
off: { C5: true }
onComponentUpdate: { cid: 'C5', property: 'state', content: 0, value: false }

Die Schritte im Einzelnen

1. Anmelden: Auf stateChange mit User Authorization needed folgen auth und init. Warum das Programm auf stateChange wartet, steht unter Verbinden und Anmelden.
2. Komponenten lesen: getAllComponents liefert alle Komponenten, die der Benutzer sehen darf. Mit withProperties: false und withMappings: false enthält die Antwort nur Stammdaten und aktuelle Werte, ohne die Beschreibung der Properties. Den Aufbau einer Komponente erklärt das Datenmodell.
3. Schalten: componentUpdate setzt eine Property. Die Antwort enthält je CID true, wenn der Controller den Befehl angenommen hat, und false, wenn nicht, etwa bei einer unbekannten CID oder fehlender Berechtigung. true heißt noch nicht, dass das Gerät geschaltet hat.
4. Änderungen mitlesen: Was das Gerät tatsächlich meldet, kommt als onComponentUpdate. Das Event enthält eine Liste von Änderungen und kommt für alle Komponenten, die der Benutzer sehen darf. Das Programm filtert deshalb nach der CID.
5. Szene ausführen: executeScene mit der ID aus getScenes. Die Antwort true kommt erst, wenn die Szene vollständig abgelaufen ist. Bei einer unbekannten ID antwortet der Controller mit {errorCode: 112, errorText: 'Not found'}. Fehler 116 (Timeout) heißt, dass die Bestätigung ausblieb, nicht dass die Szene nicht gestartet wurde.

Jeder Aufruf antwortet bei einem Fehler mit errorCode und errorText. Entscheiden Sie im Code anhand von errorCode; errorText ist für Menschen gedacht und in der Sprache aus init übersetzt. Die Liste der Fehlercodes steht auf apidocs.

HTTP (curl)

Über HTTP stehen dieselben Aufrufe zur Verfügung, nur ohne Events. Alle Einzelheiten stehen unter HTTP-API.

1. Anmelden und Sitzungs-ID holen

curl -s -X POST -H "auth-username: USERNAME" -H "auth-password: PASSWORD" \
  http://<controller-ip>/api/v1/auth

{"sessionID":"<session-id>","userID":<user-id>}

userID ist die ID Ihres Benutzers. Die weiteren Aufrufe verwenden die Sitzungs-ID im Header x-nomos-sid.

2. Komponenten lesen

curl -s -X POST -H "x-nomos-sid: <session-id>" -H "content-type: application/json" \
  -d '{"withProperties":false,"withMappings":false}' \
  http://<controller-ip>/api/v1/getAllComponents

[ ...,
  {"cid":"C5","name":"Switch","category":"Switches","type":"Switch",
   "data":[{"value":false,"content":0,"lastUpdate":"2026-10-08T12:48:28.130Z","property":"state"}, ...],
   "rooms":[17], ...},
  ... ]

3. Schalten

curl -s -X POST -H "x-nomos-sid: <session-id>" -H "content-type: application/json" \
  -d '{"cid":"C5","property":"state","value":true}' \
  http://<controller-ip>/api/v1/componentUpdate

{"C5":true}

4. Wert abfragen

Ohne Events fragen Sie den Wert mit getComponentData ab:

curl -s -X POST -H "x-nomos-sid: <session-id>" -H "content-type: application/json" \
  -d '{"cid":"C5","property":"state"}' \
  http://<controller-ip>/api/v1/getComponentData

{"value":true,"content":1,"lastUpdate":"2026-10-08T12:49:05.877Z"}

Danach schalten Sie mit "value":false wieder aus.

5. Szene ausführen

curl -s -X POST -H "x-nomos-sid: <session-id>" -H "content-type: application/json" \
  -d '{"id":4}' \
  http://<controller-ip>/api/v1/executeScene

Die Antwort ist true, sobald die Szene abgelaufen ist.

6. Abmelden

curl -s -X POST -H "x-nomos-sid: <session-id>" http://<controller-ip>/api/v1/logout

true

Danach ist die Sitzungs-ID ungültig.

Wie es weitergeht

• Verbinden und Anmelden: HTTPS, Sitzungen und Rechte
• Datenmodell: was in einer Komponente steht und welche Properties es gibt
• API-Referenz: alle Aufrufe und Events