@pgogas/wsjtx-js v0.0.1

@pgogas/wsjtx-js

A JavaScript library for parsing WSJT-X UDP messages. WSJT-X is a popular amateur radio software package for weak signal communication modes like FT8, FT4, JT65, and WSPR.

Features

• 🔍 Complete UDP Message Parsing - Supports all WSJT-X message types (Heartbeat, Status, Decode, Clear, Reply, QSO Logged, etc.)
• 📡 Event-Driven Architecture - Easy-to-use event emitter for real-time message handling
• 🎯 Big-Endian Format Support - Proper handling of WSJT-X's big-endian UDP format
• 🔧 QDataStream Compatible - Fully compatible with Qt's QDataStream binary format
• ✅ Type-Safe - Well-defined message classes with comprehensive JSDoc documentation
• 🧪 Thoroughly Tested - Comprehensive test suite with high code coverage

Installation

npm install @pgogas/wsjtx-js

Quick Start

Basic Usage

const { WsjtxListener } = require('@pgogas/wsjtx-js');

// Create a listener on the default WSJT-X UDP port
const listener = new WsjtxListener({ port: 2237 });

// Listen for decode messages (new stations decoded)
listener.on('decode', (message) => {
  console.log(`Decoded: ${message.message} (SNR: ${message.snr}dB)`);
});

// Listen for status updates
listener.on('status', (message) => {
  console.log(`Frequency: ${message.frequency}Hz, Mode: ${message.mode}`);
});

// Start listening
await listener.start();
console.log('Listening for WSJT-X messages...');

Manual Message Parsing

const { WsjtxParser } = require('@pgogas/wsjtx-js');

// Parse a UDP datagram buffer
const message = WsjtxParser.parse(udpBuffer);
console.log(`Message type: ${message.constructor.name}`);
console.log(`From station: ${message.id}`);

Supported Message Types

Event-Driven Listener

The WsjtxListener class extends Node.js EventEmitter and provides these events:

Message Events

• message - Any message received (with message object and remote info)
• heartbeat - Heartbeat messages
• status - Status updates
• decode - New decodes
• qsologged - Logged QSOs
• wspr - WSPR decodes
• clear - Clear window commands
• close - WSJT-X closing

System Events

• listening - Listener started successfully
• stopped - Listener stopped
• error - Network or system error
• parseError - Failed to parse a message

Example: Complete Event Handling

const { WsjtxListener } = require('@pgogas/wsjtx-js');

const listener = new WsjtxListener({ port: 2237 });

// Handle decode messages
listener.on('decode', (message, rinfo) => {
  console.log(`🔍 New decode from ${message.id}:`);
  console.log(`   Message: "${message.message}"`);
  console.log(`   SNR: ${message.snr}dB`);
  console.log(`   Mode: ${message.mode}`);
  console.log(`   Time: ${message.time}s`);
});

// Handle status updates
listener.on('status', (message) => {
  console.log(`📊 Status update from ${message.id}:`);
  console.log(`   Frequency: ${message.frequency}Hz`);
  console.log(`   Mode: ${message.mode}`);
  console.log(`   Transmitting: ${message.transmitting}`);
});

// Handle QSO logging
listener.on('qsologged', (message) => {
  console.log(`📝 QSO logged with ${message.dxCall}`);
  console.log(`   Grid: ${message.dxGrid}`);
  console.log(`   Mode: ${message.mode}`);
  console.log(`   Report: ${message.reportSent}/${message.reportReceived}`);
});

// Handle errors gracefully
listener.on('error', (error) => {
  console.error('Listener error:', error.message);
});

listener.on('parseError', (error, buffer, rinfo) => {
  console.error(`Parse error from ${rinfo.address}: ${error.message}`);
});

// Start listening
await listener.start();

WSJT-X Configuration

To use this library, configure WSJT-X to send UDP messages:

1. In WSJT-X, go to File → Settings
2. Click the Reporting tab
3. Check Enable PSK Reporter Spotting
4. Set UDP Server: 127.0.0.1 (or your server IP)
5. Set UDP Server Port: 2237 (or your chosen port)
6. Check Accept UDP requests

Message Format Details

All WSJT-X UDP messages follow this format:

Header (12 bytes):
- Magic Number: 0xadbccbda (4 bytes)
- Schema Version: uint32 (4 bytes) 
- Message Type: uint32 (4 bytes)

Payload:
- Station ID: QString
- Message-specific fields...

The library handles the big-endian format and QDataStream encoding automatically.

API Reference

WsjtxListener

Constructor

new WsjtxListener(options)

Options:

• port (number): UDP port to listen on (default: 2237)
• address (string): IP address to bind to (default: '127.0.0.1')

Methods

• start() → Promise - Start listening for messages
• stop() → Promise - Stop listening
• isListening() → boolean - Check if currently listening
• address() → object - Get current bind address/port

WsjtxParser

Static Methods

• parse(buffer) → Message - Parse a UDP datagram buffer

Message Classes

All message classes extend BaseMessage and include:

• id (string): Station identifier
• schemaVersion (number): Message schema version
• Message-specific properties...

Examples

See the /examples directory for complete working examples:

• listener.js - Comprehensive message listener with all event types
• Run with: npm start or node examples/listener.js

Testing

# Run tests
npm test

# Run tests with coverage
npm run test:coverage

# Run linting
npm run lint

Contributing

1. Fork the repository
2. Create a feature branch: git checkout -b feature-name
3. Make your changes and add tests
4. Run the test suite: npm test
5. Submit a pull request

Protocol References

• WSJT-X Source Code
• Qt QDataStream Documentation

License

MIT License - see LICENSE file for details

Publishing (For Maintainers)

This package uses semantic versioning and includes a publishing script for easy releases:

# Check status and run tests
npm run publish:check

# Publish with version bump
npm run publish:patch  # Bug fixes (1.0.0 → 1.0.1)
npm run publish:minor  # New features (1.0.0 → 1.1.0)
npm run publish:major  # Breaking changes (1.0.0 → 2.0.0)

Requirements:

• Must be logged into npm: npm login
• All tests must pass
• Working directory should be clean (committed changes)

Related Projects

• WsjtxUdpLib - .NET implementation that inspired this library
• WSJT-X - The official WSJT-X software

Amateur Radio

This library is designed for amateur radio operators. A valid amateur radio license is required to operate WSJT-X and transmit on amateur frequencies.

73!