hamlib 0.1.5 → 0.1.6

package/Readme.md

@@ -4,6 +4,7 @@ A comprehensive Node.js wrapper for [Hamlib](https://hamlib.github.io/) - contro
 
 ## 🚀 Features
 
+- **Async/Await Support**: All operations are asynchronous and non-blocking for optimal performance
 - **Built-in Methods**: Complete radio control API including memory channels, RIT/XIT, scanning, levels, functions, and more
 - **303+ Supported Radios**: Works with Yaesu, Icom, Kenwood, Elecraft, FlexRadio, and many more
 - **Multi-platform**: Pre-built binaries for Windows x64, Linux x64/ARM64, macOS ARM64
@@ -11,6 +12,25 @@ A comprehensive Node.js wrapper for [Hamlib](https://hamlib.github.io/) - contro
 - **TypeScript Support**: Full type definitions and IntelliSense
 - **Modern JavaScript**: CommonJS and ES Modules support
 
+## ⚡ Async Operations
+
+**All radio control operations are asynchronous** to prevent blocking the Node.js event loop during I/O operations:
+
+```javascript
+// ✅ Correct - Using async/await
+await rig.setFrequency(144390000);
+const frequency = await rig.getFrequency();
+
+// ✅ Correct - Using Promises
+rig.setFrequency(144390000)
+  .then(() => rig.getFrequency())
+  .then(freq => console.log('Frequency:', freq))
+  .catch(err => console.error('Error:', err));
+
+// ❌ Incorrect - Operations are no longer synchronous
+// rig.setFrequency(144390000); // This won't work as expected
+```
+
 ## 📦 Quick Start
 
 ```bash
@@ -20,25 +40,29 @@ npm install node-hamlib
 ```javascript
 const { HamLib } = require('node-hamlib');
 
-// Find your radio model
-const rigs = HamLib.getSupportedRigs();
-console.log('Supported radios:', rigs.length);
+async function controlRadio() {
+  // Find your radio model
+  const rigs = HamLib.getSupportedRigs();
+  console.log('Supported radios:', rigs.length);
 
-// Connect to radio
-const rig = new HamLib(1035, '/dev/ttyUSB0'); // FT-991A
-rig.open();
+  // Connect to radio
+  const rig = new HamLib(1035, '/dev/ttyUSB0'); // FT-991A
+  await rig.open();
 
-// Basic control
-rig.setFrequency(144390000); // 144.39 MHz
-rig.setMode('FM');
-rig.setPtt(true);
+  // Basic control
+  await rig.setFrequency(144390000); // 144.39 MHz
+  await rig.setMode('FM');
+  await rig.setPtt(true);
 
-// Get status
-console.log('Frequency:', rig.getFrequency());
-console.log('Mode:', rig.getMode());
-console.log('Signal:', rig.getStrength());
+  // Get status
+  console.log('Frequency:', await rig.getFrequency());
+  console.log('Mode:', await rig.getMode());
+  console.log('Signal:', await rig.getStrength());
 
-rig.close();
+  await rig.close();
+}
+
+controlRadio().catch(console.error);
 ```
 
 ## 📡 Complete API Reference
@@ -74,9 +98,9 @@ const rig = new HamLib(1035, 'localhost:4532');      // rigctld
 #### `open()` / `close()` / `destroy()`
 Connection control
 ```javascript
-rig.open();              // Open connection
-rig.close();             // Close (can reopen)
-rig.destroy();           // Destroy permanently
+await rig.open();        // Open connection
+await rig.close();       // Close (can reopen)
+await rig.destroy();     // Destroy permanently
 ```
 
 #### `getConnectionInfo()`
@@ -93,22 +117,22 @@ console.log('Status:', info.status);
 #### Frequency Control
 ```javascript
 // Set frequency (Hz)
-rig.setFrequency(144390000);
-rig.setFrequency(144390000, 'VFO-A');
+await rig.setFrequency(144390000);
+await rig.setFrequency(144390000, 'VFO-A');
 
 // Get frequency
-const freq = rig.getFrequency();
-const freqA = rig.getFrequency('VFO-A');
+const freq = await rig.getFrequency();
+const freqA = await rig.getFrequency('VFO-A');
 ```
 
 #### Mode Control
 ```javascript
 // Set mode
-rig.setMode('FM');
-rig.setMode('USB', 'wide');
+await rig.setMode('FM');
+await rig.setMode('USB', 'wide');
 
 // Get mode
-const mode = rig.getMode();
+const mode = await rig.getMode();
 console.log('Mode:', mode.mode);
 console.log('Bandwidth:', mode.bandwidth);
 ```
@@ -116,22 +140,22 @@ console.log('Bandwidth:', mode.bandwidth);
 #### VFO Control
 ```javascript
 // Set VFO
-rig.setVfo('VFO-A');
-rig.setVfo('VFO-B');
+await rig.setVfo('VFO-A');
+await rig.setVfo('VFO-B');
 
 // Get current VFO
-const vfo = rig.getVfo();
+const vfo = await rig.getVfo();
 ```
 
 #### PTT Control
 ```javascript
-rig.setPtt(true);   // Transmit
-rig.setPtt(false);  // Receive
+await rig.setPtt(true);   // Transmit
+await rig.setPtt(false);  // Receive
 ```
 
 #### Signal Monitoring
 ```javascript
-const strength = rig.getStrength();
+const strength = await rig.getStrength();
 console.log('Signal strength:', strength);
 ```
 
@@ -406,39 +430,48 @@ async function radioControl() {
   const rig = new HamLib(ft991a.rigModel, '/dev/ttyUSB0');
   
   try {
-    rig.open();
+    await rig.open();
     console.log('Connected to', rig.getConnectionInfo().port);
     
     // Set up radio
-    rig.setFrequency(144390000);
-    rig.setMode('FM');
-    rig.setLevel('RFPOWER', 0.5);
-    rig.setFunction('NB', true);
+    await rig.setFrequency(144390000);
+    await rig.setMode('FM');
+    await rig.setLevel('RFPOWER', 0.5);
+    await rig.setFunction('NB', true);
     
     // Store memory channel
-    rig.setMemoryChannel(1, {
+    await rig.setMemoryChannel(1, {
       frequency: 144390000,
       mode: 'FM',
       description: 'Local Repeater'
     });
     
     // Monitor signal
-    setInterval(() => {
-      const freq = rig.getFrequency();
-      const mode = rig.getMode();
-      const strength = rig.getStrength();
-      
-      console.log(`${freq/1000000} MHz ${mode.mode} S:${strength}`);
+    const monitorInterval = setInterval(async () => {
+      try {
+        const freq = await rig.getFrequency();
+        const mode = await rig.getMode();
+        const strength = await rig.getStrength();
+        
+        console.log(`${freq/1000000} MHz ${mode.mode} S:${strength}`);
+      } catch (err) {
+        console.error('Monitor error:', err.message);
+      }
     }, 1000);
     
+    // Stop monitoring after 30 seconds
+    setTimeout(() => {
+      clearInterval(monitorInterval);
+    }, 30000);
+    
   } catch (error) {
     console.error('Error:', error.message);
   } finally {
-    rig.close();
+    await rig.close();
   }
 }
 
-radioControl();
+radioControl().catch(console.error);
 ```
 
 ## 📋 Supported Radios

package/index.d.ts

@@ -224,25 +224,25 @@ declare class HamLib {
    * Must be called before other operations
    * @throws Throws error when connection fails
    */
-  open(): void;
+  open(): Promise<number>;
 
   /**
    * Set VFO (Variable Frequency Oscillator)
    * @param vfo VFO identifier, typically 'VFO-A' or 'VFO-B'
    * @throws Throws error when device doesn't support or operation fails
    */
-  setVfo(vfo: VFO): void;
+  setVfo(vfo: VFO): Promise<number>;
 
   /**
    * Set frequency
    * @param frequency Frequency value in hertz
    * @param vfo Optional VFO to set frequency on ('VFO-A' or 'VFO-B'). If not specified, uses current VFO
    * @example
-   * rig.setFrequency(144390000); // Set to 144.39MHz on current VFO
-   * rig.setFrequency(144390000, 'VFO-A'); // Set to 144.39MHz on VFO-A
-   * rig.setFrequency(144390000, 'VFO-B'); // Set to 144.39MHz on VFO-B
+   * await rig.setFrequency(144390000); // Set to 144.39MHz on current VFO
+   * await rig.setFrequency(144390000, 'VFO-A'); // Set to 144.39MHz on VFO-A
+   * await rig.setFrequency(144390000, 'VFO-B'); // Set to 144.39MHz on VFO-B
    */
-  setFrequency(frequency: number, vfo?: VFO): void;
+  setFrequency(frequency: number, vfo?: VFO): Promise<number>;
 
   /**
    * Set radio mode
@@ -250,60 +250,60 @@ declare class HamLib {
    * @param bandwidth Optional bandwidth setting ('narrow', 'wide', or default)
    * @note Operates on the current VFO (RIG_VFO_CURR)
    * @example
-   * rig.setMode('USB');
-   * rig.setMode('FM', 'narrow');
+   * await rig.setMode('USB');
+   * await rig.setMode('FM', 'narrow');
    */
-  setMode(mode: RadioMode, bandwidth?: 'narrow' | 'wide'): void;
+  setMode(mode: RadioMode, bandwidth?: 'narrow' | 'wide'): Promise<number>;
 
   /**
    * Set PTT (Push-to-Talk) status
    * @param state true to enable PTT, false to disable PTT
    * @note Operates on the current VFO (RIG_VFO_CURR)
    */
-  setPtt(state: boolean): void;
+  setPtt(state: boolean): Promise<number>;
 
   /**
    * Get current VFO
    * @returns Current VFO identifier
    */
-  getVfo(): string;
+  getVfo(): Promise<string>;
 
   /**
    * Get current frequency
    * @param vfo Optional VFO to get frequency from ('VFO-A' or 'VFO-B'). If not specified, uses current VFO
    * @returns Current frequency value in hertz
    * @example
-   * rig.getFrequency(); // Get frequency from current VFO
-   * rig.getFrequency('VFO-A'); // Get frequency from VFO-A
-   * rig.getFrequency('VFO-B'); // Get frequency from VFO-B
+   * await rig.getFrequency(); // Get frequency from current VFO
+   * await rig.getFrequency('VFO-A'); // Get frequency from VFO-A
+   * await rig.getFrequency('VFO-B'); // Get frequency from VFO-B
    */
-  getFrequency(vfo?: VFO): number;
+  getFrequency(vfo?: VFO): Promise<number>;
 
   /**
    * Get current radio mode
    * @returns Object containing mode and bandwidth information
    * @note Operates on the current VFO (RIG_VFO_CURR)
    */
-  getMode(): ModeInfo;
+  getMode(): Promise<ModeInfo>;
 
   /**
    * Get current signal strength
    * @returns Signal strength value
    * @note Operates on the current VFO (RIG_VFO_CURR)
    */
-  getStrength(): number;
+  getStrength(): Promise<number>;
 
   /**
    * Close connection to device
    * Does not destroy object, can re-establish connection by calling open()
    */
-  close(): void;
+  close(): Promise<number>;
 
   /**
    * Destroy connection to device
    * Should delete object reference after calling to enable garbage collection
    */
-  destroy(): void;
+  destroy(): Promise<number>;
 
   /**
    * Get connection information

package/lib/index.js

@@ -35,8 +35,16 @@ class HamLib {
    * Must be called before other operations
    * @throws {Error} Throws error when connection fails
    */
-  open() {
-    return this._nativeInstance.open();
+  async open() {
+    return new Promise((resolve, reject) => {
+      this._nativeInstance.open((err, result) => {
+        if (err) {
+          reject(new Error(err.message || 'Failed to open connection'));
+        } else {
+          resolve(result);
+        }
+      });
+    });
   }
 
   /**
@@ -44,8 +52,16 @@ class HamLib {
    * @param {string} vfo - VFO identifier ('VFO-A' or 'VFO-B')
    * @throws {Error} Throws error when device doesn't support or operation fails
    */
-  setVfo(vfo) {
-    return this._nativeInstance.setVfo(vfo);
+  async setVfo(vfo) {
+    return new Promise((resolve, reject) => {
+      this._nativeInstance.setVfo(vfo, (err, result) => {
+        if (err) {
+          reject(new Error(err.message || 'Failed to set VFO'));
+        } else {
+          resolve(result);
+        }
+      });
+    });
   }
 
   /**
@@ -53,11 +69,26 @@ class HamLib {
    * @param {number} frequency - Frequency in hertz
    * @param {string} [vfo] - Optional VFO ('VFO-A' or 'VFO-B')
    */
-  setFrequency(frequency, vfo) {
-    if (vfo) {
-      return this._nativeInstance.setFrequency(frequency, vfo);
-    }
-    return this._nativeInstance.setFrequency(frequency);
+  async setFrequency(frequency, vfo) {
+    return new Promise((resolve, reject) => {
+      if (vfo) {
+        this._nativeInstance.setFrequency(frequency, vfo, (err, result) => {
+          if (err) {
+            reject(new Error(err.message || 'Failed to set frequency'));
+          } else {
+            resolve(result);
+          }
+        });
+      } else {
+        this._nativeInstance.setFrequency(frequency, (err, result) => {
+          if (err) {
+            reject(new Error(err.message || 'Failed to set frequency'));
+          } else {
+            resolve(result);
+          }
+        });
+      }
+    });
   }
 
   /**
@@ -65,27 +96,58 @@ class HamLib {
    * @param {string} mode - Radio mode ('USB', 'LSB', 'FM', 'PKTFM', etc.)
    * @param {string} [bandwidth] - Optional bandwidth ('narrow', 'wide')
    */
-  setMode(mode, bandwidth) {
-    if (bandwidth) {
-      return this._nativeInstance.setMode(mode, bandwidth);
-    }
-    return this._nativeInstance.setMode(mode);
+  async setMode(mode, bandwidth) {
+    return new Promise((resolve, reject) => {
+      if (bandwidth) {
+        this._nativeInstance.setMode(mode, bandwidth, (err, result) => {
+          if (err) {
+            reject(new Error(err.message || 'Failed to set mode'));
+          } else {
+            resolve(result);
+          }
+        });
+      } else {
+        this._nativeInstance.setMode(mode, (err, result) => {
+          if (err) {
+            reject(new Error(err.message || 'Failed to set mode'));
+          } else {
+            resolve(result);
+          }
+        });
+      }
+    });
   }
 
   /**
    * Set PTT (Push-to-Talk) status
    * @param {boolean} state - true to enable PTT, false to disable
    */
-  setPtt(state) {
-    return this._nativeInstance.setPtt(state);
+  async setPtt(state) {
+    return new Promise((resolve, reject) => {
+      this._nativeInstance.setPtt(state, (err, result) => {
+        if (err) {
+          reject(new Error(err.message || 'Failed to set PTT'));
+        } else {
+          resolve(result);
+        }
+      });
+    });
   }
 
   /**
    * Get current VFO
    * @returns {string} Current VFO identifier
    */
-  getVfo() {
-    return this._nativeInstance.getVfo();
+  async getVfo() {
+    return new Promise((resolve, reject) => {
+      this._nativeInstance.getVfo((err, result) => {
+        if (err) {
+          reject(new Error(err.message || 'Failed to get VFO'));
+        } else {
+          resolve(result);
+        }
+      });
+    });
   }
 
   /**
@@ -93,43 +155,90 @@ class HamLib {
    * @param {string} [vfo] - Optional VFO ('VFO-A' or 'VFO-B')
    * @returns {number} Current frequency in hertz
    */
-  getFrequency(vfo) {
-    if (vfo) {
-      return this._nativeInstance.getFrequency(vfo);
-    }
-    return this._nativeInstance.getFrequency();
+  async getFrequency(vfo) {
+    return new Promise((resolve, reject) => {
+      if (vfo) {
+        this._nativeInstance.getFrequency(vfo, (err, result) => {
+          if (err) {
+            reject(new Error(err.message || 'Failed to get frequency'));
+          } else {
+            resolve(result);
+          }
+        });
+      } else {
+        this._nativeInstance.getFrequency((err, result) => {
+          if (err) {
+            reject(new Error(err.message || 'Failed to get frequency'));
+          } else {
+            resolve(result);
+          }
+        });
+      }
+    });
   }
 
   /**
    * Get current radio mode
    * @returns {Object} Object containing mode and bandwidth information
    */
-  getMode() {
-    return this._nativeInstance.getMode();
+  async getMode() {
+    return new Promise((resolve, reject) => {
+      this._nativeInstance.getMode((err, result) => {
+        if (err) {
+          reject(new Error(err.message || 'Failed to get mode'));
+        } else {
+          resolve(result);
+        }
+      });
+    });
   }
 
   /**
    * Get current signal strength
    * @returns {number} Signal strength value
    */
-  getStrength() {
-    return this._nativeInstance.getStrength();
+  async getStrength() {
+    return new Promise((resolve, reject) => {
+      this._nativeInstance.getStrength((err, result) => {
+        if (err) {
+          reject(new Error(err.message || 'Failed to get signal strength'));
+        } else {
+          resolve(result);
+        }
+      });
+    });
   }
 
   /**
    * Close connection to device
    * Connection can be re-established by calling open()
    */
-  close() {
-    return this._nativeInstance.close();
+  async close() {
+    return new Promise((resolve, reject) => {
+      this._nativeInstance.close((err, result) => {
+        if (err) {
+          reject(new Error(err.message || 'Failed to close connection'));
+        } else {
+          resolve(result);
+        }
+      });
+    });
   }
 
   /**
    * Destroy connection to device
    * Object reference should be deleted after calling this
    */
-  destroy() {
-    return this._nativeInstance.destroy();
+  async destroy() {
+    return new Promise((resolve, reject) => {
+      this._nativeInstance.destroy((err, result) => {
+        if (err) {
+          reject(new Error(err.message || 'Failed to destroy connection'));
+        } else {
+          resolve(result);
+        }
+      });
+    });
   }
 
   /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "hamlib",
-  "version": "0.1.5",
+  "version": "0.1.6",
   "description": "Node.js wrapper for hamlib radio control library",
   "main": "index.js",
   "module": "lib/index.mjs",