@trippnology/lib-js8call v1.0.3

lib-js8call

A library to help you interface your NodeJS app with JS8Call (tested with JS8Call v2.2.0).

What can I use this for?

Integrate JS8Call into your existing app, or come up with something entirely new! Here are a couple of apps that use this library:

• js8-cli - Pipe text from anywhere into JS8Call via the command line.
• JS8Assistant - Companion app that adds some nifty features to make your JS8 sessions more fun and useful.

How about an LED "ON AIR" light to show when you are transmitting? A Rasperry Pi and the Johnny Five library are an easy way to hook up all sorts of hardware. The only limit is your imagination! If you make something cool, create an issue with the details, and I'll add you to the list.

Installation

npm install @trippnology/lib-js8call

Usage

const js8 = require('@trippnology/lib-js8call')();
// Note the extra () at the end

You can now listen to events and act on them as you wish. It's a good idea to wait for a tcp.connected event before you try to interact with JS8Call:

js8.on('tcp.connected', (connection) => {
	// At this point, we have setup the connection
	console.log(
		'Server listening %s:%s Mode: %s',
		connection.address,
		connection.port,
		connection.mode
	);
	// You can now safely do your thing!
	MyApp.init();
});

If you don't want to auto connect, disable TCP and connect when you're ready:

const js8 = require('@trippnology/lib-js8call')({ tcp: { enabled: false } });
// Later, when your app is ready...
js8.tcp.connect().then((connection) => {
	console.log(connection);
});

You can either listen to the "firehose" packet event, emitted on every message we get from JS8Call:

js8.on('packet', (packet) => {
	// Do your custom stuff
	processPacket(packet);
});

... or individual events you are interested in:

js8.on('rig.ptt', (packet) => {
	console.log('[Rig] PTT is %s', packet.value);
});

You can find runnable examples of both approaches in demo/manual-processing.js and demo/individual-events.js respectively.

Don't forget to handle errors:

js8.on('error', (err) => {
	console.log('Something went wrong:');
	console.error(err);
});

Events

Individual event names mirror the JS8Call JSON API, with a few additions:

Please note that while JS8Call uses FULL CAPS for message types, event names are in all lower case.

Options

You can pass in any options you wish to set manually when you require the module. Sensible defaults will be provided for anything you omit.

const js8 = require('@trippnology/lib-js8call')({
	debug: true,
	tcp: { host: '192.168.1.123', port: 12345 },
});

Available options

Features

Sending an API request to JS8Call

This is a low level feature that allows you to construct the request to your own requirements.

// You can send your own JSON string
js8.send(
	'{ "type": "INBOX.STORE_MESSAGE", "params": { "CALLSIGN": "M7GMT", "TEXT": "Testing JSON API" } }'
);
// Or just send an object and it will be converted for you
js8.send({
	type: 'INBOX.STORE_MESSAGE',
	params: { CALLSIGN: 'M7GMT', TEXT: 'Testing JSON API' },
});

Shortcuts

As well as being able to construct your own API messages, some convenience methods and properties have been provided.

Help

Inbox

Mode

Rig

RX

Station

TCP

TX

Utils

Promises

Most functions return a promise, so you can do stuff once it resolves or rejects, if you need to:

js8.tx
	.sendMessage('Your custom text')
	.then(() => {
		console.log('TX finished');
	})
	.catch((err) => {
		console.log('Something went wrong:');
		console.error(err);
	});

Considerations

You will get at error if both TCP and UDP interfaces are enabled at the same time. While this does technically work, it will likely lead to duplicate traffic and headaches for you! TCP only is preferred.

Detecting when JS8Call is TXing is currently unreliable. We currently listen for RIG.PTT messages and cache the value, but a RIG.PTT with a value of offdoesn't mean that the send buffer is empty. As a workaround, we manually check the buffer with js8.tx.getText() when we receive a rig.ptt.off, and if the buffer is empty, we set rig.safe_to_tx to true.

js8.tx.sendMessage() will check the value of rig.safe_to_tx before sending a message:

js8.tx
	.sendMessage('Hello, world!')
	// If it's safe to TX, message is sent and promise resolves
	.then((message) => {
		console.log('Message sent: %s', message);
	})
	// If the rig is busy, the promise rejects
	.catch((err) => {
		console.log(err); // Prints: 'Rig busy'
	});

You can also listen to the rig.safe_to_tx event to monitor this value in your app:

js8.on('rig.safe_to_tx', (safety) => {
	console.log('Is it safe to TX? %s', safety ? 'yes' : 'no');
});

Hopefully, in the future, there will be additional API methods that allow us to check if it is safe to TX before trying to do so. Maybe JS8Call could send a TX.START message when it starts sending a message, and then a TX.END message once the whole transmission has finished or been aborted?

A future enhancement could be a message queue, so users could call js8.tx.sendMessage(), and the message would be sent once the rig becomes available.

Message types

The JS8Call API documentation is incomplete, so we are implementing API features as they are understood. API handling starts here in the source code.

For message types discovered so far, see JS8Call JSON API or console.log(js8.help.valid_message_types) from within your app.

Contributing

1. Fork it!
2. Create your feature branch: git checkout -b my-new-feature develop
3. Commit your changes: git commit -am 'Add some feature'
4. Push to the branch: git push origin my-new-feature
5. Submit a pull request :D

History

The bulk of this project was written over the Christmas break 2020. Future additions and changes will be noted here.

Credits

Copyright (c) 2021 Rikki Tripp.

A huge thanks to Rick VA1UAV for his feedback, feature suggestions, testing, and bug reports.

License

See LICENSE