hamlib 0.1.2 → 0.1.4

package/Readme.md

@@ -1,253 +1,457 @@
 # node-hamlib
 
-A Node.js wrapper for [Hamlib](https://hamlib.github.io/) - control amateur radio transceivers from JavaScript/TypeScript.
+A comprehensive Node.js wrapper for [Hamlib](https://hamlib.github.io/) - control amateur radio transceivers from JavaScript/TypeScript.
 
 ## 🚀 Features
 
-- **Pre-built binaries**: No compilation needed for most platforms
-- **Multi-platform support**: Windows x64, Linux x64/ARM64, macOS ARM64
-- **CommonJS & ES Modules**: Works with both `require()` and `import`
-- **TypeScript support**: Full type definitions included
-- **Serial & Network**: Direct serial connection or network via rigctld
-- **Comprehensive API**: All essential radio control functions
+- **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
+- **Connection Types**: Serial ports, network (rigctld), and direct control
+- **TypeScript Support**: Full type definitions and IntelliSense
+- **Modern JavaScript**: CommonJS and ES Modules support
 
-## 📦 Installation
+## 📦 Quick Start
 
 ```bash
 npm install node-hamlib
 ```
 
-The package will automatically:
-1. Try to use pre-built binaries for your platform
-2. Fall back to compiling from source if needed
-3. Provide helpful error messages for missing dependencies
+```javascript
+const { HamLib } = require('node-hamlib');
 
-## 🔧 System Requirements
+// Find your radio model
+const rigs = HamLib.getSupportedRigs();
+console.log('Supported radios:', rigs.length);
 
-### For Pre-built Binaries
-- Node.js 12.0.0 or higher
-- Supported platforms: Windows x64, Linux x64/ARM64, macOS ARM64
+// Connect to radio
+const rig = new HamLib(1035, '/dev/ttyUSB0'); // FT-991A
+rig.open();
 
-### For Source Compilation
-- All of the above, plus:
-- **Linux**: `libhamlib-dev` package
-- **macOS**: `hamlib` via Homebrew
-- **Windows**: hamlib via vcpkg or manual installation
-- **Build tools**: `node-gyp` and platform-specific compilers
+// Basic control
+rig.setFrequency(144390000); // 144.39 MHz
+rig.setMode('FM');
+rig.setPtt(true);
 
-### Install System Dependencies
+// Get status
+console.log('Frequency:', rig.getFrequency());
+console.log('Mode:', rig.getMode());
+console.log('Signal:', rig.getStrength());
 
-```bash
-# Ubuntu/Debian
-sudo apt-get install libhamlib-dev libhamlib-utils
+rig.close();
+```
 
-# macOS
-brew install hamlib
+## 📡 Complete API Reference
 
-# Windows (using vcpkg)
-vcpkg install hamlib:x64-windows
+### 🔍 Radio Discovery
+
+#### `HamLib.getSupportedRigs()`
+Get all supported radio models
+```javascript
+const rigs = HamLib.getSupportedRigs();
+console.log(`Found ${rigs.length} supported radios`);
+
+// Find your radio
+const yaesu = rigs.filter(r => r.mfgName === 'Yaesu');
+const ft991a = rigs.find(r => r.modelName === 'FT-991A');
+console.log('FT-991A Model ID:', ft991a.rigModel);
 ```
 
-## 📋 Usage
+### 🔌 Connection Management
 
-### CommonJS (Node.js)
+#### `new HamLib(model, port)`
+Create radio instance
 ```javascript
-const { HamLib } = require('node-hamlib');
+// Serial connection
+const rig = new HamLib(1035, '/dev/ttyUSB0');        // Linux
+const rig = new HamLib(1035, '/dev/cu.usbserial-1420'); // macOS  
+const rig = new HamLib(1035, 'COM3');                // Windows
 
-// Create instance with radio model and port
-const rig = new HamLib(1035, '/dev/ttyUSB0');
+// Network connection
+const rig = new HamLib(1035, 'localhost:4532');      // rigctld
+```
 
-// Open connection
-rig.open();
+#### `open()` / `close()` / `destroy()`
+Connection control
+```javascript
+rig.open();              // Open connection
+rig.close();             // Close (can reopen)
+rig.destroy();           // Destroy permanently
+```
 
-// Control your radio
-rig.setFrequency(144390000); // 144.39 MHz
+#### `getConnectionInfo()`
+Get connection details
+```javascript
+const info = rig.getConnectionInfo();
+console.log('Connection type:', info.connectionType);
+console.log('Port:', info.port);
+console.log('Status:', info.status);
+```
+
+### 📻 Basic Radio Control
+
+#### Frequency Control
+```javascript
+// Set frequency (Hz)
+rig.setFrequency(144390000);
+rig.setFrequency(144390000, 'VFO-A');
+
+// Get frequency
+const freq = rig.getFrequency();
+const freqA = rig.getFrequency('VFO-A');
+```
+
+#### Mode Control
+```javascript
+// Set mode
 rig.setMode('FM');
-rig.setPtt(true);
+rig.setMode('USB', 'wide');
 
-// Get radio status
-console.log('Current frequency:', rig.getFrequency());
-console.log('Current mode:', rig.getMode());
-console.log('Signal strength:', rig.getStrength());
+// Get mode
+const mode = rig.getMode();
+console.log('Mode:', mode.mode);
+console.log('Bandwidth:', mode.bandwidth);
+```
 
-// Close connection
-rig.close();
+#### VFO Control
+```javascript
+// Set VFO
+rig.setVfo('VFO-A');
+rig.setVfo('VFO-B');
+
+// Get current VFO
+const vfo = rig.getVfo();
 ```
 
-### ES Modules (ESM)
+#### PTT Control
 ```javascript
-import { HamLib } from 'node-hamlib';
+rig.setPtt(true);   // Transmit
+rig.setPtt(false);  // Receive
+```
 
-const rig = new HamLib(1035, '/dev/ttyUSB0');
-// ... same API as above
+#### Signal Monitoring
+```javascript
+const strength = rig.getStrength();
+console.log('Signal strength:', strength);
 ```
 
-### TypeScript
-```typescript
-import { HamLib, ConnectionInfo, ModeInfo } from 'node-hamlib';
+### 💾 Memory Channel Management
 
-const rig = new HamLib(1035, '/dev/ttyUSB0');
-rig.open();
+#### `setMemoryChannel(channel, data)`
+Store memory channel
+```javascript
+rig.setMemoryChannel(1, {
+  frequency: 144390000,
+  mode: 'FM',
+  description: 'Local Repeater'
+});
+```
 
-const info: ConnectionInfo = rig.getConnectionInfo();
-const mode: ModeInfo = rig.getMode();
+#### `getMemoryChannel(channel, readOnly)`
+Retrieve memory channel
+```javascript
+const channel = rig.getMemoryChannel(1);
+console.log('Channel 1:', channel);
 ```
 
-## 🔌 Connection Types
+#### `selectMemoryChannel(channel)`
+Select memory channel
+```javascript
+rig.selectMemoryChannel(1);
+```
 
-### Serial Connection
+### 🎛️ RIT/XIT Control
+
+#### RIT (Receiver Incremental Tuning)
 ```javascript
-// Linux/Raspberry Pi
-const rig = new HamLib(1035, '/dev/ttyUSB0');
+rig.setRit(100);        // +100 Hz offset
+const rit = rig.getRit();
+```
 
-// macOS
-const rig = new HamLib(1035, '/dev/cu.usbserial-1420');
+#### XIT (Transmitter Incremental Tuning)
+```javascript
+rig.setXit(-50);        // -50 Hz offset
+const xit = rig.getXit();
+```
 
-// Windows
-const rig = new HamLib(1035, 'COM3');
+#### Clear RIT/XIT
+```javascript
+rig.clearRitXit();      // Clear both offsets
 ```
 
-### Network Connection (rigctld)
+### 🔍 Scanning Operations
+
+#### `startScan(type, channel)`
+Start scanning
 ```javascript
-// Connect to rigctld daemon
-const rig = new HamLib(1035, 'localhost:4532');
-const rig = new HamLib(1035, '192.168.1.100:4532');
+rig.startScan('VFO');     // VFO scan
+rig.startScan('MEM');     // Memory scan
+rig.startScan('PROG');    // Program scan
 ```
 
-Start rigctld daemon:
-```bash
-# Basic usage
-rigctld -m 1035 -r /dev/ttyUSB0
+#### `stopScan()`
+Stop scanning
+```javascript
+rig.stopScan();
+```
+
+### 🎚️ Level Controls
+
+#### `getSupportedLevels()`
+Get available level controls
+```javascript
+const levels = rig.getSupportedLevels();
+console.log('Available levels:', levels);
+// ['AF', 'RF', 'SQL', 'RFPOWER', 'MICGAIN', ...]
+```
+
+#### `setLevel(type, value)` / `getLevel(type)`
+Control audio and RF levels
+```javascript
+rig.setLevel('AF', 0.7);          // Audio gain 70%
+rig.setLevel('RF', 0.5);          // RF gain 50%
+rig.setLevel('SQL', 0.3);         // Squelch 30%
+rig.setLevel('RFPOWER', 0.5);     // TX power 50%
+rig.setLevel('MICGAIN', 0.8);     // Mic gain 80%
+
+// Get levels
+const audioGain = rig.getLevel('AF');
+const rfGain = rig.getLevel('RF');
+```
 
-# With custom port
-rigctld -m 1035 -r /dev/ttyUSB0 -t 5001
+### 🔧 Function Controls
 
-# With remote access
-rigctld -m 1035 -r /dev/ttyUSB0 -T 0.0.0.0
+#### `getSupportedFunctions()`
+Get available function controls
+```javascript
+const functions = rig.getSupportedFunctions();
+console.log('Available functions:', functions);
+// ['NB', 'COMP', 'VOX', 'TONE', 'TSQL', 'TUNER', ...]
 ```
 
-## 🎛️ API Reference
+#### `setFunction(type, enable)` / `getFunction(type)`
+Control radio functions
+```javascript
+rig.setFunction('NB', true);      // Enable noise blanker
+rig.setFunction('COMP', true);    // Enable compressor
+rig.setFunction('VOX', true);     // Enable VOX
+rig.setFunction('TUNER', true);   // Enable auto tuner
+
+// Get function status
+const nbEnabled = rig.getFunction('NB');
+const compEnabled = rig.getFunction('COMP');
+```
 
-### Constructor
-- `new HamLib(model, port?)`: Create a new instance
-  - `model`: Radio model number (find yours with `rigctl -l`)
-  - `port`: Optional serial port or network address
+### 📡 Split Operations
 
-### Connection Methods
-- `open()`: Open connection to radio
-- `close()`: Close connection (can reopen)
-- `destroy()`: Destroy connection permanently
+#### Split Frequency
+```javascript
+rig.setSplitFreq(144340000);      // TX frequency
+const txFreq = rig.getSplitFreq();
+```
 
-### Control Methods
-- `setVfo(vfo)`: Set VFO ('VFO-A' or 'VFO-B')
-- `setFrequency(freq, vfo?)`: Set frequency in Hz
-- `setMode(mode, bandwidth?)`: Set mode ('USB', 'LSB', 'FM', etc.)
-- `setPtt(state)`: Set PTT on/off
+#### Split Mode
+```javascript
+rig.setSplitMode('FM', 'wide');   // TX mode
+const txMode = rig.getSplitMode();
+```
 
-### Query Methods
-- `getVfo()`: Get current VFO
-- `getFrequency(vfo?)`: Get frequency in Hz
-- `getMode()`: Get current mode and bandwidth
-- `getStrength()`: Get signal strength
-- `getConnectionInfo()`: Get connection details
+#### Split Control
+```javascript
+rig.setSplit(true, 'VFO-B');      // Enable split
+const splitStatus = rig.getSplit();
+```
 
-## 🏗️ Development
+### 📻 VFO Operations
 
-### Building from Source
-```bash
-# Install dependencies
-npm install
+#### `vfoOperation(operation)`
+VFO operations
+```javascript
+rig.vfoOperation('CPY');      // Copy VFO A to B
+rig.vfoOperation('XCHG');     // Exchange VFO A and B
+rig.vfoOperation('UP');       // Frequency up
+rig.vfoOperation('DOWN');     // Frequency down
+rig.vfoOperation('TOGGLE');   // Toggle VFO A/B
+```
 
-# Build native module
-npm run build
+### 📶 Antenna Selection
 
-# Run tests
-npm test
+#### `setAntenna(antenna)` / `getAntenna()`
+Antenna control
+```javascript
+rig.setAntenna(1);            // Select antenna 1
+rig.setAntenna(2);            // Select antenna 2
+const antenna = rig.getAntenna();
 ```
 
-### Testing the Module
-```bash
-# Test module loading
-node test/test_loader.js
+## 🎯 Complete Example
 
-# Test basic functionality
-node test/mod.js
+```javascript
+const { HamLib } = require('node-hamlib');
 
-# Test network connection
-node test/test_network.js
+async function radioControl() {
+  // Find radios
+  const rigs = HamLib.getSupportedRigs();
+  const ft991a = rigs.find(r => r.modelName === 'FT-991A');
+  
+  if (!ft991a) {
+    console.log('FT-991A not found');
+    return;
+  }
+  
+  // Connect
+  const rig = new HamLib(ft991a.rigModel, '/dev/ttyUSB0');
+  
+  try {
+    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);
+    
+    // Store memory channel
+    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}`);
+    }, 1000);
+    
+  } catch (error) {
+    console.error('Error:', error.message);
+  } finally {
+    rig.close();
+  }
+}
+
+radioControl();
 ```
 
-## 📂 Project Structure
+## 📋 Supported Radios
+
+This library supports **303+ radio models** from major manufacturers:
+
+| Manufacturer | Models | Popular Radios |
+|--------------|--------|----------------|
+| **Yaesu** | 46 | FT-991A, FT-891, FT-857D, FT-817ND |
+| **Icom** | 83 | IC-7300, IC-9700, IC-705, IC-7610 |
+| **Kenwood** | 35 | TS-2000, TS-590SG, TS-890S, TH-D74 |
+| **Elecraft** | 7 | K3, K4, KX3, KX2 |
+| **FlexRadio** | 10 | 6300, 6400, 6500, 6600, 6700 |
+| **Others** | 122 | AOR, JRC, Ten-Tec, Winradio, etc. |
+
+### Finding Your Radio
+```javascript
+const rigs = HamLib.getSupportedRigs();
 
+// Search by manufacturer
+const yaesu = rigs.filter(r => r.mfgName === 'Yaesu');
+
+// Search by model name
+const ft991a = rigs.find(r => r.modelName.includes('FT-991A'));
+
+// List all radios
+rigs.forEach(rig => {
+  console.log(`${rig.rigModel}: ${rig.mfgName} ${rig.modelName}`);
+});
 ```
-node-hamlib/
-├── lib/                    # JavaScript wrapper code
-│   ├── index.js           # Main CommonJS entry
-│   ├── index.mjs          # ES Module entry
-│   └── binary-loader.js   # Binary loading logic
-├── src/                   # C++ source code
-├── prebuilds/             # Pre-built binaries
-├── scripts/               # Build and install scripts
-├── test/                  # Test files
-├── index.js               # Package entry point
-├── index.d.ts             # TypeScript definitions
-└── binding.gyp            # Build configuration
+
+## 🛠️ Installation & Setup
+
+### System Requirements
+- Node.js 12.0.0 or higher
+- Supported platforms: Windows x64, Linux x64/ARM64, macOS ARM64
+
+### Install Dependencies (if building from source)
+```bash
+# Ubuntu/Debian
+sudo apt-get install libhamlib-dev
+
+# macOS
+brew install hamlib
+
+# Windows
+vcpkg install hamlib:x64-windows
 ```
 
-## 🤝 Contributing
+### Building from Source
+```bash
+npm install
+npm run build
+```
+
+### Testing
+```bash
+npm test
+```
 
-1. Fork the repository
-2. Create a feature branch
-3. Make your changes
-4. Test thoroughly
-5. Submit a pull request
+## 🔧 Connection Types
 
-## 📋 Supported Platforms
+### Serial Connection
+```javascript
+// Linux
+const rig = new HamLib(1035, '/dev/ttyUSB0');
 
-| Platform | Architecture | Status |
-|----------|-------------|---------|
-| Linux    | x64         | ✅ Pre-built (native) |
-| Linux    | ARM64       | ✅ Pre-built (native) |
-| macOS    | ARM64       | ✅ Pre-built (native) |
-| Windows  | x64         | ✅ Pre-built (native) |
+// macOS
+const rig = new HamLib(1035, '/dev/cu.usbserial-1420');
 
-## 🐛 Troubleshooting
+// Windows
+const rig = new HamLib(1035, 'COM3');
+```
 
-### Binary Loading Issues
-If you see "Failed to load hamlib native module":
+### Network Connection (rigctld)
+```javascript
+const rig = new HamLib(1035, 'localhost:4532');
+```
 
-1. **Check platform support**: Ensure your platform is supported
-2. **Install system dependencies**: Follow the installation guide above
-3. **Try building from source**: `npm run build`
-4. **Check permissions**: Ensure you have access to the serial port
+Start rigctld:
+```bash
+rigctld -m 1035 -r /dev/ttyUSB0 -t 4532
+```
+
+## 🐛 Troubleshooting
 
-### Serial Port Issues
+### Permission Issues (Linux)
 ```bash
-# Linux: Add user to dialout group
 sudo usermod -a -G dialout $USER
+# Log out and back in
+```
 
-# Check available ports
+### Finding Serial Ports
+```bash
+# Linux
 ls /dev/tty*
 
-# Test with rigctl
-rigctl -m 1035 -r /dev/ttyUSB0 f
+# macOS
+ls /dev/cu.*
+
+# Windows
+# Use Device Manager
 ```
 
-### Network Connection Issues
+### Testing Connection
 ```bash
-# Test rigctld connection
-telnet localhost 4532
-
-# In telnet session:
-f  # get frequency
-q  # quit
+# Test with rigctl
+rigctl -m 1035 -r /dev/ttyUSB0 f
 ```
 
 ## 📄 License
 
-This project is licensed under the LGPL license - see the [COPYING](COPYING) file for details.
+LGPL - see [COPYING](COPYING) file for details.
 
-## 🔗 Related Projects
+## 🔗 Links
 
-- [Hamlib](https://hamlib.github.io/) - The underlying radio control library
-- [rigctl](https://github.com/Hamlib/Hamlib) - Command-line radio control utility
+- [Hamlib Project](https://hamlib.github.io/)
+- [Supported Radios](https://github.com/Hamlib/Hamlib/wiki/Supported-Radios)
+- [rigctl Documentation](https://hamlib.github.io/manpages/rigctl.html)