hamlib 0.2.7 → 0.3.1

package/lib/index.js

@@ -1,4 +1,5 @@
 const path = require('path');
+const { EventEmitter } = require('events');
 const nodeGypBuild = require('node-gyp-build');
 // Ensure loader resolves from package root (contains prebuilds/ and build/)
 const nativeModule = nodeGypBuild(path.join(__dirname, '..'));
@@ -9,7 +10,7 @@ const nativeModule = nodeGypBuild(path.join(__dirname, '..'));
  * This is a wrapper around the native hamlib module that provides
  * a consistent interface for controlling amateur radio devices.
  */
-class HamLib {
+class HamLib extends EventEmitter {
   /**
    * Create a new HamLib instance
    * @param {number} model - Radio model number (run `rigctl -l` to find your device model)
@@ -18,7 +19,9 @@ class HamLib {
    *   - Network: 'localhost:4532' or '192.168.1.100:4532' (auto-switches to NETRIGCTL mode)
    */
   constructor(model, port) {
+    super();
     this._nativeInstance = new nativeModule.HamLib(model, port);
+    this._managedSpectrumRunning = false;
   }
 
   /**
@@ -187,6 +190,9 @@ class HamLib {
    * Connection can be re-established by calling open()
    */
   async close() {
+    if (this._managedSpectrumRunning) {
+      await this.stopManagedSpectrum();
+    }
     return this._nativeInstance.close();
   }
 
@@ -195,6 +201,9 @@ class HamLib {
    * Object reference should be deleted after calling this
    */
   async destroy() {
+    if (this._managedSpectrumRunning) {
+      await this.stopManagedSpectrum();
+    }
     return this._nativeInstance.destroy();
   }
 
@@ -1151,6 +1160,158 @@ class HamLib {
     return this._nativeInstance.sendRaw(data, replyMaxLen);
   }
 
+  /**
+   * Get official Hamlib spectrum capability metadata from the backend.
+   * @returns {Promise<Object>} Spectrum capability object.
+   */
+  async getSpectrumCapabilities() {
+    return this._nativeInstance.getSpectrumCapabilities();
+  }
+
+  /**
+   * Summarize whether official Hamlib spectrum streaming is usable for this rig.
+   * @returns {Promise<Object>} Product-oriented support summary.
+   */
+  async getSpectrumSupportSummary() {
+    const capabilities = await this.getSpectrumCapabilities();
+    const supportedFunctions = this.getSupportedFunctions();
+    const supportedLevels = this.getSupportedLevels();
+    const hasSpectrumFunction = supportedFunctions.includes('SPECTRUM');
+    const hasSpectrumHoldFunction = supportedFunctions.includes('SPECTRUM_HOLD');
+    const hasTransceiveFunction = supportedFunctions.includes('TRANSCEIVE');
+    const asyncDataSupported = capabilities.asyncDataSupported ?? hasSpectrumFunction;
+    const configurableLevels = ['SPECTRUM_MODE', 'SPECTRUM_SPAN', 'SPECTRUM_SPEED', 'SPECTRUM_REF', 'SPECTRUM_AVG']
+      .filter((name) => supportedLevels.includes(name));
+
+    return {
+      supported: Boolean(hasSpectrumFunction),
+      asyncDataSupported: Boolean(asyncDataSupported),
+      hasSpectrumFunction,
+      hasSpectrumHoldFunction,
+      hasTransceiveFunction,
+      configurableLevels,
+      scopes: capabilities.scopes ?? [],
+      modes: capabilities.modes ?? [],
+      spans: capabilities.spans ?? [],
+      avgModes: capabilities.avgModes ?? [],
+    };
+  }
+
+  /**
+   * Apply official Hamlib spectrum settings using high-level level/function APIs.
+   * Unsupported settings are skipped silently.
+   * @param {Object} [config]
+   */
+  async configureSpectrum(config = {}) {
+    const summary = await this.getSpectrumSupportSummary();
+    const applyLevel = async (name, value) => {
+      if (value === undefined || !summary.configurableLevels.includes(name)) return;
+      await this.setLevel(name, value);
+    };
+
+    if (summary.hasSpectrumHoldFunction && config.hold !== undefined) {
+      await this.setFunction('SPECTRUM_HOLD', Boolean(config.hold));
+    }
+
+    await applyLevel('SPECTRUM_MODE', config.mode);
+    await applyLevel('SPECTRUM_SPAN', config.spanHz);
+    await applyLevel('SPECTRUM_SPEED', config.speed);
+    await applyLevel('SPECTRUM_REF', config.referenceLevel);
+    await applyLevel('SPECTRUM_AVG', config.averageMode);
+
+    return summary;
+  }
+
+  /**
+   * Start the official Hamlib spectrum callback stream.
+   * @param {(line: Object) => void} [callback]
+   * @returns {Promise<boolean>}
+   */
+  async startSpectrumStream(callback) {
+    const listener = typeof callback === 'function'
+      ? callback
+      : (line) => this.emit('spectrumLine', line);
+    return this._nativeInstance.startSpectrumStream(listener);
+  }
+
+  /**
+   * Stop the official Hamlib spectrum callback stream.
+   * @returns {Promise<boolean>}
+   */
+  async stopSpectrumStream() {
+    return this._nativeInstance.stopSpectrumStream();
+  }
+
+  /**
+   * High-level managed spectrum startup for application use.
+   * @param {Object} [config]
+   */
+  async startManagedSpectrum(config = {}) {
+    const summary = await this.getSpectrumSupportSummary();
+    if (!summary.supported) {
+      throw new Error('Official Hamlib spectrum streaming is not supported by this rig/backend');
+    }
+
+    if (this._managedSpectrumRunning) {
+      return true;
+    }
+
+    await this.startSpectrumStream((line) => this.emit('spectrumLine', line));
+
+    try {
+      try {
+        await this.setConf('async', '1');
+      } catch (_) {
+        try {
+          await this.setConf('async', 'True');
+        } catch (_) {
+          // Not every backend accepts the config write even if async is supported.
+        }
+      }
+
+      await this.configureSpectrum({ hold: false, ...config });
+      await this.setFunction('SPECTRUM', true);
+      if (summary.hasTransceiveFunction) {
+        await this.setFunction('TRANSCEIVE', true);
+      }
+    } catch (error) {
+      try {
+        await this.stopManagedSpectrum();
+      } catch (_) {
+        // Ignore cleanup failures and surface the original startup error.
+      }
+      throw error;
+    }
+
+    this._managedSpectrumRunning = true;
+    this.emit('spectrumStateChanged', { active: true });
+    return true;
+  }
+
+  /**
+   * High-level managed spectrum shutdown for application use.
+   */
+  async stopManagedSpectrum() {
+    try {
+      const supportedFunctions = this.getSupportedFunctions();
+      if (supportedFunctions.includes('TRANSCEIVE')) {
+        await this.setFunction('TRANSCEIVE', false);
+      }
+      if (supportedFunctions.includes('SPECTRUM_HOLD')) {
+        await this.setFunction('SPECTRUM_HOLD', false);
+      }
+      if (supportedFunctions.includes('SPECTRUM')) {
+        await this.setFunction('SPECTRUM', false);
+      }
+    } finally {
+      await this.stopSpectrumStream();
+    }
+
+    this._managedSpectrumRunning = false;
+    this.emit('spectrumStateChanged', { active: false });
+    return true;
+  }
+
   /**
    * Set a backend configuration parameter
    * @param {string} name - Configuration token name

package/package.json

@@ -1,7 +1,7 @@
 {
   "name": "hamlib",
-  "version": "0.2.7",
-  "description": "Node.js wrapper for hamlib radio control library",
+  "version": "0.3.1",
+  "description": "Node.js bindings for Hamlib rig control with official spectrum streaming support",
   "main": "index.js",
   "module": "lib/index.mjs",
   "types": "index.d.ts",
@@ -30,6 +30,7 @@
     "lib/",
     "prebuilds/",
     "src/",
+    "docs/",
     "index.js",
     "index.d.ts",
     "binding.gyp",
@@ -43,9 +44,11 @@
     "rebuild": "node-gyp rebuild",
     "clean": "node-gyp clean",
     "test": "node test/test_loader.js",
+    "test:version": "node test/test_version.js",
     "test:network": "node test/test_network.js",
     "test:dummy": "node test/test_dummy_complete.js",
     "test:serial": "node test/test_serial_config.js",
+    "test:spectrum": "node test/test_spectrum_stream.js",
     "prebuild": "prebuildify --napi --strip",
     "prepare": "",
     "bundle": "node scripts/bundle-deps.js",