homematic-rega

Node.js Homematic CCU ReGaHSS remote script interface

This module encapsulates the communication with the "ReGaHSS" — the logic layer of the Homematic CCU — through its remote script endpoint (rega.exe). ES module, promise API, no dependencies, Node.js >= 20.

• execute arbitrary scripts and read back the script's variables
• get names and ids of devices and channels
• get the current values of all datapoints
• get variables including value and meta data, set variables
• get programs, execute and activate/deactivate them
• get rooms and functions including assigned channels
• rename objects

${...} i18n placeholders (e.g. ${roomKitchen}) are translated by default. Official and inofficial documentation of the scripting language: wikimatic.de.

Install

npm install homematic-rega

Usage

import {Rega} from 'homematic-rega';

const rega = new Rega({host: '192.168.2.105'});

const {output, objects} = await rega.exec('string x = "Hello";\nWriteLine(x # " World!");');
console.log(output); // "Hello World!\n"
console.log(objects); // {exec: '/rega.exe', sessionId: '', httpUserAgent: '', x: 'Hello'}

const variables = await rega.getVariables();

Options

| option | default | description | | ----------- | -------------------- | ----------------------------------------------------------------------- | | host | — | hostname or IP address of the CCU (required) | | port | 8181 (48181 tls) | rega remote script port | | tls | false | connect using TLS | | insecure | false | accept invalid/self-signed TLS certificates | | username | — | CCU user for basic authentication (with password) | | language | 'de' | language of the placeholder translations | | translate | true | translate ${...} placeholders in names of variables, rooms, functions | | timeout | 30000 | request timeout in ms | | timeZone | local time | IANA time zone of the CCU, used to convert timestamps | | webPort | 80 (443 tls) | port of the CCU web UI, where the translations are downloaded from | | agent | no keep-alive | http.Agent/https.Agent for the requests, or false; see below |

The default agent does not keep connections alive (new http.Agent({keepAlive: false})). Node's http.globalAgent pools connections since Node 19, and ReGaHSS itself (port 8183 on the CCU) answers HTTP/1.1 without Connection: close but closes every connection a few milliseconds after the response — a request that reuses the pooled socket in that window fails with socket hang up. lighttpd on 8181 handles keep-alive properly; pass your own agent if you want pooling there.

API

All methods return Promises.

| method | resolves to | | ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- | | exec(script) | {output, objects} — the script's output and every variable set in the script (strings) | | script(file) | same, for a script file (UTF-8) | | getChannels() | [{id, address, name}] — devices and channels | | getValues() | [{name, value, ts}] — every datapoint, name = <interface>.<channel>.<datapoint> | | getVariables() | [{id, name, info, val, ts, unit, type, enum, channel}] — type is boolean/number/string, enum an array, channel an id or null | | getPrograms() | [{id, name, info, active, ts}] — ts = last execution | | getRooms() | [{id, name, channels}] — channels are channel ids | | getFunctions() | [{id, name, channels}] | | setVariable(id, value) | {output, objects} | | startProgram(id) | | | setProgram(id, active) | | | setName(id, name) | |

Timestamps (ts) are epoch milliseconds; 0 means "never" (the CCU's 1970-01-01 01:00:00). They are converted from the CCU's local time — set timeZone when the CCU is not in the time zone of the process. Text is decoded as ISO-8859-1, which is what the ReGaHSS speaks.

Exported helpers: parseResponse(body), parseTimestamp(string, timeZone), unescapeLatin1(string).

Migration from 1.x

| 1.x | 2.0 | | ------------------------------------------- | --------------------------------------------------- | | const Rega = require('homematic-rega') | import {Rega} from 'homematic-rega' | | rega.exec(script, (err, output, objects)) | const {output, objects} = await rega.exec(script) | | rega.getVariables((err, res)) etc. | await rega.getVariables() | | {inSecure, auth, user, pass} | {insecure, username, password} | | {disableTranslation: true} | {translate: false} | | ts: '2026-01-15 12:00:00' | ts: 1768478400000 (ms), timeZone option | | enum: ''/'a;b', channel: ''/'1234' | enum: []/['a', 'b'], channel: null/1234 |

Related projects

• node-red-contrib-ccu — Node-RED nodes for the Homematic CCU
• hm2mqtt — interface between Homematic and MQTT
• binrpc — Node.js client/server for the Homematic BINRPC protocol
• homematic-xmlrpc — Node.js client/server for the Homematic XMLRPC protocol

License

MIT (c) Sebastian Raff

Changes per release: CHANGELOG.md.