@packet-net/soundmodem 0.62.0

package/src/modem.js

@@ -0,0 +1,224 @@
+// pdn-soundmodem in a browser tab: the C# modem core compiled to WebAssembly, a Web Audio
+// graph either side of it, and a PTT line over Web Serial. This is the sound-card answer to
+// the question a KISS TNC on a serial port answers, and it sits in the same place: raw AX.25
+// frames in, raw AX.25 frames out, and a carrier-sense reading. No waterfall, no config API,
+// no KISS framing - there is no serial link here to frame anything for.
+//
+// The audio contract with the wasm module is one rate, the AudioContext's: the module
+// decimates into the mode's DSP rate and upsamples back out with the same anti-aliased
+// filters the daemon uses on a real sound card, so nothing here resamples and the browser's
+// own resampler never touches modem audio.
+
+const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+
+/** PTT on a serial control line - the RTS/DTR keying every packet interface has done for decades. */
+export class SerialPtt {
+  /**
+   * Prompts for a port (must be called from a user gesture) and opens it.
+   * @param {{ signal?: 'rts' | 'dtr', baudRate?: number }} [options]
+   * @returns {Promise<SerialPtt>}
+   */
+  static async request({ signal = 'rts', baudRate = 9600 } = {}) {
+    if (!navigator.serial) throw new Error('this browser has no Web Serial (Chrome or Edge required)')
+    const port = await navigator.serial.requestPort()
+    await port.open({ baudRate })
+    const ptt = new SerialPtt(port, signal)
+    await ptt.unkey()
+    return ptt
+  }
+
+  /**
+   * @param {SerialPort} port an open Web Serial port
+   * @param {'rts' | 'dtr'} [signal] which control line keys the radio
+   */
+  constructor(port, signal = 'rts') {
+    this.port = port
+    this.signal = signal
+  }
+
+  #signals(on) {
+    return this.signal === 'dtr' ? { dataTerminalReady: on } : { requestToSend: on }
+  }
+
+  key() { return this.port.setSignals(this.#signals(true)) }
+  unkey() { return this.port.setSignals(this.#signals(false)) }
+  async close() { await this.unkey(); await this.port.close() }
+}
+
+/** PTT that keys nothing - for a VOX interface, or for listening only. */
+export const NoPtt = { key: async () => {}, unkey: async () => {}, close: async () => {} }
+
+export class SoundModem {
+  #exports
+  #handle = 0
+  #context
+  #stream
+  #worklet
+  #frameListeners = new Set()
+  #transmitting = false
+
+  /**
+   * Loads the WebAssembly runtime and the modem core. Do this once per page; opening and
+   * closing modes afterwards is cheap.
+   */
+  /**
+   * @param {string} [frameworkUrl] where the WebAssembly bundle lives; the default is the
+   *   copy shipped alongside this module, which is right for a CDN and for self-hosting.
+   * @returns {Promise<SoundModem>}
+   */
+  static async load(frameworkUrl = new URL('../_framework/dotnet.js', import.meta.url).href) {
+    const { dotnet } = await import(frameworkUrl)
+    const runtime = await dotnet.withDiagnosticTracing(false).create()
+    const exports = await runtime.getAssemblyExports(runtime.getConfig().mainAssemblyName)
+    return new SoundModem(exports.Modem)
+  }
+
+  constructor(exports) {
+    this.#exports = exports
+    this.txDelayMs = 300
+    this.txTailMs = 20
+    this.pttLeadMs = 50
+  }
+
+  /**
+   * Every mode the catalogue can build, e.g. afsk1200, bpsk300, qpsk2400, fsk9600-il2p.
+   * @returns {string[]}
+   */
+  get modes() { return this.#exports.Modes() }
+
+  /** The audio rate the graph is running at, once open. @returns {number} */
+  get sampleRate() { return this.#context?.sampleRate ?? 0 }
+
+  /** True while this station is keyed. @returns {boolean} */
+  get transmitting() { return this.#transmitting }
+
+  /**
+   * Opens the radio: microphone (or USB codec input) in, speaker (or USB codec output) out,
+   * a mode running between them.
+   *
+   * The three audio-processing constraints are not optional. A browser will happily hand a
+   * modem echo-cancelled, noise-suppressed, automatically-gained audio, and every one of
+   * those is a defect generator a demodulator cannot see around.
+   */
+  /**
+   * @param {{ mode?: string, inputDeviceId?: string, outputDeviceId?: string,
+   *           ptt?: { key(): Promise<void>, unkey(): Promise<void>, close?(): Promise<void> },
+   *           sampleRate?: number }} [options]
+   * @returns {Promise<number>} the rate the DSP chain ended up running at
+   */
+  async open({ mode = 'afsk1200', inputDeviceId, outputDeviceId, ptt = NoPtt, sampleRate = 48000 } = {}) {
+    this.ptt = ptt
+    this.#stream = await navigator.mediaDevices.getUserMedia({
+      audio: {
+        deviceId: inputDeviceId ? { exact: inputDeviceId } : undefined,
+        channelCount: 1,
+        echoCancellation: false,
+        noiseSuppression: false,
+        autoGainControl: false,
+      },
+    })
+
+    this.#context = new AudioContext({ sampleRate, latencyHint: 'playback' })
+    if (outputDeviceId && this.#context.setSinkId) await this.#context.setSinkId(outputDeviceId)
+    await this.#context.audioWorklet.addModule(new URL('./rx-worklet.js', import.meta.url))
+
+    this.mode = mode
+    this.#handle = this.#exports.Open(mode, this.#context.sampleRate)
+    this.dspRate = this.#exports.DspRateOf(this.#handle)
+
+    const source = this.#context.createMediaStreamSource(this.#stream)
+    this.#worklet = new AudioWorkletNode(this.#context, 'sound-modem-rx', {
+      numberOfInputs: 1,
+      numberOfOutputs: 0,
+      processorOptions: { blockSize: 1024 },
+    })
+    this.#worklet.port.onmessage = (event) => this.#receive(event.data)
+    source.connect(this.#worklet)
+    await this.#context.resume()
+    return this.dspRate
+  }
+
+  /**
+   * Subscribes to decoded frames - raw AX.25 bytes, no flags and no FCS. Returns the
+   * unsubscribe. There can be several: a soundcard modem hears the whole channel, and the
+   * session layer wanting a frame must not stop a monitor pane seeing it.
+   */
+  /**
+   * @param {(frame: Uint8Array) => void} callback
+   * @returns {() => void} the unsubscribe
+   */
+  onFrame(callback) {
+    this.#frameListeners.add(callback)
+    return () => { this.#frameListeners.delete(callback) }
+  }
+
+  /** True while the demodulator sees a coherent packet signal (the DCD lamp). @returns {boolean} */
+  get carrierDetect() { return !this.#transmitting && this.#exports.CarrierDetect(this.#handle) }
+
+  /**
+   * Carrier sense: busy while anything is on channel, ourselves included.
+   * @returns {boolean}
+   */
+  channelBusy() {
+    if (this.#transmitting) return true
+    return this.#exports.ChannelBusy(this.#handle)
+  }
+
+  /** @param {Float32Array} samples */
+  #receive(samples) {
+    // Our own transmission is not traffic to decode, and hearing it would only teach the
+    // busy detector that the channel is occupied by the station that is talking.
+    if (this.#transmitting) return
+    this.#exports.Feed(this.#handle, new Uint8Array(samples.buffer, samples.byteOffset, samples.byteLength))
+    const packed = this.#exports.TakeFrames(this.#handle)
+    for (let at = 0; at < packed.length;) {
+      const length = packed[at] | (packed[at + 1] << 8)
+      const frame = packed.subarray(at + 2, at + 2 + length)
+      for (const listener of this.#frameListeners) listener(frame)
+      at += 2 + length
+    }
+  }
+
+  /**
+   * Keys the radio and sends one AX.25 frame. TXDELAY is inside the modulated audio, so the
+   * only waits here are the radio's own: a lead before the audio starts, and a tail after it
+   * ends - and the tail has to include the output latency, because the last sample leaves the
+   * graph well before it leaves the sound card.
+   */
+  /**
+   * @param {Uint8Array} ax25Frame one AX.25 frame, no flags and no FCS
+   * @param {number} [txDelayMs]
+   * @returns {Promise<void>}
+   */
+  async transmit(ax25Frame, txDelayMs = this.txDelayMs) {
+    const pcm = new Float32Array(this.#exports.Modulate(this.#handle, ax25Frame, txDelayMs).buffer)
+    const buffer = this.#context.createBuffer(1, pcm.length, this.#context.sampleRate)
+    buffer.copyToChannel(pcm, 0)
+
+    this.#transmitting = true
+    try {
+      await this.ptt.key()
+      await sleep(this.pttLeadMs)
+      const node = this.#context.createBufferSource()
+      node.buffer = buffer
+      node.connect(this.#context.destination)
+      const ended = new Promise((resolve) => { node.onended = resolve })
+      node.start()
+      await ended
+      await sleep(this.txTailMs + Math.round((this.#context.outputLatency ?? 0) * 1000))
+    } finally {
+      await this.ptt.unkey()
+      this.#transmitting = false
+      this.#exports.ResetCarrierState(this.#handle)
+    }
+  }
+
+  async close() {
+    if (this.#handle) this.#exports.Close(this.#handle)
+    this.#handle = 0
+    this.#worklet?.port.close()
+    this.#stream?.getTracks().forEach((t) => t.stop())
+    await this.#context?.close()
+    await this.ptt?.close?.()
+  }
+}

package/src/rx-worklet.js

@@ -0,0 +1,32 @@
+// The receive end of the audio graph. This runs on the audio render thread, where the .NET
+// runtime cannot go (an AudioWorklet has no module loader and no threads of its own), so all
+// it does is gather render quanta into blocks big enough to be worth a message and hand them
+// over. The DSP happens where the runtime is.
+//
+// A block is one allocation per ~21 ms at 48 kHz. That is the price of not having
+// SharedArrayBuffer: a shared ring would need COOP/COEP headers on the page, which static
+// hosting often will not set, and a packet modem does not need the microseconds it would buy.
+class SoundModemRx extends AudioWorkletProcessor {
+  constructor(options) {
+    super()
+    this.blockSize = options?.processorOptions?.blockSize ?? 1024
+    this.block = new Float32Array(this.blockSize)
+    this.at = 0
+  }
+
+  process(inputs) {
+    const channel = inputs[0]?.[0]
+    if (!channel) return true
+    for (let i = 0; i < channel.length; i++) {
+      this.block[this.at++] = channel[i]
+      if (this.at === this.blockSize) {
+        this.port.postMessage(this.block, [this.block.buffer])
+        this.block = new Float32Array(this.blockSize)
+        this.at = 0
+      }
+    }
+    return true
+  }
+}
+
+registerProcessor('sound-modem-rx', SoundModemRx)

package/src/transport.js

@@ -0,0 +1,85 @@
+// The modem as a transport: the slot a KISS TNC on a serial port occupies, filled by a sound
+// card instead.
+//
+// This file imports nothing. It satisfies a transport contract by shape - `start`, `send`,
+// `stop`, and a `channelBusy()` for carrier sense - so any link layer that wants raw AX.25
+// frames from somewhere can take them from here without either side knowing about the other.
+// A station picks its modem the way it always has: a TNC on a lead, or the sound card.
+
+/**
+ * Classic p-persistent CSMA, AX.25 §6.4.2 - the same loop the C# SoundModemChannel runs:
+ * while the channel is busy, wait a slot; when it is clear, roll p, and on a failed roll wait
+ * a slot and try again. It belongs to the modem rather than to a link layer because it is a
+ * property of a shared half-duplex radio channel: whoever owns the PTT owns the contention.
+ */
+async function contend({ channelBusy, persistence, slotTimeMs, signal }) {
+  const sleep = (ms) => new Promise((resolve) => setTimeout(resolve, ms))
+  for (;;) {
+    if (signal?.aborted) throw new DOMException('aborted', 'AbortError')
+    if (channelBusy()) { await sleep(slotTimeMs); continue }
+    if (Math.floor(Math.random() * 256) <= persistence) return
+    await sleep(slotTimeMs)
+  }
+}
+
+/** A transport, and a carrier-sense source, backed by a {@link SoundModem}. */
+export class SoundModemTransport {
+  /**
+   * @param {import('./modem.js').SoundModem} modem an open SoundModem
+   * @param options KISS channel-access parameters, in KISS units: persistence 0-255 where
+   *   p = (value + 1) / 256, slot time and TXDELAY in milliseconds. The defaults are the
+   *   daemon's.
+   */
+  constructor(modem, { txDelayMs = 300, persistence = 63, slotTimeMs = 100 } = {}) {
+    this.modem = modem
+    /** @type {(() => void) | undefined} */
+    this.unsubscribe = undefined
+    this.txDelayMs = txDelayMs
+    this.persistence = persistence
+    this.slotTimeMs = slotTimeMs
+    this.running = false
+    /** Transmissions are serialised: one radio, one keyup at a time. */
+    this.queue = Promise.resolve()
+  }
+
+  /**
+   * @param {(frame: Uint8Array) => void} onFrame
+   * @returns {Promise<void>}
+   */
+  async start(onFrame) {
+    this.unsubscribe?.()
+    this.unsubscribe = this.modem.onFrame(onFrame)
+    this.running = true
+  }
+
+  /**
+   * @param {Uint8Array} axBytes one AX.25 frame, no flags and no FCS
+   * @returns {Promise<void>}
+   */
+  async send(axBytes) {
+    if (!this.running) throw new Error('transport not started')
+    const send = this.queue.then(async () => {
+      await contend({
+        channelBusy: () => this.modem.channelBusy(),
+        persistence: this.persistence,
+        slotTimeMs: this.slotTimeMs,
+      })
+      await this.modem.transmit(axBytes, this.txDelayMs)
+    })
+    // Keep the chain alive after a failed send so one error does not wedge the radio.
+    this.queue = send.catch(() => {})
+    return send
+  }
+
+  async stop() {
+    this.running = false
+    this.unsubscribe?.()
+    this.unsubscribe = undefined
+  }
+
+  /**
+   * Carrier sense: a null would mean "cannot tell", and this modem always can.
+   * @returns {boolean}
+   */
+  channelBusy() { return this.modem.channelBusy() }
+}

package/types/index.d.ts

@@ -0,0 +1,2 @@
+export { SoundModemTransport } from "./transport.js";
+export { SoundModem, SerialPtt, NoPtt } from "./modem.js";

package/types/modem.d.ts

@@ -0,0 +1,116 @@
+/** PTT on a serial control line - the RTS/DTR keying every packet interface has done for decades. */
+export class SerialPtt {
+    /**
+     * Prompts for a port (must be called from a user gesture) and opens it.
+     * @param {{ signal?: 'rts' | 'dtr', baudRate?: number }} [options]
+     * @returns {Promise<SerialPtt>}
+     */
+    static request({ signal, baudRate }?: {
+        signal?: "rts" | "dtr";
+        baudRate?: number;
+    }): Promise<SerialPtt>;
+    /**
+     * @param {SerialPort} port an open Web Serial port
+     * @param {'rts' | 'dtr'} [signal] which control line keys the radio
+     */
+    constructor(port: SerialPort, signal?: "rts" | "dtr");
+    port: SerialPort;
+    signal: "rts" | "dtr";
+    key(): any;
+    unkey(): any;
+    close(): Promise<void>;
+    #private;
+}
+export namespace NoPtt {
+    function key(): Promise<void>;
+    function unkey(): Promise<void>;
+    function close(): Promise<void>;
+}
+export class SoundModem {
+    /**
+     * Loads the WebAssembly runtime and the modem core. Do this once per page; opening and
+     * closing modes afterwards is cheap.
+     */
+    /**
+     * @param {string} [frameworkUrl] where the WebAssembly bundle lives; the default is the
+     *   copy shipped alongside this module, which is right for a CDN and for self-hosting.
+     * @returns {Promise<SoundModem>}
+     */
+    static load(frameworkUrl?: string): Promise<SoundModem>;
+    constructor(exports: any);
+    txDelayMs: number;
+    txTailMs: number;
+    pttLeadMs: number;
+    /**
+     * Every mode the catalogue can build, e.g. afsk1200, bpsk300, qpsk2400, fsk9600-il2p.
+     * @returns {string[]}
+     */
+    get modes(): string[];
+    /** The audio rate the graph is running at, once open. @returns {number} */
+    get sampleRate(): number;
+    /** True while this station is keyed. @returns {boolean} */
+    get transmitting(): boolean;
+    /**
+     * Opens the radio: microphone (or USB codec input) in, speaker (or USB codec output) out,
+     * a mode running between them.
+     *
+     * The three audio-processing constraints are not optional. A browser will happily hand a
+     * modem echo-cancelled, noise-suppressed, automatically-gained audio, and every one of
+     * those is a defect generator a demodulator cannot see around.
+     */
+    /**
+     * @param {{ mode?: string, inputDeviceId?: string, outputDeviceId?: string,
+     *           ptt?: { key(): Promise<void>, unkey(): Promise<void>, close?(): Promise<void> },
+     *           sampleRate?: number }} [options]
+     * @returns {Promise<number>} the rate the DSP chain ended up running at
+     */
+    open({ mode, inputDeviceId, outputDeviceId, ptt, sampleRate }?: {
+        mode?: string;
+        inputDeviceId?: string;
+        outputDeviceId?: string;
+        ptt?: {
+            key(): Promise<void>;
+            unkey(): Promise<void>;
+            close?(): Promise<void>;
+        };
+        sampleRate?: number;
+    }): Promise<number>;
+    ptt: {
+        key(): Promise<void>;
+        unkey(): Promise<void>;
+        close?(): Promise<void>;
+    } | undefined;
+    mode: string | undefined;
+    dspRate: any;
+    /**
+     * Subscribes to decoded frames - raw AX.25 bytes, no flags and no FCS. Returns the
+     * unsubscribe. There can be several: a soundcard modem hears the whole channel, and the
+     * session layer wanting a frame must not stop a monitor pane seeing it.
+     */
+    /**
+     * @param {(frame: Uint8Array) => void} callback
+     * @returns {() => void} the unsubscribe
+     */
+    onFrame(callback: (frame: Uint8Array) => void): () => void;
+    /** True while the demodulator sees a coherent packet signal (the DCD lamp). @returns {boolean} */
+    get carrierDetect(): boolean;
+    /**
+     * Carrier sense: busy while anything is on channel, ourselves included.
+     * @returns {boolean}
+     */
+    channelBusy(): boolean;
+    /**
+     * Keys the radio and sends one AX.25 frame. TXDELAY is inside the modulated audio, so the
+     * only waits here are the radio's own: a lead before the audio starts, and a tail after it
+     * ends - and the tail has to include the output latency, because the last sample leaves the
+     * graph well before it leaves the sound card.
+     */
+    /**
+     * @param {Uint8Array} ax25Frame one AX.25 frame, no flags and no FCS
+     * @param {number} [txDelayMs]
+     * @returns {Promise<void>}
+     */
+    transmit(ax25Frame: Uint8Array, txDelayMs?: number): Promise<void>;
+    close(): Promise<void>;
+    #private;
+}

package/types/rx-worklet.d.ts

@@ -0,0 +1,7 @@
+declare class SoundModemRx {
+    constructor(options: any);
+    blockSize: any;
+    block: Float32Array<any>;
+    at: number;
+    process(inputs: any): boolean;
+}

package/types/transport.d.ts

@@ -0,0 +1,39 @@
+/** A transport, and a carrier-sense source, backed by a {@link SoundModem}. */
+export class SoundModemTransport {
+    /**
+     * @param {import('./modem.js').SoundModem} modem an open SoundModem
+     * @param options KISS channel-access parameters, in KISS units: persistence 0-255 where
+     *   p = (value + 1) / 256, slot time and TXDELAY in milliseconds. The defaults are the
+     *   daemon's.
+     */
+    constructor(modem: import("./modem.js").SoundModem, { txDelayMs, persistence, slotTimeMs }?: {
+        txDelayMs?: number | undefined;
+        persistence?: number | undefined;
+        slotTimeMs?: number | undefined;
+    });
+    modem: import("./modem.js").SoundModem;
+    /** @type {(() => void) | undefined} */
+    unsubscribe: (() => void) | undefined;
+    txDelayMs: number;
+    persistence: number;
+    slotTimeMs: number;
+    running: boolean;
+    /** Transmissions are serialised: one radio, one keyup at a time. */
+    queue: Promise<void>;
+    /**
+     * @param {(frame: Uint8Array) => void} onFrame
+     * @returns {Promise<void>}
+     */
+    start(onFrame: (frame: Uint8Array) => void): Promise<void>;
+    /**
+     * @param {Uint8Array} axBytes one AX.25 frame, no flags and no FCS
+     * @returns {Promise<void>}
+     */
+    send(axBytes: Uint8Array): Promise<void>;
+    stop(): Promise<void>;
+    /**
+     * Carrier sense: a null would mean "cannot tell", and this modem always can.
+     * @returns {boolean}
+     */
+    channelBusy(): boolean;
+}