Datenmodell

Komponenten, Properties, Werte, Räume, Bereiche, Szenen und Variablen in der API des nomos system Controllers

Diese Seite erklärt die Begriffe, mit denen die API arbeitet. Die vollständigen Felder jeder Antwort stehen auf apidocs.

Komponente und CID

Eine Komponente ist das, was an einem Gerät steuerbar oder ablesbar ist: ein Schaltausgang, ein Dimmer, ein Temperatursensor. Ein Gerät kann mehrere Komponenten haben. Den Unterschied erklärt Gerät und Komponente im Integratoren-Handbuch. Die API kennt nur Komponenten.

Jede Komponente hat eine CID, etwa C5. Alle Aufrufe, die eine Komponente betreffen, adressieren sie über die CID. Die CID bleibt gleich, solange die Komponente besteht. Entfernen Sie ein Gerät und binden es neu ein, bekommen seine Komponenten neue CIDs.

Die wichtigsten Felder einer Komponente aus getAllComponents:

Feld	Inhalt
cid	die CID
name	der Name, wie er in der App erscheint
category, type	Art der Komponente, etwa Lighting und Lightbulb
manufacturer, model, platform	Hersteller, Modell und Anbindung, etwa MQTT
rooms	IDs der Räume, denen die Komponente zugeordnet ist
properties	was sich setzen lässt (siehe unten)
mappings	was die Komponente meldet (siehe unten)
data	die aktuellen Werte (siehe unten)

Neben den Komponenten Ihrer Geräte liefert getAllComponents auch Komponenten des Controllers selbst, etwa für das Wetter (openweather_…) oder interne Automationsbausteine (native_…). Komponenten, deren CID mit native_ beginnt, kann nur ein Admin schalten.

CIDs finden

• In der Konfigurationsoberfläche: Öffnen Sie das Gerät. Die Adresse der Geräteseite endet mit der CID, etwa #/device/C5.
• Über die API: getAllComponents liefert alle Komponenten mit cid, name und rooms. Suchen Sie die passende über Name und Raum. Speichern Sie in Ihrer Anbindung die CID, nicht den Namen, denn Namen lassen sich ändern.

Properties und Werte

Jede Komponente beschreibt ihre Möglichkeiten in drei Feldern. Ein gekürzter Dimmer:

{
  "cid": "C6",
  "name": "Dimmer",
  "category": "Lighting",
  "type": "Lightbulb",
  "properties": {
    "state": {"datatype": "bool"},
    "level": {"datatype": "int", "min": 0, "max": 100, "unit": "percent"}
  },
  "mappings": {
    "state": {"datatype": "bool"},
    "reachable": {"datatype": "bool"},
    "level": {"datatype": "int", "min": 0, "max": 100, "unit": "percent"}
  },
  "data": [
    {"property": "state", "value": false, "content": null, "lastUpdate": "2026-04-04T07:44:21.634Z"},
    {"property": "reachable", "value": true, "content": true, "lastUpdate": "2026-04-04T07:44:21.634Z"},
    {"property": "level", "value": 0, "content": 0, "unit": "%", "lastUpdate": "2026-10-08T06:06:39.424Z"}
  ]
}

• properties sind die Properties, die Sie mit componentUpdate setzen können, mit Datentyp und, wo es sie gibt, Grenzen (min, max).
• mappings sind die Werte, die die Komponente meldet.
• data enthält die aktuellen Werte, je Eintrag mit property, value, content, lastUpdate und gegebenenfalls unit.

value und content

• value ist der Wert im richtigen Datentyp, etwa true, 21 oder 0.5. Rechnen und vergleichen Sie mit value.
• content ist der Wert zur Anzeige, bei Werten mit Einheit etwa "21 °C", sonst oft der Rohwert. Werten Sie content nicht aus.
• unit ist die Einheit zur Anzeige.

Temperaturen, Druck, Geschwindigkeiten und Längen liefert der Controller in den Einheiten, die in den Systemeinstellungen gewählt sind, etwa °C oder °F. Welche das sind, liefert getSystemUnits.

Häufige Properties

Welche Properties eine Komponente hat, hängt vom Gerät ab. Lesen Sie sie aus properties. Häufig sind:

Property	Bedeutung	Beispiel für componentUpdate
state	ein/aus	{"cid": "C5", "property": "state", "value": true}
level	Helligkeit in Prozent	{"cid": "C6", "property": "level", "value": 50}
position	Position eines Behangs in Prozent	{"cid": "C9", "property": "position", "value": 100}
setpoint	Solltemperatur	{"cid": "C8", "property": "setpoint", "value": 21.5}

Zahlen lassen sich relativ ändern: "value": "+=10" erhöht um 10, "value": "-=10" senkt um 10.

componentUpdate kann auch alle Komponenten eines Raums oder Bereichs auf einmal schalten, wahlweise gefiltert nach Kategorie oder Typ, etwa {"room": 17, "property": "state", "value": false, "filterCategory": "Lighting"}. Die Varianten stehen auf apidocs.

Änderungen

Ändert sich ein Wert, meldet der Controller ihn über Socket.io als onComponentUpdate: eine Liste von Einträgen mit cid, property, value, content und gegebenenfalls unit. Über HTTP gibt es keine Events; dort fragen Sie einzelne Werte mit getComponentData ab.

Ändert sich nicht ein Wert, sondern die Komponente selbst, etwa ihr Name oder ihre Raumzuordnung, sendet der Controller eigene Events wie onComponentNameChange oder onComponentAttached.

Räume und Bereiche

• Räume liefert getRooms, je Raum mit id und name. Eine Komponente nennt ihre Räume im Feld rooms.
• Bereiche fassen Räume zusammen, etwa Stockwerke. In der API heißen sie Floors: getFloors liefert sie, und das Feld floor eines Raums nennt die Bereiche, zu denen er gehört.

Ein Benutzer sieht nur die Räume, für die er berechtigt ist, siehe Rechte.

Szenen

Eine Szene setzt mehrere Komponenten auf einmal. getScenes liefert die Szenen, die der Benutzer sehen darf, je Szene mit id und name. executeScene mit der id führt eine Szene aus.

Variablen

Variablen speichern Werte für Automationen, siehe Variablen im Integratoren-Handbuch. In der API heißen sie System Variables: getSystemVariables liefert sie mit id, name, type und currentValue, setSystemVariable ändert sie, und onSystemVariableUpdated meldet Änderungen.

Die Aufrufe für Variablen darf nur ein Admin verwenden.