icom-wlan-node 0.1.0 → 0.2.0

package/README.md

@@ -1,4 +1,4 @@
-# @boybook/icom-wlan
+# icom-wlan-node
 
 Icom WLAN (UDP) protocol implementation in Node.js + TypeScript, featuring:
 
@@ -16,7 +16,7 @@ Acknowledgements: Thanks to FT8CN (https://github.com/N0BOY/FT8CN) for sharing p
 ## Install
 
 ```
-npm install @boybook/icom-wlan
+npm install icom-wlan-node
 ```
 
 Build from source:
@@ -29,7 +29,7 @@ npm run build
 ## Quick Start
 
 ```ts
-import { IcomControl, AUDIO_RATE } from '@boybook/icom-wlan';
+import { IcomControl, AUDIO_RATE } from 'icom-wlan-node';
 
 const rig = new IcomControl({
   control: { ip: '192.168.1.50', port: 50001 },
@@ -106,37 +106,175 @@ await rig.setPtt(false);
   - `civFrame(Buffer)` — one complete CI‑V frame (FE FE ... FD)
   - `audio({ pcm16: Buffer })` — audio frames
   - `error(Error)` — UDP errors
+  - `connectionLost(ConnectionLostInfo)` — session timeout detected
+  - `connectionRestored(ConnectionRestoredInfo)` — reconnected successfully
+  - `reconnectAttempting(ReconnectAttemptInfo)` — reconnect attempt started
+  - `reconnectFailed(ReconnectFailedInfo)` — reconnect attempt failed
 - Methods
   - `connect()` / `disconnect()` — connects control + CIV + audio sub‑sessions; resolves when all ready
   - `sendCiv(buf: Buffer)` — send a raw CI‑V frame
   - `setPtt(on: boolean)` — key/unkey; also manages TX meter polling and audio tailing
   - `sendAudioFloat32(samples: Float32Array, addLeadingBuffer?: boolean)` / `sendAudioPcm16(samples: Int16Array)`
+  - `getConnectionPhase()` — returns current ConnectionPhase (IDLE, CONNECTING, CONNECTED, DISCONNECTING, RECONNECTING)
+  - `getConnectionMetrics()` — returns detailed ConnectionMetrics (phase, uptime, session states, etc.)
+  - `getConnectionState()` — returns per‑session ConnectionState (control, civ, audio)
+  - `isAnySessionDisconnected()` — returns true if any session is disconnected
+  - `configureMonitoring(config)` — configure connection monitoring and auto‑reconnect behavior
+
+### Connection Management & Auto-Reconnect
+
+The library features a robust state machine for connection lifecycle management with automatic reconnection support.
+
+#### Connection State Machine
+
+```ts
+ConnectionPhase: IDLE → CONNECTING → CONNECTED → DISCONNECTING
+                   ↓                      ↓
+                RECONNECTING ←────────────┘
+```
+
+#### Basic Usage
+
+```ts
+// Connect (idempotent - safe to call multiple times)
+await rig.connect();
+
+// Query connection phase
+const phase = rig.getConnectionPhase(); // 'IDLE' | 'CONNECTING' | 'CONNECTED' | ...
+
+// Get detailed metrics
+const metrics = rig.getConnectionMetrics();
+console.log(metrics.phase);       // Current phase
+console.log(metrics.uptime);      // Milliseconds since connected
+console.log(metrics.sessions);    // Per-session states {control, civ, audio}
+
+// Disconnect (also idempotent)
+await rig.disconnect();
+```
+
+#### Connection Monitoring Events
+
+```ts
+// Connection lost (any session timeout)
+rig.events.on('connectionLost', (info) => {
+  console.error(`Lost: ${info.sessionType}, idle: ${info.timeSinceLastData}ms`);
+});
+
+// Connection restored after reconnect
+rig.events.on('connectionRestored', (info) => {
+  console.log(`Restored after ${info.downtime}ms downtime`);
+});
+
+// Reconnect attempt started
+rig.events.on('reconnectAttempting', (info) => {
+  console.log(`Reconnect attempt #${info.attemptNumber}, delay: ${info.delay}ms`);
+});
+
+// Reconnect attempt failed
+rig.events.on('reconnectFailed', (info) => {
+  console.error(`Attempt #${info.attemptNumber} failed: ${info.error}`);
+  if (!info.willRetry) console.error('Giving up - max retries reached');
+});
+```
+
+#### Auto-Reconnect Configuration
+
+```ts
+rig.configureMonitoring({
+  timeout: 8000,              // Session timeout: 8s (default: 5s)
+  checkInterval: 1000,        // Check every 1s (default: 1s)
+  autoReconnect: true,        // Enable auto-reconnect (default: false)
+  maxReconnectAttempts: 10,   // Max retries (default: undefined = infinite)
+  reconnectBaseDelay: 2000,   // Base delay: 2s (default: 2s)
+  reconnectMaxDelay: 30000    // Max delay: 30s (default: 30s, uses exponential backoff)
+});
+```
+
+**Exponential Backoff**: Delays are `baseDelay × 2^(attempt-1)`, capped at `maxDelay`.
+Example: 2s → 4s → 8s → 16s → 30s (capped) → 30s ...
+
+#### Error Handling
+
+**Common Errors**:
+
+```ts
+try {
+  await rig.connect();
+} catch (err) {
+  if (err.message.includes('timeout')) {
+    // Connection timeout (no response from radio)
+  } else if (err.message.includes('Login failed')) {
+    // Authentication error (check userName/password)
+  } else if (err.message.includes('Radio reported connected=false')) {
+    // Radio rejected connection (may be busy with another client)
+  } else if (err.message.includes('Cannot connect while disconnecting')) {
+    // Invalid state transition (wait for disconnect to complete)
+  }
+}
+
+// Listen for UDP errors
+rig.events.on('error', (err) => {
+  console.error('UDP error:', err.message);
+  // Network issues, invalid packets, etc.
+});
+```
+
+**Connection States to Handle**:
+- **CONNECTING**: Wait or show "connecting..." UI
+- **CONNECTED**: Normal operation
+- **RECONNECTING**: Show "reconnecting..." UI, disable TX
+- **DISCONNECTING**: Cleanup in progress
+- **IDLE**: Not connected
 
 ### High‑Level API
 
 The library exposes common CI‑V operations as friendly methods. Addresses are handled internally (`ctrAddr=0xe0`, `rigAddr` discovered via capabilities).
 
-- `setFrequency(hz: number)`
-- `setMode(mode: IcomMode | number, { dataMode?: boolean })`
-- `setPtt(on: boolean)`
+#### Rig Control
+
+- `setFrequency(hz: number)` — Set operating frequency in Hz
+- `setMode(mode: IcomMode | number, options?: { dataMode?: boolean })` — Set mode (supports string or numeric code)
+- `setPtt(on: boolean)` — Key/unkey transmitter
+
+**Supported Modes** (IcomMode string constants):
+- `'LSB'`, `'USB'`, `'AM'`, `'CW'`, `'RTTY'`, `'FM'`, `'WFM'`, `'CW_R'`, `'RTTY_R'`, `'DV'`
+- Or use numeric codes: `0x00` (LSB), `0x01` (USB), `0x02` (AM), etc.
+
+#### Rig Query
+
 - `readOperatingFrequency(options?: QueryOptions) => Promise<number|null>`
 - `readOperatingMode(options?: QueryOptions) => Promise<{ mode: number; filter?: number; modeName?: string; filterName?: string } | null>`
 - `readTransmitFrequency(options?: QueryOptions) => Promise<number|null>`
 - `readTransceiverState(options?: QueryOptions) => Promise<'TX' | 'RX' | 'UNKNOWN' | null>`
 - `readBandEdges(options?: QueryOptions) => Promise<Buffer|null>`
+
+#### Meters & Levels
+
 - `readSWR(options?: QueryOptions) => Promise<{ raw: number; swr: number; alert: boolean } | null>`
 - `readALC(options?: QueryOptions) => Promise<{ raw: number; percent: number; alert: boolean } | null>`
 - `getConnectorWLanLevel(options?: QueryOptions) => Promise<{ raw: number; percent: number } | null>`
 - `getLevelMeter(options?: QueryOptions) => Promise<{ raw: number; percent: number } | null>`
-- `setConnectorWLanLevel(level: number)`
-- `setConnectorDataMode(mode: ConnectorDataMode | number)`
+- `setConnectorWLanLevel(level: number)` — Set WLAN audio level (0-255)
+
+#### Connector Settings
 
-Examples:
+- `setConnectorDataMode(mode: ConnectorDataMode | number)` — Set data routing mode (supports string or numeric)
+
+**Supported Connector Modes** (ConnectorDataMode string constants):
+- `'MIC'` (0x00), `'ACC'` (0x01), `'USB'` (0x02), `'WLAN'` (0x03)
+
+#### Examples
 
 ```ts
-// Set frequency and mode (USB-D)
+// Set frequency and mode using string constants
 await rig.setFrequency(14074000);
-await rig.setMode(0x01, { dataMode: true }); // USB=0x01, data mode
+await rig.setMode('USB', { dataMode: true }); // USB-D for FT8
+
+// Or use numeric codes
+await rig.setMode(0x01, { dataMode: true }); // USB=0x01
+
+// Set LSB mode
+await rig.setMode('LSB');
 
 // Query current frequency (Hz)
 const hz = await rig.readOperatingFrequency({ timeout: 3000 });
@@ -156,12 +294,15 @@ await rig.setPtt(false);
 const swr = await rig.readSWR({ timeout: 2000 });
 const alc = await rig.readALC({ timeout: 2000 });
 const wlanLevel = await rig.getConnectorWLanLevel({ timeout: 2000 });
-const level = await rig.getLevelMeter({ timeout: 1500 });
-await rig.setConnectorWLanLevel(0x0120);
-await rig.setConnectorDataMode(0x01); // e.g., DATA
 
-if (level) {
-  console.log(`Generic Level Meter: raw=${level.raw} (${level.percent.toFixed(1)}%)`);
+// Set connector to WLAN mode using string constant
+await rig.setConnectorDataMode('WLAN');
+// Or numeric: await rig.setConnectorDataMode(0x03);
+
+await rig.setConnectorWLanLevel(120); // Set WLAN audio level
+
+if (wlanLevel) {
+  console.log(`WLAN Level: ${wlanLevel.percent.toFixed(1)}%`);
 }
 ```
 

package/dist/core/Session.d.ts

@@ -1,4 +1,5 @@
 import { UdpClient } from '../transport/UdpClient';
+import { SessionType } from '../types';
 export interface SessionOptions {
     ip: string;
     port: number;
@@ -19,10 +20,12 @@ export declare class Session {
     lastSentTime: number;
     lastReceivedTime: number;
     private address;
+    private handlers;
     private txHistory;
     private areYouThereTimer?;
     private pingTimer?;
     private destroyed;
+    sessionType?: SessionType;
     constructor(address: SessionOptions, handlers: SessionHandlers);
     open(): void;
     close(): void;
@@ -40,4 +43,10 @@ export declare class Session {
     stopPing(): void;
     stopTimers(): void;
     setRemote(ip: string, port: number): void;
+    /**
+     * Reset session state to initial values
+     * Call this before reconnecting to ensure clean state
+     * (especially important after radio restart)
+     */
+    resetState(): void;
 }

package/dist/core/Session.js

@@ -19,21 +19,24 @@ class Session {
         this.txHistory = new Map();
         this.destroyed = false;
         this.address = address;
+        this.handlers = handlers;
         this.udp.on('data', (rinfo, data) => {
             if (this.destroyed)
                 return;
             this.lastReceivedTime = Date.now();
             try {
-                // Peek type directly to avoid late requires during teardown
-                const t = data.length >= 6 ? data.readUInt16LE(4) : -1;
-                (0, debug_1.dbgV)(`RX port=${this.localPort} from ${rinfo.address}:${rinfo.port} len=${data.length} type=${t >= 0 ? '0x' + t.toString(16) : 'n/a'}`);
+                const type = data.length >= 6 ? data.readUInt16LE(4) : -1;
+                (0, debug_1.dbgV)(`RX port=${this.localPort} from ${rinfo.address}:${rinfo.port} len=${data.length} type=${type >= 0 ? '0x' + type.toString(16) : 'n/a'}`);
             }
             catch { }
             handlers.onData(data);
         });
         this.udp.on('error', handlers.onSendError);
     }
-    open() { this.udp.open(); }
+    open() {
+        this.destroyed = false; // Reset destroyed flag to allow sending data after reconnection
+        this.udp.open();
+    }
     close() {
         this.stopTimers();
         this.destroyed = true;
@@ -78,8 +81,9 @@ class Session {
     } }
     startAreYouThere() {
         this.stopAreYouThere();
+        (0, debug_1.dbg)(`Starting AreYouThere timer for ${this.address.ip}:${this.address.port}`);
         this.areYouThereTimer = setInterval(() => {
-            (0, debug_1.dbgV)(`AYT -> ${this.address.ip}:${this.address.port} localId=${this.localId}`);
+            (0, debug_1.dbg)(`AYT -> ${this.address.ip}:${this.address.port} localId=${this.localId}`);
             this.sendUntracked(IcomPackets_1.ControlPacket.toBytes(IcomPackets_1.Cmd.ARE_YOU_THERE, 0, this.localId, 0));
         }, 500);
     }
@@ -101,5 +105,30 @@ class Session {
     setRemote(ip, port) {
         this.address = { ip, port };
     }
+    /**
+     * Reset session state to initial values
+     * Call this before reconnecting to ensure clean state
+     * (especially important after radio restart)
+     */
+    resetState() {
+        // Reset destroyed flag to ensure session is usable after state reset
+        this.destroyed = false;
+        // Generate new IDs
+        this.localId = Date.now() >>> 0;
+        this.remoteId = 0;
+        // Reset sequence numbers
+        this.trackedSeq = 1;
+        this.pingSeq = 0;
+        this.innerSeq = 0x30;
+        // Reset tokens
+        this.rigToken = 0;
+        this.localToken = (Date.now() & 0xffff) >>> 0;
+        // Reset timestamps
+        this.lastSentTime = Date.now();
+        this.lastReceivedTime = Date.now();
+        // Clear history
+        this.txHistory.clear();
+        (0, debug_1.dbgV)(`Session state reset: localId=${this.localId}, localToken=${this.localToken}`);
+    }
 }
 exports.Session = Session;

package/dist/index.js

@@ -15,7 +15,7 @@ var __exportStar = (this && this.__exportStar) || function(m, exports) {
 };
 Object.defineProperty(exports, "__esModule", { value: true });
 exports.AUDIO_RATE = exports.IcomRigCommands = exports.intToTwoByteBcd = exports.parseTwoByteBcd = exports.getFilterString = exports.getConnectorModeString = exports.getModeString = exports.getConnectorModeCode = exports.getModeCode = exports.METER_THRESHOLDS = exports.DEFAULT_CONTROLLER_ADDR = exports.CONNECTOR_MODE_MAP = exports.MODE_MAP = exports.IcomControl = void 0;
-// Export types
+// Export types (includes ConnectionPhase, ConnectionMetrics, etc.)
 __exportStar(require("./types"), exports);
 // Export main class
 var IcomControl_1 = require("./rig/IcomControl");

package/dist/rig/IcomCiv.js

@@ -12,9 +12,14 @@ class IcomCiv {
     }
     start() {
         this.stop();
-        // keep-alive open/close
+        // CIV session watchdog: Keep-alive mechanism to maintain CIV connection
+        // Matches FT8CN's startCivDataTimer() implementation:
+        // - Checks every 500ms if CIV session is receiving data
+        // - If no data received for >2000ms, sends OpenClose(true) to re-establish connection
+        // - This prevents silent disconnection where radio stops responding without error
         this.openTimer = setInterval(() => {
             if (Date.now() - this.sess.lastReceivedTime > 2000) {
+                (0, debug_1.dbg)('CIV watchdog: No data for >2s, sending OpenClose to keep alive');
                 this.sendOpenClose(true);
             }
         }, 500);

package/dist/rig/IcomControl.d.ts

@@ -1,4 +1,4 @@
-import { IcomRigOptions, RigEventEmitter, IcomMode, ConnectorDataMode, SetModeOptions, QueryOptions, SwrReading, AlcReading, WlanLevelReading, LevelMeterReading } from '../types';
+import { IcomRigOptions, RigEventEmitter, IcomMode, ConnectorDataMode, SetModeOptions, QueryOptions, SwrReading, AlcReading, WlanLevelReading, LevelMeterReading, ConnectionState, ConnectionMonitorConfig, ConnectionPhase, ConnectionMetrics } from '../types';
 import { IcomCiv } from './IcomCiv';
 import { IcomAudio } from './IcomAudio';
 export declare class IcomControl {
@@ -14,15 +14,58 @@ export declare class IcomControl {
     private tokenTimer?;
     private civAssembleBuf;
     private meterTimer?;
-    private loginReady;
-    private civReady;
-    private audioReady;
-    private resolveLoginReady;
-    private resolveCivReady;
-    private resolveAudioReady;
+    private connectionSession;
+    private nextSessionId;
+    private abortHandlers;
+    private monitorTimer?;
+    private monitorConfig;
     constructor(options: IcomRigOptions);
     get events(): RigEventEmitter;
+    /**
+     * Transition to a new connection phase with logging
+     * @private
+     */
+    private transitionTo;
+    /**
+     * Validate if a state transition is legal
+     * @private
+     */
+    private canTransitionTo;
+    /**
+     * Abort an ongoing connection attempt by session ID
+     * @private
+     */
+    private abortConnectionAttempt;
+    /**
+     * Connect to the rig
+     * Idempotent: multiple calls during CONNECTING phase are safe
+     * @throws Error if called during DISCONNECTING phase
+     */
     connect(): Promise<void>;
+    /**
+     * Internal connection implementation
+     * Uses local promises to avoid race conditions
+     * Uses phased timeout: 30s for overall, 10s for sub-sessions after login
+     * @param sessionId - Unique session ID to prevent race conditions
+     */
+    private _doConnect;
+    /**
+     * Create local promises for connection readiness
+     * This avoids race conditions with instance variables
+     * @param sessionId - Connection session ID for abort handler tracking
+     */
+    private createReadyPromises;
+    /**
+     * Start unified connection monitoring
+     * Monitors all three sessions from a single timer to avoid race conditions
+     * @private
+     */
+    private startUnifiedMonitoring;
+    /**
+     * Stop unified connection monitoring
+     * @private
+     */
+    private stopUnifiedMonitoring;
     disconnect(): Promise<void>;
     sendCiv(data: Buffer): void;
     /**
@@ -152,4 +195,62 @@ export declare class IcomControl {
     private stopMeterPolling;
     private onAudioData;
     private sendConnectionRequest;
+    /**
+     * Configure unified connection monitoring
+     * @param config - Monitoring configuration options
+     * @example
+     * rig.configureMonitoring({ timeout: 10000, checkInterval: 2000, autoReconnect: true });
+     */
+    configureMonitoring(config: ConnectionMonitorConfig): void;
+    /**
+     * Get current connection state for all sessions
+     * @returns Object with connection state for each session
+     */
+    getConnectionState(): {
+        control: ConnectionState;
+        civ: ConnectionState;
+        audio: ConnectionState;
+    };
+    /**
+     * Check if any session has lost connection
+     * @returns true if any session is disconnected
+     */
+    isAnySessionDisconnected(): boolean;
+    /**
+     * Handle connection lost event from a session
+     * Simplified strategy: any session loss triggers full reconnect
+     * @private
+     */
+    private handleConnectionLost;
+    /**
+     * Schedule a full reconnection (all sessions)
+     * Uses simple while loop with exponential backoff
+     * @private
+     */
+    private scheduleFullReconnect;
+    /**
+     * Connect with timeout (helper for reconnection)
+     * @private
+     */
+    private connectWithTimeout;
+    /**
+     * Sleep helper (returns a Promise)
+     * @private
+     */
+    private sleep;
+    /**
+     * Calculate reconnect delay using exponential backoff
+     * @private
+     */
+    private calculateReconnectDelay;
+    /**
+     * Get current connection phase
+     * @returns Current connection phase (IDLE, CONNECTING, CONNECTED, etc.)
+     */
+    getConnectionPhase(): ConnectionPhase;
+    /**
+     * Get detailed connection metrics for monitoring and diagnostics
+     * @returns Connection metrics including phase, uptime, session states
+     */
+    getConnectionMetrics(): ConnectionMetrics;
 }