@slaplacian/tsups 0.0.0-stage → 0.1.1

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Léo Victor Cruz Vasconcelos
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -1,3 +1,83 @@
-# Temporary Holding Version
+# tsups
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Cross-platform (macOS / Linux / Windows) command-line monitor for TS Shara UPS
+units that speak the Megatec **Q1** serial protocol over USB.
+
+The UPS speaks the Megatec **Q1** protocol over a USB-serial port at 2400 baud:
+
+| Command | Meaning                                  |
+|---------|------------------------------------------|
+| `I`     | Identify (reply must contain `TS`)       |
+| `F`     | Rating info                              |
+| `Q1`    | Status (polled every 2 s)                |
+| `T` / `TL` / `Tnn` | 10 s test / test until low / nn-minute test |
+| `Q`     | Toggle beeper                            |
+| `Sn`    | Turn output off after n minutes          |
+| `C`, `CT` | Cancel shutdown / cancel test        |
+
+### Hardware quirks (TS Shara USB interface, STM32 `0483:5740`)
+
+Measured on a real unit; handled in `src/serial.js`:
+
+- A reply is held until the host writes again. `tsups` sends a bare `\r`
+  every 300 ms after a command to release it.
+- A command sent right after a reply is silently dropped. `tsups` waits
+  500 ms after the last reply before sending the next command.
+- `F` reports the input voltage as `Univ.` (universal / bivolt).
+
+## Install
+
+```sh
+npm install -g @slaplacian/tsups
+```
+
+On Linux, add yourself to the `dialout` group (or `uucp` on Arch) to access
+`/dev/ttyUSB*`.
+
+## Usage
+
+```sh
+tsups detect                 # find the UPS
+tsups status                 # one reading
+tsups status --json
+tsups monitor                # continuous; Ctrl+C to stop
+tsups monitor --events-only --log ups.jsonl \
+  --on-event 'osascript -e "display notification \"$UPS_MESSAGE\" with title \"UPS\""'
+tsups test quick | low | 5
+tsups beep
+tsups shutdown 3 --yes       # UPS output OFF in 3 minutes
+tsups cancel-shutdown
+tsups raw Q1                 # send anything, print reply
+```
+
+Events: `UTILITY_FAIL`, `UTILITY_RESTORED`, `LOW_BATTERY`, `OK_BATTERY`,
+`BYPASS_ENABLED/DISABLED`, `UPS_FAULT`, `BATTERY_TEST_STARTED/FINISHED`,
+`SHUTDOWN_PENDING/CANCELLED`, `BEEP_ENABLED/DISABLED`, `COMM_OK`, `COMM_FAIL`.
+
+To shut down the computer on power loss, use `--on-event` with a script that
+checks `$UPS_EVENT` (e.g. `LOW_BATTERY`) and runs `shutdown -h +1`.
+
+## Notes
+
+- Status bit 6 is reported per the Megatec spec (1 = shutdown pending).
+- Q1 replies with a malformed status field are rejected instead of parsed.
+- `tsups monitor --json` output can be sent to InfluxDB with
+  [`upsflux`](https://github.com/slaplacian/upsflux).
+
+## Development
+
+```sh
+npm install
+npm test        # parsing, battery %, event detection, command formatting
+npm link        # puts your working copy of `tsups` on your PATH
+```
+
+## Disclaimer
+
+Independent project, not affiliated with or endorsed by TS Shara. Product
+names are trademarks of their respective owners. Sending `S`/`T` commands
+switches the UPS output or runs battery tests; use at your own risk.
+
+## License
+
+MIT

package/package.json

@@ -1,6 +1,44 @@
 {
   "name": "@slaplacian/tsups",
-  "version": "0.0.0-stage",
-  "stub": true,
-  "description": "Temporary package placeholder for staged publishing"
-}
+  "version": "0.1.1",
+  "description": "Cross-platform CLI monitor for TS Shara UPS units (Megatec/Q1 serial protocol)",
+  "keywords": [
+    "ups",
+    "megatec",
+    "q1",
+    "ts-shara",
+    "nobreak",
+    "serial",
+    "cli",
+    "monitor"
+  ],
+  "author": "Léo Victor Cruz Vasconcelos",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/slaplacian/tsups.git"
+  },
+  "homepage": "https://github.com/slaplacian/tsups#readme",
+  "bugs": {
+    "url": "https://github.com/slaplacian/tsups/issues"
+  },
+  "type": "module",
+  "bin": {
+    "tsups": "src/cli.js"
+  },
+  "files": [
+    "src"
+  ],
+  "scripts": {
+    "test": "node --test test/"
+  },
+  "engines": {
+    "node": ">=20"
+  },
+  "license": "MIT",
+  "dependencies": {
+    "serialport": "^13.0.0"
+  },
+  "publishConfig": {
+    "access": "public"
+  }
+}

package/src/args.js

@@ -0,0 +1,51 @@
+import { parseArgs } from 'node:util';
+
+// Levenshtein distance, used to suggest the option the user probably meant.
+function distance(a, b) {
+  let prev = Array.from({ length: b.length + 1 }, (_, i) => i);
+  for (let i = 1; i <= a.length; i++) {
+    const row = [i];
+    for (let j = 1; j <= b.length; j++) {
+      row[j] = Math.min(prev[j] + 1, row[j - 1] + 1, prev[j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+    }
+    prev = row;
+  }
+  return prev[b.length];
+}
+
+export function suggestOption(given, names) {
+  const name = given.replace(/^-+/, '').split('=')[0];
+  let best = null;
+  for (const n of names) {
+    const d = distance(name, n);
+    if (d <= Math.max(2, Math.floor(n.length / 3)) && (!best || d < best.d)) best = { n, d };
+  }
+  return best && `--${best.n}`;
+}
+
+// parseArgs without the stack trace: prints a one-line error, a suggestion for
+// mistyped options, and exits with status 2 (usage error).
+export function parseCli(config, prog) {
+  try {
+    return parseArgs(config);
+  } catch (err) {
+    if (!err.code?.startsWith('ERR_PARSE_ARGS')) throw err;
+    let msg = `${prog}: ${err.message.split('. ')[0].replace(/\.$/, '')}`;
+    if (err.code === 'ERR_PARSE_ARGS_UNKNOWN_OPTION') {
+      const given = err.message.match(/'([^']+)'/)?.[1] ?? '';
+      const hint = suggestOption(given, Object.keys(config.options));
+      if (hint) msg += `; did you mean ${hint}?`;
+    }
+    console.error(`${msg}\nRun "${prog} --help" for the list of options.`);
+    process.exit(2);
+  }
+}
+
+// When the reading end of a pipe goes away (`| head`, or the next program in
+// the pipeline exited), stop quietly instead of crashing with EPIPE.
+export function exitOnClosedPipe(onClose = () => process.exit(0)) {
+  process.stdout.on('error', (err) => {
+    if (err.code === 'EPIPE') onClose();
+    else throw err;
+  });
+}

package/src/cli.js

@@ -0,0 +1,313 @@
+#!/usr/bin/env node
+import { spawn } from 'node:child_process';
+import { appendFileSync } from 'node:fs';
+import {
+  CMD,
+  parseQ1,
+  parseRating,
+  parseInfo,
+  isQ1Reply,
+  isRatingReply,
+  isInfoReply,
+  diffStatus,
+  testCommand,
+  shutdownCommand,
+} from './protocol.js';
+import { UpsConnection, detectPort, listPorts } from './serial.js';
+import { parseCli, exitOnClosedPipe } from './args.js';
+
+const HELP = `tsups - TS Shara UPS monitor (Megatec Q1 protocol, 2400 baud)
+
+Usage: tsups <command> [options]
+
+Commands:
+  ports                   List serial ports
+  detect                  Probe ports for a TS UPS (sends "I", expects "TS")
+  info                    Show identification (I) and rating (F) replies
+  status                  Read one Q1 status sample
+  monitor                 Poll continuously and report events
+  test [quick|low|<min>]  Battery test: 10 s (default), until low, or N minutes
+  cancel-test             Cancel a running battery test
+  beep                    Toggle the UPS beeper
+  shutdown <min> --yes    Turn UPS output OFF after <min> (0.2-0.9 or 1-10)
+  cancel-shutdown         Cancel a pending shutdown
+  raw <cmd>               Send a raw command (CR appended) and print the reply
+
+Options:
+  -p, --port <path>       Serial port (default: auto-detect)
+  -j, --json              Machine-readable JSON output
+  -i, --interval <sec>    Monitor poll interval (default 2)
+      --events-only       Monitor: print events only, not every sample
+      --log <file>        Monitor: append samples and events as JSON lines
+      --on-event <cmd>    Monitor: run a shell command on each event; gets
+                          UPS_EVENT, UPS_MESSAGE, UPS_SEVERITY, UPS_JSON env vars
+      --shutdown-on-fail <min>  Monitor: send S<min> to the UPS on utility failure
+      --shutdown-on-low <min>   Monitor: send S<min> to the UPS on low battery
+      --match <text>      Detect: identification substring (default "TS")
+  -y, --yes               Confirm commands that cut power
+  -v, --verbose           Print probe details
+  -h, --help              Show this help
+`;
+
+const { values: opt, positionals } = parseCli({
+  allowPositionals: true,
+  options: {
+    port: { type: 'string', short: 'p' },
+    json: { type: 'boolean', short: 'j' },
+    interval: { type: 'string', short: 'i', default: '2' },
+    'events-only': { type: 'boolean' },
+    log: { type: 'string' },
+    'on-event': { type: 'string' },
+    'shutdown-on-fail': { type: 'string' },
+    'shutdown-on-low': { type: 'string' },
+    match: { type: 'string', default: 'TS' },
+    yes: { type: 'boolean', short: 'y' },
+    verbose: { type: 'boolean', short: 'v' },
+    help: { type: 'boolean', short: 'h' },
+  },
+}, 'tsups');
+
+exitOnClosedPipe();
+
+const [command, ...args] = positionals;
+const verbose = (msg) => opt.verbose && console.error(`[probe] ${msg}`);
+const trace = (msg) => opt.verbose && console.error(`[serial] ${msg}`);
+const out = (human, data) => console.log(opt.json ? JSON.stringify(data) : human);
+
+async function resolvePort() {
+  if (opt.port) return opt.port;
+  const found = await detectPort({ match: opt.match, log: verbose });
+  if (!found) throw new Error('no UPS found; check the USB cable or pass --port');
+  verbose(`using ${found.path}`);
+  return found.path;
+}
+
+async function withConnection(fn) {
+  const conn = new UpsConnection(await resolvePort(), { trace });
+  await conn.open();
+  try {
+    return await fn(conn);
+  } finally {
+    await conn.close();
+  }
+}
+
+async function readRating(conn) {
+  try {
+    return parseRating(await conn.query(CMD.rating, { accept: isRatingReply }));
+  } catch {
+    return null;
+  }
+}
+
+function formatSample(s) {
+  const f = s.flags;
+  const mode = f.utilityFail ? 'ON BATTERY' : 'ONLINE';
+  const extras = [
+    f.batteryLow && 'BATTERY LOW',
+    f.bypass && 'BYPASS',
+    f.upsFailed && 'FAULT',
+    f.testInProgress && 'TESTING',
+    f.shutdownActive && 'SHUTDOWN PENDING',
+  ].filter(Boolean);
+  return (
+    `${mode}${extras.length ? ' [' + extras.join(', ') + ']' : ''}  ` +
+    `in ${s.inputVoltage}V  out ${s.outputVoltage}V  load ${s.loadPercent}%  ` +
+    `${s.frequency}Hz  batt ${s.batteryVoltage}V (${s.batterySOC}%)  ` +
+    `${s.temperature}°C  beep ${f.beeperOn ? 'on' : 'off'}`
+  );
+}
+
+const commands = {
+  async ports() {
+    const ports = await listPorts();
+    out(
+      ports.map((p) => `${p.path}\t${p.manufacturer ?? ''}\t${p.vendorId ?? ''}:${p.productId ?? ''}`).join('\n') ||
+        'no serial ports found',
+      ports,
+    );
+  },
+
+  async detect() {
+    const found = await detectPort({ match: opt.match, log: verbose });
+    if (!found) {
+      out('no UPS found', { found: false });
+      process.exitCode = 1;
+      return;
+    }
+    out(`${found.path}\t${found.info}`, { found: true, ...found });
+  },
+
+  async info() {
+    await withConnection(async (conn) => {
+      const info = parseInfo(await conn.query(CMD.identify, { accept: isInfoReply }));
+      const rating = await readRating(conn);
+      out(
+        `Company: ${info.company}\nModel:   ${info.model}\nVersion: ${info.version}\nRaw:     ${info.raw}\n` +
+          (rating
+            ? `Rating:  ${typeof rating.voltage === 'number' ? rating.voltage + 'V' : rating.voltage} ${rating.current}A, battery ${rating.batteryVoltage}V, ${rating.frequency}Hz`
+            : 'Rating:  (no reply to F)'),
+        { port: conn.path, info, rating },
+      );
+    });
+  },
+
+  async status() {
+    await withConnection(async (conn) => {
+      const rating = await readRating(conn);
+      const line = await conn.query(CMD.status, { accept: isQ1Reply });
+      const sample = parseQ1(line, rating);
+      if (!sample) throw new Error(`unrecognised Q1 reply: ${JSON.stringify(line)}`);
+      out(formatSample(sample), { port: conn.path, ts: Date.now(), ...sample });
+    });
+  },
+
+  async test() {
+    const kind = args[0] ?? 'quick';
+    const cmd = kind === 'quick' ? CMD.quickTest : kind === 'low' ? CMD.lowTest : testCommand(kind);
+    await withConnection((conn) => conn.send(cmd));
+    out(`sent ${JSON.stringify(cmd)}`, { sent: cmd });
+  },
+
+  async 'cancel-test'() {
+    await withConnection((conn) => conn.send(CMD.cancelTest));
+    out('battery test cancelled', { sent: CMD.cancelTest });
+  },
+
+  async beep() {
+    await withConnection((conn) => conn.send(CMD.toggleBeep));
+    out('beeper toggled', { sent: CMD.toggleBeep });
+  },
+
+  async shutdown() {
+    if (args[0] === undefined) throw new Error('usage: tsups shutdown <minutes> --yes');
+    const cmd = shutdownCommand(args[0]);
+    if (!opt.yes) throw new Error(`this turns UPS output OFF after ${args[0]} min; re-run with --yes`);
+    await withConnection((conn) => conn.send(cmd));
+    out(`sent ${JSON.stringify(cmd)}; cancel with "tsups cancel-shutdown"`, { sent: cmd });
+  },
+
+  async 'cancel-shutdown'() {
+    await withConnection((conn) => conn.send(CMD.cancelShutdown));
+    out('shutdown cancelled', { sent: CMD.cancelShutdown });
+  },
+
+  async raw() {
+    if (!args[0]) throw new Error('usage: tsups raw <command>');
+    await withConnection(async (conn) => {
+      const reply = await conn.query(`${args[0]}\r`).catch((e) => `(${e.message})`);
+      out(reply, { sent: args[0], reply });
+    });
+  },
+
+  async monitor() {
+    const intervalMs = Math.max(1, Number(opt.interval)) * 1000;
+    const failCmd = opt['shutdown-on-fail'] && shutdownCommand(opt['shutdown-on-fail']);
+    const lowCmd = opt['shutdown-on-low'] && shutdownCommand(opt['shutdown-on-low']);
+    let last = null;
+    let conn = null;
+
+    const record = (obj) => {
+      if (opt.log) appendFileSync(opt.log, JSON.stringify(obj) + '\n');
+    };
+
+    const emit = async (ev, sample) => {
+      const event = { type: 'event', ts: Date.now(), ...ev, sample };
+      record(event);
+      const stamp = new Date(event.ts).toISOString();
+      out(`${stamp}  ${ev.severity.toUpperCase().padEnd(8)} ${ev.code}: ${ev.message}`, event);
+      if (opt['on-event']) {
+        spawn(opt['on-event'], {
+          shell: true,
+          stdio: 'inherit',
+          env: {
+            ...process.env,
+            UPS_EVENT: ev.code,
+            UPS_MESSAGE: ev.message,
+            UPS_SEVERITY: ev.severity,
+            UPS_JSON: JSON.stringify(event),
+          },
+        }).on('error', (e) => console.error(`[on-event] ${e.message}`));
+      }
+      const shutdown = ev.code === 'UTILITY_FAIL' ? failCmd : ev.code === 'LOW_BATTERY' ? lowCmd : null;
+      if (shutdown && conn?.isOpen) {
+        await conn.send(shutdown);
+        console.error(`[monitor] sent UPS shutdown ${JSON.stringify(shutdown)}`);
+      }
+    };
+
+    const connect = async () => {
+      const c = new UpsConnection(await resolvePort(), { trace });
+      await c.open();
+      c.rating = await readRating(c);
+      return c;
+    };
+
+    let stopping = false;
+    const stop = async () => {
+      stopping = true;
+      await conn?.close();
+      process.exit(0);
+    };
+    process.on('SIGINT', stop);
+    process.on('SIGTERM', stop);
+
+    let misses = 0;
+    while (!stopping) {
+      if (!conn?.isOpen) {
+        try {
+          conn = await connect();
+          misses = 0;
+          await emit({ code: 'COMM_OK', message: `Connected on ${conn.path}`, severity: 'success' });
+        } catch (err) {
+          if (last !== 'offline') {
+            await emit({ code: 'COMM_FAIL', message: err.message, severity: 'warning' });
+            last = 'offline';
+          }
+          await new Promise((r) => setTimeout(r, 8000)); // rescan period
+          continue;
+        }
+      }
+
+      try {
+        const sample = parseQ1(await conn.query(CMD.status, { accept: isQ1Reply }), conn.rating);
+        if (sample) {
+          misses = 0;
+          const prev = typeof last === 'string' && last !== 'offline' ? last : null;
+          for (const ev of diffStatus(sample.status, prev)) await emit(ev, sample);
+          last = sample.status;
+          record({ type: 'sample', ts: Date.now(), ...sample });
+          if (!opt['events-only']) {
+            out(`${new Date().toISOString()}  ${formatSample(sample)}`, { type: 'sample', ts: Date.now(), ...sample });
+          }
+        }
+      } catch (err) {
+        if (++misses >= 3) {
+          await emit({ code: 'COMM_FAIL', message: `Lost contact with UPS: ${err.message}`, severity: 'warning' });
+          last = 'offline';
+          await conn.close();
+        }
+      }
+      await new Promise((r) => setTimeout(r, intervalMs));
+    }
+  },
+};
+
+async function main() {
+  if (opt.help || !command) {
+    console.log(HELP);
+    return;
+  }
+  const run = commands[command];
+  if (!run) {
+    console.error(`unknown command: ${command}\n\n${HELP}`);
+    process.exitCode = 2;
+    return;
+  }
+  await run();
+}
+
+main().catch((err) => {
+  console.error(`tsups: ${err.message}`);
+  process.exitCode = 1;
+});

package/src/protocol.js

@@ -0,0 +1,197 @@
+// Megatec / Voltronic "Q1" serial protocol, as used by TS Shara UPS units.
+
+export const BAUD_RATE = 2400;
+
+// Exact byte sequences sent to the UPS.
+export const CMD = {
+  identify: 'I\r\n',
+  status: 'Q1\r\n',
+  rating: 'F\r',
+  quickTest: 'T\r', // 10-second battery test
+  lowTest: 'TL\r', // test until battery low
+  toggleBeep: 'Q\r',
+  // Other standard Megatec commands.
+  cancelShutdown: 'C\r',
+  cancelTest: 'CT\r',
+};
+
+// Bit order of the 8-char status field in a Q1 reply (b7..b0, left to right).
+export const STATUS_BITS = [
+  'utilityFail',
+  'batteryLow',
+  'bypass',
+  'upsFailed',
+  'standby',
+  'testInProgress',
+  'shutdownActive',
+  'beeperOn',
+];
+
+const toNum = (s) => {
+  const n = parseFloat(s);
+  return Number.isNaN(n) ? 0 : n;
+};
+
+const stripPrefix = (line) => line.trim().replace(/^[#(]/, '').trim();
+
+// Lead-acid resting voltage -> state-of-charge lookup for 12 V and 24 V banks.
+const SOC_POINTS = [100, 90, 80, 70, 60, 50, 40, 30, 20, 10, 0];
+const SOC_VOLTS = {
+  12: [12.2, 12.09, 11.98, 11.87, 11.76, 11.64, 11.53, 11.42, 11.31, 10.91, 10.5],
+  24: [24.4, 24.18, 23.96, 23.74, 23.52, 23.28, 23.06, 22.84, 22.62, 21.82, 21.0],
+};
+
+export function calcSOC(volts, nominal) {
+  const table = SOC_VOLTS[nominal === 24 ? 24 : 12];
+  if (volts > table[0]) return 100;
+  if (volts <= table[table.length - 1]) return 0;
+  for (let i = 0; i < table.length - 1; i++) {
+    if (volts <= table[i] && volts > table[i + 1]) {
+      const slope = (SOC_POINTS[i] - SOC_POINTS[i + 1]) / (table[i] - table[i + 1]);
+      return Math.round(Math.max(0, Math.min(100, SOC_POINTS[i] - slope * (table[i] - volts))));
+    }
+  }
+  return 0;
+}
+
+// Without a rating reply, guess the bank voltage from the live reading (> 18 V => 24 V).
+export function nominalBatteryVoltage(batteryVolts, rating) {
+  if (rating?.batteryVoltage) {
+    const n = Math.round(rating.batteryVoltage / 12) * 12;
+    if (n === 12 || n === 24) return n;
+  }
+  return batteryVolts > 18 ? 24 : 12;
+}
+
+export function decodeStatus(bits) {
+  const out = {};
+  STATUS_BITS.forEach((name, i) => {
+    out[name] = bits[i] === '1';
+  });
+  return out;
+}
+
+// "(127.0 127.0 127.0 000 60.0 13.5 30.0 00000001" -> reading object, or null.
+export function parseQ1(line, rating) {
+  const parts = stripPrefix(line).split(/\s+/);
+  if (parts.length < 8) return null;
+  const [input, inputFault, output, load, freq, battery, temp, status] = parts;
+  if (!/^[01]{8}$/.test(status)) return null;
+  const batteryVoltage = toNum(battery);
+  const nominal = nominalBatteryVoltage(batteryVoltage, rating);
+  return {
+    inputVoltage: toNum(input),
+    inputFaultVoltage: toNum(inputFault),
+    outputVoltage: toNum(output),
+    loadPercent: toNum(load),
+    frequency: toNum(freq),
+    batteryVoltage,
+    batteryNominal: nominal,
+    batterySOC: calcSOC(batteryVoltage, nominal),
+    temperature: toNum(temp),
+    status,
+    flags: decodeStatus(status),
+  };
+}
+
+export const isQ1Reply = (line) => line.trim().startsWith('(') && parseQ1(line) !== null;
+
+// "#Univ. 100 24.00 60.0": four fields, the last two numeric.
+export const isRatingReply = (line) => {
+  if (!line.trim().startsWith('#')) return false;
+  const parts = stripPrefix(line).split(/\s+/);
+  return parts.length === 4 && parts.slice(2).every((p) => /^\d+(\.\d+)?$/.test(p));
+};
+
+export const isInfoReply = (line) => line.trim().startsWith('#') && !isRatingReply(line);
+
+// "#220.0 000 024.0 50.0" -> rated voltage, current, battery voltage, frequency.
+// TS Shara bivolt units report the voltage as "Univ." (universal input).
+export function parseRating(line) {
+  if (!isRatingReply(line)) return null;
+  const [voltage, current, batteryVoltage, frequency] = stripPrefix(line).split(/\s+/);
+  return {
+    voltage: Number.isNaN(parseFloat(voltage)) ? voltage : toNum(voltage),
+    current: toNum(current),
+    batteryVoltage: toNum(batteryVoltage),
+    frequency: toNum(frequency),
+    raw: line.trim(),
+  };
+}
+
+// "#TS -222  250514 Senoid  15 V010207057": Megatec fixed columns of
+// 15/10/10 chars separated by single spaces.
+export function parseInfo(line) {
+  const body = line.trim().replace(/^#/, '');
+  return {
+    company: body.slice(0, 15).trim(),
+    model: body.slice(16, 26).trim(),
+    version: body.slice(27, 37).trim(),
+    raw: line.trim(),
+  };
+}
+
+// Events emitted when a status bit flips.
+const EVENT_DEFS = {
+  utilityFail: [
+    { code: 'UTILITY_RESTORED', message: 'Utility power restored', severity: 'success' },
+    { code: 'UTILITY_FAIL', message: 'Utility power failure, running on battery', severity: 'warning' },
+  ],
+  batteryLow: [
+    { code: 'OK_BATTERY', message: 'Battery OK', severity: 'info' },
+    { code: 'LOW_BATTERY', message: 'Battery low', severity: 'critical' },
+  ],
+  bypass: [
+    { code: 'BYPASS_DISABLED', message: 'Bypass inactive', severity: 'info' },
+    { code: 'BYPASS_ENABLED', message: 'Bypass active', severity: 'info' },
+  ],
+  upsFailed: [
+    { code: 'UPS_FAULT_CLEARED', message: 'UPS fault cleared', severity: 'success' },
+    { code: 'UPS_FAULT', message: 'UPS reports internal fault', severity: 'critical' },
+  ],
+  testInProgress: [
+    { code: 'BATTERY_TEST_FINISHED', message: 'Battery test finished', severity: 'success' },
+    { code: 'BATTERY_TEST_STARTED', message: 'Battery test started', severity: 'success' },
+  ],
+  // Per the Megatec spec, bit 6 = 1 means a shutdown countdown is active.
+  shutdownActive: [
+    { code: 'SHUTDOWN_CANCELLED', message: 'UPS shutdown inactive', severity: 'info' },
+    { code: 'SHUTDOWN_PENDING', message: 'UPS shutdown countdown active', severity: 'warning' },
+  ],
+  beeperOn: [
+    { code: 'BEEP_DISABLED', message: 'Beeper disabled', severity: 'info' },
+    { code: 'BEEP_ENABLED', message: 'Beeper enabled', severity: 'info' },
+  ],
+};
+
+export function diffStatus(current, previous) {
+  if (!previous) return [];
+  const events = [];
+  STATUS_BITS.forEach((name, i) => {
+    const defs = EVENT_DEFS[name];
+    if (!defs || current[i] === previous[i]) return;
+    events.push({ ...defs[current[i] === '1' ? 1 : 0], bit: name });
+  });
+  return events;
+}
+
+// T<nn>: battery test for nn minutes (01..99).
+export function testCommand(minutes) {
+  const n = Number(minutes);
+  if (!Number.isInteger(n) || n < 1 || n > 99) {
+    throw new Error('test minutes must be an integer from 1 to 99');
+  }
+  return `T${String(n).padStart(2, '0')}\r`;
+}
+
+// S<n>: shut UPS output down after n minutes; .2-.9 or 01-10 per Megatec spec.
+export function shutdownCommand(minutes) {
+  const n = Number(minutes);
+  if (n >= 0.2 && n < 1 && Math.round(n * 10) === n * 10) {
+    return `S.${Math.round(n * 10)}\r`;
+  }
+  if (Number.isInteger(n) && n >= 1 && n <= 10) {
+    return `S${String(n).padStart(2, '0')}\r`;
+  }
+  throw new Error('shutdown delay must be 0.2-0.9 or an integer 1-10 (minutes)');
+}

package/src/serial.js

@@ -0,0 +1,174 @@
+import { readdirSync } from 'node:fs';
+import { SerialPort } from 'serialport';
+import { BAUD_RATE, CMD, isInfoReply } from './protocol.js';
+
+// USB serial devices by name. Used on Linux when SerialPort.list() cannot run:
+// it shells out to udevadm, which minimal containers do not have.
+export function scanDevPorts(dir = '/dev', names = readdirSync(dir)) {
+  return names
+    .filter((n) => /^tty(ACM|USB)\d+$/.test(n))
+    .sort()
+    .map((n) => ({ path: `${dir}/${n}` }));
+}
+
+export async function listPorts() {
+  try {
+    return await SerialPort.list();
+  } catch (err) {
+    if (process.platform !== 'linux') throw err;
+    return scanDevPorts();
+  }
+}
+
+export const isPermissionError = (err) => /permission denied|EACCES/i.test(`${err?.code} ${err?.message}`);
+
+// The TS Shara USB interface (STM32 CDC, 0483:5740) holds each reply until the
+// host writes again. A bare CR is ignored by the UPS but releases the reply.
+const KICK = '\r';
+const KICK_EVERY_MS = 300;
+// A command written right after a reply is silently dropped by the UPS;
+// measured on hardware: 0 ms gap fails, 500 ms works.
+const MIN_GAP_AFTER_RX_MS = 500;
+
+// Line-oriented connection: replies are CR-terminated, one reply per query.
+export class UpsConnection {
+  constructor(path, { baudRate = BAUD_RATE, trace = () => {} } = {}) {
+    this.path = path;
+    this.trace = trace;
+    this.port = new SerialPort({ path, baudRate, autoOpen: false });
+    this.buffer = '';
+    this.waiter = null;
+    this.chain = Promise.resolve();
+    this.lastRxAt = 0;
+    this.port.on('data', (chunk) => this.#onData(chunk));
+  }
+
+  async open() {
+    await new Promise((resolve, reject) => {
+      this.port.open((err) => (err ? reject(err) : resolve()));
+    });
+    // Release and discard any reply left pending by a previous session.
+    await this.#write(KICK);
+    await new Promise((r) => setTimeout(r, KICK_EVERY_MS));
+    this.buffer = '';
+  }
+
+  close() {
+    return new Promise((resolve) => {
+      if (!this.port.isOpen) return resolve();
+      this.port.close(() => resolve());
+    });
+  }
+
+  get isOpen() {
+    return this.port.isOpen;
+  }
+
+  onClose(fn) {
+    this.port.on('close', fn);
+    this.port.on('error', fn);
+  }
+
+  #onData(chunk) {
+    this.buffer += chunk.toString('latin1');
+    let idx;
+    while ((idx = this.buffer.indexOf('\r')) !== -1) {
+      const line = this.buffer.slice(0, idx).trim();
+      this.buffer = this.buffer.slice(idx + 1);
+      if (!line) continue;
+      this.lastRxAt = Date.now();
+      this.trace(`RX ${JSON.stringify(line)}`);
+      if (this.waiter?.accept(line)) {
+        const { resolve } = this.waiter;
+        this.waiter = null;
+        resolve(line);
+      } else if (this.waiter) {
+        this.trace('   (ignored: not the expected reply)');
+      }
+    }
+  }
+
+  #write(cmd) {
+    if (cmd !== KICK) this.trace(`TX ${JSON.stringify(cmd)}`);
+    return new Promise((resolve, reject) => {
+      this.port.write(cmd, (err) => {
+        if (err) return reject(err);
+        this.port.drain((e) => (e ? reject(e) : resolve()));
+      });
+    });
+  }
+
+  // Serialised so concurrent callers never interleave on the wire.
+  #enqueue(fn) {
+    const run = this.chain.then(fn, fn);
+    this.chain = run.catch(() => {});
+    return run;
+  }
+
+  async #settle() {
+    const wait = this.lastRxAt + MIN_GAP_AFTER_RX_MS - Date.now();
+    if (wait > 0) await new Promise((r) => setTimeout(r, wait));
+  }
+
+  send(cmd) {
+    return this.#enqueue(async () => {
+      await this.#settle();
+      await this.#write(cmd);
+    });
+  }
+
+  // Resolves with the first reply line that passes `accept`.
+  query(cmd, { timeout = 3000, accept = () => true } = {}) {
+    return this.#enqueue(async () => {
+      await this.#settle();
+      this.buffer = '';
+      let kicker;
+      const reply = new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+          this.waiter = null;
+          reject(new Error(`no reply to ${JSON.stringify(cmd)} within ${timeout} ms`));
+        }, timeout);
+        this.waiter = {
+          accept,
+          resolve: (line) => {
+            clearTimeout(timer);
+            resolve(line);
+          },
+        };
+      }).finally(() => clearInterval(kicker));
+      await this.#write(cmd);
+      kicker = setInterval(() => this.#write(KICK).catch(() => {}), KICK_EVERY_MS);
+      return reply;
+    });
+  }
+}
+
+// Probe: send "I", accept the port if the reply contains "TS".
+// Throws when no UPS was found but some port could not be opened for lack of
+// permission, since "not found" would hide the real cause.
+export async function detectPort({ match = 'TS', timeout = 3000, log = () => {} } = {}) {
+  const ports = await listPorts();
+  const denied = [];
+  for (const info of ports) {
+    const lower = info.path.toLowerCase();
+    if (lower.includes('bluetooth') || lower.includes('blth')) continue;
+    const conn = new UpsConnection(info.path, { trace: (m) => log(`${info.path}: ${m}`) });
+    try {
+      await conn.open();
+      const reply = await conn.query(CMD.identify, { timeout, accept: isInfoReply });
+      if (reply.includes(match)) return { path: info.path, info: reply };
+    } catch (err) {
+      log(`${info.path}: ${err.message}`);
+      if (isPermissionError(err)) denied.push(info.path);
+    } finally {
+      await conn.close();
+    }
+  }
+  if (denied.length) {
+    throw new Error(
+      `permission denied on ${denied.join(', ')}; add your user to the "dialout" group ` +
+        '(or "uucp" on Arch) and log in again, or run with sudo',
+    );
+  }
+  return null;
+}