Data Model

Components, properties, values, rooms, zones, scenes and variables in the nomos system Controller API

This page explains the terms the API works with. The complete fields of every answer are on apidocs.

Component and CID

A component is what can be controlled or read on a device: a switch output, a dimmer, a temperature sensor. A device can have several components. Device and component in the integrator handbook explains the difference. The API only knows components.

Every component has a CID, such as C5. Every call that concerns a component addresses it by its CID. The CID stays the same as long as the component exists. If you remove a device and add it again, its components get new CIDs.

The most important fields of a component from getAllComponents:

Field	Content
cid	the CID
name	the name as shown in the app
category, type	kind of component, such as Lighting and Lightbulb
manufacturer, model, platform	manufacturer, model and connection, such as MQTT
rooms	IDs of the rooms the component is assigned to
properties	what can be set (see below)
mappings	what the component reports (see below)
data	the current values (see below)

Besides the components of your devices, getAllComponents also returns components of the controller itself, for example for the weather (openweather_…) or internal automation building blocks (native_…). Components whose CID starts with native_ can only be switched by an admin.

Finding CIDs

• In the configuration interface: Open the device. The address of the device page ends with the CID, such as #/device/C5.
• Through the API: getAllComponents returns every component with cid, name and rooms. Pick the right one by name and room. Store the CID in your integration, not the name, because names can change.

Properties and values

Every component describes its capabilities in three fields. A shortened 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 are the properties you can set with componentUpdate, with data type and, where they exist, limits (min, max).
• mappings are the values the component reports.
• data holds the current values, each entry with property, value, content, lastUpdate and, where applicable, unit.

value and content

• value is the value in its proper data type, such as true, 21 or 0.5. Calculate and compare with value.
• content is the value for display, for values with a unit something like "21 °C", otherwise often the raw value. Do not parse content.
• unit is the unit for display.

The controller returns temperatures, pressure, speeds and lengths in the units chosen in the system settings, such as °C or °F. getSystemUnits tells you which ones.

Common properties

Which properties a component has depends on the device. Read them from properties. Common ones are:

Property	Meaning	Example for componentUpdate
state	on/off	{"cid": "C5", "property": "state", "value": true}
level	brightness in percent	{"cid": "C6", "property": "level", "value": 50}
position	position of a blind in percent	{"cid": "C9", "property": "position", "value": 100}
setpoint	target temperature	{"cid": "C8", "property": "setpoint", "value": 21.5}

Numbers can be changed relatively: "value": "+=10" raises by 10, "value": "-=10" lowers by 10.

componentUpdate can also switch all components of a room or zone at once, optionally filtered by category or type, for example {"room": 17, "property": "state", "value": false, "filterCategory": "Lighting"}. The variants are on apidocs.

Changes

When a value changes, the controller reports it over Socket.io as onComponentUpdate: a list of entries with cid, property, value, content and, where applicable, unit. There are no events over HTTP; there you query single values with getComponentData.

When not a value but the component itself changes, such as its name or its room assignment, the controller sends events of their own, such as onComponentNameChange or onComponentAttached.

Rooms and zones

• Rooms come from getRooms, each with id and name. A component lists its rooms in the field rooms.
• Zones group rooms, for example by floor. In the API they are called floors: getFloors returns them, and the field floor of a room lists the zones it belongs to.

A user only sees the rooms they are permitted to see, see Permissions.

Scenes

A scene sets several components at once. getScenes returns the scenes the user may see, each with id and name. executeScene with the id executes a scene.

Variables

Variables store values for automations, see Variables in the integrator handbook. In the API they are called system variables: getSystemVariables returns them with id, name, type and currentValue, setSystemVariable changes them, and onSystemVariableUpdated reports changes.

Only an admin may use the calls for variables.