Node-RED

Flows with the Node-RED plugin node-red-contrib-nomos

Every controller comes with Node-RED and the plugin node-red-contrib-nomos preinstalled. The plugin provides nodes for components, scenes and automations, and one for every API call. How to open Node-RED on the controller and who may log in is described in Node-RED in the integrator handbook.

Versions

• Since version 3.1.0 the controller runs Node-RED 5.0.7. Node-RED shows the installed version of the plugin under "Manage palette".
• From plugin version 1.5.3 on, the plugin needs a controller running version 2.8.2 or later.
• The current version of the plugin is listed on npm.

Connecting to the controller

All nodes work through a configuration node of the type nomos-hub. On the controller it already exists and points to the controller itself (127.0.0.1, port 80).

You can also install the plugin into a Node-RED of your own, for instance on a server next to the controller:

cd ~/.node-red
npm install node-red-contrib-nomos

In the nomos-hub you then enter the controller's address and port as well as user name and password of a nomos account. The plugin connects via Socket.io over HTTP, not HTTPS; only run it within your own network. The flows work with the permissions of that account. Create a dedicated user with as few permissions as possible for it, see Recommendation.

Nodes

Components: Frequent properties have nodes of their own, such as state, level, position or setpoint; the component node reaches every property of every component. A component node has one input and three outputs:

	Content of msg.payload
Input	value to set, for example true
Output 1	true if setting the value failed, otherwise false
Output 2	every change as an object with cid, property, value and content
Output 3	the new value only

Other objects: The nodes scene, event, timer and notificationprofile trigger scenes, automations, timers and notification profiles, or react to them.

API: Every API call has a node of its own, generated from the same description as the API reference. The parameters go into msg.payload as an object. Output 1 returns the answer, output 2 an error with errorCode and errorText.

Blocked functions

A flow runs unattended and often with far-reaching permissions. Some calls are therefore deliberately not available as nodes:

• logging in and the own account, such as auth, logout or setOwnUserPassword
• tokens and credentials, such as the MCP tokens or keys and accesses of integrations
• creating, changing or removing users and permissions
• remote access, VPN, cloud and port forwarding
• the state of the system: restart, software update, reset, network, restoring a backup
• pairing other controllers and reaching into them
• commissioning KNX devices and setting up gateways that use up one-time accesses
• progress messages that only serve the configuration interface

If you need one of these calls, use the Socket.io or HTTP API with a suitable account.

Example flow

The flow switches a device on and off at the press of a button and shows every new state in the debug panel. A second branch asks the controller for its version.

[
  {"id":"a1","type":"inject","name":"On","props":[{"p":"payload"}],"payload":"true","payloadType":"bool","wires":[["a3"]]},
  {"id":"a2","type":"inject","name":"Off","props":[{"p":"payload"}],"payload":"false","payloadType":"bool","wires":[["a3"]]},
  {"id":"a3","type":"nomos-state","config":"","cid":"","name":"","topic":"","filter":false,"wires":[["a4"],[],["a5"]]},
  {"id":"a4","type":"debug","name":"Control error","active":true,"complete":"payload","wires":[]},
  {"id":"a5","type":"debug","name":"State","active":true,"complete":"payload","wires":[]},
  {"id":"b1","type":"inject","name":"","props":[{"p":"payload"}],"payload":"","payloadType":"date","wires":[["b2"]]},
  {"id":"b2","type":"nomosapi-getversion","config":"","name":"","topic":"","filter":false,"wires":[["b3"],["b3"]]},
  {"id":"b3","type":"debug","name":"getVersion","active":true,"complete":"payload","wires":[]}
]

Import the flow through "Import" in the menu. Then select the controller in the State node and in the getVersion node, select the component in the State node, and click "Deploy".

Clicking "On" and then "Off" shows in the debug panel:

Control error: false
State: true
Control error: false
State: false

Clicking the third inject node returns the version:

getVersion: { api: "0.3.41", ncd: "1.15", engine: "1.2.2" }