api

Classes

Device

The base class for all devices, holds some information about the device and provides basic functionality

Transceiver

The base transceiver class. Polls for VFO frequencies by default. Subclasses need to implement VFO get/set commands as that is what defines a transceiver.

Driver

A driver connects a device to a real physical device. This is the base class for all drivers.

WebUSBDriver

Drivers for the WebUSB API supported by chromium based browsers

CP210xWebUSBDriver

A rudimentary WebUSB based driver for CP210x devices by Silicon Labs used e.g. in some Yaesu transceivers.

WebSerialDriver

A WebSerial based driver for Chromium browsers.

DummyDriver

A dummy driver that never reads any data and that doesn't write anything.

LogDriver

An internal driver that wraps another driver and decorates the write function and data observable to capture logs.

SerialPortDriver

A driver for the Node SerialPort library.

WebSocketDriver

A driver that receives data from websockets and writes to websockets as well.

Members

DeviceType

The different device types implemented in ham-js, currently only Transceiver is really in use.

AGCAttack

A value for the AGC attack time.

AntennaTunerState

The state of the antenna tuner, can be on/off and tuning.

Direction

A generic direction enum, used e.g. for navigating device menus via commands.

TransceiverEventType

The different types of transceiver events

TransceiverVendor

The different vendors of transceivers

VFOType

The different VFO types of transceivers

DriverType

The different driver types. Every driver class uses its own type. It is used for introspection and validation of supported drivers on devices at runtime.

Constants

Bands

The amateur radio bands supported by devices.

CTCSSFrequencies

All available CTCSS frequencies.

Functions

command(schemaShape) ⇒ function

Declare a method on a Device as a command: handles logging, input validation and introspection.

device(schemaShape) ⇒ object

This decorator is useful for devices which receive a second (object) parameter when constructed (e.g. ICOM devices need a controller and device address).

supportedDrivers(supportedDrivers) ⇒ object

This decorator allows to define the drivers this device supports. For introspection reasons we use an enum here. If not used the device supports all available drivers. Hint: You can use the convenience arrays of drivers, such as DeviceAgnosticDriverTypes.

delimiterParser(source, delimiter) ⇒ Observable

A utility that groups emissions of a source observable which are delimited by a certain delimiter.

fromLittleEndianBCD(input) ⇒ number

Convert an input in little endian BCD to number

getDigit(input, n) ⇒ number

Get the n-th digit of a (integer) number

getNumberOfDigits(input) ⇒ number

Get the number of digits of an integer number

padBytesEnd(input, length) ⇒ Uint8Array

Pad an input with zero bytes until it reaches a certain length

parseResponse(input, parser, formatter, distinctKey) ⇒ Observable

Parses an input observable into some kind of value, formats it iff it's not null/undefined, optionally only emits distinct elements and sets a timestamp on its emissions. This is mostly used for device events, e.g. VFO frequency changes coming from a transceiver "event bus" which potentially contains different events.

poll(observableFactory, distinctKey, interval) ⇒ Observable

Polls an observable factory (usually a function returning a promise) every n ms and emits values including a timestamp Note: The observable returned by this utility wait for calls to the factory to return. It is not guaranteed to return a value every n ms.

toLittleEndianBCD(input) ⇒ Uint8Array

Converts an input number to BCD in little endian byte order.

invertMap(input) ⇒ Map

A type safe utility to invert a JavaScript Map.

oneOf(ary) ⇒ z.Schema

a zod utility to validate inclusion of a value in an array

Device

The base class for all devices, holds some information about the device and provides basic functionality

Kind: global class

• Device
  • new Device(driver, parameter)
  • instance
    • .responseTimeout
    • .data
    • .events
    • .driverLog ⇒ Observable | undefined
    • .deviceLog ⇒ Observable | undefined
    • .isOpen ⇒ boolean
    • .open(config)
    • .close()
    • .getCommandSchema(command) ⇒ object
    • .getCommands() ⇒ Array.<string>
    • .readResponse(command, mapFn, responseTimeout) ⇒ Promise
  • static
    • .deviceSchema ⇒ object
    • .displayName ⇒ string
    • .supportedDrivers ⇒ Array.<DriverType>

new Device(driver, parameter)

The constructor for devices, which always (also in subclasses) takes this shape to allow for introspection and type-safety at runtime and buildtime.

Param	Type	Description
driver	Driver	The driver this device uses to communicate with a real physical device.
parameter	object	Optional additional parameters this device needs to function properly, such as target device addresses etc.. This is described using the @device decorater and can be introspected at runtime using deviceSchema.

device.responseTimeout

The response timeout used by readResponse

Kind: instance property of Device

device.data

The optional device data from which readResponse reads after writing a command to the driver.

Kind: instance property of Device

device.events

The optional events coming from a device (such as Yaesu TRX which have "Auto Information" which automatically sends data to the computer when anything changes).

Kind: instance property of Device

device.driverLog ⇒ Observable | undefined

When a device is opened with logDriver: true this returns the driver log.

Kind: instance property of Device
Returns: Observable | undefined -

the driver log which contains all messages written through the driver to a real physical device

device.deviceLog ⇒ Observable | undefined

When a device is opened with logDevice: true this returns the device log.

Kind: instance property of Device
Returns: Observable | undefined -

the device log which contains all calls to commands and their parameters and timestamps.

device.isOpen ⇒ boolean

Whether the device is open. By default this delegates to the driver.

Kind: instance property of Device
Returns: boolean -

Whether this device is open for calling commands.

device.open(config)

Open the device for executing commands, reading data and subscribing to events. By defaults this delegates to the driver and handles setting up logging.

Kind: instance method of Device

Param	Type	Description
config	object	the open configuration
config.logDriver	boolean	Whether the device should log driver calls
config.logDevice	boolean	Whether the device should log command calls
config.log	boolean	Whether the device should log both

device.close()

Close the device for executing commands, reading data and subscribing to events.

Kind: instance method of Device

device.getCommandSchema(command) ⇒ object

Get the command schema for a given command

Kind: instance method of Device
Returns: object -

The JSON schema describing the object parameter for that command

Param	Type	Description
command	string	the key of a command method

device.getCommands() ⇒ Array.<string>

Get all keys of implemented commands.

Kind: instance method of Device
Returns: Array.<string> -

An array containing all the keys of commands this device implements.

device.readResponse(command, mapFn, responseTimeout) ⇒ Promise

Convenience method to write a command and wait for a specific response from the real physical device. Handles timeouts as well. Needs the data property and DataType type parameter to be defined.

Kind: instance method of Device
Returns: Promise -

A promise that resolves with the first value the mapFn returns that is not null/undefined and rejects when a timeout happens.

Param	Type	Description
command	Uint8Array | string	the command to write
mapFn	function	A function which is called with responses after the command was written. Should return null or undefined for responses that are not of interest.
responseTimeout	number	An optional response timeout in ms, overrides the responseTimeout defined on the device.

Device.deviceSchema ⇒ object

The optional device schema of the device. This is used for devices which need additional parameters to be instantiated, such as the controller/device address in the case of ICOM devices.

Kind: static property of Device
Returns: object -

The JSON schema describing the second parameter to the constructor.

Device.displayName ⇒ string

Convenience method to get the display name of the device.

Kind: static property of Device
Returns: string -

the concatenated device vendor and device name

Device.supportedDrivers ⇒ Array.<DriverType>

Get the supported driver (types) of the device, default is all members of DriverType.

Kind: static property of Device
Returns: Array.<DriverType> -

An array of driver types this device supports (trying to instantiate a device with a non-supported driver results in an error).

Transceiver

The base transceiver class. Polls for VFO frequencies by default. Subclasses need to implement VFO get/set commands as that is what defines a transceiver.

Kind: global class

• Transceiver
  • .getVFOFrequency(parameter) ⇒ Promise.<number>
  • .setVFOFrequency(parameter)

transceiver.getVFOFrequency(parameter) ⇒ Promise.<number>

Get the frequency of the specified VFO.

Kind: instance method of Transceiver
Returns: Promise.<number> -

A promise resolving to the frequency of the specified VFO

Param	Type	Description
parameter	object	The vfo configuration which which to return the frequency
parameter.vfo	VFOType	The vfo for which to return the frequency

transceiver.setVFOFrequency(parameter)

Set the frequency of the specified VFO.

Kind: instance method of Transceiver

Param	Type	Description
parameter	object	The vfo configuration which which to set the frequency
parameter.vfo	VFOType	The vfo for which to set the frequency
parameter.frequency	number	The frequency to which to set the VFO

Driver

A driver connects a device to a real physical device. This is the base class for all drivers.

Kind: global class

• Driver
  • .textEncoder
  • .isOpen ⇒ boolean
  • .stringData(encoding, options) ⇒ Observable.<string>
  • .writeString(data) ⇒ void | Promise.<void>

driver.textEncoder

The default text encoder of the driver. Overwrite this for custom string encodings.

Kind: instance property of Driver

driver.isOpen ⇒ boolean

Returns whether the driver is open for reading and writing.

Kind: instance property of Driver
Returns: boolean -

Whether this driver is open

driver.stringData(encoding, options) ⇒ Observable.<string>

Get the data of the driver as utf-8 observable.

Kind: instance method of Driver
Returns: Observable.<string> -

An observable of strings based on the Uint8Array-based data property

Param	Type	Default	Description
encoding	string	"utf-8"	The encoding of the text decoder used on emissions of the data property
options	object		Options for the text decoder

driver.writeString(data) ⇒ void | Promise.<void>

Convenience method to write strings instead of bytes to the real physical device. This method uses the protected textEncoder property to encode the input string to bytes.

Kind: instance method of Driver
Returns: void | Promise.<void> -

A promise that resolves after the data was written, or void if the write method doesn't return a promise

Param	Type	Description
data	string	The data to write

WebUSBDriver

Drivers for the WebUSB API supported by chromium based browsers

Kind: global class

webUSBDriver.deviceFilters

The device filters supported by this driver. Can be handed directly to requestDevice in order to only show supported devices.

Kind: instance property of WebUSBDriver

CP210xWebUSBDriver

A rudimentary WebUSB based driver for CP210x devices by Silicon Labs used e.g. in some Yaesu transceivers.

Kind: global class

WebSerialDriver

A WebSerial based driver for Chromium browsers.

Kind: global class

new WebSerialDriver(serialPort, options)

The constructor for the web serial driver

Param	Type	Description
serialPort	object	a serial port returned by requestPort
options	object	Options used for opening the serial port (such as baudRate)

DummyDriver

A dummy driver that never reads any data and that doesn't write anything.

Kind: global class

LogDriver

An internal driver that wraps another driver and decorates the write function and data observable to capture logs.

Kind: global class

SerialPortDriver

A driver for the Node SerialPort library.

Kind: global class

new SerialPortDriver(serialPort, timeout)

The constructor for the node serial port driver. Make sure to hand in a serial port that is not opened yet and has autoOpen set to false.

Param	Type	Default	Description
serialPort	SerialPortStream		A not-yet-open serial port (make sure to set autoOpen to false.
timeout	number	1000	A timeout used for writing to the serial port

WebSocketDriver

A driver that receives data from websockets and writes to websockets as well.

Kind: global class

DeviceType

The different device types implemented in ham-js, currently only Transceiver is really in use.

Kind: global variable

AGCAttack

A value for the AGC attack time.

Kind: global variable

AntennaTunerState

The state of the antenna tuner, can be on/off and tuning.

Kind: global variable

Direction

A generic direction enum, used e.g. for navigating device menus via commands.

Kind: global variable

TransceiverEventType

The different types of transceiver events

Kind: global variable

TransceiverVendor

The different vendors of transceivers

Kind: global variable

VFOType

The different VFO types of transceivers

Kind: global variable

DriverType

The different driver types. Every driver class uses its own type. It is used for introspection and validation of supported drivers on devices at runtime.

Kind: global variable

Bands

The amateur radio bands supported by devices.

Kind: global constant

CTCSSFrequencies

All available CTCSS frequencies.

Kind: global constant

command(schemaShape) ⇒ function

Declare a method on a Device as a command: handles logging, input validation and introspection.

Kind: global function
Returns: function -

The decorated method

Param	Type	Description
schemaShape	object	An object describing a zod schema (not a schema itself, but what you pass to z.object(...))

device(schemaShape) ⇒ object

This decorator is useful for devices which receive a second (object) parameter when constructed (e.g. ICOM devices need a controller and device address).

Kind: global function
Returns: object -

The decorated class

Param	Type	Description
schemaShape	object	An object describing a zod schema (not a schema itself, but what you pass to z.object(...))

supportedDrivers(supportedDrivers) ⇒ object

This decorator allows to define the drivers this device supports. For introspection reasons we use an enum here. If not used the device supports all available drivers. Hint: You can use the convenience arrays of drivers, such as DeviceAgnosticDriverTypes.

Kind: global function
Returns: object -

the decorated class

Param	Type	Description
supportedDrivers	Array.<DriverType>	the supported drivers in form of the DriverType associated with them

delimiterParser(source, delimiter) ⇒ Observable

A utility that groups emissions of a source observable which are delimited by a certain delimiter.

Kind: global function
Returns: Observable -

A new observable which emits parsed emissions of the source observable

Param	Type	Description
source	Observable	The source observable
delimiter	string | number	The delimiter for which the parser looks

Example

const source = of("F", "A", "14", "350", "000;")
 const parsed = delimiterParser(source, ";")
 parsed.subscribe(console.log) // "FA14350000;"
 

fromLittleEndianBCD(input) ⇒ number

Convert an input in little endian BCD to number

Kind: global function
Returns: number -

The number described by the input data

Param	Type	Description
input	Uint8Array	data formatted in little endian BCD

getDigit(input, n) ⇒ number

Get the n-th digit of a (integer) number

Kind: global function
Returns: number -

the digit at index n of the input number

Param	Type	Description
input	number	the input number
n	number	the index of the digit to return

getNumberOfDigits(input) ⇒ number

Get the number of digits of an integer number

Kind: global function
Returns: number -

The number of digits of the input number

Param	Type	Description
input	number	The input number

padBytesEnd(input, length) ⇒ Uint8Array

Pad an input with zero bytes until it reaches a certain length

Kind: global function
Returns: Uint8Array -

the input data padded with zero bytes at the end (or the input data itself if it already had the appropriate length)

Param	Type	Description
input	Uint8Array	Input data
length	number	the length in bytes the output should be long

parseResponse(input, parser, formatter, distinctKey) ⇒ Observable

Parses an input observable into some kind of value, formats it iff it's not null/undefined, optionally only emits distinct elements and sets a timestamp on its emissions. This is mostly used for device events, e.g. VFO frequency changes coming from a transceiver "event bus" which potentially contains different events.

Kind: global function
Returns: Observable -

an observable which emits parsed and formatted values based on the params

Param	Type	Description
input	Observable	an input observable
parser	function	a function which takes an emission from the input observable and parses it into something the formatter understands or null/undefined which terminates processing of this event
formatter	function	a function which takes in what the parser returned and formats it to be something a consumer understands
distinctKey	string	an optional key of the object the formatter returned. If two consecutive emissions have the same key the returned observable will not emit again.

Example

return trxData
   .pipe(
     parseResponse(
       response$,
       this.parseTrxEvent, // e.g. reads bytes into an object describing the device state, containing frequency, mode, ...
       (trxEvent) => ({ frequency: trxEvent.frequency }),
       "frequency"
     )
   )

poll(observableFactory, distinctKey, interval) ⇒ Observable

Polls an observable factory (usually a function returning a promise) every n ms and emits values including a timestamp Note: The observable returned by this utility wait for calls to the factory to return. It is not guaranteed to return a value every n ms.

Kind: global function
Returns: Observable -

An observable that emits with every finished poll call to observable factory

Param	Type	Default	Description
observableFactory	function		a function to poll
distinctKey	string		a key which needs to change in order for the returned observable to emit
interval	number	500	the minimum amount of milliseconds for which to repeat the call to observableFactory

Example

const $freq = poll(async () => ({ frequency: await getFrequency() }), "frequency")
 $freq.subscribe(console.log)

toLittleEndianBCD(input) ⇒ Uint8Array

Converts an input number to BCD in little endian byte order.

Kind: global function
Returns: Uint8Array -

the BCD representation of the input number in little endian byte order

Param	Type	Description
input	number	The input number

invertMap(input) ⇒ Map

A type safe utility to invert a JavaScript Map.

Kind: global function
Returns: Map -

The inverted map (type-safe)

Param	Type	Description
input	Map	The input map to invert

oneOf(ary) ⇒ z.Schema

a zod utility to validate inclusion of a value in an array

Kind: global function
Returns: z.Schema -

A zod schema describing the validation

Param	Type	Description
ary	Array	The array in which the valud should be included.