wiim2mqtt 0.1.0

package/lib/upnp.js

@@ -0,0 +1,535 @@
+/**
+ * Minimal UPnP client for one MediaRenderer: device description, SOAP actions and GENA
+ * event subscriptions with a single NOTIFY listener.
+ *
+ * Subscription lifecycle (ROADMAP W-9):
+ *  - SUBSCRIBE with TIMEOUT Second-1800, renew at timeout - 60 s.
+ *  - Any renewal failure (WiiM answers 412 after a while) → 'lost', UNSUBSCRIBE best effort,
+ *    fresh SUBSCRIBE with backoff 2 s … 60 s (cap), up to 5 min while the callback is unreachable.
+ *  - The initial NOTIFY must arrive within `initialNotifyTimeout` (30 s), otherwise the callback
+ *    is assumed unreachable → 'lost' with code ENOTIFY and the same retry loop.
+ */
+
+import {EventEmitter} from 'node:events';
+import dgram from 'node:dgram';
+import http from 'node:http';
+import {URL} from 'node:url';
+import {XMLParser} from 'fast-xml-parser';
+import {parsePropertySet, parseLastChange} from './didl.js';
+
+export const SERVICES = {
+    AVTransport: 'urn:schemas-upnp-org:service:AVTransport:1',
+    RenderingControl: 'urn:schemas-upnp-org:service:RenderingControl:1',
+    PlayQueue: 'urn:schemas-wiimu-com:service:PlayQueue:1',
+};
+
+export class UpnpError extends Error {
+    constructor(code, message, extra = {}) {
+        super(message);
+        this.name = 'UpnpError';
+        this.code = code;
+        Object.assign(this, extra);
+    }
+}
+
+const xml = new XMLParser({
+    ignoreAttributes: false,
+    attributeNamePrefix: '',
+    ignoreDeclaration: true,
+    removeNSPrefix: true,
+    parseTagValue: false,
+    trimValues: true,
+    isArray: (name) => name === 'service' || name === 'device',
+});
+
+function escapeXml(text) {
+    return String(text).replace(/&/g, '&amp;').replace(/</g, '&lt;').replace(/>/g, '&gt;').replace(/"/g, '&quot;');
+}
+
+/** Find the address this host uses to reach `host` (no packet is sent). */
+export function detectLocalAddress(host, port = 1900) {
+    return new Promise((resolve, reject) => {
+        const socket = dgram.createSocket('udp4');
+        socket.once('error', (err) => {
+            socket.close();
+            reject(err);
+        });
+        socket.connect(port, host, () => {
+            try {
+                const {address} = socket.address();
+                socket.close();
+                resolve(address);
+            } catch (err) {
+                socket.close();
+                reject(err);
+            }
+        });
+    });
+}
+
+/** Parse description.xml → {udn, friendlyName, model, manufacturer, services: {AVTransport: {controlURL, eventSubURL, serviceType}}} */
+export function parseDescription(body, baseUrl) {
+    const doc = xml.parse(body);
+    const root = doc.root;
+    const device = root && Array.isArray(root.device) ? root.device[0] : root && root.device;
+    if (!device) {
+        throw new UpnpError('EDESCRIBE', 'description.xml without <device>');
+    }
+    const base = (root && root.URLBase) || baseUrl;
+    const services = {};
+    const list = device.serviceList && device.serviceList.service;
+    for (const service of Array.isArray(list) ? list : list ? [list] : []) {
+        const name = Object.keys(SERVICES).find((key) => SERVICES[key] === service.serviceType);
+        const key = name || String(service.serviceType).split(':').slice(-2, -1)[0];
+        services[key] = {
+            serviceType: service.serviceType,
+            serviceId: service.serviceId,
+            controlURL: new URL(service.controlURL, base).toString(),
+            eventSubURL: service.eventSubURL ? new URL(service.eventSubURL, base).toString() : undefined,
+        };
+    }
+    return {
+        udn: device.UDN,
+        friendlyName: device.friendlyName,
+        model: device.modelName,
+        manufacturer: device.manufacturer,
+        deviceType: device.deviceType,
+        services,
+    };
+}
+
+/** Parse a SOAP response body → the action's out arguments as {Name: value} */
+export function parseSoapResponse(body, action) {
+    const doc = xml.parse(body);
+    const env = doc.Envelope;
+    const bodyEl = env && env.Body;
+    if (!bodyEl) {
+        throw new UpnpError('ESOAP', `${action}: not a soap envelope`);
+    }
+    if (bodyEl.Fault) {
+        const detail = bodyEl.Fault.detail && bodyEl.Fault.detail.UPnPError;
+        throw new UpnpError(
+            'ESOAP',
+            `${action}: upnp error ${detail ? detail.errorCode : ''} ${detail ? detail.errorDescription : bodyEl.Fault.faultstring || ''}`.trim(),
+            {
+                errorCode: detail ? Number(detail.errorCode) : undefined,
+                errorDescription: detail ? detail.errorDescription : undefined,
+            },
+        );
+    }
+    const response = bodyEl[`${action}Response`];
+    if (!response || typeof response !== 'object') {
+        return {};
+    }
+    const result = {};
+    for (const [key, value] of Object.entries(response)) {
+        if (key === 'xmlns:u' || key === 'xmlns') {
+            continue;
+        }
+        result[key] =
+            value === null || value === undefined
+                ? ''
+                : typeof value === 'object'
+                  ? (value['#text'] ?? '')
+                  : String(value);
+    }
+    return result;
+}
+
+function httpRequest(url, {method = 'GET', headers = {}, body, timeout = 10000} = {}) {
+    return new Promise((resolve, reject) => {
+        const req = http.request(url, {method, headers, timeout}, (res) => {
+            const chunks = [];
+            res.on('data', (c) => chunks.push(c));
+            res.on('end', () =>
+                resolve({
+                    statusCode: res.statusCode,
+                    headers: res.headers,
+                    body: Buffer.concat(chunks).toString('utf8'),
+                }),
+            );
+            res.on('error', reject);
+        });
+        req.on('timeout', () => req.destroy(new UpnpError('ETIMEDOUT', `${method} ${url}: timeout`)));
+        req.on('error', (err) =>
+            reject(
+                err instanceof UpnpError
+                    ? err
+                    : new UpnpError('ECONNFAILED', `${method} ${url}: ${err.message}`, {cause: err}),
+            ),
+        );
+        if (body !== undefined) {
+            req.write(body);
+        }
+        req.end();
+    });
+}
+
+export class UpnpClient extends EventEmitter {
+    /**
+     * @param {object} options
+     * @param {string} options.host device address
+     * @param {number} [options.port] description port (49152)
+     * @param {string} [options.callbackHost] address the device uses to reach us (default: detected)
+     * @param {number} [options.callbackPort] listener port (0 = ephemeral)
+     * @param {number} [options.subscriptionTimeout] requested GENA timeout in seconds
+     * @param {number} [options.initialNotifyTimeout] ms to wait for the initial NOTIFY
+     * @param {object} [options.log]
+     * @param {object} [options.timers] {setTimeout, clearTimeout} for tests
+     */
+    constructor({
+        host,
+        port = 49152,
+        callbackHost,
+        callbackPort = 0,
+        subscriptionTimeout = 1800,
+        initialNotifyTimeout = 30000,
+        log,
+        timers,
+    }) {
+        super();
+        this.host = host;
+        this.port = port;
+        this.baseUrl = `http://${host}:${port}`;
+        this.callbackHost = callbackHost;
+        this.callbackPort = callbackPort;
+        this.subscriptionTimeout = subscriptionTimeout;
+        this.initialNotifyTimeout = initialNotifyTimeout;
+        this.log = log || {debug() {}, info() {}, warn() {}};
+        this.timers = timers || {setTimeout, clearTimeout};
+        this.description = undefined;
+        this.server = undefined;
+        this.subscriptions = new Map(); // service name → {sid, timeout, timer, backoff, initialTimer, stopped}
+        this.stopped = false;
+    }
+
+    async describe() {
+        const res = await httpRequest(`${this.baseUrl}/description.xml`);
+        if (res.statusCode !== 200) {
+            throw new UpnpError('EDESCRIBE', `description.xml: http ${res.statusCode}`);
+        }
+        this.description = parseDescription(res.body, this.baseUrl);
+        return this.description;
+    }
+
+    service(name) {
+        const service = this.description && this.description.services[name];
+        if (!service) {
+            throw new UpnpError('ENOSERVICE', `service ${name} not offered by the device`);
+        }
+        return service;
+    }
+
+    /** Invoke a SOAP action. */
+    async action(serviceName, actionName, args = {}) {
+        const service = this.service(serviceName);
+        const argXml = Object.entries(args)
+            .map(([k, v]) => `<${k}>${escapeXml(v)}</${k}>`)
+            .join('');
+        const body =
+            '<?xml version="1.0" encoding="utf-8"?>' +
+            '<s:Envelope xmlns:s="http://schemas.xmlsoap.org/soap/envelope/" s:encodingStyle="http://schemas.xmlsoap.org/soap/encoding/">' +
+            `<s:Body><u:${actionName} xmlns:u="${service.serviceType}">${argXml}</u:${actionName}></s:Body></s:Envelope>`;
+        this.log.debug('upnp >', serviceName, actionName, args);
+        const res = await httpRequest(service.controlURL, {
+            method: 'POST',
+            headers: {
+                'Content-Type': 'text/xml; charset="utf-8"',
+                SOAPACTION: `"${service.serviceType}#${actionName}"`,
+                'Content-Length': Buffer.byteLength(body),
+            },
+            body,
+        });
+        this.log.debug(
+            'upnp <',
+            serviceName,
+            actionName,
+            res.statusCode,
+            res.body.length > 500 ? res.body.slice(0, 500) + '…' : res.body,
+        );
+        const result = parseSoapResponse(res.body, actionName);
+        if (res.statusCode !== 200) {
+            throw new UpnpError('ESOAP', `${actionName}: http ${res.statusCode}`, {statusCode: res.statusCode});
+        }
+        return result;
+    }
+
+    /** AVTransport GetInfoEx (LinkPlay extension): everything about the current track in one call. */
+    async getInfoEx() {
+        const r = await this.action('AVTransport', 'GetInfoEx', {InstanceID: 0});
+        return {
+            transportState: r.CurrentTransportState,
+            status: r.CurrentTransportStatus,
+            track: r.Track,
+            duration: r.TrackDuration,
+            position: r.RelTime,
+            metadata: r.TrackMetaData,
+            uri: r.TrackURI,
+            loopMode: r.LoopMode,
+            playMedium: r.PlayMedium,
+            trackSource: r.TrackSource,
+            volume: r.CurrentVolume,
+            mute: r.CurrentMute,
+            slaveList: r.SlaveList,
+            raw: r,
+        };
+    }
+
+    /** PlayQueue GetKeyMapping → {maxNumber, presets: [{number, name, source, pic}]} */
+    async getKeyMapping() {
+        const r = await this.action('PlayQueue', 'GetKeyMapping', {});
+        const queue = r.QueueContext || '';
+        const doc = xml.parse(queue);
+        const context = doc.KeyList || doc.QueueContext || doc;
+        const presets = [];
+        let maxNumber = 0;
+        const walk = (obj) => {
+            if (!obj || typeof obj !== 'object') {
+                return;
+            }
+            for (const [key, value] of Object.entries(obj)) {
+                if (/^MaxNumber$/i.test(key)) {
+                    maxNumber = Number(value) || maxNumber;
+                } else if (/^Key\d+$/i.test(key) && value && typeof value === 'object') {
+                    presets.push({
+                        number: Number(key.replace(/^Key/i, '')),
+                        name: String(value.Name || '').replace(/_#~.*$/, ''),
+                        source: String(value.Source || ''),
+                        pic: String(value.PicUrl || ''),
+                        url: String(value.Url || ''),
+                    });
+                } else if (value && typeof value === 'object') {
+                    walk(value);
+                }
+            }
+        };
+        walk(context);
+        presets.sort((a, b) => a.number - b.number);
+        return {maxNumber: maxNumber || presets.length, presets: presets.filter((p) => p.name || p.url)};
+    }
+
+    /*
+     * GENA
+     */
+
+    async startListener() {
+        if (this.server) {
+            return;
+        }
+        if (!this.callbackHost) {
+            this.callbackHost = await detectLocalAddress(this.host);
+        }
+        this.server = http.createServer((req, res) => this.handleNotify(req, res));
+        await new Promise((resolve, reject) => {
+            this.server.once('error', reject);
+            this.server.listen(this.callbackPort, '0.0.0.0', () => {
+                this.server.off('error', reject);
+                this.callbackPort = this.server.address().port;
+                resolve();
+            });
+        });
+        this.log.debug('upnp listener', this.callbackUrl('<service>'));
+    }
+
+    callbackUrl(serviceName) {
+        return `http://${this.callbackHost}:${this.callbackPort}/notify/${serviceName}`;
+    }
+
+    handleNotify(req, res) {
+        const chunks = [];
+        req.on('data', (c) => chunks.push(c));
+        req.on('end', () => {
+            const body = Buffer.concat(chunks).toString('utf8');
+            const sid = req.headers.sid;
+            const serviceName = String(req.url || '').split('/')[2];
+            const sub = this.subscriptions.get(serviceName);
+            if (req.method !== 'NOTIFY' || !sub || sub.sid !== sid) {
+                this.log.debug('upnp < notify ignored', req.method, req.url, sid);
+                res.writeHead(412);
+                res.end();
+                return;
+            }
+            res.writeHead(200);
+            res.end();
+            this.log.debug('upnp < notify', serviceName, body.length > 800 ? body.slice(0, 800) + '…' : body);
+            if (sub.initialTimer) {
+                this.timers.clearTimeout(sub.initialTimer);
+                sub.initialTimer = undefined;
+            }
+            sub.backoff = 0;
+            let variables;
+            try {
+                variables = parsePropertySet(body);
+                if (variables.LastChange !== undefined) {
+                    variables = {...variables, ...parseLastChange(variables.LastChange)};
+                    delete variables.LastChange;
+                }
+            } catch (err) {
+                this.log.warn('upnp notify parse error', err.message);
+                return;
+            }
+            this.emit('event', {service: serviceName, variables, raw: body});
+        });
+    }
+
+    /** Subscribe to the given services (names from SERVICES) and keep the subscriptions alive. */
+    async subscribe(serviceNames) {
+        await this.startListener();
+        this.stopped = false;
+        for (const name of serviceNames) {
+            if (!this.description.services[name] || !this.description.services[name].eventSubURL) {
+                this.log.debug('upnp service', name, 'not evented on this device');
+                continue;
+            }
+            if (!this.subscriptions.has(name)) {
+                this.subscriptions.set(name, {sid: undefined, timer: undefined, initialTimer: undefined, backoff: 0});
+            }
+            await this.doSubscribe(name);
+        }
+    }
+
+    async doSubscribe(name) {
+        const sub = this.subscriptions.get(name);
+        if (!sub || this.stopped) {
+            return;
+        }
+        const service = this.service(name);
+        try {
+            const res = await httpRequest(service.eventSubURL, {
+                method: 'SUBSCRIBE',
+                headers: {
+                    CALLBACK: `<${this.callbackUrl(name)}>`,
+                    NT: 'upnp:event',
+                    TIMEOUT: `Second-${this.subscriptionTimeout}`,
+                },
+            });
+            if (res.statusCode !== 200 || !res.headers.sid) {
+                throw new UpnpError('ESUBSCRIBE', `${name}: subscribe answered http ${res.statusCode}`, {
+                    statusCode: res.statusCode,
+                });
+            }
+            sub.sid = res.headers.sid;
+            sub.timeout = parseTimeout(res.headers.timeout, this.subscriptionTimeout);
+            this.scheduleRenew(name);
+            sub.initialTimer = this.timers.setTimeout(() => {
+                sub.initialTimer = undefined;
+                this.onLost(
+                    name,
+                    new UpnpError(
+                        'ENOTIFY',
+                        `${name}: no initial event within ${this.initialNotifyTimeout / 1000} s (callback ${this.callbackUrl(name)} unreachable from the device?)`,
+                    ),
+                );
+            }, this.initialNotifyTimeout);
+            this.log.debug('upnp subscribed', name, sub.sid, 'timeout', sub.timeout);
+            this.emit('subscribed', {service: name, sid: sub.sid, timeout: sub.timeout});
+        } catch (err) {
+            this.onLost(name, err);
+        }
+    }
+
+    scheduleRenew(name) {
+        const sub = this.subscriptions.get(name);
+        if (!sub) {
+            return;
+        }
+        const delay = Math.max(30, sub.timeout - 60) * 1000;
+        this.timers.clearTimeout(sub.timer);
+        sub.timer = this.timers.setTimeout(() => this.renew(name), delay);
+    }
+
+    async renew(name) {
+        const sub = this.subscriptions.get(name);
+        if (!sub || !sub.sid || this.stopped) {
+            return;
+        }
+        const service = this.service(name);
+        try {
+            const res = await httpRequest(service.eventSubURL, {
+                method: 'SUBSCRIBE',
+                headers: {SID: sub.sid, TIMEOUT: `Second-${this.subscriptionTimeout}`},
+            });
+            if (res.statusCode !== 200) {
+                throw new UpnpError('ERENEW', `${name}: renew answered http ${res.statusCode}`, {
+                    statusCode: res.statusCode,
+                });
+            }
+            sub.timeout = parseTimeout(res.headers.timeout, this.subscriptionTimeout);
+            this.scheduleRenew(name);
+            this.log.debug('upnp renewed', name, sub.sid, 'timeout', sub.timeout);
+            this.emit('renewed', {service: name, sid: sub.sid, timeout: sub.timeout});
+        } catch (err) {
+            this.onLost(name, err);
+        }
+    }
+
+    /** A subscription failed (subscribe, renew or no initial event): clean up and retry with backoff. */
+    onLost(name, error) {
+        const sub = this.subscriptions.get(name);
+        if (!sub || this.stopped) {
+            return;
+        }
+        this.timers.clearTimeout(sub.timer);
+        this.timers.clearTimeout(sub.initialTimer);
+        sub.timer = undefined;
+        sub.initialTimer = undefined;
+        const oldSid = sub.sid;
+        sub.sid = undefined;
+        if (oldSid) {
+            this.doUnsubscribe(name, oldSid).catch(() => {});
+        }
+        sub.backoff = Math.min(sub.backoff ? sub.backoff * 2 : 2, error && error.code === 'ENOTIFY' ? 300 : 60);
+        this.emit('lost', {service: name, error, retryIn: sub.backoff});
+        sub.timer = this.timers.setTimeout(() => this.doSubscribe(name), sub.backoff * 1000);
+    }
+
+    /** Drop every subscription and subscribe afresh (after missed events). */
+    resubscribe(reason) {
+        for (const name of this.subscriptions.keys()) {
+            const sub = this.subscriptions.get(name);
+            sub.backoff = 0;
+            this.onLost(name, new UpnpError('ERESUBSCRIBE', `${name}: ${reason}`));
+        }
+    }
+
+    async doUnsubscribe(name, sid) {
+        const service = this.service(name);
+        await httpRequest(service.eventSubURL, {method: 'UNSUBSCRIBE', headers: {SID: sid}, timeout: 2000});
+    }
+
+    /** Stop renewals, unsubscribe everything (best effort) and close the listener. */
+    async stop() {
+        this.stopped = true;
+        const pending = [];
+        for (const [name, sub] of this.subscriptions) {
+            this.timers.clearTimeout(sub.timer);
+            this.timers.clearTimeout(sub.initialTimer);
+            if (sub.sid) {
+                pending.push(this.doUnsubscribe(name, sub.sid).catch(() => {}));
+                sub.sid = undefined;
+            }
+        }
+        await Promise.all(pending);
+        this.subscriptions.clear();
+        if (this.server) {
+            await new Promise((resolve) => this.server.close(() => resolve()));
+            this.server.closeAllConnections?.();
+            this.server = undefined;
+        }
+    }
+
+    /** true while at least one subscription has a SID */
+    get subscribed() {
+        for (const sub of this.subscriptions.values()) {
+            if (sub.sid) {
+                return true;
+            }
+        }
+        return false;
+    }
+}
+
+function parseTimeout(header, fallback) {
+    const match = /Second-(\d+)/i.exec(String(header || ''));
+    return match ? Number(match[1]) : fallback;
+}

package/package.json

@@ -0,0 +1,60 @@
+{
+  "name": "wiim2mqtt",
+  "version": "0.1.0",
+  "description": "Interface between WiiM (LinkPlay) audio streamers and MQTT, with Home Assistant discovery",
+  "type": "module",
+  "main": "index.js",
+  "preferGlobal": true,
+  "bin": {
+    "wiim2mqtt": "index.js"
+  },
+  "files": [
+    "index.js",
+    "config.js",
+    "lib/"
+  ],
+  "engines": {
+    "node": "^20.19 || ^22.12 || >=24"
+  },
+  "scripts": {
+    "start": "node index.js",
+    "lint": "eslint . && prettier --check .",
+    "format": "prettier --write . && eslint --fix .",
+    "test": "node --test",
+    "test:watch": "node --test --watch"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/hobbyquaker/wiim2mqtt.git"
+  },
+  "keywords": [
+    "mqtt",
+    "smarthome",
+    "mqtt-smarthome",
+    "home-automation",
+    "home-assistant",
+    "wiim",
+    "linkplay",
+    "upnp",
+    "audio",
+    "streamer"
+  ],
+  "author": "Sebastian Raff <hobbyquaker@gmail.com> (https://hobbyquaker.github.io)",
+  "license": "MIT",
+  "bugs": {
+    "url": "https://github.com/hobbyquaker/wiim2mqtt/issues"
+  },
+  "homepage": "https://github.com/hobbyquaker/wiim2mqtt",
+  "dependencies": {
+    "fast-xml-parser": "^4.5.0",
+    "mqtt": "^5.5.0",
+    "yargs": "^17.7.2"
+  },
+  "devDependencies": {
+    "@eslint/js": "^9.0.0",
+    "eslint": "^9.0.0",
+    "eslint-config-prettier": "^10.0.0",
+    "globals": "^16.0.0",
+    "prettier": "^3.0.0"
+  }
+}