hm-simulator 0.1.0 → 1.0.0

package/index.js

@@ -1,20 +1,84 @@
 #!/usr/bin/env node
 
+'use strict';
+
+const {parseArgs} = require('node:util');
+
 const HmSim = require('./sim.js');
+const pkg = require('./package.json');
+
+const {values: args} = parseArgs({
+    options: {
+        'listen-address': {type: 'string', default: '127.0.0.1'},
+        'binrpc-port': {type: 'string', default: '2001'},
+        'xmlrpc-port': {type: 'string', default: '2010'},
+        'virtual-port': {type: 'string'},
+        'cuxd-port': {type: 'string'},
+        'rega-port': {type: 'string', default: '8181'},
+        'no-rega': {type: 'boolean', default: false},
+        verbosity: {type: 'string', short: 'v', default: 'info'},
+        version: {type: 'boolean', default: false},
+        help: {type: 'boolean', short: 'h', default: false},
+    },
+});
+
+if (args.version) {
+    console.log(pkg.version);
+    process.exit(0);
+}
 
-const log = require('yalm');
+if (args.help) {
+    console.log(`hm-simulator ${pkg.version} - simulates a Homematic CCU
 
-log.setLevel('debug');
+Usage: hm-simulator [options]
+
+  --listen-address <ip>   default 127.0.0.1
+  --binrpc-port <port>    rfd, default 2001
+  --xmlrpc-port <port>    hmipserver, default 2010
+  --virtual-port <port>   VirtualDevices, off unless given
+  --cuxd-port <port>      CUxD, off unless given
+  --rega-port <port>      ReGa mock, default 8181
+  --no-rega               do not start the ReGa mock
+  -v, --verbosity <level> error|warn|info|debug, default info
+  --version
+  -h, --help`);
+    process.exit(0);
+}
+
+const LEVELS = ['error', 'warn', 'info', 'debug'];
+const level = LEVELS.indexOf(args.verbosity) === -1 ? 2 : LEVELS.indexOf(args.verbosity);
+const logAt = (index, method) =>
+    level >= index ? (...arguments_) => console[method](new Date().toISOString(), ...arguments_) : () => {};
+
+const log = {
+    error: logAt(0, 'error'),
+    warn: logAt(1, 'warn'),
+    info: logAt(2, 'log'),
+    debug: logAt(3, 'log'),
+};
+
+const port = (value) => (value === undefined ? undefined : Number.parseInt(value, 10));
 
 const hmSim = new HmSim({
     log,
     devices: {
         rfd: require('./data/devices-rfd.json'),
-        hmip: require('./data/devices-hmip.json')
+        hmip: require('./data/devices-hmip.json'),
     },
     config: {
-        listenAddress: '127.0.0.1',
-        binrpcListenPort: 2001,
-        xmlrpcListenPort: 2010
-    }
+        listenAddress: args['listen-address'],
+        binrpcListenPort: port(args['binrpc-port']),
+        xmlrpcListenPort: port(args['xmlrpc-port']),
+        virtualListenPort: port(args['virtual-port']),
+        cuxdListenPort: port(args['cuxd-port']),
+    },
+    rega: args['no-rega'] ? undefined : {port: port(args['rega-port']), listenAddress: args['listen-address']},
 });
+
+for (const signal of ['SIGINT', 'SIGTERM']) {
+    process.on(signal, () => {
+        log.info('got', signal, '- shutting down');
+        hmSim.close();
+        process.exit(0);
+    });
+}

package/lib/binrpc-codec.js

@@ -0,0 +1,100 @@
+'use strict';
+
+/**
+ * Minimal binrpc response encoder.
+ *
+ * binrpc's own server only ever writes message type 0x01 (response); the real rfd/crRFD answers an
+ * invalid call with message type 0xff and a struct body holding faultCode and faultString. To be
+ * able to send both, the simulator encodes responses itself instead of reaching into binrpc's
+ * internals. The encoding mirrors binrpc's protocol module byte for byte (every 32 bit word
+ * big-endian, strings ascii, doubles as mantissa/exponent pair); `test/binrpc-codec.test.js`
+ * verifies that against a real binrpc client.
+ */
+
+function word32(value) {
+    const buf = Buffer.alloc(4);
+    buf.writeUInt32BE(value >>> 0, 0);
+    return buf;
+}
+
+function encodeInteger(value) {
+    return Buffer.concat([word32(0x01), word32(value)]);
+}
+
+function encodeDouble(value) {
+    const exponent = Math.floor(Math.log(Math.abs(value)) / Math.LN2) + 1;
+    const mantissa = Math.floor(value * Math.pow(2, -exponent) * (1 << 30));
+    return Buffer.concat([word32(0x04), word32(mantissa), word32(exponent)]);
+}
+
+function encodeString(value) {
+    const str = String(value);
+    return Buffer.concat([word32(0x03), word32(str.length), Buffer.from(str, 'ascii')]);
+}
+
+function encodeBool(value) {
+    return Buffer.concat([word32(0x02), Buffer.from([value ? 1 : 0])]);
+}
+
+function encodeKey(key) {
+    return Buffer.concat([word32(key.length), Buffer.from(key, 'ascii')]);
+}
+
+function encodeData(data) {
+    if (data === undefined || data === null) {
+        return encodeString('');
+    }
+    switch (typeof data) {
+        case 'number':
+            return data % 1 === 0 ? encodeInteger(data) : encodeDouble(data);
+        case 'boolean':
+            return encodeBool(data);
+        case 'string':
+            return encodeString(data);
+        case 'object':
+            break;
+        default:
+            return encodeString(String(data));
+    }
+
+    if (Array.isArray(data)) {
+        return Buffer.concat([word32(0x100), word32(data.length), ...data.map((item) => encodeData(item))]);
+    }
+
+    if (typeof data.explicitDouble === 'number') {
+        return encodeDouble(data.explicitDouble);
+    }
+
+    const keys = Object.keys(data).filter((key) => data[key] !== undefined);
+    const members = [];
+    for (const key of keys) {
+        members.push(encodeKey(key), encodeData(data[key]));
+    }
+    return Buffer.concat([word32(0x101), word32(keys.length), ...members]);
+}
+
+function message(type, body) {
+    return Buffer.concat([Buffer.from('Bin', 'ascii'), Buffer.from([type]), word32(body.length), body]);
+}
+
+/**
+ * @param {*} data
+ * @returns {Buffer} message type 0x01
+ */
+function encodeResponse(data) {
+    return message(0x01, encodeData(data === undefined ? '' : data));
+}
+
+/**
+ * @param {{faultCode: number, faultString: string}} fault
+ * @returns {Buffer} message type 0xff
+ */
+function encodeFault(fault) {
+    const body = encodeData({
+        faultCode: Number(fault.faultCode) || 0,
+        faultString: fault.faultString === undefined ? '' : String(fault.faultString),
+    });
+    return message(0xff, body);
+}
+
+module.exports = {encodeData, encodeResponse, encodeFault};

package/lib/faults.js

@@ -0,0 +1,126 @@
+'use strict';
+
+/**
+ * Fault responses.
+ *
+ * The real interface processes (rfd/crRFD, hmipserver, CUxD) answer invalid calls with an XML-RPC
+ * fault (binrpc message type 0xff with a struct body). The exact codes and strings are not
+ * publicly specified, so until 2026-09-05 the table below was an educated guess following the
+ * negative-code convention of the eq3 XML-RPC API.
+ *
+ * It is a measurement now. Homematic Manager's roadmap task 6 probed both interface processes of
+ * two CCUs on firmware 3.89.8 with calls that cannot change anything - an address that does not
+ * exist, a paramset that does not exist, a read-only parameter, a method that does not exist - and
+ * recorded what came back; `docs/config-pending.md` in that repository has the full tables and the
+ * script that produced them.
+ *
+ * The two processes disagree, and not only in wording:
+ *
+ * - hmipserver answers a fault for nearly everything and uses **-5 `Invalid parameter or value`**
+ *   for every kind of bad `putParamset`, whatever went wrong.
+ * - rfd answers **no fault at all** for a whole class of mistakes: an unknown paramset name is
+ *   taken as a peer address, a missing argument defaults, a write to a read-only datapoint is
+ *   accepted. What it does fault on, it names differently.
+ *
+ * {@link DEFAULT_FAULTS} is hmipserver's table, because that is the one an application has to
+ * survive; {@link BIDCOS_FAULTS} is rfd's, for a simulator that models a BidCos interface. Every
+ * entry can still be overridden through the `faults` constructor option, and `sim.faults` exposes
+ * the effective table.
+ */
+
+/** hmipserver 3.89.8, measured 2026-09-05. */
+const DEFAULT_FAULTS = {
+    // no handler for the requested method name. hmipserver answers this at the HTTP level and
+    // sends no faultCode at all, so -1 is the simulator's stand-in
+    unknownMethod: {faultCode: -1, faultString: 'Invalid XML-RPC message'},
+    // device or channel address not known to this interface process
+    unknownInstance: {faultCode: -2, faultString: 'Invalid device'},
+    // the device/channel exists but does not have the requested paramset
+    unknownParamset: {faultCode: -2, faultString: 'Invalid device'},
+    // the paramset exists but does not contain the requested parameter (getValue/setValue)
+    unknownParameter: {faultCode: -5, faultString: 'Unknown Parameter for value key'},
+    // the two channels are not linked with each other
+    unknownLink: {faultCode: -2, faultString: 'Invalid device'},
+    // parameter exists but OPERATIONS does not include write (2)
+    readOnly: {faultCode: -5, faultString: 'Invalid parameter or value'},
+    // value has a type the parameter's TYPE does not accept
+    typeError: {faultCode: -5, faultString: 'Invalid parameter or value'},
+    // ENUM index/name not in VALUE_LIST. hmipserver does *not* check MIN..MAX at all - see the
+    // 'hmip' configPendingMode in lib/sim.js
+    outOfRange: {faultCode: -5, faultString: 'Invalid parameter or value'},
+    // the stored configuration of a channel cannot be transferred to the device: the fault a
+    // poisoned channel answers to every putParamset, including one with an empty struct
+    invalidValue: {faultCode: -5, faultString: 'Invalid parameter or value'},
+    // method understood but not implemented for this interface: clearConfigCache,
+    // restoreConfigToDevice and determineParameter all answer this on hmipserver
+    notSupported: {faultCode: -1, faultString: 'Generic error'},
+    // device is known but currently not reachable (a sleeping battery device)
+    notReachable: {faultCode: -1, faultString: 'Generic error (UNREACH)'},
+    // malformed parameters. hmipserver lets a Java NullPointerException through here and answers
+    // -321 with the exception message, which is not something an application can rely on
+    invalidArguments: {faultCode: -321, faultString: 'Invalid arguments'},
+};
+
+/** rfd (BidCos-RF) 3.89.8, measured 2026-09-05. */
+const BIDCOS_FAULTS = {
+    unknownMethod: {faultCode: -1, faultString: 'unknown method name'},
+    unknownInstance: {faultCode: -2, faultString: 'Unknown instance'},
+    // rfd does not fault here at all: an unknown paramset name is taken as a peer channel address
+    // and the link defaults come back. The entry covers what the simulator cannot model.
+    unknownParamset: {faultCode: -2, faultString: 'Unknown instance'},
+    unknownParameter: {faultCode: -5, faultString: 'Unknown parameter'},
+    unknownLink: {faultCode: -1, faultString: 'Failure'},
+    // rfd accepts a setValue on a read-only datapoint, so this is never raised against it
+    readOnly: {faultCode: -5, faultString: 'Unknown parameter'},
+    typeError: {faultCode: -5, faultString: 'Unknown parameter'},
+    outOfRange: {faultCode: -5, faultString: 'Unknown parameter'},
+    invalidValue: {faultCode: -5, faultString: 'Unknown parameter'},
+    notSupported: {faultCode: -1, faultString: 'Failure'},
+    notReachable: {faultCode: -1, faultString: 'Failure'},
+    invalidArguments: {faultCode: -1, faultString: 'Failure'},
+};
+
+/** The measured tables by name, for `new HmSim({faults: FAULT_TABLES.bidcos})`. */
+const FAULT_TABLES = {hmip: DEFAULT_FAULTS, bidcos: BIDCOS_FAULTS};
+
+/** Error carrying an XML-RPC fault. */
+class RpcFault extends Error {
+    constructor(faultCode, faultString, detail) {
+        super(detail ? `${faultString}: ${detail}` : faultString);
+        this.name = 'RpcFault';
+        this.faultCode = faultCode;
+        this.faultString = faultString;
+        this.detail = detail;
+    }
+
+    /** The struct a binrpc fault carries as its body. */
+    toStruct() {
+        return {faultCode: this.faultCode, faultString: this.faultString};
+    }
+}
+
+/**
+ * Builds a fault factory bound to a (possibly overridden) fault table.
+ * @param {object} [overrides] partial table, same shape as DEFAULT_FAULTS
+ * @returns {{table: object, fault: function(string, string=): RpcFault}}
+ */
+function createFaults(overrides = {}) {
+    const table = {};
+    for (const [key, value] of Object.entries(DEFAULT_FAULTS)) {
+        table[key] = {...value, ...overrides[key]};
+    }
+    for (const [key, value] of Object.entries(overrides)) {
+        if (!table[key]) {
+            table[key] = {...value};
+        }
+    }
+
+    const fault = (key, detail) => {
+        const entry = table[key] || table.unknownMethod;
+        return new RpcFault(entry.faultCode, entry.faultString, detail);
+    };
+
+    return {table, fault};
+}
+
+module.exports = {DEFAULT_FAULTS, BIDCOS_FAULTS, FAULT_TABLES, RpcFault, createFaults};

package/lib/method-help.js

@@ -0,0 +1,50 @@
+'use strict';
+
+/**
+ * Answers to `system.methodHelp`. The real interface processes answer with a one line signature;
+ * the wording here follows the eq3 XML-RPC API documentation.
+ */
+module.exports = {
+    'system.listMethods': 'array system.listMethods() - names of all methods this interface knows',
+    'system.methodHelp': 'string system.methodHelp(string method) - the documentation of a method',
+    'system.multicall': 'array system.multicall(array calls) - execute several method calls at once',
+    init: 'string init(string url, string interfaceId) - register or (with an empty id) remove a logic layer',
+    listDevices: 'array listDevices() - descriptions of all devices and channels',
+    getDeviceDescription: 'struct getDeviceDescription(string address) - description of one device or channel',
+    getParamsetDescription:
+        'struct getParamsetDescription(string address, string paramsetType) - description of a paramset',
+    getParamsetId: 'string getParamsetId(string address, string paramsetType) - identifier of a paramset',
+    getParamset: 'struct getParamset(string address, string paramsetKey) - values of a paramset',
+    putParamset: 'void putParamset(string address, string paramsetKey, struct set) - write values of a paramset',
+    getValue: 'ValueType getValue(string address, string valueKey) - read one value',
+    setValue: 'void setValue(string address, string valueKey, ValueType value) - write one value',
+    ping: 'boolean ping(string callerId) - triggers a PONG event',
+    getLinks: 'array getLinks(string address, int flags) - links of a channel or of the whole interface',
+    getLinkInfo: 'struct getLinkInfo(string senderAddress, string receiverAddress) - name and description of a link',
+    setLinkInfo:
+        'void setLinkInfo(string senderAddress, string receiverAddress, string name, string description) - rename a link',
+    getLinkPeers: 'array getLinkPeers(string address) - the peers a channel is linked with',
+    addLink:
+        'void addLink(string senderAddress, string receiverAddress, string name, string description) - link two channels',
+    removeLink: 'void removeLink(string senderAddress, string receiverAddress) - remove a link',
+    activateLinkParamset:
+        'void activateLinkParamset(string address, string peerAddress, boolean longPress) - apply a link paramset',
+    rssiInfo: 'struct rssiInfo() - receive levels of all devices',
+    listBidcosInterfaces: 'array listBidcosInterfaces() - the BidCos interfaces (antennas) of this process',
+    setBidcosInterface:
+        'void setBidcosInterface(string deviceId, string interfaceId, boolean roaming) - assign a device to an interface',
+    getServiceMessages: 'array getServiceMessages() - the pending service messages',
+    setInstallMode: 'void setInstallMode(boolean on, int time, int mode) - switch the install mode',
+    getInstallMode: 'int getInstallMode() - remaining seconds of the install mode',
+    deleteDevice: 'void deleteDevice(string address, int flags) - remove a device',
+    replaceDevice:
+        'void replaceDevice(string oldDeviceAddress, string newDeviceAddress) - take over the configuration of a device',
+    reportValueUsage:
+        'void reportValueUsage(string address, string valueId, int refCounter) - announce datapoint usage',
+    updateFirmware: 'boolean updateFirmware(array deviceAddresses) - start a firmware update',
+    installFirmware: 'boolean installFirmware(string deviceAddress) - install a pending firmware',
+    clearConfigCache: 'void clearConfigCache(string address) - drop the cached configuration of a device',
+    restoreConfigToDevice: 'void restoreConfigToDevice(string address) - write the cached configuration to the device',
+    determineParameter:
+        'void determineParameter(string address, string paramsetKey, string parameterId) - read a parameter from the device',
+};

package/lib/rega.js

@@ -0,0 +1,245 @@
+'use strict';
+
+const http = require('node:http');
+
+/**
+ * ReGa (HomeMatic logic layer) mock.
+ *
+ * Answers the `rega.exe` endpoint the way the CCU does: the script output followed by an `<xml>`
+ * block. The scripts of the `homematic-rega` client are recognised by their first line
+ * (`!# devices.rega`, `!# variables.rega`, `!# programs.rega`, `!# rooms.rega`,
+ * `!# functions.rega`, `!# values.rega`); `getChannels()` uses `channels.rega`, whose first line is
+ * the historical `!# devices.rega`.
+ *
+ * Every script that is not one of those is echoed into `regaSim.scripts` (and, for the ones the
+ * mock understands, applied to the mock's state), so tests can assert on what was executed -
+ * renames (`dom.GetObject(id).Name("...")`) in particular.
+ */
+class RegaSim {
+    /**
+     * @param {object} options
+     * @param {number} [options.port=8181]
+     * @param {string} [options.listenAddress]
+     * @param {Array} [options.variables]
+     * @param {Array} [options.channels] devices and channels, the answer to `getChannels()`
+     * @param {Array} [options.programs]
+     * @param {Array} [options.rooms]
+     * @param {Array} [options.functions]
+     * @param {Array} [options.values] the answer to `getValues()`
+     * @param {object} [options.auth] {username, password} - enables HTTP basic auth
+     * @param {object} [options.tls] {key, cert} - serve https instead of http
+     * @param {object} [log]
+     */
+    constructor(options, log) {
+        this.log = log || {debug() {}, info() {}, warn() {}, error() {}};
+        this.variables = options.variables || [];
+        this.devices = options.channels || [];
+        this.programs = options.programs || [];
+        this.rooms = options.rooms || [];
+        this.functions = options.functions || [];
+        this.values = options.values || [];
+        /** every script the mock received, newest last */
+        this.scripts = [];
+        /** every rename script, as {id, name, script} */
+        this.renames = [];
+        this.auth = options.auth || null;
+
+        const handler = (request, response) => this.handleRequest(request, response);
+        this.server = options.tls
+            ? require('node:https').createServer(options.tls, handler)
+            : http.createServer(handler);
+        /** the port the mock listens on - known once `ready` resolved, which matters for port 0 */
+        this.port = options.port === undefined ? 8181 : options.port;
+        /** resolves once the mock accepts connections, rejects when the port is taken */
+        this.ready = new Promise((resolve, reject) => {
+            this.server.on('error', reject);
+            this.server.listen(this.port, options.listenAddress, () => {
+                const address = this.server.address();
+                if (address) {
+                    this.port = address.port;
+                }
+                resolve();
+            });
+        });
+    }
+
+    handleRequest(request, response) {
+        if (this.auth) {
+            const expected =
+                'Basic ' + Buffer.from(`${this.auth.username}:${this.auth.password || ''}`, 'utf8').toString('base64');
+            if (request.headers.authorization !== expected) {
+                response.writeHead(401, {
+                    'WWW-Authenticate': 'Basic realm="hm-simulator"',
+                    'Content-Type': 'text/plain',
+                });
+                response.end('Unauthorized');
+                return;
+            }
+        }
+
+        const path = (request.url || '/').split('?')[0];
+        if (!/^\/[\w-]+\.exe$/.test(path)) {
+            response.writeHead(404, {'Content-Type': 'text/plain'});
+            response.end('Not Found');
+            return;
+        }
+
+        if (request.method !== 'POST') {
+            this.send(response, this.response(''));
+            return;
+        }
+
+        const chunks = [];
+        request.on('data', (chunk) => chunks.push(chunk));
+        request.on('end', () => {
+            const script = Buffer.concat(chunks).toString('latin1');
+            this.send(response, this.response(this.exec(script)));
+        });
+    }
+
+    /**
+     * Runs a script against the mock's state.
+     * @param {string} script
+     * @returns {string|Array|object} the script's output
+     */
+    exec(script) {
+        this.scripts.push(script);
+        const line = script.split('\n')[0].trim();
+
+        switch (line) {
+            case '!# devices.rega':
+                return this.devices;
+            case '!# variables.rega':
+                return this.variables;
+            case '!# programs.rega':
+                return this.programs;
+            case '!# rooms.rega':
+                return this.rooms;
+            case '!# functions.rega':
+                return this.functions;
+            case '!# values.rega':
+                return this.values;
+            default:
+                return this.execStatement(script, line);
+        }
+    }
+
+    execStatement(script, line) {
+        let match = line.match(/dom\.GetObject\((\d+)\)\.State\(([^)]*)\)/);
+        if (match) {
+            const id = Number.parseInt(match[1], 10);
+            let value;
+            try {
+                value = JSON.parse(match[2]);
+            } catch {
+                value = match[2];
+            }
+            for (const [index, variable] of this.variables.entries()) {
+                if (variable.id === id) {
+                    this.variables[index].val = value;
+                    this.variables[index].ts = this.ts();
+                }
+            }
+            return '';
+        }
+
+        match = line.match(/dom\.GetObject\((\d+)\)\.Name\("([^"]*)"\)/);
+        if (match) {
+            const id = Number.parseInt(match[1], 10);
+            const name = match[2];
+            this.renames.push({id, name, script});
+            for (const list of [this.devices, this.variables, this.programs, this.rooms, this.functions]) {
+                for (const item of list) {
+                    if (item.id === id) {
+                        item.name = name;
+                    }
+                }
+            }
+            return '';
+        }
+
+        match = line.match(/dom\.GetObject\((\d+)\)\.Active\((true|false)\)/);
+        if (match) {
+            const id = Number.parseInt(match[1], 10);
+            for (const program of this.programs) {
+                if (program.id === id) {
+                    program.active = match[2] === 'true';
+                    program.ts = this.ts();
+                }
+            }
+            return '';
+        }
+
+        match = line.match(/dom\.GetObject\((\d+)\)\.ProgramExecute\(\)/);
+        if (match) {
+            const id = Number.parseInt(match[1], 10);
+            for (const program of this.programs) {
+                if (program.id === id) {
+                    program.ts = this.ts();
+                }
+            }
+            return '';
+        }
+
+        this.log.warn('unknown script', line);
+        return '';
+    }
+
+    send(response, body) {
+        const buffer = Buffer.from(body, 'latin1');
+        response.writeHead(200, {
+            server: 'ise GmbH HTTP-Server v2.0',
+            'accept-ranges': 'bytes',
+            'cache-control': 'no-store, no-cache',
+            'content-type': 'text/xml; charset=iso-8859-1',
+            'content-length': buffer.length,
+        });
+        response.end(buffer);
+    }
+
+    close() {
+        this.server.close();
+        if (typeof this.server.closeAllConnections === 'function') {
+            this.server.closeAllConnections();
+        }
+    }
+
+    response(stdout, vars = []) {
+        if (typeof stdout !== 'string') {
+            stdout = JSON.stringify(stdout);
+        }
+
+        const xml = [
+            ['exec', 'rega.exe'],
+            ['sessionId', ''],
+            ['httpUserAgent', ''],
+        ].concat(vars);
+
+        stdout += '<xml>';
+        for (const [key, value] of xml) {
+            stdout += `<${key}>${value}</${key}>`;
+        }
+        stdout += '</xml>';
+
+        return stdout;
+    }
+
+    ts() {
+        const d = new Date();
+        return (
+            d.getFullYear() +
+            '-' +
+            ('0' + (d.getMonth() + 1)).slice(-2) +
+            '-' +
+            ('0' + d.getDate()).slice(-2) +
+            ' ' +
+            ('0' + d.getHours()).slice(-2) +
+            ':' +
+            ('0' + d.getMinutes()).slice(-2) +
+            ':' +
+            ('0' + d.getSeconds()).slice(-2)
+        );
+    }
+}
+
+module.exports = RegaSim;