wiim2mqtt 0.1.0

package/lib/install.js

@@ -0,0 +1,251 @@
+/**
+ * --install / --uninstall: run wiim2mqtt as a systemd template service, one instance per device.
+ *
+ *   wiim2mqtt@<name>.service      instance = --name (= mqtt topic prefix)
+ *   /etc/wiim2mqtt/<name>.env     per-instance config (WIIM2MQTT_* variables)
+ *   system user wiim2mqtt         shared by all instances
+ *
+ * Mirrors lgtv2mqtt's lib/install.js; keep the two in sync.
+ */
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import {execFileSync} from 'node:child_process';
+
+export const SERVICE = 'wiim2mqtt';
+const UNIT_PATH = `/etc/systemd/system/${SERVICE}@.service`;
+const CONF_DIR = `/etc/${SERVICE}`;
+const STATE_DIR = `/var/lib/${SERVICE}`;
+/** first callback port handed out by --install when --callback-port is not given */
+export const CALLBACK_PORT_BASE = 49200;
+
+// options that are written to the env file (everything except --name, which is the instance)
+const ENV_OPTIONS = [
+    'address',
+    'apiUrl',
+    'mqttUrl',
+    'mqttUsername',
+    'mqttPassword',
+    'jsonPayloads',
+    'haDiscovery',
+    'haPrefix',
+    'rawSet',
+    'upnp',
+    'upnpPort',
+    'callbackHost',
+    'callbackPort',
+    'pollInterval',
+    'positionInterval',
+    'albumArtData',
+    'verbosity',
+];
+
+function run(cmd, args) {
+    return execFileSync(cmd, args, {stdio: ['ignore', 'pipe', 'inherit']})
+        .toString()
+        .trim();
+}
+
+export function envVarName(option) {
+    return 'WIIM2MQTT_' + option.replace(/[A-Z]/g, (c) => '_' + c).toUpperCase();
+}
+
+export function instanceName(name) {
+    if (!/^[A-Za-z0-9_.-]+$/.test(name)) {
+        throw new Error(`--name "${name}" cannot be used as systemd instance name (allowed: letters, digits, _ . -)`);
+    }
+    return name;
+}
+
+function envPath(name) {
+    return path.join(CONF_DIR, `${name}.env`);
+}
+
+function unitName(name) {
+    return `${SERVICE}@${name}.service`;
+}
+
+export function unitFile(execStart) {
+    return `[Unit]
+Description=wiim2mqtt %i - WiiM to MQTT bridge
+Documentation=https://github.com/hobbyquaker/wiim2mqtt
+After=network-online.target
+Wants=network-online.target
+
+[Service]
+Type=simple
+EnvironmentFile=${CONF_DIR}/%i.env
+Environment=WIIM2MQTT_NAME=%i
+ExecStart=${execStart}
+Restart=on-failure
+RestartSec=10
+SyslogIdentifier=${SERVICE}@%i
+SyslogLevelPrefix=true
+User=${SERVICE}
+Group=${SERVICE}
+StateDirectory=${SERVICE}/%i
+NoNewPrivileges=true
+ProtectSystem=full
+ProtectHome=true
+PrivateTmp=true
+
+[Install]
+WantedBy=multi-user.target
+`;
+}
+
+/**
+ * Pick a deterministic callback port for a new instance: the lowest port >= CALLBACK_PORT_BASE
+ * not used by another installed instance's env file.
+ */
+export function chooseCallbackPort(usedPorts, base = CALLBACK_PORT_BASE) {
+    const used = new Set(usedPorts.map(Number));
+    let port = base;
+    while (used.has(port)) {
+        port++;
+    }
+    return port;
+}
+
+/** Build the env file content from the parsed CLI options. */
+export function envFile(argv) {
+    const lines = [
+        `# wiim2mqtt instance "${argv.name}" - read by ${unitName(argv.name)}.`,
+        `# Edit and run: systemctl restart ${unitName(argv.name)}`,
+    ];
+    for (const option of ENV_OPTIONS) {
+        const value = argv[option];
+        if (value === undefined || value === null || value === '') {
+            continue;
+        }
+        if (option === 'callbackPort' && Number(value) === 0) {
+            continue;
+        }
+        lines.push(`${envVarName(option)}=${String(value).replace(/\n/g, ' ')}`);
+    }
+    return lines.join('\n') + '\n';
+}
+
+function installedInstances() {
+    if (!fs.existsSync(CONF_DIR)) {
+        return [];
+    }
+    return fs
+        .readdirSync(CONF_DIR)
+        .filter((f) => f.endsWith('.env'))
+        .map((f) => f.slice(0, -4));
+}
+
+function installedCallbackPorts(except) {
+    const ports = [];
+    for (const instance of installedInstances()) {
+        if (instance === except) {
+            continue;
+        }
+        const match = fs.readFileSync(envPath(instance), 'utf8').match(/^WIIM2MQTT_CALLBACK_PORT=(\d+)$/m);
+        if (match) {
+            ports.push(Number(match[1]));
+        }
+    }
+    return ports;
+}
+
+function requireRoot(option) {
+    if (os.platform() !== 'linux') {
+        throw new Error(`${option} is only supported on Linux with systemd`);
+    }
+    if (typeof process.getuid === 'function' && process.getuid() !== 0) {
+        throw new Error(`${option} must run as root, e.g. sudo wiim2mqtt ${option} --name <name> ...`);
+    }
+    if (!fs.existsSync('/run/systemd/system')) {
+        throw new Error('systemd is not running on this system');
+    }
+}
+
+/**
+ * Install the instance `argv.name` as systemd service using the other CLI options as its
+ * configuration, then enable and start it. Must run as root.
+ */
+export function installService(argv, log) {
+    requireRoot('--install');
+    const name = instanceName(argv.name);
+    const execStart = `${process.execPath} ${fs.realpathSync(process.argv[1])}`;
+
+    // shared system user
+    try {
+        run('id', ['-u', SERVICE]);
+    } catch {
+        log(`creating system user ${SERVICE}`);
+        run('useradd', [
+            '--system',
+            '--no-create-home',
+            '--home-dir',
+            STATE_DIR,
+            '--shell',
+            '/usr/sbin/nologin',
+            SERVICE,
+        ]);
+    }
+
+    // config
+    fs.mkdirSync(CONF_DIR, {recursive: true, mode: 0o750});
+    const conf = envPath(name);
+    if (!argv.callbackPort && argv.upnp !== false) {
+        // a fixed port per instance keeps firewall rules stable (and the docs honest)
+        let port;
+        if (fs.existsSync(conf)) {
+            const match = fs.readFileSync(conf, 'utf8').match(/^WIIM2MQTT_CALLBACK_PORT=(\d+)$/m);
+            port = match && Number(match[1]);
+        }
+        argv = {...argv, callbackPort: port || chooseCallbackPort(installedCallbackPorts(name))};
+        log(`upnp event listener port: ${argv.callbackPort} (WIIM2MQTT_CALLBACK_PORT)`);
+    }
+    if (fs.existsSync(conf)) {
+        fs.copyFileSync(conf, conf + '.bak');
+        log(`existing ${conf} backed up to ${conf}.bak`);
+    }
+    fs.writeFileSync(conf, envFile(argv), {mode: 0o640});
+    run('chown', ['-R', `root:${SERVICE}`, CONF_DIR]);
+    log(`wrote ${conf}`);
+
+    // template unit (shared by all instances, rewritten so ExecStart follows node/package updates)
+    fs.writeFileSync(UNIT_PATH, unitFile(execStart), {mode: 0o644});
+    log(`wrote ${UNIT_PATH} (ExecStart=${execStart})`);
+
+    run('systemctl', ['daemon-reload']);
+    run('systemctl', ['enable', '--now', unitName(name)]);
+    const others = installedInstances().filter((i) => i !== name);
+    if (others.length > 0) {
+        log(`other instances: ${others.map(unitName).join(', ')}`);
+    }
+    log(`${unitName(name)} enabled and started. logs: journalctl -u ${unitName(name)} -f`);
+}
+
+/** Stop, disable and remove the instance `argv.name`; remove the template when it was the last one. */
+export function uninstallService(argv, log) {
+    requireRoot('--uninstall');
+    const name = instanceName(argv.name);
+    const unit = unitName(name);
+
+    try {
+        run('systemctl', ['disable', '--now', unit]);
+    } catch {
+        // not installed
+    }
+    const conf = envPath(name);
+    if (fs.existsSync(conf)) {
+        fs.rmSync(conf);
+        log(`removed ${conf}`);
+    }
+    const remaining = installedInstances();
+    if (remaining.length === 0 && fs.existsSync(UNIT_PATH)) {
+        fs.rmSync(UNIT_PATH);
+        log(`removed ${UNIT_PATH} (no instances left)`);
+    }
+    run('systemctl', ['daemon-reload']);
+    log(`${unit} removed.`);
+    if (remaining.length > 0) {
+        log(`remaining instances: ${remaining.map(unitName).join(', ')}`);
+    }
+}

package/lib/log.js

@@ -0,0 +1,74 @@
+/**
+ * Minimal leveled logger (debug/info/warn/error).
+ *
+ * Two output formats:
+ *  - journal: when stdout is connected to the systemd journal (JOURNAL_STREAM is set) or
+ *    forced via WIIM2MQTT_LOG_FORMAT=journal. No timestamp (the journal has its own) and
+ *    the severity as sd-daemon prefix `<N>` which journald turns into the PRIORITY field
+ *    (`journalctl -p warning` works). Identifier/pid come from SyslogIdentifier= in the unit.
+ *  - text: `2026-08-21 14:30:25.761 <info>  message`, colored on a tty.
+ */
+
+import util from 'node:util';
+
+const LEVELS = {debug: 0, info: 1, warn: 2, error: 3};
+const SYSLOG = {debug: 7, info: 6, warn: 4, error: 3};
+const COLOR = {
+    debug: '\x1b[44m<debug>\x1b[49m',
+    info: '\x1b[30;42m<info> \x1b[39;49m',
+    warn: '\x1b[30;43m<warn> \x1b[39;49m',
+    error: '\x1b[37;1;41m<error>\x1b[49;22;39m',
+};
+const PLAIN = {debug: '<debug>', info: '<info> ', warn: '<warn> ', error: '<error>'};
+
+function timestamp(d = new Date()) {
+    const p = (n, l = 2) => String(n).padStart(l, '0');
+    return (
+        `${d.getFullYear()}-${p(d.getMonth() + 1)}-${p(d.getDate())} ` +
+        `${p(d.getHours())}:${p(d.getMinutes())}:${p(d.getSeconds())}.${p(d.getMilliseconds(), 3)}`
+    );
+}
+
+export function detectFormat(env = process.env, stream = process.stdout) {
+    if (env.WIIM2MQTT_LOG_FORMAT === 'journal' || env.WIIM2MQTT_LOG_FORMAT === 'text') {
+        return env.WIIM2MQTT_LOG_FORMAT;
+    }
+    if (env.JOURNAL_STREAM && !stream.isTTY) {
+        return 'journal';
+    }
+    return 'text';
+}
+
+export function createLogger(options = {}) {
+    const format = options.format || detectFormat();
+    const color = options.color !== undefined ? options.color : format === 'text' && Boolean(process.stdout.isTTY);
+    const write = options.write || ((line) => process.stdout.write(line + '\n'));
+    let threshold = LEVELS.info;
+
+    const log = {};
+    log.format = format;
+    log.setLevel = (level) => {
+        if (!(level in LEVELS)) {
+            throw new Error(`unknown log level ${level}`);
+        }
+        threshold = LEVELS[level];
+    };
+    log.formatLine = (level, args) => {
+        // util.format handles printf-style strings and pretty-prints objects like console.log
+        const msg = util.format(...args).replace(/\n/g, format === 'journal' ? '\n    ' : '\n');
+        if (format === 'journal') {
+            return `<${SYSLOG[level]}>${msg}`;
+        }
+        return `${timestamp()} ${(color ? COLOR : PLAIN)[level]} ${msg}`;
+    };
+    for (const level of Object.keys(LEVELS)) {
+        log[level] = (...args) => {
+            if (LEVELS[level] >= threshold) {
+                write(log.formatLine(level, args));
+            }
+        };
+    }
+    return log;
+}
+
+export default createLogger();

package/lib/payload.js

@@ -0,0 +1,112 @@
+/**
+ * MQTT payload helpers (mqtt-smarthome conventions).
+ */
+
+/**
+ * Converts an incoming MQTT payload (Buffer or string) to a JS value.
+ * Accepts plain values (numbers, booleans, strings), JSON objects/arrays and
+ * mqtt-smarthome style JSON {val: ...} (unwrapped to the value).
+ * Returns undefined for empty payloads.
+ */
+export function parsePayload(payload) {
+    const trimmed = String(payload).trim();
+    if (trimmed === '') {
+        return undefined;
+    }
+    if (trimmed.startsWith('{') || trimmed.startsWith('[')) {
+        try {
+            const parsed = JSON.parse(trimmed);
+            if (parsed && typeof parsed === 'object' && !Array.isArray(parsed) && 'val' in parsed) {
+                return parsed.val;
+            }
+            return parsed;
+        } catch {
+            // not JSON, treat as string
+        }
+    }
+    if (trimmed === 'true') {
+        return true;
+    }
+    if (trimmed === 'false') {
+        return false;
+    }
+    if (/^-?\d+(\.\d+)?$/.test(trimmed)) {
+        return Number(trimmed);
+    }
+    return trimmed;
+}
+
+/**
+ * Interprets a parsed payload as boolean: true/false, 1/0, "on"/"off", "yes"/"no".
+ * Returns undefined if the value is not recognized.
+ */
+export function toBoolean(value) {
+    if (typeof value === 'boolean') {
+        return value;
+    }
+    if (typeof value === 'number') {
+        return value !== 0;
+    }
+    if (typeof value === 'string') {
+        const s = value.trim().toLowerCase();
+        if (['true', '1', 'on', 'yes'].includes(s)) {
+            return true;
+        }
+        if (['false', '0', 'off', 'no'].includes(s)) {
+            return false;
+        }
+    }
+    return undefined;
+}
+
+/**
+ * Interprets a parsed payload as volume 0..100 (integer). Returns undefined if not a number.
+ */
+export function toVolume(value) {
+    const n = typeof value === 'number' ? value : Number(String(value).trim());
+    if (!Number.isFinite(n)) {
+        return undefined;
+    }
+    return Math.min(100, Math.max(0, Math.round(n)));
+}
+
+/**
+ * Remembers the last value per item and produces outgoing status payloads,
+ * either plain or as {val, ts, lc} JSON.
+ */
+export class StatusTracker {
+    /**
+     * @param {object} options
+     * @param {boolean} [options.json] emit {val, ts, lc} objects instead of plain values
+     * @param {() => number} [options.now] clock, for tests
+     */
+    constructor({json = false, now = Date.now} = {}) {
+        this.json = json;
+        this.now = now;
+        this.state = new Map();
+    }
+
+    /** Last known value of an item (undefined if never seen). */
+    get(item) {
+        const entry = this.state.get(item);
+        return entry && entry.val;
+    }
+
+    /**
+     * Record a new value and return what to publish.
+     * @returns {{payload: *, changed: boolean}}
+     */
+    update(item, val) {
+        const ts = this.now();
+        const previous = this.state.get(item);
+        const changed = !previous || JSON.stringify(previous.val) !== JSON.stringify(val);
+        const lc = changed ? ts : previous.lc;
+        this.state.set(item, {val, ts, lc});
+        return {payload: this.json ? {val, ts, lc} : val, changed};
+    }
+
+    /** Forget an item (e.g. when it no longer applies). Returns true if it was known. */
+    delete(item) {
+        return this.state.delete(item);
+    }
+}