icom-wlan-node 0.3.0 → 0.5.0

package/README.md

@@ -4,6 +4,7 @@ Icom WLAN (UDP) protocol implementation in Node.js + TypeScript, featuring:
 
 - Control channel handshake (AreYouThere/AreYouReady), login (0x80/0x60), token confirm/renew (0x40)
 - CI‑V over UDP encapsulation (open/close keep‑alive + CIV frame transport)
+- Scope/spectrum data capture over CI‑V `0x27`, with automatic segment assembly into friendly frame events
 - Audio stream send/receive (LPCM 16‑bit mono @ 12 kHz; 20 ms frames)
 - Typed, event‑based API; designed for use as a dependency in other Node projects
 
@@ -63,6 +64,15 @@ rig.events.on('audio', (frame) => {
   // frame.pcm16 is raw 16‑bit PCM mono @ 12 kHz
 });
 
+rig.events.on('scopeFrame', (frame) => {
+  console.log(
+    'Scope:',
+    `${frame.startFreqHz}..${frame.endFreqHz} Hz`,
+    `pixels=${frame.pixels.length}`,
+    `mode=${frame.mode}`
+  );
+});
+
 rig.events.on('error', (err) => console.error('UDP error', err));
 
 (async () => {
@@ -93,6 +103,37 @@ rig.sendAudioFloat32(tone, true);
 await rig.setPtt(false);
 ```
 
+### Scope / Spectrum
+
+```ts
+await rig.connect();
+
+rig.events.on('scopeSegment', (segment) => {
+  console.log(`scope segment ${segment.sequence}/${segment.sequenceMax}`);
+});
+
+rig.events.on('scopeFrame', (frame) => {
+  console.log('scope frame ready', {
+    startFreqHz: frame.startFreqHz,
+    endFreqHz: frame.endFreqHz,
+    pixelCount: frame.pixels.length,
+    outOfRange: frame.outOfRange
+  });
+});
+
+// Enable basic scope output
+await rig.enableScope();
+
+// Wait for one complete frame
+const frame = await rig.waitForScopeFrame({ timeout: 3000 });
+if (frame) {
+  console.log(frame.pixels[0], frame.pixels[1]);
+}
+
+// Disable scope output when finished
+await rig.disableScope();
+```
+
 ## API Overview
 
 - `new IcomControl(options)`
@@ -104,6 +145,8 @@ await rig.setPtt(false);
   - `capabilities(CapabilitiesInfo)` — civ address, audio name (0xA8)
   - `civ(Buffer)` — raw CI‑V payload bytes as transported over UDP
   - `civFrame(Buffer)` — one complete CI‑V frame (FE FE ... FD)
+  - `scopeSegment(IcomScopeSegmentInfo)` — one parsed `0x27` scope segment
+  - `scopeFrame(IcomScopeFrame)` — one assembled spectrum/waterfall frame
   - `audio({ pcm16: Buffer })` — audio frames
   - `error(Error)` — UDP errors
   - `connectionLost(ConnectionLostInfo)` — session timeout detected
@@ -114,6 +157,7 @@ await rig.setPtt(false);
   - **Connection**: `connect()` / `disconnect(options?)` — connects control + CIV + audio sub‑sessions; resolves when all ready
     - `disconnect()` accepts optional `DisconnectOptions` or `DisconnectReason` for better error handling
   - **Raw CI‑V**: `sendCiv(buf: Buffer)` — send a raw CI‑V frame
+  - **Scope / Spectrum**: `scope`, `enableScope()`, `disableScope()`, `waitForScopeFrame()`
   - **Audio TX**: `setPtt(on: boolean)`, `sendAudioFloat32()`, `sendAudioPcm16()`
   - **Rig Control**: `setFrequency()`, `setMode()`, `setConnectorDataMode()`, `setConnectorWLanLevel()`
   - **Rig Query**: `readOperatingFrequency()`, `readOperatingMode()`, `readTransmitFrequency()`, `readTransceiverState()`, `readBandEdges()`
@@ -257,6 +301,47 @@ The library exposes common CI‑V operations as friendly methods. Addresses are
 - `readTransceiverState(options?: QueryOptions) => Promise<'TX' | 'RX' | 'UNKNOWN' | null>`
 - `readBandEdges(options?: QueryOptions) => Promise<Buffer|null>`
 
+#### Scope / Spectrum
+
+- `scope: IcomScopeService` — Standalone scope service object that can be reused with other CI‑V transport paths in the future
+- `enableScope() => Promise<void>` — Send the minimal command sequence to enable basic scope output
+- `disableScope() => Promise<void>` — Send the minimal command sequence to disable scope output
+- `readScopeSpan(options?: QueryOptions & { receiver?: 0 | 1 }) => Promise<{ receiver: 0 | 1; spanHz: number } | null>` — Read current scope span
+- `setScopeSpan(spanHz: number, options?: { receiver?: 0 | 1 }) => Promise<void>` — Set scope span using CI‑V `0x27 0x15`
+- `waitForScopeFrame(options?: QueryOptions) => Promise<IcomScopeFrame | null>` — Wait for the next complete scope frame
+
+`IcomScopeFrame` shape:
+
+```ts
+interface IcomScopeFrame {
+  valid: boolean;
+  receiver: 0 | 1;
+  sequence: number;
+  sequenceMax: number;
+  mode: 0 | 1 | 2 | 3;
+  outOfRange: boolean;
+  startFreqHz: number;
+  endFreqHz: number;
+  pixels: Uint8Array;
+  rawCivPayloads: Buffer[];
+  transport: 'lan-civ' | 'serial';
+}
+```
+
+Current implementation notes:
+
+- Currently implements basic on/off controls, `0x27 0x15` span read/write, and `0x27 00 00` scope data capture
+- The parsing layer is decoupled from the UDP session layer and only depends on complete CI‑V frames
+- Frequency fields are currently parsed with `freqLen=5` by default
+- LAN aggregate waterfall payload splitting is not implemented yet; standard segment input is supported
+- The `scope` logic is designed to be reusable for future serial CI‑V or Hamlib CI‑V integration
+
+#### Antenna Tuner (ATU)
+
+- `readTunerStatus(options?: QueryOptions) => Promise<{ raw: number; state: 'OFF'|'ON'|'TUNING' } | null>` — Read tuner status (CI‑V 0x1A/0x00)
+- `setTunerEnabled(enabled: boolean) => Promise<void>` — Enable/disable internal tuner (CI‑V 0x1A/0x01)
+- `startManualTune() => Promise<void>` — Trigger one manual tune cycle (CI‑V 0x1A/0x02/0x00)
+
 #### Meters & Levels
 
 **Reception Meters** (available anytime):
@@ -383,6 +468,23 @@ await rig.setConnectorDataMode('WLAN');
 // Or numeric: await rig.setConnectorDataMode(0x03);
 
 await rig.setConnectorWLanLevel(120); // Set WLAN audio level
+
+// Scope capture
+await rig.enableScope();
+const scope = await rig.waitForScopeFrame({ timeout: 3000 });
+if (scope) {
+  console.log(`Scope ${scope.startFreqHz}..${scope.endFreqHz}, ${scope.pixels.length} pixels`);
+}
+await rig.disableScope();
+
+// Antenna tuner
+const atu = await rig.readTunerStatus({ timeout: 2000 });
+if (atu) {
+  console.log('ATU:', atu.state);
+}
+
+await rig.setTunerEnabled(true);
+await rig.startManualTune();
 ```
 
 ## Design Notes
@@ -393,6 +495,7 @@ await rig.setConnectorWLanLevel(120); // Set WLAN audio level
 - Credentials use the same simple substitution cipher as FT8CN’s Android client (`passCode`).
 - The 0x90/0x50 handshake strictly follows FT8CN’s timing and endianness. We pre‑open local CIV/Audio sockets, reply with local ports on first 0x90, then set remote ports upon 0x50.
 - CIV/audio sub‑sessions each run their own Ping/Idle and (for CIV) OpenClose keep‑alive.
+- Scope data is treated as CI‑V business payload, not as a separate UDP stream. `IcomControl` only bridges CI‑V frames into the reusable `IcomScopeService`.
 
 ### Endianness and parsing tips
 
@@ -418,33 +521,10 @@ ICOM_IP=192.168.31.253 ICOM_PORT=50001 ICOM_USER=icom ICOM_PASS=icomicom npm tes
 - Full token renewal loop and advanced status flag parsing simplified.
 - Audio receive/playback is library‑only; playback is up to the integrator.
 - Robust retransmit/multi‑retransmit handling can be extended.
+- Scope support is currently limited to basic on/off commands plus standard `0x27 00 00` segment parsing.
+- LAN aggregate waterfall payload splitting is not implemented yet.
+- Scope control subcommands beyond basic enable/disable are not implemented yet.
 
 ## License
 
 MIT
-#### Antenna Tuner (ATU)
-
-- `readTunerStatus(options?: QueryOptions) => Promise<{ raw: number; state: 'OFF'|'ON'|'TUNING' } | null>` — 读取天调状态（CI‑V 0x1A/0x00）
-- `setTunerEnabled(enabled: boolean) => Promise<void>` — 开启/关闭内置天调（CI‑V 0x1A/0x01 00/01）
-- `startManualTune() => Promise<void>` — 触发一次手动调谐（相当于 [TUNE] 键，CI‑V 0x1A/0x02/0x00）
-
-示例：
-
-```ts
-// 读取天调状态
-const atu = await rig.readTunerStatus({ timeout: 2000 });
-if (atu) console.log('ATU:', atu.state); // OFF / ON / TUNING
-
-// 启用内置天调
-await rig.setTunerEnabled(true);
-
-// 触发一次手动调谐
-await rig.startManualTune();
-
-// 可选：轮询状态直到结束
-let status;
-do {
-  await new Promise(r => setTimeout(r, 300));
-  status = await rig.readTunerStatus({ timeout: 1000 });
-} while (status && status.state === 'TUNING');
-```

package/dist/index.d.ts

@@ -1,5 +1,7 @@
 export * from './types';
 export { IcomControl } from './rig/IcomControl';
+export { IcomScopeService } from './scope/IcomScopeService';
+export { IcomScopeCommands } from './scope/IcomScopeCommands';
 export { MODE_MAP, CONNECTOR_MODE_MAP, DEFAULT_CONTROLLER_ADDR, METER_THRESHOLDS, METER_CALIBRATION, getModeCode, getConnectorModeCode, getModeString, getConnectorModeString, getFilterString, rawToPowerPercent, rawToVoltage, rawToCurrent } from './rig/IcomConstants';
 export { parseTwoByteBcd, intToTwoByteBcd } from './utils/bcd';
 export { IcomRigCommands } from './rig/IcomRigCommands';

package/dist/index.js

@@ -14,12 +14,16 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
     for (var p in m) if (p !== "default" && !Object.prototype.hasOwnProperty.call(exports, p)) __createBinding(exports, m, p);
 };
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.getDisconnectMessage = exports.ConnectionAbortedError = exports.setupBasicErrorProtection = exports.setupGlobalErrorHandlers = exports.AUDIO_RATE = exports.IcomRigCommands = exports.intToTwoByteBcd = exports.parseTwoByteBcd = exports.rawToCurrent = exports.rawToVoltage = exports.rawToPowerPercent = exports.getFilterString = exports.getConnectorModeString = exports.getModeString = exports.getConnectorModeCode = exports.getModeCode = exports.METER_CALIBRATION = exports.METER_THRESHOLDS = exports.DEFAULT_CONTROLLER_ADDR = exports.CONNECTOR_MODE_MAP = exports.MODE_MAP = exports.IcomControl = void 0;
+exports.getDisconnectMessage = exports.ConnectionAbortedError = exports.setupBasicErrorProtection = exports.setupGlobalErrorHandlers = exports.AUDIO_RATE = exports.IcomRigCommands = exports.intToTwoByteBcd = exports.parseTwoByteBcd = exports.rawToCurrent = exports.rawToVoltage = exports.rawToPowerPercent = exports.getFilterString = exports.getConnectorModeString = exports.getModeString = exports.getConnectorModeCode = exports.getModeCode = exports.METER_CALIBRATION = exports.METER_THRESHOLDS = exports.DEFAULT_CONTROLLER_ADDR = exports.CONNECTOR_MODE_MAP = exports.MODE_MAP = exports.IcomScopeCommands = exports.IcomScopeService = exports.IcomControl = void 0;
 // Export types (includes ConnectionPhase, ConnectionMetrics, etc.)
 __exportStar(require("./types"), exports);
 // Export main class
 var IcomControl_1 = require("./rig/IcomControl");
 Object.defineProperty(exports, "IcomControl", { enumerable: true, get: function () { return IcomControl_1.IcomControl; } });
+var IcomScopeService_1 = require("./scope/IcomScopeService");
+Object.defineProperty(exports, "IcomScopeService", { enumerable: true, get: function () { return IcomScopeService_1.IcomScopeService; } });
+var IcomScopeCommands_1 = require("./scope/IcomScopeCommands");
+Object.defineProperty(exports, "IcomScopeCommands", { enumerable: true, get: function () { return IcomScopeCommands_1.IcomScopeCommands; } });
 // Export constants and enums
 var IcomConstants_1 = require("./rig/IcomConstants");
 Object.defineProperty(exports, "MODE_MAP", { enumerable: true, get: function () { return IcomConstants_1.MODE_MAP; } });

package/dist/rig/IcomControl.d.ts

@@ -1,6 +1,7 @@
-import { IcomRigOptions, RigEventEmitter, IcomMode, ConnectorDataMode, SetModeOptions, QueryOptions, SwrReading, AlcReading, WlanLevelReading, LevelMeterReading, SquelchStatusReading, AudioSquelchReading, OvfStatusReading, PowerLevelReading, CompLevelReading, VoltageReading, CurrentReading, ConnectionState, ConnectionMonitorConfig, ConnectionPhase, ConnectionMetrics, DisconnectReason, DisconnectOptions, TunerStatusReading, LevelReading } from '../types';
+import { IcomRigOptions, RigEventEmitter, IcomMode, ConnectorDataMode, SetModeOptions, QueryOptions, SwrReading, AlcReading, WlanLevelReading, LevelMeterReading, SquelchStatusReading, AudioSquelchReading, OvfStatusReading, PowerLevelReading, CompLevelReading, VoltageReading, CurrentReading, ConnectionState, ConnectionMonitorConfig, ConnectionPhase, ConnectionMetrics, DisconnectReason, DisconnectOptions, TunerStatusReading, LevelReading, IcomScopeSpanInfo } from '../types';
 import { IcomCiv } from './IcomCiv';
 import { IcomAudio } from './IcomAudio';
+import { IcomScopeService } from '../scope/IcomScopeService';
 export declare class IcomControl {
     private ev;
     private sess;
@@ -8,6 +9,7 @@ export declare class IcomControl {
     private audioSess;
     civ: IcomCiv;
     audio: IcomAudio;
+    scope: IcomScopeService;
     private options;
     private rigName;
     private macAddress;
@@ -73,6 +75,15 @@ export declare class IcomControl {
      */
     disconnect(options?: DisconnectOptions | DisconnectReason): Promise<void>;
     sendCiv(data: Buffer): void;
+    enableScope(): Promise<void>;
+    disableScope(): Promise<void>;
+    readScopeSpan(options?: QueryOptions & {
+        receiver?: 0 | 1;
+    }): Promise<IcomScopeSpanInfo | null>;
+    setScopeSpan(spanHz: number, options?: {
+        receiver?: 0 | 1;
+    }): Promise<void>;
+    waitForScopeFrame(options?: QueryOptions): Promise<import("../types").IcomScopeFrame | null>;
     /**
      * Set PTT (Push-To-Talk) state
      * @param on - true to key transmitter, false to unkey

package/dist/rig/IcomControl.js

@@ -46,6 +46,9 @@ const IcomConstants_1 = require("./IcomConstants");
 const bcd_1 = require("../utils/bcd");
 const errors_1 = require("../utils/errors");
 const smeter_1 = require("../utils/smeter");
+const IcomScopeCommands_1 = require("../scope/IcomScopeCommands");
+const IcomScopeParser_1 = require("../scope/IcomScopeParser");
+const IcomScopeService_1 = require("../scope/IcomScopeService");
 class IcomControl {
     constructor(options) {
         this.ev = new events_1.EventEmitter();
@@ -92,6 +95,9 @@ class IcomControl {
         this.audioSess.open();
         this.civ = new IcomCiv_1.IcomCiv(this.civSess);
         this.audio = new IcomAudio_1.IcomAudio(this.audioSess);
+        this.scope = new IcomScopeService_1.IcomScopeService();
+        this.scope.on('scopeSegment', (segment) => this.ev.emit('scopeSegment', segment));
+        this.scope.on('scopeFrame', (frame) => this.ev.emit('scopeFrame', frame));
     }
     get events() { return this.ev; }
     // ============================================================================
@@ -510,6 +516,44 @@ class IcomControl {
         }
     }
     sendCiv(data) { this.civ.sendCivData(data); }
+    async enableScope() {
+        const ctrAddr = IcomConstants_1.DEFAULT_CONTROLLER_ADDR;
+        const rigAddr = this.civ.civAddress & 0xff;
+        this.sendCiv(IcomScopeCommands_1.IcomScopeCommands.setScopeDisplay(ctrAddr, rigAddr, true));
+        this.sendCiv(IcomScopeCommands_1.IcomScopeCommands.setScopeDataOutput(ctrAddr, rigAddr, true));
+    }
+    async disableScope() {
+        const ctrAddr = IcomConstants_1.DEFAULT_CONTROLLER_ADDR;
+        const rigAddr = this.civ.civAddress & 0xff;
+        this.sendCiv(IcomScopeCommands_1.IcomScopeCommands.setScopeDataOutput(ctrAddr, rigAddr, false));
+        this.sendCiv(IcomScopeCommands_1.IcomScopeCommands.setScopeDisplay(ctrAddr, rigAddr, false));
+    }
+    async readScopeSpan(options) {
+        const timeoutMs = options?.timeout ?? 3000;
+        const receiver = options?.receiver ?? 0;
+        const ctrAddr = IcomConstants_1.DEFAULT_CONTROLLER_ADDR;
+        const rigAddr = this.civ.civAddress & 0xff;
+        const req = IcomScopeCommands_1.IcomScopeCommands.readScopeSpan(ctrAddr, rigAddr, receiver);
+        const resp = await this.waitForCivFrame((frame) => IcomControl.matchCommandFrame(frame, 0x27, [0x15, receiver], ctrAddr, rigAddr), timeoutMs, () => this.sendCiv(req));
+        if (!resp || resp.length < 13) {
+            return null;
+        }
+        const spanHz = (0, IcomScopeParser_1.parseIcomBcdFreqLE)(resp.subarray(7, 12));
+        return {
+            receiver,
+            spanHz,
+        };
+    }
+    async setScopeSpan(spanHz, options) {
+        const receiver = options?.receiver ?? 0;
+        const ctrAddr = IcomConstants_1.DEFAULT_CONTROLLER_ADDR;
+        const rigAddr = this.civ.civAddress & 0xff;
+        this.sendCiv(IcomScopeCommands_1.IcomScopeCommands.setScopeSpan(ctrAddr, rigAddr, spanHz, receiver));
+    }
+    async waitForScopeFrame(options) {
+        const timeoutMs = options?.timeout ?? 3000;
+        return this.scope.waitForScopeFrame(timeoutMs);
+    }
     /**
      * Set PTT (Push-To-Talk) state
      * @param on - true to key transmitter, false to unkey
@@ -1514,6 +1558,7 @@ class IcomControl {
             this.civAssembleBuf = this.civAssembleBuf.subarray(end + 1);
             // Emit event
             this.ev.emit('civFrame', frame);
+            this.scope.handleCivFrame(frame, 'lan-civ');
             // Continue loop in case multiple frames are in buffer
         }
     }

package/dist/scope/IcomScopeCommands.d.ts

@@ -0,0 +1,7 @@
+export declare const IcomScopeCommands: {
+    setScopeDataOutput(ctrAddr: number, rigAddr: number, enabled: boolean): Buffer;
+    setScopeDisplay(ctrAddr: number, rigAddr: number, enabled: boolean): Buffer;
+    readScopeSpan(ctrAddr: number, rigAddr: number, receiver?: 0 | 1): Buffer;
+    setScopeSpan(ctrAddr: number, rigAddr: number, spanHz: number, receiver?: 0 | 1): Buffer;
+    encodeScopeSpanHz(spanHz: number): Buffer;
+};

package/dist/scope/IcomScopeCommands.js

@@ -0,0 +1,37 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IcomScopeCommands = void 0;
+exports.IcomScopeCommands = {
+    setScopeDataOutput(ctrAddr, rigAddr, enabled) {
+        return Buffer.from([
+            0xfe, 0xfe, rigAddr & 0xff, ctrAddr & 0xff, 0x27, 0x11, enabled ? 0x01 : 0x00, 0xfd
+        ]);
+    },
+    setScopeDisplay(ctrAddr, rigAddr, enabled) {
+        return Buffer.from([
+            0xfe, 0xfe, rigAddr & 0xff, ctrAddr & 0xff, 0x27, 0x10, enabled ? 0x01 : 0x00, 0xfd
+        ]);
+    },
+    readScopeSpan(ctrAddr, rigAddr, receiver = 0) {
+        return Buffer.from([
+            0xfe, 0xfe, rigAddr & 0xff, ctrAddr & 0xff, 0x27, 0x15, receiver & 0xff, 0xfd
+        ]);
+    },
+    setScopeSpan(ctrAddr, rigAddr, spanHz, receiver = 0) {
+        const bytes = exports.IcomScopeCommands.encodeScopeSpanHz(spanHz);
+        return Buffer.from([
+            0xfe, 0xfe, rigAddr & 0xff, ctrAddr & 0xff, 0x27, 0x15, receiver & 0xff, ...bytes, 0xfd
+        ]);
+    },
+    encodeScopeSpanHz(spanHz) {
+        const safeSpanHz = Math.max(0, Math.round(spanHz));
+        const out = Buffer.alloc(5);
+        let remaining = safeSpanHz;
+        for (let i = 0; i < out.length; i++) {
+            const twoDigits = remaining % 100;
+            out[i] = ((((twoDigits / 10) | 0) & 0x0f) << 4) | (twoDigits % 10);
+            remaining = Math.floor(remaining / 100);
+        }
+        return out;
+    }
+};

package/dist/scope/IcomScopeParser.d.ts

@@ -0,0 +1,5 @@
+import { IcomScopeSegmentInfo } from '../types';
+export declare function isScopeFrame(frame: Buffer): boolean;
+export declare function bcdByteToInt(v: number): number;
+export declare function parseIcomBcdFreqLE(bytes: Buffer): number;
+export declare function parseScopeSegment(frame: Buffer, transport: 'lan-civ' | 'serial', freqLen?: number): IcomScopeSegmentInfo | null;

package/dist/scope/IcomScopeParser.js

@@ -0,0 +1,72 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.isScopeFrame = isScopeFrame;
+exports.bcdByteToInt = bcdByteToInt;
+exports.parseIcomBcdFreqLE = parseIcomBcdFreqLE;
+exports.parseScopeSegment = parseScopeSegment;
+const SCOPE_PREFIX = [0x27, 0x00, 0x00];
+function isScopeFrame(frame) {
+    if (frame.length < 9)
+        return false;
+    if (frame[0] !== 0xfe || frame[1] !== 0xfe)
+        return false;
+    if (frame[frame.length - 1] !== 0xfd)
+        return false;
+    return frame[4] === SCOPE_PREFIX[0] && frame[5] === SCOPE_PREFIX[1] && frame[6] === SCOPE_PREFIX[2];
+}
+function bcdByteToInt(v) {
+    return (v & 0x0f) + (((v >> 4) & 0x0f) * 10);
+}
+function parseIcomBcdFreqLE(bytes) {
+    let hz = 0;
+    let multiplier = 1;
+    for (const byte of bytes) {
+        hz += (byte & 0x0f) * multiplier;
+        multiplier *= 10;
+        hz += ((byte >> 4) & 0x0f) * multiplier;
+        multiplier *= 10;
+    }
+    return hz;
+}
+function parseScopeSegment(frame, transport, freqLen = 5) {
+    if (!isScopeFrame(frame))
+        return null;
+    const payload = frame.subarray(4, frame.length - 1);
+    if (payload.length < 5)
+        return null;
+    const sequence = bcdByteToInt(payload[3]);
+    const sequenceMax = bcdByteToInt(payload[4]);
+    if (sequence <= 0 || sequenceMax <= 0 || sequence > sequenceMax)
+        return null;
+    const segment = {
+        receiver: 0,
+        sequence,
+        sequenceMax,
+        rawCivPayload: Buffer.from(payload),
+        transport
+    };
+    if (sequence === 1) {
+        const minimumHeaderLength = 3 + 2 + (freqLen * 2) + 1;
+        if (payload.length < minimumHeaderLength)
+            return null;
+        const mode = payload[5];
+        const primaryFreq = parseIcomBcdFreqLE(payload.subarray(6, 6 + freqLen));
+        const secondaryFreq = parseIcomBcdFreqLE(payload.subarray(6 + freqLen, 6 + (freqLen * 2)));
+        const outOfRange = payload[6 + (freqLen * 2)] !== 0x00;
+        let startFreqHz = primaryFreq;
+        let endFreqHz = secondaryFreq;
+        if (mode === 0) {
+            startFreqHz = Math.max(0, primaryFreq - secondaryFreq);
+            endFreqHz = primaryFreq + secondaryFreq;
+        }
+        segment.mode = mode;
+        segment.outOfRange = outOfRange;
+        segment.startFreqHz = startFreqHz;
+        segment.endFreqHz = endFreqHz;
+        const pixelOffset = 7 + (freqLen * 2);
+        segment.pixels = new Uint8Array(payload.subarray(pixelOffset));
+        return segment;
+    }
+    segment.pixels = new Uint8Array(payload.subarray(5));
+    return segment;
+}

package/dist/scope/IcomScopeService.d.ts

@@ -0,0 +1,17 @@
+import { EventEmitter } from 'events';
+import { IcomScopeFrame, IcomScopeSegmentInfo, IcomScopeTransport } from '../types';
+export interface IcomScopeServiceOptions {
+    assemblyTimeoutMs?: number;
+    freqLen?: number;
+}
+export declare class IcomScopeService extends EventEmitter {
+    private readonly assemblyTimeoutMs;
+    private readonly freqLen;
+    private readonly assemblies;
+    constructor(options?: IcomScopeServiceOptions);
+    handleCivFrame(frame: Buffer, transport: IcomScopeTransport): IcomScopeFrame | null;
+    handleScopeSegment(segment: IcomScopeSegmentInfo): IcomScopeFrame | null;
+    waitForScopeFrame(timeoutMs?: number): Promise<IcomScopeFrame | null>;
+    private cleanupExpiredAssemblies;
+    private concatChunks;
+}

package/dist/scope/IcomScopeService.js

@@ -0,0 +1,112 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.IcomScopeService = void 0;
+const events_1 = require("events");
+const IcomScopeParser_1 = require("./IcomScopeParser");
+class IcomScopeService extends events_1.EventEmitter {
+    constructor(options) {
+        super();
+        this.assemblies = new Map();
+        this.assemblyTimeoutMs = options?.assemblyTimeoutMs ?? 500;
+        this.freqLen = options?.freqLen ?? 5;
+    }
+    handleCivFrame(frame, transport) {
+        const segment = (0, IcomScopeParser_1.parseScopeSegment)(frame, transport, this.freqLen);
+        if (!segment)
+            return null;
+        return this.handleScopeSegment(segment);
+    }
+    handleScopeSegment(segment) {
+        this.cleanupExpiredAssemblies();
+        this.emit('scopeSegment', segment);
+        const key = segment.receiver;
+        const now = Date.now();
+        if (segment.sequence === 1) {
+            this.assemblies.set(key, {
+                receiver: segment.receiver,
+                expectedMax: segment.sequenceMax,
+                mode: segment.mode,
+                startFreqHz: segment.startFreqHz,
+                endFreqHz: segment.endFreqHz,
+                outOfRange: segment.outOfRange,
+                chunks: segment.pixels ? [segment.pixels] : [],
+                rawCivPayloads: [Buffer.from(segment.rawCivPayload)],
+                updatedAt: now
+            });
+        }
+        else {
+            const state = this.assemblies.get(key);
+            if (!state)
+                return null;
+            if (state.expectedMax !== segment.sequenceMax) {
+                this.assemblies.delete(key);
+                return null;
+            }
+            state.chunks.push(segment.pixels ?? new Uint8Array());
+            state.rawCivPayloads.push(Buffer.from(segment.rawCivPayload));
+            state.updatedAt = now;
+        }
+        const state = this.assemblies.get(key);
+        if (!state)
+            return null;
+        if (segment.sequence !== state.expectedMax)
+            return null;
+        if (state.mode === undefined || state.startFreqHz === undefined || state.endFreqHz === undefined || state.outOfRange === undefined) {
+            this.assemblies.delete(key);
+            return null;
+        }
+        const pixels = this.concatChunks(state.chunks);
+        const frame = {
+            valid: true,
+            receiver: state.receiver,
+            sequence: segment.sequence,
+            sequenceMax: state.expectedMax,
+            mode: state.mode,
+            outOfRange: state.outOfRange,
+            startFreqHz: state.startFreqHz,
+            endFreqHz: state.endFreqHz,
+            pixels,
+            rawCivPayloads: state.rawCivPayloads.map((payload) => Buffer.from(payload)),
+            transport: segment.transport
+        };
+        this.assemblies.delete(key);
+        this.emit('scopeFrame', frame);
+        return frame;
+    }
+    async waitForScopeFrame(timeoutMs = 3000) {
+        return new Promise((resolve) => {
+            let done = false;
+            const onFrame = (frame) => {
+                done = true;
+                this.off('scopeFrame', onFrame);
+                resolve(frame);
+            };
+            this.on('scopeFrame', onFrame);
+            setTimeout(() => {
+                if (done)
+                    return;
+                this.off('scopeFrame', onFrame);
+                resolve(null);
+            }, timeoutMs);
+        });
+    }
+    cleanupExpiredAssemblies() {
+        const now = Date.now();
+        for (const [key, state] of this.assemblies.entries()) {
+            if (now - state.updatedAt > this.assemblyTimeoutMs) {
+                this.assemblies.delete(key);
+            }
+        }
+    }
+    concatChunks(chunks) {
+        const total = chunks.reduce((sum, chunk) => sum + chunk.length, 0);
+        const out = new Uint8Array(total);
+        let offset = 0;
+        for (const chunk of chunks) {
+            out.set(chunk, offset);
+            offset += chunk.length;
+        }
+        return out;
+    }
+}
+exports.IcomScopeService = IcomScopeService;

package/dist/types.d.ts

@@ -39,6 +39,8 @@ export interface IcomRigEvents {
     capabilities: (c: CapabilitiesInfo) => void;
     civ: (data: Buffer) => void;
     civFrame: (frame: Buffer) => void;
+    scopeSegment: (segment: IcomScopeSegmentInfo) => void;
+    scopeFrame: (frame: IcomScopeFrame) => void;
     audio: (frame: AudioFrame) => void;
     error: (err: Error) => void;
     connectionLost: (info: ConnectionLostInfo) => void;
@@ -82,6 +84,36 @@ export interface QueryOptions {
      */
     timeout?: number;
 }
+export type IcomScopeTransport = 'lan-civ' | 'serial';
+export interface IcomScopeSegmentInfo {
+    receiver: 0 | 1;
+    sequence: number;
+    sequenceMax: number;
+    mode?: 0 | 1 | 2 | 3;
+    outOfRange?: boolean;
+    startFreqHz?: number;
+    endFreqHz?: number;
+    pixels?: Uint8Array;
+    rawCivPayload: Buffer;
+    transport: IcomScopeTransport;
+}
+export interface IcomScopeFrame {
+    valid: boolean;
+    receiver: 0 | 1;
+    sequence: number;
+    sequenceMax: number;
+    mode: 0 | 1 | 2 | 3;
+    outOfRange: boolean;
+    startFreqHz: number;
+    endFreqHz: number;
+    pixels: Uint8Array;
+    rawCivPayloads: Buffer[];
+    transport: IcomScopeTransport;
+}
+export interface IcomScopeSpanInfo {
+    receiver: 0 | 1;
+    spanHz: number;
+}
 /**
  * Result of a meter reading operation (SWR, ALC, etc.)
  * @deprecated Use specific types like SwrReading, AlcReading instead

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "icom-wlan-node",
-  "version": "0.3.0",
+  "version": "0.5.0",
   "description": "Icom WLAN (CI‑V, audio) protocol implementation for Node.js/TypeScript.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
@@ -10,16 +10,27 @@
     "test": "jest",
     "prepublishOnly": "npm run build",
     "lint": "eslint .",
-    "diagnose": "tsx scripts/diagnose.ts"
+    "diagnose": "tsx scripts/diagnose.ts",
+    "test:scope:real": "tsx scripts/test-scope-real.ts"
   },
-  "keywords": ["icom", "civ", "cat", "udp", "hamradio", "wlan", "audio"],
+  "keywords": [
+    "icom",
+    "civ",
+    "cat",
+    "udp",
+    "hamradio",
+    "wlan",
+    "audio"
+  ],
   "author": "boybook",
   "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/boybook/icom-wlan-node.git"
   },
-  "files": ["dist"],
+  "files": [
+    "dist"
+  ],
   "devDependencies": {
     "@types/jest": "^29.5.12",
     "@types/node": "^20.10.6",