tci-client-node 0.2.0 → 0.4.0

package/dist/index.js

@@ -20,7 +20,7 @@ function toTciError(error, fallbackCode = "protocol-error") {
 }
 
 // src/client/TciClient.ts
-import { EventEmitter as EventEmitter2 } from "eventemitter3";
+import { EventEmitter as EventEmitter3 } from "eventemitter3";
 import WebSocket2 from "ws";
 
 // src/audio/streamFrame.ts
@@ -241,6 +241,15 @@ function payloadToFloat32(frameOrPayload, sampleType) {
   }
   return output;
 }
+function decodeInterleavedIq(frame) {
+  if (frame.streamType !== 0 /* IQ_STREAM */) {
+    throw new TciError("invalid-frame", "Expected a TCI IQ stream frame");
+  }
+  if (frame.channels !== 2 || frame.sampleCount % 2 !== 0) {
+    throw new TciError("invalid-frame", `TCI IQ frame must contain interleaved I/Q pairs, got ${frame.channels} channels`);
+  }
+  return payloadToFloat32(frame);
+}
 function samplesToPayload(samples, sampleType) {
   const type = normalizeSampleType(sampleType);
   const bytes = sampleTypeBytes(type);
@@ -588,6 +597,302 @@ function ensureSemicolon(command) {
   return command.trim().endsWith(";") ? command.trim() : `${command.trim()};`;
 }
 
+// src/meter/types.ts
+var UNKNOWN_TCI_METER_CAPABILITIES = {
+  rxLevel: "unknown",
+  rxAverageLevel: "unknown",
+  rxPeakBin: "unknown",
+  txMicLevel: "unknown",
+  txRmsPower: "unknown",
+  txPeakPower: "unknown",
+  txSwr: "unknown",
+  txAlcDbfs: "unknown"
+};
+function cloneMeterCapabilities(capabilities) {
+  return { ...capabilities };
+}
+
+// src/meter/adapters.ts
+var StandardTciMeterAdapter = class {
+  declaredCapabilities;
+  options;
+  constructor(options = {}) {
+    this.options = options;
+    this.declaredCapabilities = {
+      ...UNKNOWN_TCI_METER_CAPABILITIES,
+      rxLevel: "declared",
+      txMicLevel: "declared",
+      txRmsPower: "declared",
+      txPeakPower: "declared",
+      txSwr: "declared",
+      rxAverageLevel: options.supportsRxExtended ? "declared" : "unknown",
+      rxPeakBin: options.supportsRxExtended ? "declared" : "unknown",
+      txAlcDbfs: options.txAlcUnit === "dbfs" ? "declared" : "unknown",
+      ...options.capabilities
+    };
+  }
+  normalizeInterval(intervalMs) {
+    const requestedMs = Math.round(intervalMs);
+    if (this.options.interval?.fixedMs !== void 0) {
+      return { requestedMs, appliedMs: this.options.interval.fixedMs };
+    }
+    const minMs = this.options.interval?.minMs ?? requestedMs;
+    const maxMs = this.options.interval?.maxMs ?? requestedMs;
+    const normalized = Math.max(minMs, Math.min(maxMs, requestedMs));
+    return {
+      requestedMs,
+      appliedMs: this.options.interval?.reportsApplied === false ? void 0 : normalized
+    };
+  }
+  buildEnableCommand(kind, enabled, intervalMs) {
+    return {
+      name: kind === "rx" ? "RX_SENSORS_ENABLE" : "TX_SENSORS_ENABLE",
+      args: enabled ? [true, intervalMs] : [false]
+    };
+  }
+  decode(command, receivedAtMs) {
+    switch (command.name) {
+      case "rx_sensors":
+        return decodeRx(command, receivedAtMs, "rx_sensors");
+      case "rx_channel_sensors":
+        return decodeRx(command, receivedAtMs, "rx_channel_sensors");
+      case "rx_channel_sensors_ex":
+        return decodeRx(command, receivedAtMs, "rx_channel_sensors_ex");
+      case "tx_sensors":
+        return decodeTx(command, receivedAtMs, this.options.txAlcUnit);
+      default:
+        return void 0;
+    }
+  }
+};
+function createUnknownTciMeterAdapter() {
+  return new StandardTciMeterAdapter({
+    capabilities: cloneMeterCapabilities(UNKNOWN_TCI_METER_CAPABILITIES),
+    interval: { reportsApplied: false }
+  });
+}
+function decodeRx(command, receivedAtMs, source) {
+  const receiver = integer(command.args[0]);
+  const hasChannel = source !== "rx_sensors";
+  const channel = hasChannel ? integer(command.args[1]) : 0;
+  const levelIndex = hasChannel ? 2 : 1;
+  const levelDbm = finite(command.args[levelIndex]);
+  if (receiver === void 0 || receiver < 0 || channel === void 0 || channel < 0 || levelDbm === void 0) {
+    return { issue: `Invalid ${command.originalName} meter frame: ${command.raw}` };
+  }
+  const frame = { receiver, channel, levelDbm, source, receivedAtMs };
+  if (source === "rx_channel_sensors_ex") {
+    const averageLevelDbm = finite(command.args[3]);
+    const peakBinDbm = finite(command.args[4]);
+    if (averageLevelDbm === void 0 || peakBinDbm === void 0) {
+      return { issue: `Invalid ${command.originalName} extended meter frame: ${command.raw}` };
+    }
+    frame.averageLevelDbm = averageLevelDbm;
+    frame.peakBinDbm = peakBinDbm;
+    if (command.args.length > 5) frame.extraArgs = command.args.slice(5);
+  } else if (command.args.length > levelIndex + 1) {
+    frame.extraArgs = command.args.slice(levelIndex + 1);
+  }
+  return { decoded: { kind: "rx", frame } };
+}
+function decodeTx(command, receivedAtMs, alcUnit) {
+  const trx = integer(command.args[0]);
+  if (trx === void 0 || trx < 0) {
+    return { issue: `Invalid ${command.originalName} transmitter index: ${command.raw}` };
+  }
+  const micLevelDbm = optionalFinite(command.args[1]);
+  const rmsPowerWatts = optionalFinite(command.args[2]);
+  const peakPowerWatts = optionalFinite(command.args[3]);
+  const swr = optionalFinite(command.args[4]);
+  const alcValue = alcUnit ? optionalFinite(command.args[5]) : void 0;
+  if (micLevelDbm.invalid || rmsPowerWatts.invalid || peakPowerWatts.invalid || swr.invalid || alcValue?.invalid) {
+    return { issue: `Invalid ${command.originalName} numeric meter frame: ${command.raw}` };
+  }
+  if (rmsPowerWatts.value !== void 0 && rmsPowerWatts.value < 0 || peakPowerWatts.value !== void 0 && peakPowerWatts.value < 0 || swr.value !== void 0 && swr.value < 1) {
+    return { issue: `Out-of-range ${command.originalName} meter frame: ${command.raw}` };
+  }
+  if (micLevelDbm.value === void 0 && rmsPowerWatts.value === void 0 && peakPowerWatts.value === void 0 && swr.value === void 0 && alcValue?.value === void 0) {
+    return { issue: `Empty ${command.originalName} meter frame: ${command.raw}` };
+  }
+  const frame = {
+    trx,
+    micLevelDbm: micLevelDbm.value,
+    rmsPowerWatts: rmsPowerWatts.value,
+    peakPowerWatts: peakPowerWatts.value,
+    swr: swr.value,
+    receivedAtMs
+  };
+  if (alcUnit && alcValue?.value !== void 0) frame.alc = { value: alcValue.value, unit: alcUnit };
+  const knownArgs = alcUnit ? 6 : 5;
+  if (command.args.length > knownArgs) frame.extraArgs = command.args.slice(knownArgs);
+  return { decoded: { kind: "tx", frame } };
+}
+function finite(value) {
+  if (value === void 0 || value === "") return void 0;
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? parsed : void 0;
+}
+function integer(value) {
+  const parsed = finite(value);
+  return parsed !== void 0 && Number.isInteger(parsed) ? parsed : void 0;
+}
+function optionalFinite(value) {
+  if (value === void 0 || value === "") return { invalid: false };
+  const parsed = Number(value);
+  return Number.isFinite(parsed) ? { value: parsed, invalid: false } : { invalid: true };
+}
+
+// src/meter/TciMeterStreamSession.ts
+import { EventEmitter } from "eventemitter3";
+var RX_COALESCE_MS = 20;
+var TciMeterStreamSession = class extends EventEmitter {
+  receiver;
+  channel;
+  trx;
+  requestedIntervalMs;
+  appliedIntervalMs;
+  rxEnabled;
+  txEnabled;
+  adapter;
+  callbacks;
+  capabilities;
+  pendingRx = /* @__PURE__ */ new Map();
+  closed = false;
+  constructor(options) {
+    super();
+    this.receiver = options.receiver;
+    this.channel = options.channel;
+    this.trx = options.trx;
+    this.requestedIntervalMs = options.requestedIntervalMs;
+    this.appliedIntervalMs = options.appliedIntervalMs;
+    this.rxEnabled = options.rxEnabled;
+    this.txEnabled = options.txEnabled;
+    this.adapter = options.adapter;
+    this.callbacks = options.callbacks;
+    this.capabilities = cloneMeterCapabilities(options.adapter.declaredCapabilities);
+  }
+  getCapabilities() {
+    return cloneMeterCapabilities(this.capabilities);
+  }
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.clearPendingRx();
+    try {
+      await this.callbacks.close();
+    } finally {
+      this.emit("closed");
+      this.removeAllListeners();
+    }
+  }
+  _acceptCommand(command, receivedAtMs) {
+    if (this.closed) return;
+    this.acceptEnableAcknowledgement(command);
+    const result = this.adapter.decode(command, receivedAtMs);
+    if (!result) return;
+    if (result.issue) {
+      this.emit("error", new TciError("protocol-error", result.issue));
+      return;
+    }
+    if (result.decoded?.kind === "rx") this.acceptRxFrame(result.decoded.frame);
+    if (result.decoded?.kind === "tx") this.acceptTxFrame(result.decoded.frame);
+  }
+  _fail(error) {
+    if (this.closed) return;
+    this.closed = true;
+    this.clearPendingRx();
+    this.emit("error", error);
+    this.emit("closed");
+    this.removeAllListeners();
+  }
+  acceptRxFrame(frame) {
+    if (!this.rxEnabled || frame.receiver !== this.receiver || frame.channel !== this.channel) return;
+    this.observe("rxLevel");
+    if (frame.averageLevelDbm !== void 0) this.observe("rxAverageLevel");
+    if (frame.peakBinDbm !== void 0) this.observe("rxPeakBin");
+    const key = `${frame.receiver}:${frame.channel}`;
+    const pending = this.pendingRx.get(key);
+    if (pending) {
+      const sameReading = Math.abs(pending.frame.levelDbm - frame.levelDbm) < 0.05;
+      if (sameReading && rxPriority(frame) >= rxPriority(pending.frame)) {
+        clearTimeout(pending.timer);
+        this.pendingRx.delete(key);
+      } else if (sameReading) {
+        return;
+      } else {
+        this.flushRx(key, pending);
+      }
+    }
+    const timer = setTimeout(() => {
+      const current = this.pendingRx.get(key);
+      if (current?.frame === frame) this.flushRx(key, current);
+    }, RX_COALESCE_MS);
+    this.pendingRx.set(key, { frame, timer });
+  }
+  acceptTxFrame(frame) {
+    if (!this.txEnabled || frame.trx !== this.trx) return;
+    if (frame.micLevelDbm !== void 0) this.observe("txMicLevel");
+    if (frame.rmsPowerWatts !== void 0) this.observe("txRmsPower");
+    if (frame.peakPowerWatts !== void 0) this.observe("txPeakPower");
+    if (frame.swr !== void 0) this.observe("txSwr");
+    if (frame.alc?.unit === "dbfs") this.observe("txAlcDbfs");
+    this.emit("txFrame", frame);
+  }
+  acceptEnableAcknowledgement(command) {
+    const enabled = command.args[0]?.toLowerCase();
+    if (enabled !== "true" && enabled !== "1" && enabled !== "on") return;
+    if (command.name === "rx_sensors_enable" && this.rxEnabled) {
+      this.acknowledge(["rxLevel"]);
+    }
+    if (command.name === "tx_sensors_enable" && this.txEnabled) {
+      this.acknowledge(["txMicLevel", "txRmsPower", "txPeakPower", "txSwr"]);
+    }
+  }
+  acknowledge(keys) {
+    let changed = false;
+    for (const key of keys) {
+      if (supportRank(this.capabilities[key]) < supportRank("acknowledged")) {
+        this.capabilities[key] = "acknowledged";
+        changed = true;
+      }
+    }
+    if (changed) this.emit("capabilitiesChanged", this.getCapabilities());
+  }
+  observe(key) {
+    if (this.capabilities[key] === "observed") return;
+    this.capabilities[key] = "observed";
+    this.emit("capabilitiesChanged", this.getCapabilities());
+  }
+  flushRx(key, pending) {
+    clearTimeout(pending.timer);
+    if (this.pendingRx.get(key) === pending) this.pendingRx.delete(key);
+    this.emit("rxFrame", pending.frame);
+  }
+  clearPendingRx() {
+    for (const pending of this.pendingRx.values()) clearTimeout(pending.timer);
+    this.pendingRx.clear();
+  }
+};
+function rxPriority(frame) {
+  if (frame.source === "rx_channel_sensors_ex") return 3;
+  if (frame.source === "rx_channel_sensors") return 2;
+  return 1;
+}
+function supportRank(value) {
+  switch (value) {
+    case "unsupported":
+      return -1;
+    case "unknown":
+      return 0;
+    case "declared":
+      return 1;
+    case "acknowledged":
+      return 2;
+    case "observed":
+      return 3;
+  }
+}
+
 // src/dialect/builtins.ts
 var StandardTciDialect = class {
   id;
@@ -595,6 +900,9 @@ var StandardTciDialect = class {
   streamLengthSemantics;
   supportsStreamChannels;
   supportsTxAudioSource;
+  supportsIqStream;
+  iqSampleRates;
+  meterAdapter;
   driveHasTrx;
   detector;
   resolver;
@@ -604,6 +912,9 @@ var StandardTciDialect = class {
     this.streamLengthSemantics = options.streamLengthSemantics;
     this.supportsStreamChannels = options.supportsStreamChannels;
     this.supportsTxAudioSource = options.supportsTxAudioSource;
+    this.supportsIqStream = options.supportsIqStream;
+    this.iqSampleRates = [...options.iqSampleRates];
+    this.meterAdapter = options.meterAdapter;
     this.driveHasTrx = options.driveHasTrx;
     this.detector = options.detect;
     this.resolver = options.resolve;
@@ -651,7 +962,10 @@ var expertSdr14Dialect = new StandardTciDialect({
   streamLengthSemantics: "per-channel",
   supportsStreamChannels: false,
   supportsTxAudioSource: false,
+  supportsIqStream: true,
+  iqSampleRates: [48e3, 96e3, 192e3, 384e3],
   driveHasTrx: false,
+  meterAdapter: new StandardTciMeterAdapter({ interval: { reportsApplied: false } }),
   detect: (context) => {
     const parsed = version(context);
     if (!parsed || compareTciVersion(parsed, [1, 4]) > 0) return { score: 0, evidence: [] };
@@ -664,7 +978,10 @@ var expertSdrLegacyDialect = new StandardTciDialect({
   streamLengthSemantics: "per-channel",
   supportsStreamChannels: false,
   supportsTxAudioSource: false,
+  supportsIqStream: true,
+  iqSampleRates: [48e3, 96e3, 192e3, 384e3],
   driveHasTrx: true,
+  meterAdapter: new StandardTciMeterAdapter({ interval: { reportsApplied: false } }),
   detect: (context) => {
     const parsed = version(context);
     if (!parsed || compareTciVersion(parsed, [1, 5]) < 0 || compareTciVersion(parsed, [1, 9]) >= 0) return { score: 0, evidence: [] };
@@ -677,7 +994,10 @@ var expertSdrModernDialect = new StandardTciDialect({
   streamLengthSemantics: "scalar",
   supportsStreamChannels: true,
   supportsTxAudioSource: true,
+  supportsIqStream: true,
+  iqSampleRates: [48e3, 96e3, 192e3, 384e3],
   driveHasTrx: true,
+  meterAdapter: new StandardTciMeterAdapter({ interval: { reportsApplied: false } }),
   detect: (context) => {
     const parsed = version(context);
     if (!parsed || compareTciVersion(parsed, [1, 9]) < 0) return { score: 0, evidence: [] };
@@ -695,7 +1015,13 @@ var thetisDialect = new StandardTciDialect({
   streamLengthSemantics: "scalar",
   supportsStreamChannels: true,
   supportsTxAudioSource: true,
+  supportsIqStream: true,
+  iqSampleRates: [48e3, 96e3, 192e3, 384e3],
   driveHasTrx: true,
+  meterAdapter: new StandardTciMeterAdapter({
+    interval: { minMs: 30, maxMs: 1e3 },
+    supportsRxExtended: true
+  }),
   detect: (context) => {
     const evidence = [];
     let score = 0;
@@ -721,7 +1047,13 @@ var aetherSdrDialect = new StandardTciDialect({
   streamLengthSemantics: "scalar",
   supportsStreamChannels: true,
   supportsTxAudioSource: true,
+  supportsIqStream: true,
+  iqSampleRates: [24e3, 48e3, 96e3, 192e3],
   driveHasTrx: true,
+  meterAdapter: new StandardTciMeterAdapter({
+    interval: { fixedMs: 200 },
+    txAlcUnit: "dbfs"
+  }),
   detect: (context) => {
     if (!/^aethersdr$/i.test(context.identity.device ?? "")) return { score: 0, evidence: [] };
     const evidence = [`AetherSDR device identity: ${context.identity.device}`];
@@ -740,7 +1072,10 @@ var genericObservedDialect = new StandardTciDialect({
   streamLengthSemantics: "auto",
   supportsStreamChannels: true,
   supportsTxAudioSource: true,
+  supportsIqStream: false,
+  iqSampleRates: [],
   driveHasTrx: true,
+  meterAdapter: createUnknownTciMeterAdapter(),
   detect: (context) => ({
     score: context.commandNames.has("ready") ? 10 : 0,
     evidence: ["No vendor-specific match; using observed command shapes"],
@@ -755,7 +1090,10 @@ var genericObservedDialect = new StandardTciDialect({
       streamLengthSemantics: "auto",
       supportsStreamChannels: context.commandNames.has("audio_stream_channels"),
       supportsTxAudioSource: compareTciVersion(version(context) ?? [0], [2, 0]) >= 0,
+      supportsIqStream: context.commandNames.has("iq_samplerate"),
+      iqSampleRates: context.commandNames.has("iq_samplerate") ? [48e3] : [],
       driveHasTrx,
+      meterAdapter: createUnknownTciMeterAdapter(),
       detect: genericObservedDialect.detect.bind(genericObservedDialect)
     });
   }
@@ -854,9 +1192,9 @@ function assertValidTciHandshake(commands) {
 }
 
 // src/transport/WebSocketTransport.ts
-import { EventEmitter } from "eventemitter3";
+import { EventEmitter as EventEmitter2 } from "eventemitter3";
 import WebSocket from "ws";
-var WebSocketTciTransport = class extends EventEmitter {
+var WebSocketTciTransport = class extends EventEmitter2 {
   constructor(url, WebSocketImpl = WebSocket) {
     super();
     this.url = url;
@@ -966,7 +1304,78 @@ function dataToBuffer(data) {
 }
 
 // src/client/TciClient.ts
-var TciClient = class extends EventEmitter2 {
+var TciIqStreamSession = class extends EventEmitter3 {
+  receiver;
+  _appliedSampleRate;
+  callbacks;
+  closed = false;
+  firstFrame;
+  constructor(receiver, appliedSampleRate, callbacks) {
+    super();
+    this.receiver = receiver;
+    this._appliedSampleRate = appliedSampleRate;
+    this.callbacks = callbacks;
+  }
+  get appliedSampleRate() {
+    return this._appliedSampleRate;
+  }
+  async setSampleRate(sampleRate) {
+    if (this.closed) throw new TciError("cancelled", "TCI IQ stream is closed");
+    const result = await this.callbacks.setSampleRate(sampleRate);
+    this._appliedSampleRate = result.applied;
+    return result;
+  }
+  async close() {
+    if (this.closed) return;
+    this.closed = true;
+    this.rejectFirstFrame(new TciError("cancelled", "TCI IQ stream closed before its first frame"));
+    try {
+      await this.callbacks.close();
+    } finally {
+      this.emit("closed");
+      this.removeAllListeners();
+    }
+  }
+  waitForFirstFrame(timeoutMs) {
+    if (this.firstFrame) return this.firstFrame.promise;
+    let resolvePromise;
+    let rejectPromise;
+    const promise = new Promise((resolve, reject) => {
+      resolvePromise = resolve;
+      rejectPromise = reject;
+    });
+    const timer = setTimeout(() => {
+      this.firstFrame = void 0;
+      rejectPromise(new TciError("command-timeout", `Timed out waiting for TCI IQ frame for receiver ${this.receiver}`));
+    }, timeoutMs);
+    this.firstFrame = { promise, resolve: resolvePromise, reject: rejectPromise, timer };
+    return promise;
+  }
+  _acceptFrame(frame) {
+    if (this.closed || frame.receiver !== this.receiver) return;
+    this._appliedSampleRate = frame.sampleRate;
+    const firstFrame = this.firstFrame;
+    if (firstFrame) {
+      clearTimeout(firstFrame.timer);
+      this.firstFrame = void 0;
+      firstFrame.resolve(frame);
+    }
+    this.emit("frame", frame);
+  }
+  _fail(error) {
+    if (this.closed) return;
+    this.rejectFirstFrame(error);
+    this.emit("error", error);
+  }
+  rejectFirstFrame(error) {
+    const firstFrame = this.firstFrame;
+    if (!firstFrame) return;
+    clearTimeout(firstFrame.timer);
+    this.firstFrame = void 0;
+    firstFrame.reject(error);
+  }
+};
+var TciClient = class extends EventEmitter3 {
   options;
   WebSocketImpl;
   transportFactory;
@@ -980,6 +1389,8 @@ var TciClient = class extends EventEmitter2 {
   handshakeError;
   initializationCommands = [];
   handshakeWaiter;
+  activeIqSession;
+  activeMeterSession;
   constructor(options) {
     super();
     this.options = {
@@ -1018,7 +1429,9 @@ var TciClient = class extends EventEmitter2 {
       split: {},
       dialectWarnings: [],
       rxSensors: {},
-      txSensors: {}
+      txSensors: {},
+      iq: { activeReceivers: {} },
+      dds: {}
     };
     this.stateReducers = this.createStateReducers();
   }
@@ -1043,6 +1456,7 @@ var TciClient = class extends EventEmitter2 {
     }
   }
   async disconnect(code = 1e3, reason = "client disconnect") {
+    await this.activeMeterSession?.close().catch(() => void 0);
     const transport = this.transport;
     if (!transport) return;
     await transport.disconnect(code, reason);
@@ -1057,6 +1471,133 @@ var TciClient = class extends EventEmitter2 {
   getHandshakeResult() {
     return this.handshakeResult ? cloneHandshake(this.handshakeResult) : void 0;
   }
+  getIqCapabilities() {
+    const dialect = this.requireDialect();
+    return {
+      supported: dialect.supportsIqStream,
+      currentSampleRate: this.state.iq.sampleRate,
+      supportedSampleRates: [...dialect.iqSampleRates]
+    };
+  }
+  getMeterCapabilities() {
+    if (this.activeMeterSession) return this.activeMeterSession.getCapabilities();
+    const adapter = this.activeDialect?.meterAdapter;
+    return adapter ? cloneMeterCapabilities(adapter.declaredCapabilities) : cloneMeterCapabilities(UNKNOWN_TCI_METER_CAPABILITIES);
+  }
+  async openMeterStream(options = {}) {
+    if (this.activeMeterSession) throw new TciError("protocol-error", "This TCI client already has an active meter stream session");
+    this.requireDialect();
+    const receiver = normalizeNonNegativeInteger(options.receiver ?? this.options.receiver, "meter receiver");
+    const channel = normalizeNonNegativeInteger(options.channel ?? this.options.vfo, "meter channel");
+    const trx = normalizeNonNegativeInteger(options.trx ?? this.options.trx, "meter transmitter");
+    const rxEnabled = options.rx ?? true;
+    const txEnabled = options.tx ?? true;
+    if (!rxEnabled && !txEnabled) throw new TciError("protocol-error", "TCI meter stream must enable RX, TX, or both");
+    const requestedIntervalMs = Math.round(options.intervalMs ?? 300);
+    if (!Number.isFinite(requestedIntervalMs) || requestedIntervalMs <= 0) {
+      throw new TciError("protocol-error", `Invalid TCI meter interval: ${options.intervalMs}`);
+    }
+    const adapter = this.activeDialect?.meterAdapter ?? createUnknownTciMeterAdapter();
+    const interval = adapter.normalizeInterval(requestedIntervalMs);
+    let session;
+    session = new TciMeterStreamSession({
+      receiver,
+      channel,
+      trx,
+      requestedIntervalMs: interval.requestedMs,
+      appliedIntervalMs: interval.appliedMs,
+      rxEnabled,
+      txEnabled,
+      adapter,
+      callbacks: {
+        close: async () => {
+          try {
+            if (this.isConnected()) {
+              if (rxEnabled) {
+                const command = adapter.buildEnableCommand("rx", false, interval.appliedMs ?? interval.requestedMs);
+                await this.sendCommand(command.name, command.args, { waitForReply: false }).catch(() => void 0);
+              }
+              if (txEnabled) {
+                const command = adapter.buildEnableCommand("tx", false, interval.appliedMs ?? interval.requestedMs);
+                await this.sendCommand(command.name, command.args, { waitForReply: false }).catch(() => void 0);
+              }
+            }
+          } finally {
+            if (this.activeMeterSession === session) this.activeMeterSession = void 0;
+          }
+        }
+      }
+    });
+    this.activeMeterSession = session;
+    try {
+      if (rxEnabled) {
+        const command = adapter.buildEnableCommand("rx", true, interval.appliedMs ?? interval.requestedMs);
+        await this.sendCommand(command.name, command.args, { waitForReply: false });
+      }
+      if (txEnabled) {
+        const command = adapter.buildEnableCommand("tx", true, interval.appliedMs ?? interval.requestedMs);
+        await this.sendCommand(command.name, command.args, { waitForReply: false });
+      }
+      return session;
+    } catch (error) {
+      await session.close().catch(() => void 0);
+      throw error;
+    }
+  }
+  async setIqSampleRate(sampleRate, timeoutMs = this.options.commandTimeoutMs) {
+    const capabilities = this.getIqCapabilities();
+    const requested = Math.round(sampleRate);
+    if (!capabilities.supported) throw new TciError("protocol-error", `TCI dialect ${this.requireDialect().id} does not support IQ streaming`);
+    if (!Number.isFinite(requested) || requested <= 0) throw new TciError("protocol-error", `Invalid TCI IQ sample rate: ${sampleRate}`);
+    if (capabilities.supportedSampleRates.length > 0 && !capabilities.supportedSampleRates.includes(requested)) {
+      throw new TciError("protocol-error", `TCI IQ sample rate ${requested} is not supported by dialect ${this.requireDialect().id}`);
+    }
+    if (this.state.iq.sampleRate === requested) return writeResult(requested, requested, "state");
+    const waiter = this.waitForCommand((command) => command.name === "iq_samplerate", timeoutMs, "IQ_SAMPLERATE readback");
+    try {
+      await this.sendCommand("IQ_SAMPLERATE", [requested], { waitForReply: false });
+      const reply = await waiter.promise;
+      const applied = parseNumber(reply.args[0]);
+      if (applied === void 0 || applied <= 0) throw new TciError("protocol-error", `Invalid IQ_SAMPLERATE readback: ${reply.raw}`);
+      return writeResult(requested, applied, "reply");
+    } finally {
+      waiter.cancel();
+    }
+  }
+  async openIqStream(options = {}) {
+    if (this.activeIqSession) throw new TciError("protocol-error", "This TCI client already has an active IQ stream session");
+    const capabilities = this.getIqCapabilities();
+    if (!capabilities.supported) throw new TciError("protocol-error", `TCI dialect ${this.requireDialect().id} does not support IQ streaming`);
+    const receiver = Math.floor(options.receiver ?? this.options.receiver);
+    if (!Number.isInteger(receiver) || receiver < 0) throw new TciError("protocol-error", `Invalid TCI IQ receiver: ${receiver}`);
+    const requestedRate = options.sampleRate ?? capabilities.currentSampleRate ?? capabilities.supportedSampleRates[0] ?? 48e3;
+    const rateResult = await this.setIqSampleRate(requestedRate);
+    let session;
+    session = new TciIqStreamSession(receiver, rateResult.applied, {
+      setSampleRate: (rate) => this.setIqSampleRate(rate),
+      close: async () => {
+        try {
+          if (this.isConnected()) await this.sendCommand("IQ_STOP", [receiver], { waitForReply: false });
+        } finally {
+          this.state.iq.activeReceivers[String(receiver)] = false;
+          if (this.activeIqSession === session) this.activeIqSession = void 0;
+          this.emitState();
+        }
+      }
+    });
+    this.activeIqSession = session;
+    const firstFrame = session.waitForFirstFrame(options.firstFrameTimeoutMs ?? 5e3);
+    try {
+      await this.sendCommand("IQ_START", [receiver], { waitForReply: false });
+      this.state.iq.activeReceivers[String(receiver)] = true;
+      this.emitState();
+      await firstFrame;
+      return session;
+    } catch (error) {
+      await session.close().catch(() => void 0);
+      throw error;
+    }
+  }
   async sendCommand(name, args = [], options = {}) {
     const raw = formatTciCommand(name, args);
     if (options.waitForReply === false) {
@@ -1527,11 +2068,13 @@ var TciClient = class extends EventEmitter2 {
   handleText(raw) {
     try {
       const commands = parseTciText(raw);
+      const receivedAtMs = Date.now();
       this.emit("tci:rx", raw, commands);
       for (const command of commands) {
         if (!this.handshakeResult) this.initializationCommands.push(command);
         this.queue.handleCommand(command);
         this.applyCommand(command);
+        this.activeMeterSession?._acceptCommand(command, receivedAtMs);
         this.emit("command", command);
       }
     } catch (error) {
@@ -1546,6 +2089,22 @@ var TciClient = class extends EventEmitter2 {
     this.emit("tci:binary", frame);
     this.emit("binary", frame);
     switch (frame.streamType) {
+      case 0 /* IQ_STREAM */: {
+        if (frame.channels !== 2 || frame.sampleCount % 2 !== 0) {
+          throw new TciError("invalid-frame", "TCI IQ stream frame must contain interleaved I/Q pairs");
+        }
+        this.state.iq.sampleRate = frame.sampleRate;
+        const iqFrame = {
+          frame,
+          receiver: frame.receiver,
+          sampleRate: frame.sampleRate,
+          centerFrequency: this.state.dds[String(frame.receiver)],
+          complexSampleCount: frame.frameCount
+        };
+        this.emit("iqFrame", iqFrame);
+        this.activeIqSession?._acceptFrame(iqFrame);
+        break;
+      }
       case 1 /* RX_AUDIO_STREAM */:
         this.emit("rxAudioFrame", frame);
         break;
@@ -1623,6 +2182,11 @@ var TciClient = class extends EventEmitter2 {
       this.state.modulations = args.map((mode) => mode.toLowerCase());
     });
     reducers.set("vfo", (args) => this.applyVfo(args));
+    reducers.set("dds", (args) => {
+      const receiver = parseNumber(args[0]);
+      const frequency = parseNumber(args[1]);
+      if (receiver !== void 0 && frequency !== void 0 && frequency >= 0) this.state.dds[String(receiver)] = frequency;
+    });
     reducers.set("modulation", (args) => this.applyModulation(args));
     reducers.set("trx", (args) => this.applyTrx(args));
     reducers.set("tune", (args) => this.applyBooleanByFirstArg(this.state.tune, args));
@@ -1630,6 +2194,7 @@ var TciClient = class extends EventEmitter2 {
     reducers.set("tune_drive", (args) => this.applyTuneDrive(args));
     reducers.set("split_enable", (args) => this.applyBooleanByFirstArg(this.state.split, args));
     reducers.set("rx_channel_sensors", (args) => this.applyRxChannelSensors(args));
+    reducers.set("rx_channel_sensors_ex", (args) => this.applyRxChannelSensors(args));
     reducers.set("rx_sensors", (args) => this.applyRxSensors(args));
     reducers.set("tx_sensors", (args) => this.applyTxSensors(args));
     reducers.set("audio_samplerate", (args) => this.updateAudioState({ sampleRate: parseNumber(args[0]) }));
@@ -1639,6 +2204,15 @@ var TciClient = class extends EventEmitter2 {
     reducers.set("tx_stream_audio_buffering", (args) => this.updateAudioState({ txBufferingMs: parseNumber(args[0]) }));
     reducers.set("audio_start", () => this.updateAudioState({ running: true }));
     reducers.set("audio_stop", () => this.updateAudioState({ running: false }));
+    reducers.set("iq_samplerate", (args) => {
+      this.state.iq.sampleRate = parseNumber(args[0]);
+    });
+    reducers.set("iq_start", (args) => {
+      this.state.iq.activeReceivers[String(args[0] ?? this.options.receiver)] = true;
+    });
+    reducers.set("iq_stop", (args) => {
+      this.state.iq.activeReceivers[String(args[0] ?? this.options.receiver)] = false;
+    });
     return reducers;
   }
   applyVfo(args) {
@@ -1746,6 +2320,10 @@ var TciClient = class extends EventEmitter2 {
     this.state.ready = false;
     this.queue.setConnected(false);
     this.rejectHandshake(new TciError("disconnected", "TCI connection closed during handshake", reason));
+    this.activeIqSession?._fail(new TciError("disconnected", "TCI connection closed while IQ stream was active", reason));
+    this.activeIqSession = void 0;
+    this.activeMeterSession?._fail(new TciError("disconnected", "TCI connection closed while meter stream was active", reason));
+    this.activeMeterSession = void 0;
     if (wasConnected) {
       this.emit("disconnected", reason);
       this.emitState();
@@ -1772,6 +2350,12 @@ function parseNumber(value) {
   const number = Number(value);
   return Number.isFinite(number) ? number : void 0;
 }
+function normalizeNonNegativeInteger(value, description) {
+  if (!Number.isInteger(value) || value < 0) {
+    throw new TciError("protocol-error", `Invalid TCI ${description}: ${value}`);
+  }
+  return value;
+}
 function parseBoolean(value) {
   if (value === void 0) {
     return void 0;
@@ -1826,7 +2410,9 @@ function cloneState(state) {
     dialectWarnings: [...state.dialectWarnings],
     rxSensors: cloneNested(state.rxSensors),
     txSensors: cloneNested(state.txSensors),
-    audio: state.audio ? { ...state.audio } : void 0
+    audio: state.audio ? { ...state.audio } : void 0,
+    iq: { ...state.iq, activeReceivers: { ...state.iq.activeReceivers } },
+    dds: { ...state.dds }
   };
 }
 function cloneHandshake(result) {
@@ -1845,22 +2431,29 @@ function cloneNested(value) {
   return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, { ...item }]));
 }
 export {
+  StandardTciMeterAdapter,
   TCI_STREAM_HEADER_BYTES,
   TciClient,
   TciCommandQueue,
   TciDialectRegistry,
   TciError,
+  TciIqStreamSession,
+  TciMeterStreamSession,
   TciSampleType,
   TciStreamType,
+  UNKNOWN_TCI_METER_CAPABILITIES,
   WebSocketTciTransport,
   aetherSdrDialect,
   assertValidTciHandshake,
   buildStreamFrame,
   buildTxAudioFrame,
   builtInDialects,
+  cloneMeterCapabilities,
   commandKey,
   compareTciVersion,
   createTciClient,
+  createUnknownTciMeterAdapter,
+  decodeInterleavedIq,
   defaultTciDialectRegistry,
   deinterleaveChannels,
   escapeTciText,