Node-RED Integration

Accessing Node-RED #

HyperVisu includes a powerful Node-RED integration that allows you to create custom automations and integrate with external systems. Node-RED is a flow-based programming tool that makes it easy to connect hardware devices, APIs, and online services without extensive coding knowledge.

To access the Node-RED application:

Navigate to the HyperVisu administration interface by typing your server’s IP address in a web browser
Log in with your administration credentials (username and password)
Click on the “Node-RED” button in the server administration page
A new browser tab will open with the Node-RED login page
Use the same username and password as the HyperVisu administration interface to access Node-RED

Note: The Node-RED environment runs on the same hardware as your HyperVisu server, so all integrations are local and don’t require external cloud services.

Using HyperVisu Nodes #

HyperVisu extends Node-RED by adding custom nodes that represent each type of widget in your home automation system. These nodes allow you to interact with your KNX devices directly from Node-RED.

Node Structure #

The HyperVisu Node-RED integration revolves around a main “HyperVisu” node that manages the connection with the server and provides access to all widgets, rooms, and categories. This core node establishes and maintains:

Communication with the server
Real-time updates of widget values

Additional custom nodes represent each widget type available in HyperVisu:

Pushbutton – For pushbuttons with optional status feedback
Light Switch – For ON/OFF switches specifically for lighting
Switch ON/OFF – For general ON/OFF switches (power outlets, etc.)
Analog Output – For sending analog values within a predefined range
Shutter/Blind – For controlling shutters and blinds
Temperature Controller – For heating/cooling control
Dimmer – For standard lighting dimmers
RGB Dimmer – For controlling RGB(W) lights
Tunable White Dimmer – For adjusting color temperature of white lights
Analog Input – For displaying analog values with optional trending
Digital Input – For displaying digital status values

Global command nodes are also available:

Global Lights – For controlling all lights in a room or category
Global Shutters – For controlling all shutters in a room or category
Scenario – For triggering predefined scenarios

Each node displays its name and associated room or category inside the node for easy identification.

Inputs and Outputs #

Widget nodes typically have multiple inputs and outputs that correspond to the widget’s functions. For example:

Dimmer Node:

Inputs: Toggle, On, Off, Setpoint (dimming value)
Outputs: State (on/off status), Value (brightness level), On command, Off command

Shutter/Blind Node:

Inputs: Up, Down, Stop, Blind Setpoint, Slat Setpoint
Outputs: Moving Up, Moving Down, Blind Position, Slat Position, Up, Down, Stop

When a node receives or sends data:

The message payload contains the value of the output or input
A topic field contains the widget object ID
A widget field contains the widget ID

These standardized formats make it easy to process messages between nodes and build complex automations.

Building Flows #

Node-RED uses a visual programming approach where you connect nodes together to create “flows” of data.

Connecting Nodes #

To build a flow in the Node-RED editor:

Find the HyperVisu nodes in the node palette on the left side
Drag the desired node type onto the flow
Connect nodes by dragging lines between the output of one node to the input of another
Nodes process messages sequentially as they flow through the connections

Basic flow patterns include:

Trigger flows: A trigger node (like an input or time event) causes an action through an output node
Transformation flows: Data passes through function nodes that modify values before they reach output nodes
Decision flows: Switch nodes route messages differently based on received values
Integration flows: Nodes from different systems (MQTT, HTTP, etc.) connect to exchange data

Configuring Nodes #

Each HyperVisu node must be configured to connect to a specific widget in your system:

Double-click a node to open its configuration panel
Use the dropdown menu to select the widget it should connect to
Filter options by room, category, and widget type to find the right widget
The list shows all widgets with the same type available from your HyperVisu configuration
Enable/disable MQTT broker publishing if needed (sends widget values to the built-in MQTT broker)
Click Done to save the configuration

For virtual widgets, you can send values directly from Node-RED to update the widget’s state, allowing you to integrate sensors or systems that aren’t directly connected to your KNX bus.

Deploying Flows #

After building and configuring your flows:

Click the Deploy button in the top-right corner of the Node-RED interface
Wait for the confirmation message that indicates successful deployment
Your flows are now active and will begin processing data

The Node-RED environment saves your flows automatically, and they will restart when the HyperVisu server is rebooted.

You can view the flow status in real-time:

Active connections show status indicators with values
Errors appear in the debug panel (accessed via the right sidebar)
Data can be traced using debug nodes placed in the flow

Advanced Features #

Global Commands Integration #

Global commands allow you to control multiple devices simultaneously:

Add a Global Lights or Global Shutters node to your flow
Configure it to target a specific room or category
Send an “On” or “Off” message to the node’s input to control all lights in that room
For shutters, send “Up” or “Down” to control all blinds/shutters

This is particularly useful for creating scenes or time-based controls that affect multiple devices.

Scenario Triggering #

HyperVisu scenarios (predefined groups of device states) can be triggered directly from Node-RED:

Add a Scenario node to your flow
Configure it to select the specific scenario from the available scenarios list
Connect any trigger node to its input
When triggered, the scenario will execute as if activated from the mobile app

This allows you to create complex triggers for your scenarios based on time, external events, or sensor data.

IoT Device Integration #

A major advantage of Node-RED integration is connecting non-KNX IoT devices to your HyperVisu system:

Integrating External Sensors:

Create a virtual widget in HyperVisu
Add the corresponding Node-RED node (like Analog Input)
Connect an external data source (MQTT, HTTP, etc.) to this node
When data arrives, it updates the virtual widget and appears in the HyperVisu app

Controlling External Devices:

Create a virtual output widget in HyperVisu
Add the corresponding Node-RED node (like Switch)
Connect the output to a node that controls your external device (HTTP request, MQTT publish, etc.)
When you control the virtual widget in HyperVisu, it triggers the external action

The built-in MQTT broker can be enabled for any widget, broadcasting its state changes on topics that match the widget object ID. This makes it easy to have other MQTT-capable devices respond to events in your home.

Integration Examples:

Connect weather APIs to display outdoor conditions on virtual widgets
Control smart devices that use different protocols (Zigbee, Z-Wave, WiFi)
Record energy consumption data from smart meters into InfluxDB
Build custom logic for advanced automations based on multiple conditions

By leveraging this Node-RED integration, you can extend HyperVisu beyond its native KNX capabilities to create a truly comprehensive smart home solution that integrates all your systems.

Gateways for Inverters

Gateways for Alarm Systems

Universal KNX Actuator System

Elaupro

HyperVisu

Node-RED Integration

Accessing Node-RED #