node-red-contrib-homematic-hcu 1.1.0

Node-RED nodes for access to Homematic HCU

npm install node-red-contrib-homematic-hcu

node-red-contrib-homematic-hcu

Node-RED nodes for connecting to a Homematic IP Home Control Unit (HCU) through the Homematic IP Connect API. No cloud is required.

The package provides a shared WebSocket connection, device and feature lookup, feature change events, HCU system requests, user-message requests, and Connect API authentication.

Development status: This README describes the current implementation. The package should be tested against the target HCU firmware and Node-RED environment before production use.

Note on Code Creation

This is a private Node-RED project that I created in my spare time for non-commercial purposes. Parts of this repository were created using AI-powered development tools and were subsequently reviewed, adapted, and further developed by the repository owner.

Features

• Shared WebSocket connection to the HCU.
• HCU Connect API authentication-token creation and confirmation.
• Support for the Homematic IP HCU WebSocket endpoint on port 9001.
• Optional support for self-signed TLS certificates.
• Automatic reconnect after unexpected connection loss.
• Initial retrieval and caching of the HCU system state.
• Device lookup through the Node-RED editor.
• Reading feature values from the cached system state.
• Event-driven handling of DEVICE_CHANGED events.
• Sending generic HCU system requests.
• Setting device features with request/response correlation.
• Creating and deleting HCU user messages.

Requirements

• Node-RED 4.1.10 or newer (lower versions not tested).
• Node.js 18.0.0 or newer (lower versions not tested).
• A Homematic IP HCU with the required Connect API access and plugin configuration (Enabled Developer Mode and activated Websocket conncection!).
• Network access from the Node-RED host to the HCU.
• A valid HCU authentication token and plugin ID for the WebSocket connection (can be generated by a node in this).

The package currently declares the following runtime dependency:

ws ^8.18.0

Installation

Palette Manager

1. Open the Node-RED menu.
2. Select Manage palette.
3. Open the Install tab.
4. Search for node-red-contrib-homematic-hcu.
5. Install the package.
6. Restart Node-RED if requested.

npm

From the Node-RED user directory:

cd ~/.node-red
npm install node-red-contrib-homematic-hcu

For local development:

cd ~/.node-red
npm install --no-save /path/to/node-red-contrib-homematic-hcu

After installation, restart Node-RED and deploy the flow again.

Package nodes

Node	Purpose	Inputs	Outputs
homematic-hcu-config	Shared HCU WebSocket configuration and connection	Configuration	—
New HCU connection	Creates and confirms a Connect API authentication token	1	1
hcu in	Receives HCU connection events and WebSocket messages	0	1
hcu out	Sends a generic message through the shared WebSocket	1	1
feature event	Emits a message when a configured device feature changes	0	1
get feature value	Reads a feature from the cached system state	1	1
set feature value	Sends a feature-control request and waits for its response	1	1
create user message	Creates a user message on the HCU	1	1
delete user message	Deletes a user message on the HCU	1	1

Configuration

Add one homematic-hcu-config node and use it from the other HCU nodes.

Server address

Enter only the HCU host name or IPv4 address, for example:

192.168.1.20

The WebSocket URL is constructed as:

wss://<serverAddress>:9001

Do not enter the protocol or port in the Server address field.

Plugin ID

Enter the plugin identifier used by the HCU Connect API. It is sent as the plugin-id WebSocket header and is included in outgoing HCU messages.

Auth token

Enter the HCU authentication token. It is stored as a Node-RED credential rather than as a normal flow property.

The connection uses these WebSocket headers:

authtoken: <authToken>
plugin-id: <pluginId>
hmip-system-events: true

Self-signed certificates

Enable Allow self-signed certificates only when the HCU uses a self-signed certificate in a controlled local environment. This disables TLS certificate verification for the WebSocket connection.

For production installations, certificate verification should remain enabled whenever possible.

Connection lifecycle

The configuration node connects automatically when it is created.

After the WebSocket opens, it:

1. Sends a PLUGIN_STATE_RESPONSE with pluginReadinessStatus: READY.
2. Requests the current system state using /hmip/home/getSystemState.
3. Stores the returned system state in a local cache.
4. Broadcasts connection and message events to dependent nodes.

If the connection closes unexpectedly, the node schedules a reconnect after approximately five seconds. The connection is closed without reconnecting when Node-RED deploys or shuts down the node.

New HCU connection

The New HCU connection allows you to generate all the data needed for a WebSocket connection to the HCU. This eliminates the need for additional tools or flows to establish a WebSocket connection. The data can then be used by the Config node.

Configuration

• Plugin identifier: Internal plugin identifier.
• Plugin Name: JSON language map containing at least a non-empty de value.
• Activation key: Key generated by the HCU in Developer Mode.
• Server address: HCU IPv4 address.
• Allow self-signed certificate: Disables TLS certificate verification for these HTTPS requests.

Example plugin name:

{
  "de": "Beispiel-Plugin",
  "en": "Example Plugin"
}

Successful output

The incoming message is forwarded and msg.payload is replaced with:

{
  "authToken": "auth-token",
  "clientId": "client-id",
  "serverAddress": "192.168.1.20",
  "pluginIdentifier": "de.example.plugin",
  "requestResponse": {},
  "confirmResponse": {}
}

To help troubleshoot an error, the HCU's responses are also output in requestResponse and confirmResponse.

The returned authToken is sensitive. Do not expose it through Debug nodes, logs, exported flows, or persistent context without appropriate protection.

HCU In

hcu in receives events from the shared configuration node. It has no input port and one output.

Configuration

• Connection: Required shared HCU configuration.
• Event filter: all or a specific HCU message type.
• Name: Optional display name.

With all, connection events and all WebSocket messages are forwarded. With a specific event type, only messages whose payload.type exactly matches that value are forwarded.

Connection events

When the filter is all, connection events are emitted as:

{
  "topic": "connection/open",
  "payload": {
    "type": "open"
  }
}

{
  "topic": "connection/close",
  "payload": {
    "type": "close",
    "code": 1006,
    "reason": ""
  }
}

{
  "topic": "connection/error",
  "payload": {
    "type": "error",
    "error": "error text"
  }
}

WebSocket messages

Incoming HCU messages are forwarded as:

{
  "topic": "HMIP_SYSTEM_EVENT",
  "payload": {
    "type": "HMIP_SYSTEM_EVENT"
  },
  "meta": {
    "isBinary": false,
    "parsedAsJson": true,
    "raw": "{...}"
  },
  "rawEvent": {
    "type": "message"
  }
}

For binary WebSocket data, payload is represented as a hexadecimal string. Invalid JSON text is forwarded as a string.

HCU Out

hcu out sends msg.payload as the body of an HCU message.

Configuration

• Connection: Required shared HCU configuration.
• Message type: Message type used in the outgoing request.
• Name: Optional display name.

Generated request

For this input:

{
  "payload": {
    "path": "/hmip/home/getSystemState",
    "body": {}
  }
}

The node creates:

{
  "id": "message-id-or-generated-id",
  "type": "HMIP_SYSTEM_REQUEST",
  "pluginId": "plugin-id-from-config",
  "body": {
    "path": "/hmip/home/getSystemState",
    "body": {}
  }
}

The following values are fixed by the node:

• id: msg.id or a generated ID.
• type: Configured messageType.
• pluginId: Value from the selected configuration node.
• body: msg.payload.

After successful sending, the original input message is passed through unchanged. The generated HCU request is not automatically written to the output msg.payload.

Get Feature Value

get feature value reads a feature from the cached HCU system state. It does not listen for new WebSocket events.

Configuration

• Connection: Required shared HCU configuration.
• Device: Device selected from the current cached device list.
• Feature: Feature name to read.
• Name: Optional display name.

An incoming message triggers the lookup. The input payload is not used to select the device or feature.

Device selection

The selected value is always device.id, including for devices with:

type: PLUGIN_EXTERNAL

For PLUGIN_EXTERNAL devices, pluginDeviceId is used only as part of the visible editor label.

Feature lookup

The node searches each entry in functionalChannels:

1. Direct feature property on the channel.
2. supportedOptionalFeatures on the channel.

Output

{
  "payload": {
    "lastStatusUpdate": 1710000000000,
    "label": "Living room",
    "feature": "TEMPERATURE",
    "value": 21.5
  },
  "meta": {
    "featureSource": "functionalChannels",
    "cacheTimestamp": 1710000000000
  }
}

No output message is emitted when the cache, device, or feature is unavailable. The node reports the condition through its status and, for missing cache or devices, through done(error).

Feature Event

feature event listens for HCU system events and emits a message when a selected device feature changes.

Configuration

• Connection: Required shared HCU configuration.
• Device: Device selected from the current cached device list.
• Feature: Feature name to read (e.g. actualTemperature).
• Name: Optional display name.

Output

{
  "payload": {
    "lastStatusUpdate": 1710000000000,
    "label": "Living room",
    "feature": "TEMPERATURE",
    "value": 21.5
  },
  "feature": "TEMPERATURE",
  "meta": {
    "featureSource": "functionalChannels"
  }
}

No message is emitted when the device or feature does not match.

Set Feature Value

set feature value creates an HMIP_SYSTEM_REQUEST, sends it through the shared WebSocket, and waits for the matching HMIP_SYSTEM_RESPONSE.

Configuration

• Connection: Required shared HCU configuration.
• Device: Device selected from the current cached device list.
• HMIP system request: Selected request path selected from the list (taken from the Connect API documentation).
• Name: Optional display name.

Input payload

The Input is a json-object. msg.payload is derived from the HMIP system request paths and the expected body content. These are listed in Chapter 6.8 of the Homematic IP Connect API Documentation. To turn on the light using the system request path "/hmip/device/control/SetSwitchState," the following body is sent to the node via an input node:

{
  "payload": {
    "on": true
  }
}

The inner request body becomes:

{
  "on": true,
  "deviceId": "device-id"
}

Generated request

The following request ist automatically generated by the set feature value node and sent to the HCU:

{
  "pluginId": "plugin-id",
  "id": "request-id",
  "type": "HMIP_SYSTEM_REQUEST",
  "body": {
    "path": "/hmip/device/control/setSwitchState",
    "body": {
      "on": true,
      "deviceId": "device-id"
    }
  }
}

Output

The node correlates responses using the generated request ID. After a matching HMIP_SYSTEM_RESPONSE is received, the response is added to:

msg.payload.respond

The output is emitted only after the matching response arrives. The timeout is 15 seconds. If no matching response arrives, the node reports an error and emits no output.

Create User Message

create user message sends a CREATE_USER_MESSAGE_REQUEST to the HCU which afterwards is displayed on the HMIP App screen.

Configuration

• Connection: Required shared HCU configuration.
• Message category: INFO, ERROR, or WARN.
• Title: Message title.
• Message: Message text.
• Name: Optional display name.

The title and message are sent as language maps using the same text for German and English:

{
  "de": "Message text",
  "en": "Message text"
}

Runtime overrides

The configured values can be overridden by:

msg.messageCategory
msg.title
msg.message
msg.timestamp

Output

The output corresponds to the message that was sent to the HCU. It also contains the userMessageId, which is needed, for example, when a message is to be deleted.

{
  "id": "generated-id",
  "type": "CREATE_USER_MESSAGE_REQUEST",
  "pluginId": "plugin-id",
  "body": {
    "userMessageId": "generated-uuid",
    "behaviorType": "DISMISSIBLE",
    "messageCategory": "INFO",
    "timestamp": 1710000000000,
    "title": {
      "de": "Title text",
      "en": "Title text"
    },
    "message": {
      "de": "Message text",
      "en": "Message text"
    }
  }
}

Delete User Message

delete user message sends a DELETE_USER_MESSAGE_REQUEST.

Input

The user message ID must be provided in msg.payload:

{
  "payload": "user-message-id"
}

You can take the user message id by the output of the Create User Message node.

Generated request

{
  "id": "generated-id",
  "type": "DELETE_USER_MESSAGE_REQUEST",
  "pluginId": "plugin-id",
  "body": {
    "userMessageId": "user-message-id"
  }
}

The output forwards the input message and replaces msg.payload with the generated request object.

This node does not wait for or correlate a delete response. Use hcu in with the DELETE_USER_MESSAGE_RESPONSE filter if confirmation is required.

HCU message types

The package uses HCU Connect API message types including:

HMIP_SYSTEM_REQUEST
HMIP_SYSTEM_RESPONSE
HMIP_SYSTEM_EVENT
PLUGIN_STATE_REQUEST
PLUGIN_STATE_RESPONSE
CREATE_USER_MESSAGE_REQUEST
CREATE_USER_MESSAGE_RESPONSE
DELETE_USER_MESSAGE_REQUEST
DELETE_USER_MESSAGE_RESPONSE

The exact body schema depends on the selected HCU operation. Consult the official Homematic IP Connect API documentation for the supported API paths and schemas.

Status and errors

The nodes use Node-RED status indicators to show connection and processing state. Common statuses include:

ready
connecting...
connected
not connected
waiting for events
waiting for response
response received
message sent
request sent
feature missing
device missing
connection failed
timeout

Common errors include:

WebSocket is not connected
Homematic HCU config node not found
No cached Homematic HCU system state available
No devices found in cached Homematic HCU system state
Timed out waiting for HMIP_SYSTEM_RESPONSE

Security

• Protect the Node-RED editor and runtime.
• Treat HCU authentication tokens and activation keys as secrets.
• Do not place real tokens in README files, screenshots, examples, issue reports, or exported flows.
• Avoid connecting authentication output directly to Debug nodes in production.
• Enable self-signed certificate support only in a controlled environment.
• Prefer certificate verification with a trusted certificate.
• Restrict network access to the HCU WebSocket and HTTPS ports.

Troubleshooting

The node reports not connected

Check:

• HCU IP address or host name.
• Network connectivity from the Node-RED host.
• HCU WebSocket port 9001.
• authToken.
• pluginId.
• TLS certificate trust.
• Whether self-signed certificate support is required.

The device list is empty

The editor loads devices from:

/homematic-hcu/<connectionId>/devices

Check that:

• the configuration node exists.
• the WebSocket connection is open.
• the initial system state has been received.
• the system state contains a devices array or object map.
• the Node-RED editor can access the admin endpoint.

get feature value produces no message

Check:

• the device still exists in the cached state.
• the configured value is exactly device.id.
• the feature name matches the HCU data.
• the feature is located in functionalChannels or supportedOptionalFeatures.

set feature value times out

Check:

• the WebSocket connection.
• the selected request path.
• the request body required by that path.
• the configured device ID.
• whether the HCU returned an HMIP_SYSTEM_RESPONSE with the same request ID.

Development

Install dependencies:

npm install

Install the package locally in Node-RED:

cd ~/.node-red
npm install --no-save /path/to/node-red-contrib-homematic-hcu

Examples

The package currently does not provide importable example flows. Screenshots in the example directory support understanding of node functionality.

License

MIT License. See the LICENSE file for the complete license text.

Support

I cannot guarantee prompt support, as this is a hobby project. Please use the GitHub issue tracker configured in package.json for bug reports and feature requests. Replace the repository placeholders in package.json with the actual GitHub account or organization before publishing.