@intomind/sdk 0.0.0-stage → 1.4.0

package/src/session.ts

@@ -0,0 +1,670 @@
+/**
+ * One device, as a state machine.
+ *
+ * Bytes go in, events come out, and commands go back. Nothing here performs
+ * input or output, so the same code runs behind a browser's Bluetooth
+ * stack, a desktop one, or a test with no Bluetooth at all.
+ */
+
+import {
+  CODE_BY_GAIN,
+  CODE_BY_RATE,
+  DeviceInfo,
+  FILL,
+  Invalid,
+  type CapabilityName,
+  type OpcodeName,
+  type Embedding,
+  type Prediction,
+  type Response,
+  type Status,
+  continuity,
+  decodeDeviceInfo,
+  decodeEmbedding,
+  decodePacket,
+  decodePrediction,
+  decodeResponse,
+  decodeStatus,
+  decodeTimeSync,
+  encodeRequest,
+  microvolts,
+  BIAS_MODES,
+  EMBEDDING_FORMS,
+  IDENTIFY_MAX_SECONDS,
+  INDICATOR_LEVELS,
+  checkChain,
+  encodeChain,
+  encodePredictionInput,
+  MODES,
+  NAME_MAX_COMPOSED,
+  PRODUCT_NAME,
+  composeName,
+  encodeModelInterval,
+  encodeNameParts,
+  nameFits,
+} from "./protocol.ts";
+import type {
+  BiasModeName,
+  CapabilityHighName,
+  CatalogEntry,
+  EmbeddingFormName,
+  IndicatorLevelName,
+  InputSourceName,
+  ModeName,
+  Stage,
+} from "./protocol.ts";
+import { Exchange, Timebase, type Fit } from "./timebase.ts";
+
+/** Something a caller asked of a device that the device has not offered. */
+export class SessionError extends Error {
+  /** Build one with the message explaining what was asked for. */
+  constructor(message: string) {
+    super(message);
+    this.name = "SessionError";
+  }
+}
+
+/** The device has not said what it is yet, so nothing can be decoded. */
+export class NoDeviceInfo extends SessionError {
+  constructor() {
+    super("read device info first, so nothing has to be assumed");
+    this.name = "NoDeviceInfo";
+  }
+}
+
+/** The device does not claim the capability this needs. */
+export class NotCapable extends SessionError {
+  /** Which capability was missing. */
+  readonly capability: string;
+
+  /** Build one naming the missing capability. */
+  constructor(capability: string) {
+    super(`this device does not claim the ${capability} capability`);
+    this.name = "NotCapable";
+    this.capability = capability;
+  }
+}
+
+/** Bytes to write, and where to write them. */
+export interface Command {
+  /**
+   * The sixteen bit fill of the characteristic. `protocol.uuid` turns it
+   * into the full identifier your stack wants.
+   */
+  readonly characteristic: number;
+  /** The bytes to write. */
+  readonly bytes: Uint8Array;
+  /** Whether the write must be acknowledged. */
+  readonly withResponse: boolean;
+}
+
+/** A run of samples that arrived together. */
+export class Batch {
+  /** The device's own index for the first sample. */
+  readonly index: number;
+  /** The device time of the first sample, in the device's ticks. */
+  readonly deviceTime: bigint;
+  /** Channels per row. */
+  readonly channels: number;
+  /** Converter counts, one row per sample, laid out row after row. */
+  readonly counts: Int32Array;
+  /** Lead-off status latched with the most recent sample. */
+  readonly leadoff: number;
+  /** The gain the samples were taken at. */
+  readonly gain: number;
+  /** The rate the samples were taken at, or null for a code this contract does not define. */
+  readonly sampleRateHz: number | null;
+  /** The mode the samples were taken in: 0 normal, 1 test signal, 2 inputs shorted, 3 synthetic (1.3). */
+  readonly mode: number;
+  /** 1.3: the samples were generated by the device, not measured (packet type 0x04). Never store one as a measurement. */
+  readonly synthetic: boolean;
+
+  /** Build from decoded fields. `Session` is what calls this. */
+  constructor(f: {
+    index: number;
+    deviceTime: bigint;
+    channels: number;
+    counts: Int32Array;
+    leadoff: number;
+    gain: number;
+    sampleRateHz: number | null;
+    mode?: number;
+    synthetic?: boolean;
+  }) {
+    this.index = f.index;
+    this.deviceTime = f.deviceTime;
+    this.channels = f.channels;
+    this.counts = f.counts;
+    this.leadoff = f.leadoff;
+    this.gain = f.gain;
+    this.sampleRateHz = f.sampleRateHz;
+    this.mode = f.mode ?? 0;
+    this.synthetic = f.synthetic ?? false;
+  }
+
+  /** Samples in this batch. */
+  get rows(): number {
+    return this.channels === 0 ? 0 : this.counts.length / this.channels;
+  }
+
+  /** One converter count. */
+  count(row: number, channel: number): number {
+    return this.counts[row * this.channels + channel]!;
+  }
+
+  /**
+   * One sample, in microvolts, with the device's own reference and width.
+   * Nothing is assumed about either.
+   */
+  microvolts(row: number, channel: number, info: DeviceInfo): number {
+    return microvolts(this.count(row, channel), info.vrefUv, this.gain, info.adcBits);
+  }
+}
+
+/** A break in the timeline, written down rather than smoothed over. */
+export interface Gap {
+  /** The last index before the break. */
+  readonly lastIndexBefore: number;
+  /** The first index after the break. */
+  readonly firstIndexAfter: number;
+  /** Samples missing. Null for a re-base, whose extent is not a number. */
+  readonly samplesLost: number | null;
+  /** Device time of the last sample before the break. */
+  readonly deviceTimeBefore: bigint;
+  /** Device time of the first sample after the break. */
+  readonly deviceTimeAfter: bigint;
+  /** Whether this is a re-base rather than a loss. See `samplesLost`. */
+  readonly isRebase: boolean;
+}
+
+/** What arrived. */
+export type Event =
+  | { readonly type: "samples"; readonly batch: Batch }
+  /** Announced before the batch that follows it. */
+  | { readonly type: "gap"; readonly gap: Gap }
+  | { readonly type: "status"; readonly status: Status }
+  /** A control answer. A caller that issued a command matches on this. */
+  | { readonly type: "answer"; readonly answer: Response }
+  | { readonly type: "prediction"; readonly prediction: Prediction }
+  /** 1.2: one notification of the encoder's output, a whole vector or a part of one. `protocol.EmbeddingAssembler` puts them into whole windows. */
+  | { readonly type: "embedding"; readonly embedding: Embedding }
+  /** A notification that was not a message. Counted, never guessed at. */
+  | { readonly type: "undecodable"; readonly characteristic: number }
+  /**
+   * A data packet this session already passed on, delivered again by the
+   * host's Bluetooth stack: dropped, never passed on twice, and counted. It
+   * means another program on the same computer is listening to the device,
+   * since the system sends each notification once per subscriber and every
+   * subscriber hears all of the copies. `index` is its first sample.
+   */
+  | { readonly type: "duplicate"; readonly index: number };
+
+/** One device. */
+export class Session {
+  #info: DeviceInfo | null = null;
+  #timebase: Timebase | null = null;
+  #previous: { index: number; nSamples: number; deviceTime: bigint } | null = null;
+  /** The first index and device time of the last few packets passed on, what a copy is recognized by. */
+  #recent: string[] = [];
+
+  /** Samples the device's own indexing says never arrived, over this session. */
+  samplesLost = 0;
+  /** Breaks counted as a re-base rather than a loss, over this session. */
+  rebases = 0;
+  /** Notifications that were not a message, over this session: see the "undecodable" event. */
+  undecodable = 0;
+  /** Data packets delivered twice by the host and dropped: see the "duplicate" event. */
+  duplicates = 0;
+
+  /** What was read from the device info characteristic. */
+  onDeviceInfo(bytes: Uint8Array): DeviceInfo {
+    const info = decodeDeviceInfo(bytes);
+    this.#timebase = new Timebase(info.tickHz);
+    this.#info = info;
+    return info;
+  }
+
+  /** What the device said it is, or null before it has been read. */
+  get info(): DeviceInfo | null {
+    return this.#info;
+  }
+
+  /** The same, for a caller that cannot proceed without it. */
+  requireInfo(): DeviceInfo {
+    if (this.#info === null) throw new NoDeviceInfo();
+    return this.#info;
+  }
+
+  /**
+   * Whether the device claims a capability. A device that has not said what
+   * it is claims nothing.
+   */
+  can(capability: CapabilityName | string): boolean {
+    return this.#info?.can(capability) ?? false;
+  }
+
+  /** The timebase fit from time exchanges, or null before `onDeviceInfo`. */
+  get timebase(): Timebase | null {
+    return this.#timebase;
+  }
+
+  /** Host time for a device time, once enough exchanges have been taken. */
+  hostTime(deviceTicks: bigint): number | null {
+    return this.#timebase?.hostTime(deviceTicks) ?? null;
+  }
+
+  // --- commands -------------------------------------------------------------
+
+  #command(opcode: OpcodeName, arg: number | Uint8Array | null = null): Command {
+    return { characteristic: FILL.CONTROL, bytes: encodeRequest(opcode, arg), withResponse: true };
+  }
+
+  #require(capability: CapabilityName): void {
+    if (!this.can(capability)) throw new NotCapable(capability);
+  }
+
+  /** Whether the device claims a capability from the second word of Device Info (1.3): synthetic, device_name. */
+  canHigh(capability: CapabilityHighName): boolean {
+    return this.#info !== null && this.#info.can(capability);
+  }
+
+  #requireHigh(capability: CapabilityHighName): void {
+    if (!this.canHigh(capability)) throw new NotCapable(capability);
+  }
+
+  /** Ask the device to stream. */
+  startStream(): Command {
+    return this.#command("start_stream");
+  }
+
+  /** Ask the device to stop streaming. */
+  stopStream(): Command {
+    return this.#command("stop_stream");
+  }
+
+  /**
+   * Set the rate, in samples per second. The device refuses a change while
+   * it is streaming, so every sample of a recording sits under one
+   * configuration.
+   */
+  setRate(sps: number): Command {
+    const code = CODE_BY_RATE.get(sps);
+    if (code === undefined) throw new Invalid(`${sps} samples per second is not a rate this contract defines`);
+    return this.#command("set_rate", code);
+  }
+
+  /** Set the gain. Refused while streaming. */
+  setGain(gain: number): Command {
+    const code = CODE_BY_GAIN.get(gain);
+    if (code === undefined) throw new Invalid(`a gain of ${gain} is not one this contract defines`);
+    return this.#command("set_gain", code);
+  }
+
+  /**
+   * What the amplifier listens to: 0 the electrodes, 1 the internal test
+   * signal, 2 shorted inputs. The last two are capabilities a device
+   * declares, so a device that does not offer one is not asked for it.
+   */
+  setMode(mode: number | ModeName): Command {
+    const code = typeof mode === "string" ? MODES[mode] : mode;
+    if (code === 1) this.#require("test_signal");
+    else if (code === 2) this.#require("input_short");
+    // 1.3: the device generates the signal, converter off. Only a device
+    // that claims it; the device itself refuses it while streaming and at a
+    // rate other than 500 samples a second.
+    else if (code === 3) this.#requireHigh("synthetic");
+    else if (code !== 0) throw new Invalid(`mode ${mode} is not one this contract defines`);
+    return this.#command("set_mode", code);
+  }
+
+  /** Turn lead-off detection on or off. */
+  setLeadoff(on: boolean): Command {
+    this.#require("leadoff");
+    return this.#command("set_leadoff", on ? 1 : 0);
+  }
+
+  /**
+   * Ask the device what time it is. Note the host clock either side and
+   * give both to `onTimeSync`.
+   */
+  timeSync(): Command {
+    return this.#command("time_sync");
+  }
+
+  /** The answer to a time request, with the host clock either side of it. */
+  onTimeSync(payload: Uint8Array, before: number, after: number): Fit | null {
+    const ticks = decodeTimeSync(payload);
+    if (this.#timebase === null) throw new NoDeviceInfo();
+    return this.#timebase.observe(new Exchange(before, after, ticks));
+  }
+
+  /** Zero the sample index and start a fresh epoch. */
+  resetEpoch(): Command {
+    this.#previous = null;
+    return this.#command("reset_epoch");
+  }
+
+  /** Ask for the measured battery voltage and charge. */
+  getBattery(): Command {
+    this.#require("battery_voltage");
+    return this.#command("get_battery");
+  }
+
+  /** Ask why and how many times the device has booted. */
+  getBootInfo(): Command {
+    return this.#command("get_boot_info");
+  }
+
+  /** Turn predictions on or off. */
+  setPredictions(on: boolean): Command {
+    this.#require("model");
+    return this.#command("set_predictions", on ? 1 : 0);
+  }
+
+  /** Ask for the model runtime's state. */
+  getModelInfo(): Command {
+    this.#require("model");
+    return this.#command("get_model_info");
+  }
+
+  /** Select a head slot. 0 is the built-in head. */
+  selectHead(slot: number): Command {
+    this.#require("heads");
+    return this.#command("select_head", slot);
+  }
+
+  /** Ask for the head slots and which one is selected. */
+  listHeads(): Command {
+    this.#require("heads");
+    return this.#command("list_heads");
+  }
+
+  /**
+   * Ask which encoder each head names (1.4): one record for each LIST_HEADS record, read with `decodeHeadEncoders`.
+   * A device before 1.4 is not asked, and its heads say nothing of their encoder.
+   */
+  listHeadEncoders(): Command {
+    this.#require("heads");
+    const [major, minor] = this.#info?.protocol ?? [0, 0];
+    if (major < 1 || (major === 1 && minor < 4)) throw new NotCapable("head_encoders");
+    return this.#command("list_head_encoders");
+  }
+
+  /** Remove a user head slot's contents. */
+  removeHead(slot: number): Command {
+    this.#require("heads");
+    return this.#command("remove_head", slot);
+  }
+
+  // --- processing, on devices that run a chain ------------------------------
+  //
+  // The device preprocesses its own signal. When a chain is in force only
+  // its output streams, and the chain is readable at any time, so a
+  // recording can say exactly what produced its samples. The rules a chain
+  // must meet are the device's, restated in `protocol.checkChain`, so a
+  // chain that cannot run is refused here in words before anything is
+  // sent. The device refuses a change while streaming: stop, set, start.
+
+  /** Ask for the stage kinds the device runs. `protocol.decodeCatalog` reads the answer. */
+  pipelineCatalog(): Command {
+    this.#require("pipeline");
+    return this.#command("get_pipeline_catalog");
+  }
+
+  /** Ask for the chain in force. `protocol.decodePipelineState` reads the answer. */
+  pipeline(): Command {
+    this.#require("pipeline");
+    return this.#command("get_pipeline");
+  }
+
+  /** Put a chain on the device's signal path, checked here first against the rate the device runs at. */
+  setPipeline(stages: readonly Stage[], rateSps: number, catalog?: readonly CatalogEntry[]): Command {
+    this.#require("pipeline");
+    checkChain(stages, rateSps, catalog);
+    return this.#command("set_pipeline", encodeChain(stages));
+  }
+
+  /** The natural signal, as this host's choice. */
+  clearPipeline(): Command {
+    this.#require("pipeline");
+    return this.#command("clear_pipeline");
+  }
+
+  /** The device's own default chain for its current rate. */
+  restorePipelineDefault(): Command {
+    this.#require("pipeline");
+    return this.#command("restore_pipeline_default");
+  }
+
+  /** Ask where the model's input comes from. `protocol.decodePredictionInput` reads the answer. */
+  predictionInput(): Command {
+    this.#require("model");
+    return this.#command("get_prediction_input");
+  }
+
+  /**
+   * Point the model at the stream as it is, at the natural signal, or at a
+   * chain of its own, without touching the stream. Only the model's own
+   * source carries a chain, checked here against the rate.
+   */
+  setPredictionInput(source: InputSourceName, stages: readonly Stage[] = [], rateSps = 500, catalog?: readonly CatalogEntry[]): Command {
+    this.#require("model");
+    if (source === "own_chain") checkChain(stages, rateSps, catalog);
+    else if (stages.length !== 0) throw new Invalid("only the model's own chain carries stages");
+    return this.#command("set_prediction_input", encodePredictionInput(source, stages));
+  }
+
+  /** The bias drive, on a device that claims one: off, on, or loop open. */
+  setBias(mode: BiasModeName): Command {
+    this.#require("bias_drive");
+    const code = BIAS_MODES[mode];
+    if (code === undefined) throw new Invalid(`${mode} is not a bias mode this contract defines`);
+    return this.#command("set_bias", code);
+  }
+
+  /** Ask for the bias output measured. `protocol.decodeBiasDiagnostic` reads the answer. */
+  biasDiagnostic(): Command {
+    this.#require("bias_drive");
+    return this.#command("get_bias_diagnostic");
+  }
+
+  // --- the lamp, the converter's registers, embeddings (1.2) ----------------
+
+  /** Ask for the status lamp's level. The answer's one byte is an `INDICATOR_LEVELS` value. */
+  indicator(): Command {
+    this.#require("indicator");
+    return this.#command("get_indicator");
+  }
+
+  /**
+   * Put the lamp at a level: silent, reserved (the default: low battery and a
+   * converter fault at power on), or verbose. The device keeps it across
+   * power cycles.
+   */
+  setIndicator(level: IndicatorLevelName): Command {
+    this.#require("indicator");
+    const code = INDICATOR_LEVELS[level];
+    if (code === undefined) throw new Invalid(`${level} is not a lamp level this contract defines`);
+    return this.#command("set_indicator", code);
+  }
+
+  /** Blink the lamp so this device can be told from others, for 1 to 30 seconds at every level; 0 stops one in progress. */
+  identify(seconds = 5): Command {
+    this.#require("indicator");
+    if (!Number.isInteger(seconds) || seconds < 0 || seconds > IDENTIFY_MAX_SECONDS) {
+      throw new Invalid(`identify runs 1 to ${IDENTIFY_MAX_SECONDS} seconds, or 0 to stop`);
+    }
+    return this.#command("identify", seconds);
+  }
+
+  /** Ask for the converter's registers, raw, for debugging; read only, and only while not streaming. `protocol.decodeConverterRegisters` reads the answer. */
+  converterRegisters(): Command {
+    this.#require("converter_registers");
+    return this.#command("get_converter_registers");
+  }
+
+  /**
+   * Ask the device for its encoder's output for each window while it
+   * streams: "window" for the one vector a head consumes, "tokens" for the
+   * per-slice vectors reconstruction consumes, "both", or "off". Whole
+   * windows come from `protocol.EmbeddingAssembler` fed with embedding events.
+   */
+  setEmbeddings(form: EmbeddingFormName): Command {
+    this.#require("embeddings");
+    const code = EMBEDDING_FORMS[form];
+    if (code === undefined) throw new Invalid(`${form} is not an embedding form this contract defines`);
+    return this.#command("set_embeddings", code);
+  }
+
+  // --- 1.3: the model's cadence and the device's name -----------------------
+
+  /** Ask how often the model describes a window and the least interval the device keeps; `protocol.decodeModelInterval` reads the answer. */
+  modelInterval(): Command {
+    this.#require("model_cadence");
+    return this.#command("get_model_interval");
+  }
+
+  /**
+   * One described window every `seconds`, on a grid from the stream's start;
+   * 0 is every window the device can. The device refuses a value below its
+   * minimum and keeps the setting across power cycles.
+   */
+  setModelInterval(seconds: number): Command {
+    this.#require("model_cadence");
+    return this.#command("set_model_interval", encodeModelInterval(seconds));
+  }
+
+  /** Ask for the name and the adjective a host set; `protocol.decodeNameParts` reads the answer. */
+  getName(): Command {
+    this.#requireHigh("device_name");
+    return this.#command("get_name");
+  }
+
+  /**
+   * Name the device. It advertises `name's adjective IntoMind One` from the
+   * next advertisement and keeps both parts across power cycles. The
+   * composition must fit the 29 bytes a scan response carries, so every scan
+   * list shows the whole of it; refused here when it does not, or when a
+   * part has a leading or trailing space or a control character.
+   */
+  setName(name: string, adjective: string, product: string = PRODUCT_NAME): Command {
+    this.#requireHigh("device_name");
+    if (!nameFits(name, adjective, product)) {
+      throw new Invalid(`"${composeName(name, adjective, product)}" does not fit the ${NAME_MAX_COMPOSED} bytes the air carries, or a part has a leading or trailing space or a control character`);
+    }
+    return this.#command("set_name", encodeNameParts(name, adjective));
+  }
+
+  // --- notifications --------------------------------------------------------
+
+  /**
+   * Hand in one notification, and take whatever it meant.
+   *
+   * A batch that follows a break is preceded by the gap, so a caller that
+   * writes samples down writes the gap down first and can never splice.
+   */
+  onNotification(characteristic: number, bytes: Uint8Array): Event[] {
+    switch (characteristic) {
+      case FILL.EEG_DATA:
+        return this.#onSamples(bytes);
+      case FILL.STATUS:
+        return this.#decoded(characteristic, () => ({ type: "status", status: decodeStatus(bytes) }));
+      case FILL.CONTROL_RESPONSE:
+        return this.#decoded(characteristic, () => ({ type: "answer", answer: decodeResponse(bytes) }));
+      case FILL.PREDICTIONS:
+        return this.#decoded(characteristic, () => ({
+          type: "prediction",
+          prediction: decodePrediction(bytes),
+        }));
+      case FILL.EMBEDDINGS:
+        return this.#decoded(characteristic, () => ({
+          type: "embedding",
+          embedding: decodeEmbedding(bytes),
+        }));
+      default:
+        return this.#undecodable(characteristic);
+    }
+  }
+
+  #decoded(characteristic: number, decode: () => Event): Event[] {
+    try {
+      return [decode()];
+    } catch {
+      return this.#undecodable(characteristic);
+    }
+  }
+
+  #undecodable(characteristic: number): Event[] {
+    this.undecodable += 1;
+    return [{ type: "undecodable", characteristic }];
+  }
+
+  #onSamples(bytes: Uint8Array): Event[] {
+    const info = this.#info;
+    // A device that has not said how wide it is cannot have its samples
+    // read, because the payload length only means something against a
+    // channel count.
+    if (info === null) return this.#undecodable(FILL.EEG_DATA);
+    let packet;
+    try {
+      packet = decodePacket(bytes, info.channels);
+    } catch {
+      return this.#undecodable(FILL.EEG_DATA);
+    }
+
+    const events: Event[] = [];
+    const previous = this.#previous;
+    // A packet with the first index and the device time of one just passed
+    // on is that packet again, delivered twice by the host. Dropped and
+    // counted, so no sample is passed on twice and no break is announced
+    // that did not happen. A device that restarts its count carries a new
+    // device time, so a restart is never taken for a copy, and anything else
+    // is judged by the contract's continuity rule unchanged.
+    const key = `${packet.index}:${packet.deviceTime}`;
+    if (this.#recent.includes(key)) {
+      this.duplicates += 1;
+      return [{ type: "duplicate", index: packet.index }];
+    }
+    this.#recent.push(key);
+    if (this.#recent.length > 8) this.#recent.shift();
+    if (previous !== null) {
+      const verdict = continuity(previous.index, previous.nSamples, packet.index, packet.discontinuity);
+      if (verdict.broken) {
+        if (verdict.lost === null) this.rebases += 1;
+        else this.samplesLost += verdict.lost;
+        events.push({
+          type: "gap",
+          gap: {
+            lastIndexBefore: (previous.index + previous.nSamples - 1) >>> 0,
+            firstIndexAfter: packet.index,
+            samplesLost: verdict.lost,
+            deviceTimeBefore: previous.deviceTime,
+            deviceTimeAfter: packet.deviceTime,
+            isRebase: verdict.lost === null,
+          },
+        });
+      }
+    }
+    this.#previous = { index: packet.index, nSamples: packet.nSamples, deviceTime: packet.deviceTime };
+
+    const counts = new Int32Array(packet.nSamples * info.channels);
+    for (let row = 0; row < packet.nSamples; row++) {
+      for (let c = 0; c < info.channels; c++) counts[row * info.channels + c] = packet.counts[row]![c]!;
+    }
+    events.push({
+      type: "samples",
+      batch: new Batch({
+        index: packet.index,
+        deviceTime: packet.deviceTime,
+        channels: info.channels,
+        counts,
+        leadoff: packet.loffStatp,
+        gain: packet.gain,
+        sampleRateHz: packet.sps,
+        mode: packet.mode,
+        synthetic: packet.synthetic,
+      }),
+    });
+    return events;
+  }
+}