feat: add spectrum fixed display controls

Author: boybook

README.md

@@ -204,11 +204,29 @@ Spectrum API summary:
 - `getSpectrumCapabilities()` returns conservative backend metadata exposed by the native addon.
 - `getSpectrumSupportSummary()` returns a product-oriented summary of whether official spectrum streaming is usable on the current rig/backend.
 - `configureSpectrum()` applies supported `SPECTRUM_*` levels and optional `SPECTRUM_HOLD`.
+- `getSpectrumDisplayState()` returns a normalized display state with `mode/span/fixed edges/edge slot`.
+- `configureSpectrumDisplay()` applies a normalized display config and reads back the resulting state.
+- `getSpectrumEdgeSlot()` / `setSpectrumEdgeSlot()` expose backend edge-slot control when available.
+- `getSpectrumFixedEdges()` / `setSpectrumFixedEdges()` expose direct fixed-range control using `SPECTRUM_EDGE_LOW/HIGH`.
 - `startSpectrumStream(callback?)` registers the official Hamlib spectrum callback only.
 - `stopSpectrumStream()` unregisters the official spectrum callback.
 - `startManagedSpectrum(config?)` runs the validated startup sequence for Icom/Hamlib async spectrum.
 - `stopManagedSpectrum()` runs the symmetric shutdown sequence and unregisters the callback.
 
+Fixed-range example:
+
+```javascript
+await rig.configureSpectrumDisplay({
+  mode: 'fixed',
+  edgeSlot: 1,
+  edgeLowHz: 14074000,
+  edgeHighHz: 14077000,
+});
+
+const displayState = await rig.getSpectrumDisplayState();
+console.log(displayState);
+```
+
 Emitted events:
 
 - `spectrumLine` carries a single `SpectrumLine` object with frequency edges, mode, and raw bin payload.

index.d.ts

@@ -200,17 +200,40 @@ interface SpectrumSupportSummary extends SpectrumCapabilities {
   hasSpectrumHoldFunction: boolean;
   hasTransceiveFunction: boolean;
   configurableLevels: string[];
+  supportsFixedEdges: boolean;
+  supportsEdgeSlotSelection: boolean;
+  supportedEdgeSlots: number[];
 }
 
+type SpectrumDisplayMode = 'center' | 'fixed' | 'scroll-center' | 'scroll-fixed';
+
 interface SpectrumConfig {
   hold?: boolean;
-  mode?: number;
+  mode?: number | SpectrumDisplayMode;
   spanHz?: number;
+  edgeSlot?: number;
+  edgeLowHz?: number;
+  edgeHighHz?: number;
   speed?: number;
   referenceLevel?: number;
   averageMode?: number;
 }
 
+interface SpectrumDisplayState {
+  mode: SpectrumDisplayMode | null;
+  modeId: number | null;
+  modeName: string | null;
+  spanHz: number | null;
+  edgeSlot: number | null;
+  edgeLowHz: number | null;
+  edgeHighHz: number | null;
+  supportedModes: SpectrumModeInfo[];
+  supportedSpans: number[];
+  supportedEdgeSlots: number[];
+  supportsFixedEdges: boolean;
+  supportsEdgeSlotSelection: boolean;
+}
+
 /**
  * Split mode info interface
  */
@@ -1287,6 +1310,41 @@ declare class HamLib extends EventEmitter {
    */
   configureSpectrum(config?: SpectrumConfig): Promise<SpectrumSupportSummary>;
 
+  /**
+   * Get the current spectrum edge slot if exposed by the backend.
+   */
+  getSpectrumEdgeSlot(): Promise<number>;
+
+  /**
+   * Set the current spectrum edge slot if exposed by the backend.
+   */
+  setSpectrumEdgeSlot(slot: number): Promise<number>;
+
+  /**
+   * Get supported spectrum edge slots.
+   */
+  getSpectrumSupportedEdgeSlots(): Promise<number[]>;
+
+  /**
+   * Read current fixed spectrum edges.
+   */
+  getSpectrumFixedEdges(): Promise<{lowHz: number, highHz: number}>;
+
+  /**
+   * Set current fixed spectrum edges.
+   */
+  setSpectrumFixedEdges(range: {lowHz: number, highHz: number}): Promise<{lowHz: number, highHz: number}>;
+
+  /**
+   * Get a normalized spectrum display state for application use.
+   */
+  getSpectrumDisplayState(): Promise<SpectrumDisplayState>;
+
+  /**
+   * Configure spectrum display state using a normalized application-facing shape.
+   */
+  configureSpectrumDisplay(config?: SpectrumConfig): Promise<SpectrumDisplayState>;
+
   /**
    * Start receiving official Hamlib spectrum line events.
    */

lib/index.js

@@ -4,6 +4,17 @@ const nodeGypBuild = require('node-gyp-build');
 // Ensure loader resolves from package root (contains prebuilds/ and build/)
 const nativeModule = nodeGypBuild(path.join(__dirname, '..'));
 
+const DEFAULT_SPECTRUM_EDGE_SLOTS = [1, 2, 3, 4];
+
+function normalizeSpectrumModeName(name) {
+  const normalized = String(name || '').trim().toLowerCase();
+  if (normalized === 'center') return 'center';
+  if (normalized === 'fixed') return 'fixed';
+  if (normalized === 'center scroll' || normalized === 'center-scroll' || normalized === 'scroll-center') return 'scroll-center';
+  if (normalized === 'fixed scroll' || normalized === 'fixed-scroll' || normalized === 'scroll-fixed') return 'scroll-fixed';
+  return null;
+}
+
 /**
  * HamLib class for controlling amateur radio devices
  * 
@@ -1180,8 +1191,16 @@ class HamLib extends EventEmitter {
     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']
+    const configurableLevels = ['SPECTRUM_MODE', 'SPECTRUM_SPAN', 'SPECTRUM_EDGE_LOW', 'SPECTRUM_EDGE_HIGH', 'SPECTRUM_SPEED', 'SPECTRUM_REF', 'SPECTRUM_AVG']
       .filter((name) => supportedLevels.includes(name));
+    let supportsEdgeSlotSelection = false;
+
+    try {
+      const edgeSlot = await this.getConf('SPECTRUM_EDGE');
+      supportsEdgeSlotSelection = Number.isFinite(Number.parseInt(String(edgeSlot), 10));
+    } catch (_) {
+      supportsEdgeSlotSelection = false;
+    }
 
     return {
       supported: Boolean(hasSpectrumFunction),
@@ -1190,6 +1209,9 @@ class HamLib extends EventEmitter {
       hasSpectrumHoldFunction,
       hasTransceiveFunction,
       configurableLevels,
+      supportsFixedEdges: configurableLevels.includes('SPECTRUM_EDGE_LOW') && configurableLevels.includes('SPECTRUM_EDGE_HIGH'),
+      supportsEdgeSlotSelection,
+      supportedEdgeSlots: supportsEdgeSlotSelection ? [...DEFAULT_SPECTRUM_EDGE_SLOTS] : [],
       scopes: capabilities.scopes ?? [],
       modes: capabilities.modes ?? [],
       spans: capabilities.spans ?? [],
@@ -1208,20 +1230,122 @@ class HamLib extends EventEmitter {
       if (value === undefined || !summary.configurableLevels.includes(name)) return;
       await this.setLevel(name, value);
     };
+    const resolveModeId = async (mode) => {
+      if (mode === undefined || mode === null) return undefined;
+      if (Number.isFinite(mode)) return mode;
+      const requested = normalizeSpectrumModeName(mode);
+      if (!requested) {
+        throw new Error(`Unsupported spectrum mode: ${mode}`);
+      }
+      const matched = (summary.modes ?? []).find((entry) => normalizeSpectrumModeName(entry?.name) === requested);
+      if (!matched) {
+        throw new Error(`Spectrum mode not supported by this backend: ${mode}`);
+      }
+      return matched.id;
+    };
 
     if (summary.hasSpectrumHoldFunction && config.hold !== undefined) {
       await this.setFunction('SPECTRUM_HOLD', Boolean(config.hold));
     }
 
-    await applyLevel('SPECTRUM_MODE', config.mode);
+    if (config.edgeSlot !== undefined && summary.supportsEdgeSlotSelection) {
+      await this.setSpectrumEdgeSlot(config.edgeSlot);
+    }
+
+    await applyLevel('SPECTRUM_MODE', await resolveModeId(config.mode));
     await applyLevel('SPECTRUM_SPAN', config.spanHz);
+    await applyLevel('SPECTRUM_EDGE_LOW', config.edgeLowHz);
+    await applyLevel('SPECTRUM_EDGE_HIGH', config.edgeHighHz);
     await applyLevel('SPECTRUM_SPEED', config.speed);
     await applyLevel('SPECTRUM_REF', config.referenceLevel);
     await applyLevel('SPECTRUM_AVG', config.averageMode);
 
     return summary;
   }
 
+  async getSpectrumEdgeSlot() {
+    const raw = await this.getConf('SPECTRUM_EDGE');
+    const parsed = Number.parseInt(String(raw), 10);
+    if (!Number.isFinite(parsed)) {
+      throw new Error('Spectrum edge slot is not available');
+    }
+    return parsed;
+  }
+
+  async setSpectrumEdgeSlot(slot) {
+    const parsed = Number.parseInt(String(slot), 10);
+    if (!Number.isFinite(parsed) || parsed < 1) {
+      throw new Error(`Invalid spectrum edge slot: ${slot}`);
+    }
+    await this.setConf('SPECTRUM_EDGE', String(parsed));
+    return parsed;
+  }
+
+  async getSpectrumSupportedEdgeSlots() {
+    const summary = await this.getSpectrumSupportSummary();
+    return summary.supportedEdgeSlots ?? [];
+  }
+
+  async getSpectrumFixedEdges() {
+    const [lowHz, highHz] = await Promise.all([
+      this.getLevel('SPECTRUM_EDGE_LOW'),
+      this.getLevel('SPECTRUM_EDGE_HIGH'),
+    ]);
+    return { lowHz, highHz };
+  }
+
+  async setSpectrumFixedEdges({ lowHz, highHz }) {
+    if (!Number.isFinite(lowHz) || !Number.isFinite(highHz) || lowHz >= highHz) {
+      throw new Error('Spectrum fixed edge range must satisfy lowHz < highHz');
+    }
+    await this.setLevel('SPECTRUM_EDGE_LOW', lowHz);
+    await this.setLevel('SPECTRUM_EDGE_HIGH', highHz);
+    return { lowHz, highHz };
+  }
+
+  async getSpectrumDisplayState() {
+    const summary = await this.getSpectrumSupportSummary();
+    const [modeId, spanHz, fixedEdges, edgeSlot] = await Promise.all([
+      summary.configurableLevels.includes('SPECTRUM_MODE') ? this.getLevel('SPECTRUM_MODE') : Promise.resolve(null),
+      summary.configurableLevels.includes('SPECTRUM_SPAN') ? this.getLevel('SPECTRUM_SPAN') : Promise.resolve(null),
+      summary.supportsFixedEdges ? this.getSpectrumFixedEdges() : Promise.resolve(null),
+      summary.supportsEdgeSlotSelection ? this.getSpectrumEdgeSlot().catch(() => null) : Promise.resolve(null),
+    ]);
+    const modeInfo = (summary.modes ?? []).find((entry) => entry.id === modeId) ?? null;
+    const mode = normalizeSpectrumModeName(modeInfo?.name);
+    const edgeLowHz = fixedEdges?.lowHz ?? null;
+    const edgeHighHz = fixedEdges?.highHz ?? null;
+    const derivedSpanHz = (edgeLowHz !== null && edgeHighHz !== null) ? (edgeHighHz - edgeLowHz) : null;
+
+    return {
+      mode,
+      modeId,
+      modeName: modeInfo?.name ?? null,
+      spanHz: spanHz ?? derivedSpanHz,
+      edgeSlot,
+      edgeLowHz,
+      edgeHighHz,
+      supportedModes: summary.modes ?? [],
+      supportedSpans: summary.spans ?? [],
+      supportedEdgeSlots: summary.supportedEdgeSlots ?? [],
+      supportsFixedEdges: Boolean(summary.supportsFixedEdges),
+      supportsEdgeSlotSelection: Boolean(summary.supportsEdgeSlotSelection),
+    };
+  }
+
+  async configureSpectrumDisplay(config = {}) {
+    const normalizedConfig = { ...config };
+    if ((normalizedConfig.mode === 'fixed' || normalizedConfig.mode === 'scroll-fixed')
+      && normalizedConfig.edgeLowHz !== undefined
+      && normalizedConfig.edgeHighHz !== undefined
+      && normalizedConfig.edgeLowHz >= normalizedConfig.edgeHighHz) {
+      throw new Error('Spectrum fixed edge range must satisfy edgeLowHz < edgeHighHz');
+    }
+
+    await this.configureSpectrum(normalizedConfig);
+    return this.getSpectrumDisplayState();
+  }
+
   /**
    * Start the official Hamlib spectrum callback stream.
    * @param {(line: Object) => void} [callback]

package-lock.json

@@ -1,6 +1,6 @@
 {
   "name": "hamlib",
-  "version": "0.3.1",
+  "version": "0.3.2",
   "description": "Node.js bindings for Hamlib rig control with official spectrum streaming support",
   "main": "index.js",
   "module": "lib/index.mjs",

package.json

@@ -128,6 +128,8 @@ try {
   console.log('\n🆕 补齐 API 方法存在性测试:');
   const newApiMethods = [
     'getInfo', 'sendRaw', 'getSpectrumCapabilities', 'getSpectrumSupportSummary', 'configureSpectrum',
+    'getSpectrumDisplayState', 'configureSpectrumDisplay', 'getSpectrumEdgeSlot', 'setSpectrumEdgeSlot',
+    'getSpectrumSupportedEdgeSlots', 'getSpectrumFixedEdges', 'setSpectrumFixedEdges',
     'startSpectrumStream', 'stopSpectrumStream', 'startManagedSpectrum', 'stopManagedSpectrum', 'setConf', 'getConf',
     'getPassbandNormal', 'getPassbandNarrow', 'getPassbandWide',
     'getResolution',