artnet2usb-cli 0.2.0

package/dist-cli/app/dmxOutput.js

@@ -0,0 +1,203 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.DmxOutputEngine = void 0;
+exports.buildEnttecFrame = buildEnttecFrame;
+exports.applyChannelOffset = applyChannelOffset;
+exports.deviceUid = deviceUid;
+const serialport_1 = require("serialport");
+/**
+ * USB DMX output engine. Each active route runs on its own timer (hz):
+ * it grabs the source universe's latest frame and writes it to the port
+ * using the selected protocol.
+ *  - enttec-pro: Enttec DMX USB Pro frame (0x7E, label 6, len LE, data, 0xE7)
+ *  - open-dmx:   FTDI raw DMX — 250000 baud 8N2, break + MAB + startcode + 512
+ * The device identity (uid) is independent of the port path: when the
+ * device is reconnected, the route finds its new path on its own.
+ */
+/** Enttec Pro "Output Only Send DMX" packet. (Pure — unit tested.) */
+function buildEnttecFrame(dmx) {
+    const payload = Buffer.alloc(513);
+    payload[0] = 0; // start code
+    dmx.copy(payload, 1, 0, Math.min(dmx.length, 512));
+    const frame = Buffer.alloc(payload.length + 5);
+    frame[0] = 0x7e;
+    frame[1] = 6; // label: Output Only Send DMX
+    frame.writeUInt16LE(payload.length, 2);
+    payload.copy(frame, 4);
+    frame[frame.length - 1] = 0xe7;
+    return frame;
+}
+/**
+ * Applies a channel start (patch) offset — a circular rotation, so NO DATA
+ * IS LOST: the entire 512-channel buffer is preserved, only the positions
+ * are rotated circularly.
+ *  - offset > 0: source channels 1..512 are written in order to device
+ *    channel (1+offset).. onward; the `offset` channels that overflow the
+ *    end of the buffer wrap around to the start (device channels 1..offset).
+ *  - offset < 0: the first |offset| channels of the source wrap around to
+ *    the END of the device buffer (not dropped), source channel (|offset|+1)
+ *    is written to the device's channel 1.
+ * If offset=0, returns the original buffer untouched. (Pure — unit tested.)
+ */
+function applyChannelOffset(dmx, offset) {
+    if (!offset)
+        return dmx;
+    const shifted = Buffer.alloc(512);
+    for (let i = 0; i < 512; i++) {
+        const srcIndex = ((((i - offset) % 512) + 512) % 512);
+        shifted[i] = srcIndex < dmx.length ? dmx[srcIndex] : 0;
+    }
+    return shifted;
+}
+/** Derives a persistent device identity from a serialport list record. (Pure — unit tested.) */
+function deviceUid(p) {
+    const vid = (p.vendorId ?? '?').toLowerCase();
+    const pid = (p.productId ?? '?').toLowerCase();
+    return p.serialNumber ? `${vid}:${pid}:${p.serialNumber}` : `${vid}:${pid}:${p.path}`;
+}
+class DmxOutputEngine {
+    getFrame;
+    getSettings;
+    active = new Map(); // routeId -> output
+    lastFrames = new Map(); // routeId -> last frame sent
+    constructor(getFrame, getSettings) {
+        this.getFrame = getFrame;
+        this.getSettings = getSettings;
+    }
+    async listDevices() {
+        const ports = await serialport_1.SerialPort.list();
+        return ports.map((p) => ({
+            uid: deviceUid(p),
+            path: p.path,
+            manufacturer: p.manufacturer,
+            vendorId: p.vendorId,
+            productId: p.productId,
+            serialNumber: p.serialNumber,
+            connected: true
+        }));
+    }
+    isActive(routeId) {
+        return this.active.has(routeId);
+    }
+    statusOf(route) {
+        const a = this.active.get(route.id);
+        return {
+            active: !!a && !a.error,
+            error: a?.error ?? null,
+            framesSent: a?.framesSent ?? 0,
+            frozen: !!a?.frozenFrame
+        };
+    }
+    /** Freeze: locks in the current frame; a second call returns to live. Returns: the new frozen state. */
+    toggleFreeze(route) {
+        const out = this.active.get(route.id);
+        if (!out)
+            return false;
+        if (out.frozenFrame) {
+            out.frozenFrame = null;
+            return false;
+        }
+        // Current output frame: live data, else the last frame sent, else blackout
+        const fr = this.getFrame(route.universe);
+        out.frozenFrame = Buffer.from(fr?.data ?? this.lastFrames.get(route.id) ?? Buffer.alloc(512));
+        return true;
+    }
+    /** Start a route: find the device's current port path by uid, open the port, set up the loop. */
+    async start(route) {
+        await this.stop(route.id);
+        const devices = await this.listDevices();
+        const dev = devices.find((d) => d.uid === route.deviceUid);
+        if (!dev)
+            throw new Error('device_not_connected');
+        const baud = route.protocol === 'open-dmx' ? 250000 : 57600;
+        const port = new serialport_1.SerialPort({
+            path: dev.path,
+            baudRate: baud,
+            dataBits: 8,
+            stopBits: 2,
+            parity: 'none',
+            autoOpen: false
+        });
+        await new Promise((resolve, reject) => {
+            port.open((err) => (err ? reject(err) : resolve()));
+        });
+        const hz = Math.max(1, Math.min(44, route.hz));
+        const out = { port, timer: null, framesSent: 0, error: null, writing: false, frozenFrame: null };
+        out.timer = setInterval(() => void this.tick(route, out), Math.round(1000 / hz));
+        port.on('error', (err) => {
+            out.error = err.message;
+        });
+        port.on('close', () => {
+            out.error = out.error ?? 'port_closed';
+        });
+        this.active.set(route.id, out);
+    }
+    currentFrame(route) {
+        const settings = this.getSettings();
+        const fr = this.getFrame(route.universe);
+        const fresh = fr && Date.now() - fr.lastAt <= settings.signalLossMs;
+        if (fresh) {
+            this.lastFrames.set(route.id, fr.data);
+            return fr.data;
+        }
+        // No signal: hold the last frame or blackout, depending on the setting
+        if (settings.onSignalLoss === 'blackout')
+            return Buffer.alloc(512);
+        return this.lastFrames.get(route.id) ?? null;
+    }
+    async tick(route, out) {
+        if (out.writing || !out.port.isOpen)
+            return;
+        const raw = out.frozenFrame ?? this.currentFrame(route);
+        if (!raw)
+            return;
+        const dmx = applyChannelOffset(raw, route.channelOffset ?? 0);
+        out.writing = true;
+        try {
+            if (route.protocol === 'enttec-pro') {
+                await new Promise((resolve, reject) => out.port.write(buildEnttecFrame(dmx), (err) => (err ? reject(err) : resolve())));
+            }
+            else {
+                // Open DMX: break (~1ms) + MAB (Mark After Break) + frame, via serialport set({brk}).
+                // NOTE: flush() was tried between break→data but caused jitter (reverted).
+                // In this version flush() was moved to the VERY START of the loop — it tries
+                // to clear any leftover stray byte from the previous cycle without touching
+                // the current break/MAB timing.
+                await new Promise((resolve, reject) => out.port.flush((e) => (e ? reject(e) : resolve())));
+                await new Promise((resolve, reject) => out.port.set({ brk: true }, (e) => (e ? reject(e) : resolve())));
+                await new Promise((r) => setTimeout(r, 1));
+                await new Promise((resolve, reject) => out.port.set({ brk: false }, (e) => (e ? reject(e) : resolve())));
+                await new Promise((r) => setTimeout(r, 1));
+                const frame = Buffer.alloc(513);
+                frame[0] = 0;
+                dmx.copy(frame, 1, 0, Math.min(dmx.length, 512));
+                await new Promise((resolve, reject) => out.port.write(frame, (err) => (err ? reject(err) : resolve())));
+                await new Promise((resolve, reject) => out.port.drain((err) => (err ? reject(err) : resolve())));
+            }
+            out.framesSent++;
+            out.error = null;
+        }
+        catch (err) {
+            out.error = err instanceof Error ? err.message : String(err);
+        }
+        finally {
+            out.writing = false;
+        }
+    }
+    async stop(routeId) {
+        const out = this.active.get(routeId);
+        if (!out)
+            return;
+        clearInterval(out.timer);
+        this.active.delete(routeId);
+        this.lastFrames.delete(routeId);
+        if (out.port.isOpen) {
+            await new Promise((resolve) => out.port.close(() => resolve()));
+        }
+    }
+    async stopAll() {
+        for (const id of [...this.active.keys()])
+            await this.stop(id);
+    }
+}
+exports.DmxOutputEngine = DmxOutputEngine;

package/dist-cli/cli/autoRoute.js

@@ -0,0 +1,43 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.pickAutoRoute = pickAutoRoute;
+exports.resolveAutoRouteFields = resolveAutoRouteFields;
+/**
+ * Decision logic for the "auto" command: matches when exactly 1 universe + 1 USB
+ * device have been seen, otherwise returns an error explaining which side is
+ * ambiguous — the caller then directs the user to `configure` in this case.
+ */
+function pickAutoRoute(universes, devices) {
+    if (universes.length === 0 && devices.length === 0) {
+        return { error: 'No Art-Net universe and no USB device detected. Connect your DMX interface and ensure Art-Net traffic is reaching this machine, then retry.' };
+    }
+    if (universes.length === 0) {
+        return { error: 'No Art-Net universe detected. Ensure a controller is broadcasting Art-Net on this network, then retry.' };
+    }
+    if (devices.length === 0) {
+        return { error: 'No USB serial device detected. Connect your DMX interface, then retry.' };
+    }
+    if (universes.length > 1) {
+        const list = universes.map((u) => u.universe).join(', ');
+        return { error: `${universes.length} Art-Net universes detected (${list}) — "auto" only handles a single universe. Use "configure" to pick one manually.` };
+    }
+    if (devices.length > 1) {
+        const list = devices.map((d) => d.path).join(', ');
+        return { error: `${devices.length} USB devices detected (${list}) — "auto" only handles a single device. Use "configure" to pick one manually.` };
+    }
+    return { universe: universes[0].universe, deviceUid: devices[0].uid };
+}
+/**
+ * "auto" only actually auto-detects universe+deviceUid.
+ * If no CLI flag was explicitly given for protocol/hz/channelOffset (the opts
+ * field is undefined), the previously saved "auto" route's value is preserved —
+ * otherwise, on every restart (systemd Restart=always, boot, etc.) a manually
+ * configured channelOffset/protocol would silently reset to the default.
+ */
+function resolveAutoRouteFields(existing, opts) {
+    return {
+        protocol: opts.protocol ?? existing?.protocol ?? 'open-dmx',
+        hz: opts.hz ?? existing?.hz ?? 40,
+        channelOffset: opts.channelOffset ?? existing?.channelOffset ?? 0
+    };
+}

package/dist-cli/cli/bridge.js

@@ -0,0 +1,46 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.startBridge = startBridge;
+const artnet_1 = require("../app/artnet");
+const dmxOutput_1 = require("../app/dmxOutput");
+const RECONNECT_INTERVAL_MS = 5000;
+/**
+ * Bridging without Electron — the same thing as the app.whenReady() block in
+ * app/main.ts (EXCLUDING BrowserWindow/registerIpc/preview): start the
+ * listener, auto-start the saved+enabled routes. Both the `run` and
+ * `configure` sub-commands use this.
+ *
+ * It also runs a periodic watchdog loop so that when a USB device disconnects
+ * and reconnects (e.g. a cable getting jostled backstage), it can recover
+ * without human intervention: it silently retries starting any enabled route
+ * that is currently `active:false` (errors are swallowed and retried on the
+ * next tick). app/dmxOutput.ts itself is never modified.
+ */
+async function startBridge(store, onFrame) {
+    const listener = new artnet_1.ArtNetListener();
+    const engine = new dmxOutput_1.DmxOutputEngine((u) => listener.frameOf(u), () => store.settings);
+    listener.start(onFrame);
+    for (const r of store.routes) {
+        if (r.enabled)
+            await engine.start(r).catch(() => { });
+    }
+    const reconnectTimer = setInterval(() => {
+        void (async () => {
+            for (const r of store.routes) {
+                if (!r.enabled)
+                    continue;
+                if (!engine.statusOf(r).active)
+                    await engine.start(r).catch(() => { });
+            }
+        })();
+    }, RECONNECT_INTERVAL_MS);
+    return {
+        listener,
+        engine,
+        shutdown: async () => {
+            clearInterval(reconnectTimer);
+            await engine.stopAll();
+            listener.stop();
+        }
+    };
+}

package/dist-cli/cli/configDir.js

@@ -0,0 +1,49 @@
+"use strict";
+var __importDefault = (this && this.__importDefault) || function (mod) {
+    return (mod && mod.__esModule) ? mod : { "default": mod };
+};
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.defaultConfigDir = defaultConfigDir;
+exports.portableExeDir = portableExeDir;
+exports.resolveConfigDir = resolveConfigDir;
+const node_os_1 = __importDefault(require("node:os"));
+const node_path_1 = __importDefault(require("node:path"));
+const portableConfig_1 = require("../shared/portableConfig");
+/**
+ * Recomputes, without Electron (in the CLI process), the OS-standard path that
+ * Electron's app.getPath('userData') uses — productName is kept identical so
+ * the SAME config.json is shared with the GUI ('main.ts' never calls
+ * app.setName(), so it uses build.productName from the Electron package.json).
+ *  - macOS:   ~/Library/Application Support/<productName>
+ *  - Windows: %APPDATA%/<productName>
+ *  - Linux:   ${XDG_CONFIG_HOME:-~/.config}/<productName>
+ */
+const PRODUCT_NAME = 'Relackout ArtNet 2 USB';
+function defaultConfigDir() {
+    const home = node_os_1.default.homedir();
+    if (process.platform === 'darwin') {
+        return node_path_1.default.join(home, 'Library', 'Application Support', PRODUCT_NAME);
+    }
+    if (process.platform === 'win32') {
+        return node_path_1.default.join(process.env.APPDATA ?? node_path_1.default.join(home, 'AppData', 'Roaming'), PRODUCT_NAME);
+    }
+    return node_path_1.default.join(process.env.XDG_CONFIG_HOME ?? node_path_1.default.join(home, '.config'), PRODUCT_NAME);
+}
+/**
+ * The directory the exe lives in, for a single-file compiled binary (pkg/bun) —
+ * the candidate for portable config. Null when running under plain node/tsx
+ * (execPath would be node itself, so writing config next to it would be wrong).
+ */
+function portableExeDir() {
+    if (!(0, portableConfig_1.isCompiledBinary)())
+        return null;
+    return node_path_1.default.dirname(process.execPath);
+}
+/**
+ * The config directory the CLI will use: portable-first.
+ * For a standalone binary, next to the exe (if writable, or if config.json
+ * already exists there), otherwise the OS-standard directory (same as the GUI's userData).
+ */
+function resolveConfigDir() {
+    return (0, portableConfig_1.resolvePortableConfigDir)(portableExeDir(), defaultConfigDir());
+}

package/dist-cli/cli/doctor.js

@@ -0,0 +1,42 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runDoctorChecks = runDoctorChecks;
+/**
+ * Decision logic for the `doctor` command: cross-checks the enabled routes in
+ * config.json against the USB devices currently connected. Pure — actual
+ * filesystem/hardware access happens on the caller's side (cli/index.ts).
+ */
+function runDoctorChecks(routes, devices) {
+    const issues = [];
+    const connectedUids = new Set(devices.map((d) => d.uid));
+    const enabled = routes.filter((r) => r.enabled);
+    for (const r of enabled) {
+        if (!connectedUids.has(r.deviceUid)) {
+            issues.push({ level: 'error', message: `Route "${r.id}" (universe ${r.universe}): device ${r.deviceUid} is not currently connected.` });
+        }
+        if (!Number.isInteger(r.hz) || r.hz < 1 || r.hz > 44) {
+            issues.push({ level: 'error', message: `Route "${r.id}": hz ${r.hz} is out of range (1-44).` });
+        }
+        const offset = r.channelOffset ?? 0;
+        if (!Number.isInteger(offset) || offset < -511 || offset > 511) {
+            issues.push({ level: 'error', message: `Route "${r.id}": channelOffset ${offset} is out of range (-511 to 511).` });
+        }
+    }
+    const byUniverse = new Map();
+    for (const r of enabled)
+        byUniverse.set(r.universe, [...(byUniverse.get(r.universe) ?? []), r]);
+    for (const [universe, list] of byUniverse) {
+        if (list.length > 1) {
+            issues.push({ level: 'warning', message: `Universe ${universe} is routed by ${list.length} enabled routes: ${list.map((r) => r.id).join(', ')}.` });
+        }
+    }
+    const byDevice = new Map();
+    for (const r of enabled)
+        byDevice.set(r.deviceUid, [...(byDevice.get(r.deviceUid) ?? []), r]);
+    for (const [deviceUid, list] of byDevice) {
+        if (list.length > 1) {
+            issues.push({ level: 'warning', message: `Device ${deviceUid} is targeted by ${list.length} enabled routes: ${list.map((r) => r.id).join(', ')}.` });
+        }
+    }
+    return issues;
+}