@kiosko/core 0.1.0 → 0.2.1

package/src/config/normalize.ts

@@ -6,7 +6,7 @@
 import { TIME_FORMATS } from '@kiosko/sdk/format';
 import { DEFAULT_WORKDAY } from '@kiosko/sdk/workday';
 import { suggestGrid } from '../layout/grid.ts';
-import { CONFIG_VERSION, DEFAULT_CONFIG, type Config, type Screen } from './model.ts';
+import { CONFIG_VERSION, DEFAULT_CONFIG, DEFAULT_MAX_BYTES, type Config, type Screen } from './model.ts';
 
 /**
  * Fills gaps of a config written by hand or by an older version. Never throws.
@@ -58,6 +58,7 @@ function normalizeScreen(s: Partial<Screen>, i: number): Screen {
     pixelShift: { enabled: true, amplitude: 2, periodMs: 8 * 60_000, ...(s.pixelShift ?? {}) },
     sleepWhenIdle: s.sleepWhenIdle ?? false,
     jpegQuality: s.jpegQuality ?? 90,
+    maxBytes: Math.max(0, Math.round(s.maxBytes ?? DEFAULT_MAX_BYTES)),
     maxFps: s.maxFps ?? 12,
   };
 }

package/src/config/schema.ts

@@ -262,6 +262,18 @@ export function configSchema(plugins: readonly PluginDefinition[]): S {
               keepalive: { type: 'boolean', default: true, description: 'Re-send the last frame now and then so the panel keeps it.' },
             },
           },
+          {
+            title: 'USB (LY panels)',
+            description: 'Talks to the panel over USB from Kiosko itself (Thermalright Trofeo Vision and other LY panels): no trcc, no Python. On Windows the device needs the WinUSB driver; on Linux a udev rule.',
+            type: 'object',
+            additionalProperties: false,
+            required: ['driver'],
+            properties: {
+              driver: { const: 'usb' },
+              serial: { type: 'string', description: 'USB serial number of the panel. With several identical panels it is the only way to tell them apart, and a serial that is not found is an error, never "another panel". Empty: the first one found.' },
+              keepalive: { type: 'number', minimum: 0.1, maximum: 2, default: 1, description: 'Seconds between re-sends of an unchanged frame; the firmware drops the picture after 2-3 s without one.' },
+            },
+          },
           {
             title: 'Frame file',
             description: 'Writes frame.jpg atomically into a folder; an external sender takes it to the panel.',
@@ -360,6 +372,7 @@ export function configSchema(plugins: readonly PluginDefinition[]): S {
           },
           sleepWhenIdle: { type: 'boolean', default: false, description: 'Black panel while every widget of the page has nothing worth showing.' },
           jpegQuality: { type: 'integer', minimum: 0, maximum: 100, default: 90, description: 'JPEG quality of the frames; 0 = PNG.' },
+          maxBytes: { type: 'integer', minimum: 0, maximum: 20_000_000, default: 480_000, description: 'Largest frame to send, in bytes: a bigger one is re-encoded at a lower JPEG quality until it fits. LY panels (Trofeo Vision…) drop frames over ~500 KB. 0 = no limit.' },
           maxFps: { type: 'integer', minimum: 1, maximum: 30, default: 12, description: 'Frames per second ceiling for animations.' },
         },
       },

package/src/config/store.ts

@@ -1,9 +1,11 @@
 /**
  * Reading and writing the config file. The file holds secrets (calendar
- * URLs, tokens), so it's written with 0600 and atomically.
+ * URLs, tokens), so it's written atomically and readable by its owner only (0600; an ACL
+ * on Windows).
  */
-import { chmodSync, copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
+import { copyFileSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from 'node:fs';
 import { dirname } from 'node:path';
+import { restrictToOwner } from '../fsperm.ts';
 import { paths } from '../paths.ts';
 import { CONFIG_SCHEMA_ID, type Config } from './model.ts';
 import { normalize } from './normalize.ts';
@@ -25,7 +27,7 @@ export function saveConfig(config: Config, path = paths.config): void {
   if (existsSync(path)) {
     try {
       copyFileSync(path, `${path}.bak`);
-      chmodSync(`${path}.bak`, 0o600);
+      restrictToOwner(`${path}.bak`);
     } catch {
       /* best effort */
     }
@@ -36,9 +38,5 @@ export function saveConfig(config: Config, path = paths.config): void {
   const out = { $schema: $schema || CONFIG_SCHEMA_ID, ...rest };
   writeFileSync(tmp, `${JSON.stringify(out, null, 2)}\n`, { mode: 0o600 });
   renameSync(tmp, path);
-  try {
-    chmodSync(path, 0o600);
-  } catch {
-    /* Windows */
-  }
+  restrictToOwner(path);
 }

package/src/devices.ts

@@ -3,11 +3,13 @@
  *
  *   virtual  only the editor shows it (no hardware, demos, development)
  *   trcc     `trcc serve` REST API (thermalright-trcc-linux), via @loksly/trcc-client
+ *   usb      straight over USB from Node, via @loksly/usb-ly (LY panels)
  *   file     writes `frame.jpg` atomically for an external sender (e.g. a USB
  *            sender bound to a serial number, for several identical panels)
  */
 import { mkdirSync, renameSync, writeFileSync } from 'node:fs';
 import { join } from 'node:path';
+import { LyPanel, MAX_FRAME_BYTES, findPanels, loadUsb, modelFor } from '@loksly/usb-ly';
 import { connectPanel, detectPanel, pinFrame, sendFrame, serverAlive, type TrccOptions } from '@loksly/trcc-client';
 import type { DeviceConfig } from './config/model.ts';
 import { expandPath } from './paths.ts';
@@ -31,6 +33,8 @@ export interface Device {
 
 export function encodeFor(device: DeviceConfig, jpegQuality: number): 'png' | 'jpeg' {
   if (device.driver === 'file') return device.format ?? 'jpeg';
+  // The LY firmware only takes JPEG.
+  if (device.driver === 'usb') return 'jpeg';
   return jpegQuality > 0 ? 'jpeg' : 'png';
 }
 
@@ -43,6 +47,24 @@ class VirtualDevice implements Device {
   close(): void {}
 }
 
+/**
+ * `rename` over a file another process has open fails on Windows with
+ * EPERM/EBUSY/EACCES (the sender is reading it right now): it passes in a few
+ * milliseconds, so try again a few times before giving up.
+ */
+export async function renameReplacing(from: string, to: string, rename: (a: string, b: string) => void = renameSync, tries = 8): Promise<void> {
+  for (let i = 1; ; i++) {
+    try {
+      rename(from, to);
+      return;
+    } catch (err) {
+      const code = (err as NodeJS.ErrnoException).code;
+      if (i >= tries || !(code === 'EPERM' || code === 'EBUSY' || code === 'EACCES')) throw err;
+      await new Promise((r) => setTimeout(r, 5 * i));
+    }
+  }
+}
+
 class FileDevice implements Device {
   status: DeviceStatus;
   private readonly dir: string;
@@ -56,7 +78,7 @@ class FileDevice implements Device {
       const tmp = join(this.dir, '.frame.tmp');
       writeFileSync(tmp, frame);
       // Atomic: the sender never reads half a JPEG.
-      renameSync(tmp, join(this.dir, 'frame.jpg'));
+      await renameReplacing(tmp, join(this.dir, 'frame.jpg'));
       this.status.ok = true;
       this.status.framesSent++;
       this.status.lastSentAt = Date.now();
@@ -114,10 +136,163 @@ class TrccDevice implements Device {
   }
 }
 
-export function openDevice(cfg: DeviceConfig, log: (m: string) => void): Device {
+/**
+ * A panel over USB, owned by this process. Two things the firmware asks for:
+ * a new frame goes out as soon as it exists, and an unchanged one is sent
+ * again every `keepalive` seconds, or the panel falls back to the factory logo
+ * after 2-3 s. A bus error drops the connection and reconnects with a growing
+ * pause; a panel with the configured serial number that is not there is
+ * waited for, never replaced by another one.
+ */
+export class UsbDevice implements Device {
+  status: DeviceStatus = { driver: 'usb', ok: false, message: 'connecting…', framesSent: 0, lastSentAt: null };
+  private readonly cfg: Extract<DeviceConfig, { driver: 'usb' }>;
+  private readonly log: (m: string) => void;
+  private readonly rotate: number | undefined;
+  private readonly open: (serial?: string) => Promise<LyPanel>;
+  private readonly retryMs: number;
+  private panel: LyPanel | null = null;
+  private latest: Buffer | null = null;
+  private fresh = false;
+  private lastWrite = 0;
+  private retryAt = 0;
+  private failures = 0;
+  private closed = false;
+  private pumping: Promise<void> | null = null;
+  private timer: ReturnType<typeof setInterval> | null = null;
+  private lastMessage = '';
+
+  constructor(cfg: Extract<DeviceConfig, { driver: 'usb' }>, log: (m: string) => void, o: { rotate?: number; open?: (serial?: string) => Promise<LyPanel>; retryMs?: number } = {}) {
+    this.cfg = cfg;
+    this.log = log;
+    this.rotate = o.rotate;
+    this.open = o.open ?? ((serial) => LyPanel.open(serial ? { serial } : {}));
+    this.retryMs = o.retryMs ?? 1000;
+    const every = Math.round(Math.min(2, Math.max(0.1, cfg.keepalive ?? 1)) * 1000);
+    this.timer = setInterval(() => void this.pump(), Math.min(every, 250));
+    this.timer.unref();
+  }
+
+  private say(message: string, ok: boolean): void {
+    this.status.ok = ok;
+    this.status.message = message;
+    if (message !== this.lastMessage) {
+      this.lastMessage = message;
+      this.log(message);
+    }
+  }
+
+  private due(now: number): boolean {
+    return now - this.lastWrite >= Math.min(2, Math.max(0.1, this.cfg.keepalive ?? 1)) * 1000;
+  }
+
+  /** Writes what is pending; concurrent callers share one run. */
+  private pump(): Promise<void> {
+    if (this.pumping) return this.pumping;
+    const run = async () => {
+      while (!this.closed && this.latest && Date.now() >= this.retryAt && (this.fresh || this.due(Date.now()))) {
+        try {
+          const frame = this.latest;
+          this.fresh = false;
+          if (!this.panel) await this.connect();
+          const kept = await this.panel!.send(frame);
+          this.lastWrite = Date.now();
+          this.failures = 0;
+          this.status.framesSent++;
+          this.status.lastSentAt = this.lastWrite;
+          if (!kept) this.say(`the panel dropped a ${Math.round(frame.length / 1024)} KB frame (limit ${Math.round(MAX_FRAME_BYTES / 1024)} KB): lower the JPEG quality`, false);
+          else if (!this.status.ok) this.say(this.describe(), true);
+        } catch (err) {
+          this.fresh = true; // a reconnected panel has nothing on it
+          const p = this.panel;
+          this.panel = null;
+          void p?.close().catch(() => undefined);
+          this.failures++;
+          this.retryAt = Date.now() + Math.min(30 * this.retryMs, this.retryMs * 2 ** Math.min(this.failures, 5));
+          const why = err instanceof Error ? err.message : String(err);
+          this.say(`${why}${this.cfg.serial && !why.includes(this.cfg.serial) ? ` (serial ${this.cfg.serial})` : ''}; retrying`, false);
+        }
+      }
+    };
+    this.pumping = run().finally(() => (this.pumping = null));
+    return this.pumping;
+  }
+
+  private describe(): string {
+    const i = this.panel?.info;
+    if (!i) return 'usb';
+    return `usb ${i.serial ?? i.location ?? ''} PM ${i.pm} SUB ${i.sub}${i.model ? ` ${i.model.width}×${i.model.height}` : ''}`.replace(/\s+/g, ' ');
+  }
+
+  private async connect(): Promise<void> {
+    const panel = await this.open(this.cfg.serial);
+    this.panel = panel;
+    const m = panel.info?.model;
+    if (m) {
+      this.status.detected = { width: m.width, height: m.height };
+      // The picture is turned in the compositor, before encoding: the firmware's mount angle must match the screen's.
+      if (this.rotate !== undefined && m.rotate !== this.rotate) this.log(`the panel's firmware expects rotation ${m.rotate}° but this screen has ${this.rotate}°: the picture may come out turned`);
+    }
+    this.say(this.describe(), true);
+  }
+
+  async send(frame: Buffer): Promise<void> {
+    this.latest = frame;
+    this.fresh = true;
+    await this.pump();
+  }
+
+  close(): void {
+    this.closed = true;
+    if (this.timer) clearInterval(this.timer);
+    this.timer = null;
+    const p = this.panel;
+    this.panel = null;
+    void p?.close().catch(() => undefined);
+  }
+}
+
+/** The LY panels libusb sees (serial and where), without claiming any: for `kiosko doctor`. */
+export async function listUsb(): Promise<{ ok: boolean; panels: { serial?: string; pid: number; location: string; error?: string }[]; error?: string }> {
+  try {
+    const found = await findPanels(await loadUsb());
+    return { ok: true, panels: found.map((f) => ({ ...(f.serial ? { serial: f.serial } : {}), pid: f.pid, location: f.location, ...(f.error ? { error: f.error } : {}) })) };
+  } catch (err) {
+    return { ok: false, panels: [], error: err instanceof Error ? err.message : String(err) };
+  }
+}
+
+/** The LY panels libusb sees right now, for the "add screen" menu. Never throws. */
+export async function discoverUsb(): Promise<{ serial: string; key: string; width: number; height: number; location: string; error?: string }[]> {
+  try {
+    const found = await findPanels(await loadUsb());
+    const out = [];
+    for (const f of found) {
+      // The resolution needs the hello, which needs the device: only if no other process has it.
+      let model: { width: number; height: number } | undefined;
+      if (f.serial) {
+        try {
+          const p = await LyPanel.open({ serial: f.serial });
+          model = p.info?.model;
+          await p.close();
+        } catch {
+          /* held by another process, or no driver: listed anyway */
+        }
+      }
+      out.push({ serial: f.serial ?? '', key: f.serial ?? `usb ${f.location}`, width: model?.width ?? 0, height: model?.height ?? 0, location: f.location, ...(f.error ? { error: f.error } : {}) });
+    }
+    return out;
+  } catch {
+    return [];
+  }
+}
+
+export function openDevice(cfg: DeviceConfig, log: (m: string) => void, rotate?: number): Device {
   switch (cfg.driver) {
     case 'trcc':
       return new TrccDevice(cfg, log);
+    case 'usb':
+      return new UsbDevice(cfg, log, rotate === undefined ? {} : { rotate });
     case 'file':
       return new FileDevice(cfg);
     default:

package/src/env.ts

@@ -30,9 +30,23 @@ export type LogFn = (scope: string, msg: string) => void;
 export function baseContext(cfg: Config, plugin: string, log: LogFn, now: number): BaseContext {
   let made = false;
   const dir = paths.data(plugin);
+  const cache = paths.cache(plugin);
+  let cacheMade = false;
   const base = createBaseContext({ now, locale: resolveLocale(cfg), timeFormat: cfg.timeFormat, workday: cfg.workday, ...(cfg.location ? { location: cfg.location } : {}), log: (msg: string) => log(plugin, msg) });
   return {
     ...base,
+    get cacheDir() {
+      if (!cache) return this.dataDir;
+      if (!cacheMade) {
+        try {
+          mkdirSync(cache, { recursive: true });
+        } catch {
+          return this.dataDir;
+        }
+        cacheMade = true;
+      }
+      return cache;
+    },
     get dataDir() {
       if (!made) {
         try {

package/src/fsperm.ts

@@ -0,0 +1,23 @@
+import { execFileSync } from 'node:child_process';
+import { chmodSync } from 'node:fs';
+import { userInfo } from 'node:os';
+
+/**
+ * Makes `path` readable by its owner only: mode 0600, or, on Windows (where
+ * `chmod` can't do it), an ACL without inheritance that grants just the
+ * current user. Best effort: a file system without permissions (FAT, some
+ * network shares) just keeps what it has.
+ */
+export function restrictToOwner(path: string, os: NodeJS.Platform = process.platform): void {
+  try {
+    if (os !== 'win32') {
+      chmodSync(path, 0o600);
+      return;
+    }
+    const user = process.env.USERNAME || userInfo().username;
+    const domain = process.env.USERDOMAIN;
+    execFileSync('icacls', [path, '/inheritance:r', '/grant:r', `${domain ? `${domain}\\` : ''}${user}:F`], { stdio: 'ignore', windowsHide: true, timeout: 5000 });
+  } catch {
+    /* best effort */
+  }
+}

package/src/index.ts

@@ -14,3 +14,5 @@ export * from './devices.ts';
 export * from './fonts.ts';
 export * from './paths.ts';
 export * from './env.ts';
+export * from './fsperm.ts';
+export * from './sdk-resolver.ts';

package/src/paths.ts

@@ -1,3 +1,4 @@
+import { existsSync } from 'node:fs';
 /**
  * Where Kiosko keeps its things, per platform:
  *   Linux   $XDG_CONFIG_HOME/kiosko  (~/.config/kiosko)
@@ -6,6 +7,7 @@
  * `KIOSKO_HOME` overrides all of them (tests, portable installs).
  */
 import { homedir, platform } from 'node:os';
+import { expandPath } from '@kiosko/sdk';
 import { join } from 'node:path';
 
 export function kioskoHome(): string {
@@ -32,14 +34,21 @@ export const paths = {
   get plugins() {
     return join(kioskoHome(), 'plugins');
   },
-  /** Per-plugin caches: `data/<plugin>`. */
+  /**
+   * Per-plugin re-fetchable caches, in RAM: `$XDG_RUNTIME_DIR/kiosko-cache/<plugin>`
+   * (or `/dev/shm/kiosko-cache-<uid>/<plugin>`). Null where there is no tmpfs.
+   * On Windows there is none, but the cache belongs in the machine-local
+   * profile (`%LOCALAPPDATA%\\Kiosko\\cache`), not in the roaming one `data/` uses.
+   */
+  cache(plugin: string): string | null {
+    if (platform() === 'win32') return join(process.env.LOCALAPPDATA ?? join(homedir(), 'AppData', 'Local'), 'Kiosko', 'cache', plugin.replace(/[^a-z0-9._-]/gi, '_'));
+    const base = process.env.XDG_RUNTIME_DIR && existsSync(process.env.XDG_RUNTIME_DIR) ? join(process.env.XDG_RUNTIME_DIR, 'kiosko-cache') : existsSync('/dev/shm') ? `/dev/shm/kiosko-cache-${process.getuid?.() ?? 'u'}` : null;
+    return base && join(base, plugin.replace(/[^a-z0-9._-]/gi, '_'));
+  },
+  /** Per-plugin data that must persist: `data/<plugin>`. */
   data(plugin: string) {
     return join(kioskoHome(), 'data', plugin.replace(/[^a-z0-9._-]/gi, '_'));
   },
 };
 
-/** `~/x` and `$VAR`/`${VAR}` expanded. */
-export function expandPath(p: string): string {
-  const v = p.replace(/\$(?:\{(\w+)\}|(\w+))/g, (whole, a?: string, b?: string) => process.env[a ?? b ?? ''] ?? whole);
-  return v === '~' || v.startsWith('~/') ? join(homedir(), v.slice(1)) : v;
-}
+export { expandPath };