hm-simulator 1.1.0 → 1.3.0

package/index.js

@@ -2,25 +2,77 @@
 
 'use strict';
 
+const fs = require('node:fs');
+const path = require('node:path');
 const {parseArgs} = require('node:util');
 
 const HmSim = require('./sim.js');
+const {createControlServer} = require('./lib/control.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},
-    },
-});
+const HELP = `hm-simulator ${pkg.version} - simulates a Homematic CCU
+
+Usage: hm-simulator [options]
+
+  --listen-address <ip>     default 127.0.0.1
+  --binrpc-port <port>      rfd (BIN-RPC and XML-RPC), default 2001
+  --xmlrpc-port <port>      hmipserver, default 2010
+  --wired-port <port>       BidCos-Wired, off unless given or configured
+  --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
+                            every port may be 0: the system picks a free one
+  --ports-json <file|->     once every server listens, write the ports as JSON to the file, or
+                            as one line to stdout with "-" (the log then goes to stderr)
+  --config <file>           constructor options as a .json or .js file; the flags override it
+  --devices <file>          a device file: {devices: {rfd, hmip, ...}, paramsetDescriptions, links,
+                            bidcosInterfaces}, such as data/fixtures/lab-2026-09.json; default:
+                            the bundled rfd and hmip lists
+  --tls                     serve the XML-RPC servers over TLS with a generated certificate
+  --tls-cert-out <file>     write that certificate (PEM) to the file
+  --auth <user:password>    HTTP basic auth for the XML-RPC servers and ReGa
+  --behavior-path <dir>     behaviour scripts, default the bundled examples
+  --no-behaviors            no behaviour scripts
+  --control-port <port>     the scenario API over HTTP on 127.0.0.1, off unless given
+  -v, --verbosity <level>   error|warn|info|debug, default info
+  --version
+  -h, --help`;
+
+function fail(message) {
+    console.error(`hm-simulator: ${message}`);
+    process.exit(1);
+}
+
+let args;
+try {
+    ({values: args} = parseArgs({
+        options: {
+            'listen-address': {type: 'string'},
+            'binrpc-port': {type: 'string'},
+            'xmlrpc-port': {type: 'string'},
+            'wired-port': {type: 'string'},
+            'virtual-port': {type: 'string'},
+            'cuxd-port': {type: 'string'},
+            'rega-port': {type: 'string'},
+            'no-rega': {type: 'boolean', default: false},
+            'ports-json': {type: 'string'},
+            config: {type: 'string'},
+            devices: {type: 'string'},
+            tls: {type: 'boolean', default: false},
+            'tls-cert-out': {type: 'string'},
+            auth: {type: 'string'},
+            'behavior-path': {type: 'string'},
+            'no-behaviors': {type: 'boolean', default: false},
+            'control-port': {type: 'string'},
+            verbosity: {type: 'string', short: 'v', default: 'info'},
+            version: {type: 'boolean', default: false},
+            help: {type: 'boolean', short: 'h', default: false},
+        },
+    }));
+} catch (error) {
+    fail(error.message);
+}
 
 if (args.version) {
     console.log(pkg.version);
@@ -28,23 +80,12 @@ if (args.version) {
 }
 
 if (args.help) {
-    console.log(`hm-simulator ${pkg.version} - simulates a Homematic CCU
-
-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`);
+    console.log(HELP);
     process.exit(0);
 }
 
+// with the ports on stdout, stdout carries nothing else
+const toStderr = args['ports-json'] === '-';
 const LEVELS = ['error', 'warn', 'info', 'debug'];
 const level = LEVELS.indexOf(args.verbosity) === -1 ? 2 : LEVELS.indexOf(args.verbosity);
 const logAt = (index, method) =>
@@ -52,33 +93,205 @@ const logAt = (index, method) =>
 
 const log = {
     error: logAt(0, 'error'),
-    warn: logAt(1, 'warn'),
-    info: logAt(2, 'log'),
-    debug: logAt(3, 'log'),
+    warn: logAt(1, toStderr ? 'error' : 'warn'),
+    info: logAt(2, toStderr ? 'error' : 'log'),
+    debug: logAt(3, toStderr ? 'error' : 'log'),
 };
 
-const port = (value) => (value === undefined ? undefined : Number.parseInt(value, 10));
+function port(value, name) {
+    if (value === undefined) {
+        return undefined;
+    }
+    const number = Number(value);
+    if (value === '' || !Number.isInteger(number) || number < 0 || number > 65535) {
+        fail(`--${name} wants a port number, got ${value}`);
+    }
+    return number;
+}
+
+function readJson(file) {
+    try {
+        return JSON.parse(fs.readFileSync(file, 'utf8'));
+    } catch (error) {
+        fail(`cannot read ${file}: ${error.message}`);
+    }
+}
+
+/**
+ * A device file: `{devices: {rfd, hmip, ...}, paramsetDescriptions}` (a fixture), or only the
+ * `{rfd, hmip, ...}` part.
+ */
+/**
+ * A device file: either `{<iface>: {devices}}` or a fixture `{devices, paramsetDescriptions, links,
+ * bidcosInterfaces}` as data/fixtures/ and tools/dump-ccu.js have it.
+ */
+function loadDevices(file) {
+    const content = readJson(file);
+    return content.devices && !Array.isArray(content.devices)
+        ? {
+              devices: content.devices,
+              paramsetDescriptions: content.paramsetDescriptions,
+              links: content.links,
+              bidcosInterfaces: content.bidcosInterfaces,
+          }
+        : {devices: content};
+}
+
+/** Takes what a device file brings along, unless the options already say it. */
+function applyDeviceFile(options, loaded, override) {
+    options.devices = loaded.devices;
+    for (const key of ['paramsetDescriptions', 'links', 'bidcosInterfaces']) {
+        if (loaded[key] && (override || options[key] === undefined)) {
+            options[key] = loaded[key];
+        }
+    }
+}
+
+function loadConfig(file) {
+    const absolute = path.resolve(file);
+    let options;
+    try {
+        options = /\.c?js$/.test(absolute) ? require(absolute) : readJson(absolute);
+    } catch (error) {
+        fail(`cannot load ${file}: ${error.message}`);
+    }
+    options = {...options};
+    const base = path.dirname(absolute);
+    // devices and paramsetDescriptions may be paths, relative to the file
+    if (typeof options.devices === 'string') {
+        applyDeviceFile(options, loadDevices(path.resolve(base, options.devices)), false);
+    }
+    if (typeof options.paramsetDescriptions === 'string') {
+        options.paramsetDescriptions = readJson(path.resolve(base, options.paramsetDescriptions));
+    }
+    if (typeof options.behaviorPath === 'string') {
+        options.behaviorPath = path.resolve(base, options.behaviorPath);
+    }
+    return options;
+}
 
-const hmSim = new HmSim({
-    log,
-    devices: {
+const options = args.config ? loadConfig(args.config) : {};
+
+if (args.devices) {
+    applyDeviceFile(options, loadDevices(path.resolve(args.devices)), true);
+}
+if (!options.devices) {
+    options.devices = {
         rfd: require('./data/devices-rfd.json'),
         hmip: require('./data/devices-hmip.json'),
-    },
-    config: {
-        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']},
-});
+    };
+}
+// a copy: the simulator changes the lists it is given
+options.devices = JSON.parse(JSON.stringify(options.devices));
+
+const config = {...options.config};
+const listenAddress = args['listen-address'] || config.listenAddress || '127.0.0.1';
+config.listenAddress = listenAddress;
+config.binrpcListenPort = port(args['binrpc-port'], 'binrpc-port') ?? config.binrpcListenPort ?? 2001;
+config.xmlrpcListenPort = port(args['xmlrpc-port'], 'xmlrpc-port') ?? config.xmlrpcListenPort ?? 2010;
+config.virtualListenPort = port(args['virtual-port'], 'virtual-port') ?? config.virtualListenPort;
+config.cuxdListenPort = port(args['cuxd-port'], 'cuxd-port') ?? config.cuxdListenPort;
+config.wiredListenPort = port(args['wired-port'], 'wired-port') ?? config.wiredListenPort;
+if (config.wiredListenPort !== undefined && !options.devices.wired) {
+    options.devices.wired = {devices: []};
+}
+if (options.devices.wired && config.wiredListenPort === undefined) {
+    config.wiredListenPort = 2000;
+}
+options.config = config;
+
+if (args['no-rega']) {
+    delete options.rega;
+} else {
+    options.rega = {port: 8181, listenAddress, ...options.rega};
+    if (args['rega-port'] !== undefined) {
+        options.rega.port = port(args['rega-port'], 'rega-port');
+    }
+}
+
+if (args.tls) {
+    options.tls = true;
+}
+if (args.auth !== undefined) {
+    const separator = args.auth.indexOf(':');
+    if (separator < 1) {
+        fail('--auth wants user:password');
+    }
+    options.auth = {username: args.auth.slice(0, separator), password: args.auth.slice(separator + 1)};
+}
+if (args['no-behaviors']) {
+    options.behaviorPath = false;
+} else if (args['behavior-path'] !== undefined) {
+    options.behaviorPath = path.resolve(args['behavior-path']);
+}
+options.log = log;
+
+const controlPort = port(args['control-port'], 'control-port');
+
+/** Writes a file so that a reader never sees half of it. */
+function writeAtomically(file, content) {
+    const temporary = `${file}.${process.pid}.tmp`;
+    fs.writeFileSync(temporary, content);
+    fs.renameSync(temporary, file);
+}
+
+let hmSim;
+let control;
+
+function shutdown(code) {
+    if (control) {
+        control.close();
+    }
+    if (hmSim) {
+        hmSim.close();
+    }
+    process.exit(code);
+}
+
+async function main() {
+    hmSim = new HmSim(options);
+    try {
+        await hmSim.whenReady();
+    } catch (error) {
+        // EADDRINUSE and friends name the address and the port
+        console.error(`hm-simulator: ${error.message}`);
+        shutdown(1);
+    }
+
+    if (controlPort !== undefined) {
+        try {
+            control = await createControlServer(hmSim, {port: controlPort, log: log.error});
+        } catch (error) {
+            console.error(`hm-simulator: control port: ${error.message}`);
+            shutdown(1);
+        }
+    }
+
+    if (args['tls-cert-out'] && hmSim.tls) {
+        writeAtomically(path.resolve(args['tls-cert-out']), hmSim.tls.cert);
+    }
+
+    const ports = {...hmSim.ports};
+    if (hmSim.regaSim) {
+        ports.rega = hmSim.regaSim.port;
+    }
+    if (control) {
+        ports.control = control.address().port;
+    }
+    log.info('listening', JSON.stringify(ports));
+
+    if (args['ports-json'] === '-') {
+        process.stdout.write(JSON.stringify(ports) + '\n');
+    } else if (args['ports-json']) {
+        writeAtomically(path.resolve(args['ports-json']), JSON.stringify(ports) + '\n');
+    }
+}
 
 for (const signal of ['SIGINT', 'SIGTERM']) {
     process.on(signal, () => {
         log.info('got', signal, '- shutting down');
-        hmSim.close();
-        process.exit(0);
+        shutdown(0);
     });
 }
+
+main();

package/lib/control.js

@@ -0,0 +1,133 @@
+'use strict';
+
+const http = require('node:http');
+
+/**
+ * The scenario calls the control endpoint lets through. Everything a test does to a simulator it
+ * does not run in its own process: devices, events, service messages, interface processes, and
+ * reading back what the simulator saw.
+ */
+const SCENARIO_METHODS = new Set([
+    'addDevice',
+    'removeDevice',
+    'fireEvent',
+    'setValue',
+    'setServiceMessage',
+    'scriptNewDevices',
+    'scriptKeyMismatch',
+    'dropConnection',
+    'stopInterface',
+    'startInterface',
+    'restartInterface',
+    'fireEvents',
+    'injectFault',
+    'clearFaults',
+    'getCallbackLog',
+    'setReachable',
+    'setLowBattery',
+    'setDutyCycle',
+    'setCarrierSense',
+    'offerFirmware',
+    'schedule',
+    'getDevice',
+    'getWriteLog',
+    'getConfigPending',
+    'getPoisonedChannels',
+    'getMissingParamsetDescriptions',
+    'getTempKey',
+    'getInstallMode',
+]);
+
+function send(response, status, body) {
+    const json = JSON.stringify(body === undefined ? null : body);
+    response.writeHead(status, {'Content-Type': 'application/json', 'Content-Length': Buffer.byteLength(json)});
+    response.end(json);
+}
+
+function readBody(request) {
+    return new Promise((resolve, reject) => {
+        const chunks = [];
+        request.on('data', (chunk) => chunks.push(chunk));
+        request.on('end', () => resolve(Buffer.concat(chunks).toString('utf8')));
+        request.on('error', reject);
+    });
+}
+
+/**
+ * The scenario API over HTTP, for a simulator that runs in a process of its own (the CLI's
+ * `--control-port`). Loopback only.
+ *
+ * - `POST /scenario/<method>` with a JSON array of arguments, `GET /scenario/<method>` without;
+ *   answers `{"result": …}`, a fault as 400 `{"error", "faultCode", "faultString"}`, an unknown
+ *   method as 404.
+ * - `GET /ports`: the ports the simulator listens on.
+ *
+ * `setValue` is the device reporting a value, as a behaviour script does (`sim.api`), not a client
+ * writing one.
+ *
+ * @param {object} sim a HmSim
+ * @param {object} options
+ * @param {number} options.port
+ * @param {function} [options.log] (…args) for errors
+ * @returns {Promise<http.Server>} once listening
+ */
+function createControlServer(sim, {port, log = () => {}}) {
+    const server = http.createServer(async (request, response) => {
+        const url = new URL(request.url, 'http://localhost');
+        if (url.pathname === '/ports' && request.method === 'GET') {
+            send(response, 200, sim.ports);
+            return;
+        }
+
+        const match = /^\/scenario\/([A-Za-z]+)$/.exec(url.pathname);
+        if (!match || !['GET', 'POST'].includes(request.method)) {
+            send(response, 404, {error: 'not found'});
+            return;
+        }
+        const method = match[1];
+        if (!SCENARIO_METHODS.has(method) || typeof sim[method] !== 'function') {
+            send(response, 404, {error: `unknown scenario call ${method}`});
+            return;
+        }
+
+        let args = [];
+        if (request.method === 'POST') {
+            const body = await readBody(request);
+            try {
+                args = body.trim() === '' ? [] : JSON.parse(body);
+            } catch (error) {
+                send(response, 400, {error: `body is no JSON: ${error.message}`});
+                return;
+            }
+            if (!Array.isArray(args)) {
+                send(response, 400, {error: 'body must be a JSON array of arguments'});
+                return;
+            }
+        }
+
+        try {
+            const result =
+                method === 'setValue'
+                    ? sim.setValue(args[0], args[1], args[2], args[3], {internal: true})
+                    : await sim[method](...args);
+            send(response, 200, {result});
+        } catch (error) {
+            if (error.faultCode !== undefined) {
+                send(response, 400, {error: error.message, faultCode: error.faultCode, faultString: error.faultString});
+                return;
+            }
+            log('control', method, error.stack || error.message);
+            send(response, 500, {error: error.message});
+        }
+    });
+
+    return new Promise((resolve, reject) => {
+        server.once('error', reject);
+        server.listen(port, '127.0.0.1', () => {
+            server.removeListener('error', reject);
+            resolve(server);
+        });
+    });
+}
+
+module.exports = {createControlServer, SCENARIO_METHODS};

package/lib/faults.d.ts

@@ -0,0 +1,48 @@
+// Type declarations for lib/faults.js (`require('hm-simulator/lib/faults.js')`).
+
+/** An XML-RPC fault: what the interface process answers. */
+export interface FaultEntry {
+    faultCode: number;
+    faultString: string;
+}
+
+/** The names of the fault table's entries. */
+export type FaultName =
+    | 'unknownMethod'
+    | 'unknownInstance'
+    | 'unknownParamset'
+    | 'unknownParameter'
+    | 'unknownLink'
+    | 'readOnly'
+    | 'typeError'
+    | 'outOfRange'
+    | 'invalidValue'
+    | 'notSupported'
+    | 'notReachable'
+    | 'invalidArguments';
+
+/** A fault table: every name above, plus whatever an override added. */
+export type FaultTable = Record<FaultName, FaultEntry> & Record<string, FaultEntry>;
+
+/** hmipserver 3.89.8, measured 2026-09-05 - the default. */
+export declare const DEFAULT_FAULTS: FaultTable;
+/** rfd 3.89.8, measured 2026-09-05. */
+export declare const BIDCOS_FAULTS: FaultTable;
+/** The measured tables by name, for `new HmSim({faults: FAULT_TABLES.bidcos})`. */
+export declare const FAULT_TABLES: {hmip: FaultTable; bidcos: FaultTable};
+
+/** Error carrying an XML-RPC fault. */
+export declare class RpcFault extends Error {
+    constructor(faultCode: number, faultString: string, detail?: string);
+    faultCode: number;
+    faultString: string;
+    detail?: string;
+    /** The struct a BIN-RPC fault carries as its body. */
+    toStruct(): FaultEntry;
+}
+
+/** A fault factory bound to a (possibly overridden) table. */
+export declare function createFaults(overrides?: Partial<Record<FaultName | (string & {}), Partial<FaultEntry>>>): {
+    table: FaultTable;
+    fault: (name: FaultName | (string & {}), detail?: string) => RpcFault;
+};

package/lib/method-help.js

@@ -19,6 +19,10 @@ module.exports = {
     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',
+    logLevel: 'int logLevel(int level) - set the log level of the interface process; without a level read it',
+    changeKey: 'void changeKey(string passphrase) - change the security key of the interface',
+    refreshDeployedDeviceFirmwareList:
+        'void refreshDeployedDeviceFirmwareList() - read the directory of deployed device firmware again',
     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:
@@ -51,4 +55,18 @@ module.exports = {
     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',
+    getKeyMismatchDevice:
+        'string getKeyMismatchDevice(boolean reset) - the serial of a device that holds another key, reset clears it',
+    addDevice: 'struct addDevice(string serialNumber) - pair one device by its serial; BidCos only',
+    suppressServiceMessages:
+        'void suppressServiceMessages(string channelAddress, string parameter, boolean suppress) - suppress a service message, an empty parameter for all; HmIP only',
+    getSuppressedServiceMessages:
+        'array getSuppressedServiceMessages(string channelAddress) - the suppressed service parameters of a channel; HmIP only',
+    getMetadata: 'ValueType getMetadata(string address, string key) - a stored metadata value',
+    setMetadata: 'void setMetadata(string address, string key, ValueType value) - store a metadata value',
+    getAllMetadata: 'struct getAllMetadata(string address) - every metadata value of an address; BidCos only',
+    listReplaceableDevices: 'array listReplaceableDevices(string address) - the devices a device can replace',
+    getVersion: 'string getVersion() - the version of the interface process',
+    getLGWStatus: 'struct getLGWStatus() - the state of the LAN gateways',
+    setInterfaceClock: 'void setInterfaceClock(int utcSeconds, int offsetMinutes) - set the clock sent to the devices',
 };

package/lib/paramset-index.js

@@ -0,0 +1,107 @@
+'use strict';
+
+/**
+ * Finds a paramset description for a device whose firmware has none.
+ *
+ * The descriptions are keyed `<interface>/<type>/<firmware>/<version>/<channelType>/<paramset>`,
+ * so a device whose firmware is older or newer than every dump in the set has no description at
+ * all, although the channel layout of the same type and VERSION is the same. The index groups the
+ * keys by everything but the firmware and picks the nearest firmware: the highest one at or below
+ * the device's, else the lowest one above it.
+ */
+
+/**
+ * Firmware as numbers, part by part; `2.31.25.20180526` is `[2, 31, 25, 20180526]`, so a dated
+ * build sorts after its undated version. A part that is no number counts as -1.
+ * @param {string} firmware
+ * @returns {number[]}
+ */
+function firmwareParts(firmware) {
+    return String(firmware)
+        .split('.')
+        .map((part) => {
+            const number = Number.parseInt(part, 10);
+            return Number.isNaN(number) ? -1 : number;
+        });
+}
+
+/**
+ * @param {number[]} a
+ * @param {number[]} b
+ * @returns {number} < 0, 0 or > 0
+ */
+function compareFirmware(a, b) {
+    const length = Math.max(a.length, b.length);
+    for (let index = 0; index < length; index++) {
+        const left = a[index] === undefined ? -1 : a[index];
+        const right = b[index] === undefined ? -1 : b[index];
+        if (left !== right) {
+            return left - right;
+        }
+    }
+    return 0;
+}
+
+class ParamsetIndex {
+    /**
+     * @param {object} descriptions key -> paramset description
+     */
+    constructor(descriptions) {
+        this.descriptions = descriptions;
+        /** `<interface>/<type>/<version>/<channelType>/<paramset>` -> [{parts, key}] sorted by firmware */
+        this.groups = undefined;
+    }
+
+    build() {
+        const groups = new Map();
+        for (const key of Object.keys(this.descriptions)) {
+            const fields = key.split('/');
+            if (fields.length !== 6) {
+                continue;
+            }
+            const [prefix, type, firmware, version, channelType, paramset] = fields;
+            const group = [prefix, type, version, channelType, paramset].join('/');
+            if (!groups.has(group)) {
+                groups.set(group, []);
+            }
+            groups.get(group).push({parts: firmwareParts(firmware), key});
+        }
+        for (const entries of groups.values()) {
+            entries.sort((a, b) => compareFirmware(a.parts, b.parts));
+        }
+        this.groups = groups;
+    }
+
+    /**
+     * The key of the nearest firmware for a key that has no description.
+     * @param {string} key `<interface>/<type>/<firmware>/<version>/<channelType>/<paramset>`
+     * @returns {string|null}
+     */
+    nearest(key) {
+        const fields = key.split('/');
+        if (fields.length !== 6) {
+            return null;
+        }
+        if (!this.groups) {
+            this.build();
+        }
+        const [prefix, type, firmware, version, channelType, paramset] = fields;
+        const entries = this.groups.get([prefix, type, version, channelType, paramset].join('/'));
+        if (!entries || entries.length === 0) {
+            return null;
+        }
+
+        const wanted = firmwareParts(firmware);
+        let below = null;
+        for (const entry of entries) {
+            if (compareFirmware(entry.parts, wanted) <= 0) {
+                below = entry;
+            } else {
+                return (below || entry).key;
+            }
+        }
+        return below.key;
+    }
+}
+
+module.exports = {ParamsetIndex, firmwareParts, compareFirmware};