Developers
Connect your own software to the nomos system Controller
This handbook shows how to connect your own software to the nomos system Controller: how to connect and log in, how to read values and switch devices, and how the data is structured. Every example has been run against a real controller.
The complete reference of every call, event and field is on apidocs.nomos-system.com. This handbook explains how things fit together and links there for the details.
Which interface for what
| You want to … | Interface | More |
|---|---|---|
| stay connected, switch devices and learn about changes as they happen | Socket.io | Connect and Authenticate, Quickstart |
| send single calls from a script or from a system without Socket.io | HTTP | HTTP API |
| exchange values with a system that speaks MQTT | MQTT | MQTT |
| have an address of your own called whenever a value changes | Webhook | Webhooks |
| let an AI assistant access the controller | MCP | MCP |
| build flows graphically on the controller | Node-RED | Node-RED |
Socket.io and HTTP offer the same calls. The difference: over Socket.io the controller reports changes on its own, over HTTP it only answers requests.
Before you start
- Your program reaches the controller on the local network. You find its address in the configuration interface or in your router.
- Create a separate user for your integration, with only the permissions it needs. The reasons are under Permissions.
- The JavaScript examples need Node.js 18 or later, the HTTP examples curl.
Contents
- Connect and Authenticate: addresses and ports, the login sequence, sessions, HTTPS, permissions, lockout after failed attempts, remote access
- Quickstart: a complete example in JavaScript and with curl
- Data Model: components, properties and values, rooms, zones, scenes, variables
- HTTP API: calls, authentication, responses and error codes
- MQTT: topics, following and setting values, running scenes, security
- Webhooks: have an address of your own called when values change
- MCP: the MCP endpoint, token permissions, clients and the nomos MCP Bridge
- Node-RED: the plugin, its nodes, blocked functions, an example flow
- Changes and Compatibility: what changed for integrations since version 2.8
Further sources
- API reference with every call and event
- Node-RED plugin on GitHub
- Integrator handbook for everything set up in the configuration interface