@meshbench/client 0.0.1

package/lib/sessions.mjs

@@ -0,0 +1,122 @@
+// Which workbenches are running on this machine.
+//
+// `Workbench.attach()` goes to one address, which is enough while there is one
+// session per user. Two runs side by side - a soak beside the workbench
+// somebody is watching, two jobs on one CI runner - need a second address, and
+// until this existed the only record of where it was lived in the head of
+// whoever typed it.
+//
+// A module function rather than a method, because the question comes before a
+// connection: a script asks what is running in order to decide what to attach
+// to.
+//
+// # Telling a live session from what a dead one left behind
+//
+// A workbench killed with SIGKILL cannot clean up after itself, and neither
+// obvious check survives that. A unix socket file outlives the process that
+// bound it; a pid is reused, so a pid that exists today may name somebody
+// else's program. Both would report a dead session as running. So the check is
+// a connect to the address itself, which is the same check the workbench makes
+// before it takes an address, and the leftover file is removed when nothing
+// answers. A session's own tidying up shortens this directory; it is not what
+// makes the answer right.
+//
+// Windows works the same way: there the address is a loopback host and port and
+// the check is a TCP connect. Nothing here is unix-only.
+
+import fs from "node:fs";
+import path from "node:path";
+
+import { Connection, SESSIONS_ENV, cacheDir } from "./socket.mjs";
+
+/** How long a live session is given to describe itself. Generous, because the
+ *  answer is not worth a wrong row: a session in the middle of something slow is
+ *  still running and is listed either way, with its description missing. */
+export const DETAIL_WAIT_MS = 2000;
+
+/** The per-user directory the session files live in. */
+export function sessionsDir() {
+  return process.env[SESSIONS_ENV] || path.join(cacheDir(), "sessions");
+}
+
+/** The workbenches running on this machine, oldest first.
+ *
+ *  A session that has died is not listed, however it died, and what it left
+ *  behind is removed on the way past.
+ *
+ *  Each row is `{address, pid, startedAt, token, version, mode, project,
+ *  nodes}`. Pass one to `Workbench.attach({session})`: that is the way to reach
+ *  a second TCP session, whose token sits beside its address in its own file
+ *  where the per-user rendezvous file two of them share has only one. */
+export async function sessions() {
+  const dir = sessionsDir();
+  let entries;
+  try {
+    entries = fs.readdirSync(dir).filter((f) => f.endsWith(".json")).sort();
+  } catch {
+    return []; // no directory is no sessions, not a failure to report
+  }
+  const found = await Promise.all(entries.map(async (name) => {
+    const file = path.join(dir, name);
+    const row = read(file);
+    if (row === null) return null;
+    const detail = await describe(row);
+    if (detail === null) {
+      // Nothing is answering there, so nothing is running there.
+      try { fs.rmSync(file); } catch { /* somebody else got there first */ }
+      return null;
+    }
+    return { ...row, ...detail };
+  }));
+  // Oldest first, so two runs listed twice come back in the same order. The
+  // timestamps are RFC 3339 written by one program on one machine, so the text
+  // sorts in time order, and the address settles a tie whatever happens.
+  return found.filter(Boolean).sort((a, b) =>
+    (a.startedAt + a.address).localeCompare(b.startedAt + b.address));
+}
+
+function read(file) {
+  let got;
+  try {
+    got = JSON.parse(fs.readFileSync(file, "utf8"));
+  } catch {
+    // A file this package cannot read is a file it did not write, and refusing
+    // to list anything because of one would make the whole answer hostage to it.
+    return null;
+  }
+  if (!got.address) return null;
+  return {
+    address: got.address,
+    pid: got.pid || 0,
+    startedAt: String(got.started_at || ""),
+    token: String(got.token || ""),
+  };
+}
+
+/** One connection, both answers: whether anything is there, and what it is
+ *  running. A connection that opens is a live session whether or not it finds a
+ *  moment to describe itself. */
+async function describe(row) {
+  let conn;
+  try {
+    conn = await Connection.open({
+      address: row.address, token: row.token,
+      connectTimeoutMs: DETAIL_WAIT_MS, callTimeoutMs: DETAIL_WAIT_MS,
+    });
+  } catch {
+    return null;
+  }
+  try {
+    const got = (await conn.call("session.hello")) || {};
+    return {
+      version: String(got.version || ""),
+      mode: String(got.mode || ""),
+      project: String(got.project || ""),
+      nodes: got.nodes || 0,
+    };
+  } catch {
+    return {};
+  } finally {
+    conn.close();
+  }
+}

package/lib/sets.mjs

@@ -0,0 +1,275 @@
+// Generated by tools/clientgen. DO NOT EDIT.
+//
+// The closed sets, from internal/world/scenario. Named members rather than free
+// strings so an editor can complete them and a member that has gone is
+// undefined at the call site - and generated so the list cannot be wrong the
+// week somebody adds a board.
+//
+// Every member is a plain string, so it goes on the wire as itself and a
+// literal is still accepted anywhere one of these is asked for. The names match
+// the Python client's exactly, so a script moved between the two changes the
+// dots and nothing else.
+
+/** What a node is. */
+export const Kind = Object.freeze({
+  /** forwards, and nothing else */
+  SIMPLE_REPEATER: "simple-repeater",
+  /** forwards, serves clients, holds state */
+  ADVANCED_REPEATER: "advanced-repeater",
+  /** a user's device - the thing a phone connects to */
+  COMPANION: "companion",
+  /**
+   * holds posts for clients to collect, and does not forward: a mesh that
+   * treats one as a repeater overstates its own reach
+   */
+  ROOM_SERVER: "room-server",
+  /**
+   * runs no firmware and transmits nothing; captures the summed field at its
+   * antenna and hands back IQ
+   */
+  SDR_OBSERVER: "sdr-observer",
+  /**
+   * interference that is not MeshCore, propagated through the same terrain
+   * as everything else
+   */
+  EMITTER: "emitter",
+});
+
+/**
+ * A hardware profile this build knows about.
+ *
+ * A node's board decides its transmit ceiling, its receive chain's noise
+ * figure and the battery the energy model uses, so naming one that does not
+ * exist is refused rather than defaulted.
+ */
+export const Board = Object.freeze({
+  /** ESP32-S3, SX1262, by Ebyte. */
+  EBYTE_EORA_S3: "Ebyte_EoRa-S3",
+  /** ESP32, SX1262, by Ebyte. */
+  GENERIC_E22_SX1262: "Generic_E22_sx1262",
+  /** ESP32-S3, SX1262, by Heltec. */
+  HELTEC_E213: "Heltec_E213",
+  /** ESP32-S3, SX1262, by Heltec. */
+  HELTEC_E290: "Heltec_E290",
+  /** ESP32-S3, SX1262, by Heltec. */
+  HELTEC_WSL3: "Heltec_WSL3",
+  /** ESP32-S3, SX1262, by Heltec. */
+  HELTEC_WIRELESS_PAPER: "Heltec_Wireless_Paper",
+  /** ESP32-S3, SX1262, by Heltec. */
+  HELTEC_WIRELESS_TRACKER: "Heltec_Wireless_Tracker",
+  /** nRF52840, SX1262, by Heltec. */
+  HELTEC_MESH_SOLAR: "Heltec_mesh_solar",
+  /** nRF52840, SX1262, by Heltec. */
+  HELTEC_T096: "Heltec_t096",
+  /** nRF52840, SX1262, by Heltec. */
+  HELTEC_T114: "Heltec_t114",
+  /** ESP32, SX1276, by Heltec. */
+  HELTEC_V2: "Heltec_v2",
+  /** ESP32-S3, SX1262, by Heltec. */
+  HELTEC_V3: "Heltec_v3",
+  /** ESP32-S3, SX1262, by LILYGO. */
+  LILYGO_T3S3_SX1262: "LilyGo_T3S3_sx1262",
+  /** ESP32-S3, SX1262, by LILYGO. */
+  LILYGO_TBEAM_1W: "LilyGo_TBeam_1W",
+  /** ESP32-S3, SX1262, by LILYGO. */
+  LILYGO_TDECK: "LilyGo_TDeck",
+  /** ESP32-S3, SX1262, by RAKwireless. */
+  RAK_3112: "RAK_3112",
+  /** nRF52840, SX1262, by RAKwireless. */
+  RAK_4631: "RAK_4631",
+  /** ESP32-S3, SX1262, by LILYGO. */
+  STATION_G2: "Station_G2",
+  /** ESP32-S3, SX1262, by LILYGO. */
+  STATION_G3_ESP32: "Station_G3_ESP32",
+  /** ESP32, SX1262, by LILYGO. */
+  TBEAM_SX1262: "Tbeam_SX1262",
+  /** ESP32-S3, SX1262, by Seeed. */
+  XIAO_S3: "Xiao_S3",
+  /** ESP32-S3, SX1262, by Seeed. */
+  XIAO_S3_WIO: "Xiao_S3_WIO",
+  /** nRF52840, SX1262, by Seeed. */
+  XIAO_NRF52: "Xiao_nrf52",
+  /** ESP32-S3, SX1262, by Heltec. */
+  HELTEC_TRACKER_V2: "heltec_tracker_v2",
+  /** ESP32-S3, SX1262, by Heltec. */
+  HELTEC_V4: "heltec_v4",
+});
+
+/** Every board, for a caller offering a choice. */
+export const Boards = Object.freeze(Object.values(Board));
+
+/**
+ * A named set of LoRa parameters for a territory.
+ *
+ * An agreement between operators rather than a configuration, which is why
+ * the list is baked in rather than fetched.
+ */
+export const Preset = Object.freeze({
+  /** 915.800 MHz, 250.0 kHz, SF10, CR 4/5. */
+  AUSTRALIA: "Australia",
+  /** 916.575 MHz, 62.5 kHz, SF7, CR 4/8. */
+  AUSTRALIA_NARROW: "Australia (Narrow)",
+  /** 915.075 MHz, 125.0 kHz, SF9, CR 4/5. */
+  AUSTRALIA_MID: "Australia (Mid)",
+  /** 923.125 MHz, 62.5 kHz, SF8, CR 4/8. */
+  AUSTRALIA_SA_WA: "Australia: SA, WA",
+  /** 923.125 MHz, 62.5 kHz, SF8, CR 4/5. */
+  AUSTRALIA_QLD: "Australia: QLD",
+  /** 923.125 MHz, 62.5 kHz, SF8, CR 4/8. */
+  BRAZIL: "Brazil",
+  /** 869.618 MHz, 62.5 kHz, SF8, CR 4/8. */
+  EU_UK_NARROW: "EU/UK (Narrow)",
+  /** 869.525 MHz, 250.0 kHz, SF11, CR 4/5. */
+  EU_UK_DEPRECATED: "EU/UK (Deprecated)",
+  /** 869.432 MHz, 62.5 kHz, SF7, CR 4/5. */
+  CZECH_REPUBLIC_NARROW: "Czech Republic (Narrow)",
+  /** 433.650 MHz, 250.0 kHz, SF11, CR 4/5. */
+  EU_433MHZ_LONG_RANGE: "EU 433MHz (Long Range)",
+  /** 433.650 MHz, 62.5 kHz, SF8, CR 4/8. */
+  EU_433MHZ_NARROW: "EU 433MHz (Narrow)",
+  /** 869.618 MHz, 62.5 kHz, SF7, CR 4/5. */
+  NETHERLANDS: "Netherlands",
+  /** 917.375 MHz, 250.0 kHz, SF11, CR 4/5. */
+  NEW_ZEALAND: "New Zealand",
+  /** 917.375 MHz, 62.5 kHz, SF7, CR 4/5. */
+  NEW_ZEALAND_NARROW: "New Zealand (Narrow)",
+  /** 433.375 MHz, 62.5 kHz, SF9, CR 4/6. */
+  PORTUGAL_433: "Portugal 433",
+  /** 869.618 MHz, 62.5 kHz, SF7, CR 4/6. */
+  PORTUGAL_868: "Portugal 868",
+  /** 869.618 MHz, 62.5 kHz, SF8, CR 4/8. */
+  SWITZERLAND: "Switzerland",
+  /** 910.525 MHz, 62.5 kHz, SF7, CR 4/5. */
+  USA_CANADA_RECOMMENDED: "USA/Canada (Recommended)",
+  /** 920.250 MHz, 62.5 kHz, SF8, CR 4/5. */
+  VIETNAM_NARROW: "Vietnam (Narrow)",
+  /** 920.250 MHz, 250.0 kHz, SF11, CR 4/5. */
+  VIETNAM_DEPRECATED: "Vietnam (Deprecated)",
+});
+
+/** Every preset, for a caller offering a choice. */
+export const Presets = Object.freeze(Object.values(Preset));
+
+/** What a fresh scenario uses. */
+export const DEFAULT_PRESET = "EU/UK (Narrow)";
+
+/**
+ * The MeshCore application a node runs, named as upstream names its example
+ * directory.
+ *
+ * The string every firmware verb is keyed on. The published catalogue spells
+ * some of the same things differently - "repeater", "room-server" - and
+ * those belong to the release assets; typing one at a verb pins nothing, and
+ * the run then refuses to start with no clue as to why.
+ */
+export const Role = Object.freeze({
+  /** forwards; both repeater kinds run it and differ only in configuration */
+  SIMPLE_REPEATER: "simple_repeater",
+  /** a user's device - the thing a phone connects to */
+  COMPANION_RADIO: "companion_radio",
+  /** holds posts for clients to collect, and does not forward */
+  SIMPLE_ROOM_SERVER: "simple_room_server",
+  /**
+   * the USB companion build; board images only, where a board publishes both
+   * transports at one version
+   */
+  COMPANION_RADIO_USB: "companion_radio_usb",
+  /** the Bluetooth companion build; board images only */
+  COMPANION_RADIO_BLE: "companion_radio_ble",
+});
+
+/** Every role, for a caller offering a choice. */
+export const Roles = Object.freeze(Object.values(Role));
+
+/** What happened to an event. */
+export const Class = Object.freeze({
+  /** this node transmitted it */
+  SENT: "sent",
+  /** this node decoded it, for the first time */
+  RECEIVED: "received",
+  /**
+   * missed because this node's own transmitter was keyed; LoRa is half
+   * duplex
+   */
+  HALF_DUPLEX: "half-duplex",
+  /** would have decoded, but a stronger signal took it */
+  INTERFERENCE: "interference",
+  /**
+   * decoded its header, then a collision destroyed more symbols than the
+   * coding rate could repair
+   */
+  COLLISION: "collision",
+  /**
+   * arrived at a demodulator already locked to another packet; a LoRa
+   * receiver decodes one at a time
+   */
+  RECEIVER_BUSY: "receiver-busy",
+  /** too quiet: under the demodulator's threshold for its spreading factor */
+  FLOOR: "floor",
+  /**
+   * a miss whose cause the engine did not establish; never assume it was a
+   * weak signal
+   */
+  UNCLASSIFIED: "unclassified",
+});
+
+/** Every class, for a caller offering a choice. */
+export const Classes = Object.freeze(Object.values(Class));
+
+/** A pane of a node's own window. */
+export const Tab = Object.freeze({
+  /** the firmware's text console, which only a repeater has */
+  CONSOLE: "Console",
+  /** channels, contacts and the companion command line */
+  COMPANION: "Companion",
+  /** an observer's antenna: serve it, read the address */
+  SDR: "SDR",
+  /** what this node is: identity, radio, regions, firmware */
+  SETTINGS: "Settings",
+  /** what the chip is really doing */
+  RADIO: "Radio",
+  /** what this node stands under and which way it points */
+  ANTENNA: "Antenna",
+  /** what it has cost and what it has carried */
+  STATS: "Stats",
+  /** what it has heard and sent, in order */
+  ACTIVITY: "Activity",
+  /** hand this companion to a real client */
+  CONNECT: "Connect",
+  /**
+   * the board drawn as itself - its screen, its lamps, the buttons somebody
+   * can press; only a board that declares any of that grows it
+   */
+  HARDWARE: "Hardware",
+  /**
+   * what the node printed: its serial port, the emulator running it, or the
+   * radio model beside it
+   */
+  OUTPUT: "Output",
+});
+
+/** Every tab, for a caller offering a choice. */
+export const Tabs = Object.freeze(Object.values(Tab));
+
+/** How an imported deployment meets what is already loaded. */
+export const Strategy = Object.freeze({
+  /**
+   * throw away what is loaded and take the import; what the shipped fixtures
+   * were built with
+   */
+  REPLACE: "replace-all",
+  /** keep what is loaded and add the names it has not got */
+  ADD: "add",
+});
+
+/** How a served companion is reached. */
+export const Transport = Object.freeze({
+  /**
+   * a socket on every interface, on a port the system picks; the one to
+   * point a phone or another machine at
+   */
+  TCP: "tcp",
+  /** a pseudo-terminal, for a client that wants a serial port */
+  SERIAL: "serial",
+});
+

package/lib/sim.mjs

@@ -0,0 +1,125 @@
+// The clock, and the run.
+
+import { MeshbenchError } from "./errors.mjs";
+import {
+  FIRMWARE_WAIT_MS, JOB_WAIT_MS, RUN_WAIT_MS, secs, waitFor,
+} from "./wait.mjs";
+
+/** The clock, and the run. Live. */
+export class Sim {
+  constructor(wb) { this._wb = wb; }
+
+  /** What the clock is doing. */
+  async state() { return (await this._wb.call("sim.state")) || {}; }
+
+  async playing() { return Boolean((await this.state()).playing); }
+
+  async nowMs() { return (await this.state()).now_ms || 0; }
+
+  /** Bring the run up: wait out the warm, start every node, and play.
+   *
+   *  Deliberately not one call to `sim.start`. That verb is the play button's
+   *  own handler and answers four ways - it pauses if already playing, declines
+   *  while links are being measured, or starts firmware and does not play - so
+   *  a script pressing it once gets whichever of those the moment happens to be
+   *  in.
+   *
+   *  Worse, it only starts firmware when no node is running. Pin a build onto
+   *  two nodes of a fifty-eight node fixture and it considers the mesh started,
+   *  plays with fifty-six of them down, and says nothing.
+   *
+   *  So this asks for the three things it actually wants, in order, and checks
+   *  each one. */
+  async start({ warmMs = JOB_WAIT_MS, firmwareMs = FIRMWARE_WAIT_MS } = {}) {
+    // The links first. Nothing that follows means anything against a matrix
+    // that is still being measured.
+    await this._wb.waitIdle(warmMs);
+    // Idle is not the same as measured. A warm that stopped to ask permission
+    // to download terrain finishes its own job row, so the wait above returns
+    // in a moment having waited for nothing: no link was measured, and every
+    // study after this would answer over free space.
+    const held = await this.state();
+    if (held.warm_held) {
+      const note = (held.ground || {}).note ||
+        "call terrain.allow to answer the question either way";
+      throw new MeshbenchError(
+        "the link measurement is held: no terrain has been downloaded and no " +
+        `link has been measured. ${note}`);
+    }
+    // Then every node that is not up, which firmware.start does and sim.start
+    // does only when none of them are.
+    const st = await this._wb.firmware.state();
+    if ((st.running || 0) < (st.nodes || 0)) {
+      await this._wb.firmware.start();
+      await this._wb.firmware.waitStarted(firmwareMs);
+    }
+    // Then the clock, by its own name. play cannot pause, which is the other
+    // half of what made sim.start unusable from a script.
+    if (!(await this.playing())) await this.play();
+  }
+
+  async play() { await this._wb.call("sim.play"); }
+
+  async pause() { await this._wb.call("sim.pause"); }
+
+  /** Press the play button as the window presses it, and answer as it answers.
+   *
+   *  Almost never what a script means - `start()` is - and here because the
+   *  verb exists and a client that hid it would send somebody back to `call`. */
+  async toggle() { return (await this._wb.call("sim.toggle")) || {}; }
+
+  /** Advance one tick, which is `step_ms` of simulated time. */
+  async step() { await this._wb.call("sim.step"); }
+
+  /** Put the clock and the counters back to the start of the run. */
+  async reset() { await this._wb.call("sim.reset"); }
+
+  /** Step a paused run, which is how a command gets the time it needs to be
+   *  answered without starting the clock. */
+  async settle(steps = 60) { await this._wb.call("sim.settle", { steps }); }
+
+  /** Fix the run. Same seed, same scenario, same result - which is what makes a
+   *  changed result mean something. */
+  async setSeed(seed) { await this._wb.call("sim.seed", { seed }); }
+
+  /** How much simulated time one tick advances. */
+  async setStepMs(ms) { await this._wb.call("sim.speed", { step_ms: ms }); }
+
+  /** Whether play starts MeshCore on every node, or runs the channel with
+   *  nothing behind it. */
+  async setRealFirmware(on = true) { await this._wb.call("sim.kind", { real: on }); }
+
+  /** Advance the mesh's own clock by this much, and wait for it.
+   *
+   *  Two clocks, one call, and they are not the same one. `simulatedMs` is the
+   *  mesh's: five minutes here is five minutes of its time. `waitMs` is yours -
+   *  how long you are prepared to sit here before giving up. On 155 emulated
+   *  nodes five simulated minutes is a great deal more than five of yours,
+   *  which is why the second is separate and generous. */
+  async run(simulatedMs, { waitMs = RUN_WAIT_MS } = {}) {
+    if (!(simulatedMs > 0)) {
+      throw new MeshbenchError("run() needs a length in simulated milliseconds");
+    }
+    await this._wb.call("sim.run", { for_ms: simulatedMs });
+    await this.waitStopped(waitMs);
+  }
+
+  /** Wait for a run to end. `timeoutMs` is wall clock. */
+  waitStopped(timeoutMs = RUN_WAIT_MS) {
+    return waitFor(async () => {
+      const st = await this.state();
+      if (!st.playing) return [true, ""];
+      return [false, `${secs(st.now_ms || 0)} of simulated time`];
+    }, timeoutMs, "the run to finish");
+  }
+
+  /** Wait for the mesh's clock to reach a moment. `atMs` is simulated time;
+   *  `timeoutMs` is yours. */
+  waitUntil(atMs, timeoutMs = RUN_WAIT_MS) {
+    return waitFor(async () => {
+      const st = await this.state();
+      if ((st.now_ms || 0) >= atMs) return [true, ""];
+      return [false, secs(st.now_ms || 0)];
+    }, timeoutMs, `simulated time to reach ${secs(atMs)}`);
+  }
+}