This guide is intended for developers who want to integrate trx-control with their own software, e.g. logging or contesting software.

The Client/Server Protocol

General Principles

A client accesses the trx-control daemon trxd(8) over TCP/IP using either a plain IP socket or a WebSocket. Both IPv4 and IPv6 are supported.

All data exchange is done using JSON formatted data packages. If a plain socket is used, the so-called NDJSON (Newline Delimited JSON) format is to be used, i.e. the JSON data is sent as one line, delimited by a newline character.

All requests will be answered by a response.

Terms and Definitions

Usually the metric system is being used in trx-control.

Frequencies

Frequencies are expressed as integers in hertz. So 14.285 MHz must be expressed as 14285000.

Operating modes

Operating modes are indicated by shortcuts that speak for themselves. When querying the operating mode from a transceiver, or during automatic status updates, drivers may optionally return a field displayName that shows the name of the operating mode as used by the respective manufacturor.

The modes designations and meanings need rework.
Shortcut Operating mode

am

Amplitude modulation

c4fm

C4FM digital modulation

cw

Morse code telegraphy

dmr

Digital mode radio

dv

D-Star digital voice

dr

D-Star digital repeater

fm

Frequency modulation

lsb

Lower side band SSB

m17

M17 digital modulation

nfm

Narrow band frequency modulation

r-cw

Receive only telegraphy

usb

Upper side band SSB

wfm

Wide band frequency modulation

rtty

RTTY

cw-r

CW-R

rtty-r

RTTY-R

cw-u

CW-U

rtty-l

RTTY-L

cw-l

CW-L

rtty-u

RTTY-U

data-fm

Data FM

fm-n

FM-N

data-u

Data U

am-n

AM-N

psk

PSK

data-fm-n

Data FM-N

cw-r

CW-R

dig

DIG

pkt

PKT

fmn

FMN

VFOs / Bands

Most transceivers can operate in more than on band simultaneously. Some vendors call these independent VFOs "Bands", some refer to them as "VFO".

In trx-control they are named vfo-n starting at vfo-1 and counting up. So most transceivers will have vfo-1 and vfo-2.

Shortcut Meaning

vfo-1

First VFO

vfo-2

Second VFO

…​

…​

vfo-n

n-th VFO

VFO Operating modes

Shortcut VFO operating modes

vfo

VFO mode

memory

Memory mode

call

Call mode

dv

DV (digital voice) mode

Altitudes

Altitudes are expressed as integers in meters above sea level.

Position data

Position data is expressed as degrees with sign.

Speed

Speed is expressed in meters per second (m/s).

Request format

Every request must contain at least a request field. Depending on the request type, one or more mandatory or optional fields must be present.

The response to each request will at least contain a status and a response field. The status indicates success (Ok) or failure (Error). The response field is usually set to the value of the request field.

Usually parameters are sent back in a response.

Request is empty or contains invalid JSON data:

{
  "status": "Error",
  "reason": "Invalid input data or no input data at all"
}

Request does not contain a request field:

{
  "status": "Error",
  "reason": "No request"
}

Client sent an unknown request:

{
  "status": "Error",
  "reason": "Unknown request",
  "request": "<whatever the client sent as request>"
}

Destinations

As trx-control supports an unlimited number of devices, extensions etc. the concept of destinations is used. Each transceiver, device, or, extension represents a named destination. With every request you can send the optional "to" field, indicating the destination the request should be dispatched to.

A destination can be set by sending JSON data containing only the to field, without a request. Once set, the destination will be used for all subsequent requests until a new destination is specified. If no destination has ever been specified, the request will be dispatched to the default transceiver.

The list of available destinations can be queried with the list-destination request.

Destination types
Name Destination Type

transceiver

Transceiver

sdr

SDR Radio

rotor

Antenna rotor

relay

Relays

gpio

GPIO Pins

internal

Internal, e.g. NMEA decoder

extension

Lua extension

General Requests

These requests are processed by trxd(8) and are not routed to a device or extension.

Request Purpose  Parameters Response

list-destination

List available destinations

type
The type of destinations to return.

An array containing name and type fields.

If the type is transceiver and this is the default transceiver, then the array will contain the boolean field default, set to true. No default field will be sent otherwise.

to

Select a destination

version

Query the version number of the running trxd(8) daemon.

An array with the following fields:
version
The version number in the form <major>.<minor>.<patch>.
release
The release number of this version.

Controlling Transceivers

Parameters in italic are optional.

Request Purpose  Parameters Response

get-info

Request information about a transceiver

name
The name of the transceiver.

frequencyRange
An array containing min and max numbers indicating the minimum and maximum operating frequency.

operatingModes
An array of strings containing the operating modes.

audio
An array containing the following optional fields:

output
The audio output channel

input
The audio input channel

power-on

Turn the transceiver on.

power-off

Turn the transceiver off.

set-frequency

Set the operating frequency

frequency
The operating frequency

vfo
For which VFO to set the frequency (vfo-1, vfo-2, etc.).

get-frequency

Get the operating frequency

vfo
For which VFO to get the frequency (vfo-1, vfo-2, etc.).

frequency
The operating frequency

set-mode

Set the operating mode

mode
The operating mode

band
The band, either main or sub

get-mode

Get the operating mode

mode
The operating mode

band
The band, either main or sub

set-ptt

Set the PTT mode

ptt
The PTT mode, either on or off

get-ptt

Get the PTT mode

ptt
The PTT mode, either on or off

lock-trx

Lock the transceiver

unlock-trx

Unlock the transceiver

start-status-updates

Start sending automatic status updates

Upon status changes, a JSON package with the following fields is sent to the client:

request
Contains the string status-update

from
The name of the destination from which the status update originated.

status
An array with the following fields:

frequency
The operating frequency

mode
The operating mode

stop-status-updates

Stop sending automatic status updates
Replies or status updates from a transceiver controller will always contain the field from which contains the name of the destination.

GPIO

GPS/NMEA

If configured, the nmea destination can be used to query the current fix data, i.e. date, time, position, locator etc.

Request Purpose Parameters Response

get-fix

Get the last fix received from the connected device.

fix
An array with the fields described in the following table.

get-fix response data returned in the fix array of the response:

Name Value

date

The current date in the format DD.MM.YYYY.

time

The current UTC time in the format HH:MM:SS

longitude

The longitude in degrees.

latitude

The latitude in degrees.

altitude

The altitude in m above sea level.

variation

The magnetic variation in degrees.

course

The course in degrees.

speed

The speed in m/s.

status

0 = not receiving data , 1 = receiving data.

mode

The current receiver mode, A=autonomous, D = DGPS, E = DR, I = initializing.

locator

The grid square (Maidenhead) locator.

Extensions

Common commands

All extensions understand the listen and unlisten command to listen to status updates (or stop listening for them). What a status update actually means is of course depending on the extension.

Request Purpose Parameters Response

listen

Start listening for status updates

unlisten

Stop listening for status updates

config

The config extension can be used to access the trxd(8) configuration. Currently it can only be used for read access.

Request Purpose Parameters Response

getConfiguration

Get the current configuration

An array containing all configuration elements
Be aware that the configuration might contain sensitive information such as password or database connection strings!

ping

The ping extension serves the sole purpose to check the liveliness of trx-control.

Request Purpose Parameters Response

ping

Check connection

response
The string pong

trxd
An array containing:

version
The trxd version

The ping extension does not send status updates, even if you sent a listen request.

memory

The memory extension manages memories and memory groups that are stored in a PostgreSQL database.

Example configuration
extensions:
  memory:
    script: memory
    configuration:
      connStr: dbname=trx-control
      datestyle: German
Request Purpose Parameters Response

getTopLevel

Get the toplevel list of memory groups and memory entries

An array of entries containing the following fields:

entry
Either group or memory

id
The id (UUID) of the memory or memory group

name
Name of the entry

supplement
Any supplement to the name

descr
A longer description of the entry

The following entries are only present when entry is set to memory:

type
The type of the memory entry, can be quick, call, channel, or, repeater

rx
The RX frequency

tx
The TX frequency

shift
A TX shift, including sign

mode
The operating mode
Memory Groups
Request Purpose Parameters Response

getMemoryGroup

Get the entries of a specific memory group

group
The id (UUID) of the memory group to retrieve

Identical to the getTopLevel request

addMemoryGroup

Add a new memory group

name
The name of the new group

supplement
A supplement to the name

descr
A longer description of the group

id
The UUID of the newly created group
Adding a New Memory Channel
Request Purpose Parameters Response

addMemory

Add a new memory entry

name
The name of the new memory

supplement
A supplement to the name

descr
A longer description of the memory entry

rx
The RX frequency

tx
The TX frequency

shift
A frequency shift including sign, if any

mode
The operating mode

id
The id (UUID) od the newly created memory entry

hamqth

The hamqth extension can be used to make online queries to the HamQTH.com database. All callsigns are locally cached for quicker access if queried multiple times or by different clients.

Example configuration
extensions:
  hamqth:
    script: hamqth
    configuration:
      username: MYCALLSIGN
      password: sicrit
Request Purpose Parameters Response

lookup

Lookup a callsign in the HamQTH.com database or the local cache

callsign
The callsign to be looked up

An array containing the fields described in the table below.
lookup Response Data
Name Value / Content

callsign

The callsign

nick

The name used on the air

qth

Callsign’s QTH

country

The country

adif

ADIF ID of country related to callsign

itu

ITU zone

cq

CQ (WAZ) zone

grid

Station locator

adr_city

City address

adr_zip

Postcode

adr_country

Country related to the address

adr_adif

ADIF ID of address country

lotw

Y - uses LoTW, N - doesn’t use LoTW, ? - unknown

eqsl

Y - uses eQSL, N - doesn’t use eQSL, ? - unknown

qsl

Y - accept QSL via bureau, N - doesn’t accept QSL via bureau, ? - unknown

email

E-mail

picture

Link to user’s picture

latitude

Station position - latitude

longitude

Station position - longitude

continent

Continent

utc_offset

Offset to UTC time in station location

source

Either hamqth or cache, depending whether the information was retrieved from HamQTH.com or taken from the local cache

The hamqth extension does not send status updates, even if you sent a listen request.

qrz

The qrz extension can be used to make online queries to the QRZ.com database. All callsigns are locally cached for quicker access if queried multiple times or by different clients.

A QRZ.com subscription is needed for the full functionality of this extension. Without a subscription, you will only get limited data and the number of lookups is limited to 100/day.
See https://shop.qrz.com/collections/subscriptions for all QRZ.com subscription options.
Example configuration
extensions:
  qrz:
    script: qrz
    configuration:
      username: MYCALLSIGN
      password: sicrit
Request Purpose Parameters Response

lookup

Lookup a callsign in the QRZ.COM database or the local cache

callsign
The callsign to be looked up

An array containing the following fields:

call
The callsign

name
The name

fname
The surname

addr2
Address information

country
The country

source
Either qrz or cache, depending whether the information was retrieved from QRZ.com or taken from the local cache

The qrz extension does not send status updates, even if you sent a listen request.

dxcluster

The dxcluster extension can be used for DXCluster spots as well as for SOTA-Cluster spots.

Example Configuration

The example configuration will run two instances of the dxcluster extension, one to get DXCluster spots and one to get SOTA spots:

extensions:
  dxcluster:
    script: dxcluster
    configuration:
      host: wr3d.dxcluster.net
      port: 7300
      callsign: MYCALLSIGN

  sotacluster:
    script: dxcluster
    configuration:
      host: cluster.sota.co.uk
      port: 7300
      callsign: MYCALLSIGN
      source: sotacluster
Request Purpose Parameters Response

getSpots

Get recent spots

maxSpots
The maximum number of spots to return

An array named dxcluster or whatever is configured in the source config parameter containing spot information as follows:

spotter
Who spotted the callsign

frequency
The frequency

spotted
The callsign being spotted

message
The optional message

time
The timestamp in UTC

When you send the listen request, the dxcluster extension will send new spots automatically as they arrive in a JSON package with the same fields as for the getSpots request in a spot array.

tasmota

The tasmota extension can control power plugs with the alternative Tasmota firmware found at https://github.com/arendst/Tasmota.

Example configuration
extensions:
  tasmota:
    script: tasmota
    configuration:
      address: 192.168.4.1
Request Purpose Parameters Response

power

Query power state

power
Either on or off

power

Set power state

state
Either on or off

power
Either on or off
The trx-control project is looking for contributors

We are looking for contributors in different areas:

JavaScript, HTML, CSS: If you are familiar with HTML, CSS, and JavaScript you can help with the JavaScript library that allows for easy integration of trx-control into existing web applications or you can help developing the WebTRX web client which is generic client in a single page application.

Lua / YAML: Maintain transceiver descriptions and CAT protocols.

C: Work in the core of trx-control. Be warned: It uses POSIX threads all over the place…​

Package maintainer: While we already build binary packages for many Linux distributions, your favourite one may not be in the list. Why not maintain prebuilt binary packages for it, e.g. on ArchLinux AUR (ArchLinux User Repositories) or SUSEs OBS (Open Build System).

Tester: You test the software against the transceivers you own and report any issues.

Documentation: Keep an eye on the documentation (online and man pages) and make sure they are kept up to date.

Anything else: Have a great idea? A client library for a specific programming language? An integration in existing software? Anything else? Please bring your idea(s) to the table!

If your interested in helping with the development of trx-control, please contact info@hb9ssb.radio for more information or contact us in our matrix room.

Go to the trx-control main page