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.

Units

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.

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.

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 all available destinations

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

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

set-frequency

Set the operating frequency

frequency
The operating frequency

get-frequency

Get the operating frequency

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

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.

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

wavelog

Configuration of /etc/trxd.yaml
extensions:
  wavelog:
    script: wavelog
    configuration:
      url: "https://<wavelog url>/index.php"
      apiKey: "<your rw api key>"
      # set ssl to false if you use self-signed certificates
      ssl: true
API Calls in Detail
"verify"
Purpose

Tests if the extension is available.

Parameter

None

Usage
{ "request": "verify" , "to": "wavelog" }
Result
{ "status": "Ok", "reply": "wavelog: extension running" }
"auth"
Purpose

Tests if the API Key is working with the configured URL.

Parameter

None

Usage
{ "request": "auth", "to": "wavelog" }
Result
{ "rights": "rw", "request": "wavelog", "api": "auth", "auth": "Valid", "status": "Ok" }
"radio"
Purpose

Send tranceiver mode, qrg and other parameters to wavelog.

Parameter
option type value

frequency

integer

required - Set the QRG in Hertz, e.g. 145500000

mode

string

required - Set the mode, e.g. FM

radio

string

optional - Set the radio name, displayed in Wavelog. E.g. FT-991A trxd. Default: trx-control

prop_mode

string

optional - Set the propagation mode, e.g. SAT or EME. Must match [Adif Specs](https://adif.org/314/ADIF_314.htm#Propagation_Mode_Enumeration)

sat_name

string

optional - Set the satellite name, e.g. AO-92. Must match [LoTW Sat ID’s](https://lotw.arrl.org/lotw-help/frequently-asked-questions/#sats)

power

integer/float\*

optional - Set the transmission power in watts (without unit! this is a number\*), e.g. 100

uplink_freq

integer

optional - Set the uplink frequency in Hertz, e.g. 435000000

uplink_mode

string

optional - Set the uplink mode, e.g. USB

frequency_rx

integer

optional - Set the receive frequency in Hertz, e.g. 145000000

downlink_freq

integer

optional - Set the downlink frequency in Hertz, e.g. 145800000

mode_rx

string

optional - Set the receive mode, e.g. FM

downlink_mode

string

optional - Set the downlink mode, e.g. USB
*Power: floats are allowed but get rounded! 1.5 will be shown as 2.
Usage
{ "request": "radio", "to": "wavelog", "frequency": 145512500, "mode": "FM", "radio": "FT817ND trxd", "power": 5 }
Result
{ "radio": "FT817ND trxd", "mode": "FM", "api": "radio", "status": "Ok", "frequency": 145512500, "request": "wavelog" }
"qso"
Purpose

Log QSOs directly to Wavelog.

Parameter
option type value

station_id

integer

required - The station ID which the QSO belongs to. E.g. 2

adif

string

required - The ADIF data containing one or more QSOs as plain ADIF text. E.g. <call:6>HB9HIL <gridsquare:4>JN47 <mode:2>FM <rst_sent:2>59 <rst_rcvd:2>59 <qso_date:8>20241102 <time_on:6>152300 <band:2>2m <station_callsign:6>HB9HIL <eor>

dryrun

boolean

optional - For testing purposes enable the dryrun. Default: false
Usage
{ "request": "qso", "to": "wavelog", "station_id": 2, "adif": "<call:6>HB9HIL <gridsquare:4>JN47 <mode:2>FM <rst_sent:2>59 <rst_rcvd:2>59 <qso_date:8>20241102 <time_on:6>152300 <band:2>2m <station_callsign:6>HB9HIL <eor>" }
Result
{ "request": "wavelog", "adif_errors": 0, "message": [""], "status": "created", "reason": "", "adif_count": 1, "api": "qso" }
"private_lookup"
Purpose

Check your complete Wavelog database for callsigns and get all necessary information back.

Parameter
option type value

callsign

string

required - The callsign you are looking for, e.g. HB9HIL

station_ids

array

optional - You can search only in particular station_ids, if not set it will search through all available. Set e.g. [3,5,8,11]

band

string

optional - Search for a particular band, e.g. 40m

mode

string

optional - Search for a particular mode, e.g. PSK
Usage
{ "request": "private_lookup", "to": "wavelog", "callsign": "HB9HIL" }
Result
{ "dxcc_id": "287", "bearing": "", "callsign": "HB9HIL", "call_worked": true, "dxcc": "SWITZERLAND", "us_county": "", "call_worked_band": false, "dxcc_cqz": "14", "dxcc_lat": "47", "dxcc_long": "7.5", "location": "", "state": "", "cont": "", "api": "private_lookup", "request": "wavelog", "dxcc_confirmed_on_band": false, "gridsquare": "JN47", "dxcc_confirmed": true, "qsl_manager": "", "status": "Ok", "dxcc_flag": "🇨🇭", "suffix_slash": "", "call_worked_band_mode": false, "dxcc_confirmed_on_band_mode": false, "lotw_member": false, "call_confirmed_band": false, "call_confirmed": false, "iota_ref": "", "call_confirmed_band_mode": false, "name": "" }
return type value

callsign

string

The callsign, e.g., HB9HIL

dxcc

string

DXCC entity, e.g., SWITZERLAND

dxcc_id

integer

DXCC ID, e.g., 287

dxcc_lat

float

Latitude of DXCC, e.g., 47

dxcc_long

float

Longitude of DXCC, e.g., 7.5

dxcc_cqz

integer

CQ zone of DXCC, e.g., 14

dxcc_flag

string

Flag emoji for DXCC, e.g., 🇨🇭

cont

string

Continent code, e.g., EU

name

string

Operator’s name, e.g., Fabian

gridsquare

string

Grid square, e.g., JN47

location

string

Location or city, e.g., Appenzell

iota_ref

string

IOTA reference, e.g., OC-001

state

string

State or province, e.g., AI

us_county

string

U.S. county, if applicable

qsl_manager

string

QSL manager, e.g., N3ABC

bearing

integer

Bearing from station location

call_worked

boolean

Whether the call was worked

call_worked_band

boolean

Whether the call was worked on band

call_worked_band_mode

boolean

Whether the call was worked on band and mode

lotw_member

boolean

Whether the operator is a LoTW member

dxcc_confirmed_on_band

boolean

Whether DXCC confirmed on band

dxcc_confirmed_on_band_mode

boolean

Whether DXCC confirmed on band and mode

dxcc_confirmed

boolean

Whether DXCC is confirmed

call_confirmed

boolean

Whether the call is confirmed

call_confirmed_band

boolean

Whether the call is confirmed on band

call_confirmed_band_mode

boolean

Whether the call is confirmed on band/mode

suffix_slash

string

Callsign suffix, if applicable
For band and mode information the parameters for these two are required.
"logbook_check_callsign"
DEPRECATED. It’s not recommended to use this anymore under Wavelog. Use private_lookup instead.
Purpose

Check if a callsign is the logbook or not. Returns only "Found" or "Not Found".

Parameter
option type value

callsign

string

required - The callsign you are looking for

slug

string

required - The public slug of the logbook, which contains several locations.

band

string

optional - You can check if the callsign was worked on a particular band.
Usage
{ "request": "logbook_check_callsign", "to": "wavelog", "callsign": "HB9HIL", "slug": "log" }
Result
{ "callsign": "HB9HIL", "result": "Found", "status": "Ok", "request": "wavelog", "api": "logbook_check_callsign" }
"logbook_check_grid"
Purpose

Check if a gridsquare was worked before. Optional if it was confirmed or on a particular band.

Parameter
option type value

grid

string

required - The gridsquare you are looking for, e.g. JN47

slug

string

required - The public slug of the logbook, which contains several locations.

band

string

optional - You can check if the callsign was worked on a particular band

cnfm

string

optional - Check if it was confirmed via qsl , lotw or eqsl (qrz.com and clublog not implemented yet as of 11/2024)
Usage
{ "request": "logbook_check_grid", "to": "wavelog", "grid": "JN47", "slug": "log", "cnfm": "lotw" }
Result
{ "gridsquare": "JN47", "result": "Confirmed", "status": "Ok", "request": "wavelog", "api": "logbook_check_grid" }
"statistics"
Purpose

Very basic API which returns a few numbers

Parameter

none

Usage
{ "request": "statistics", "to": "wavelog" }
Result
{ "year_qsos": "468", "api": "statistics", "today_qsos": "2", "month_qsos": "4", "status": "Ok", "total_qsos": "1667", "request": "wavelog" }
"station_info"
Purpose

Very basic API which returns all station locations of the user.

Parameter

none

Usage
{ "request": "station_info", "to": "wavelog" }
Result
{ "request": "wavelog", "status": "Ok", "api": "station_info", "result": [ { "station_profile_name": "Appenzell Test", "station_gridsquare": "JN47RH", "station_active": "1", "station_callsign": "HB9HIL", "station_id": "1" }, { "station_profile_name": "App 2", "station_gridsquare": "JN47RR", "station_active": [], "station_callsign": "HB9HIL", "station_id": "3" } ] }
"get_contacts_adif"
Purpose

Returns ADIF data from a defined QSO ID. With this you can get a list with your latest QSO.

Due to memory limitations this currently works for up to 100-150 QSOs before the trxd service fails and restarts. Investigation needed.
Parameter
option type value

station_id

integer

required - The station ID you want the latest contacts from

fetchfromid

integer

required - The last QSO ID from where you want all later QSOs in the ADIF file

limit

integer

optional - limit the amount of returned QSOs. Default in Wavelog is 20000 QSOs
Usage
{ "request": "get_contacts_adif", "to": "wavelog", "station_id": 1, "fetchfromid": 2042 }
Result

(adif data is shorted for display reasons.)

{ "api": "get_contacts_adif", "exported_qsos": 11, "message": "Export successful", "lastfetchedid": "2053", "status": "Ok", "request": "wavelog", "adif": "Wavelog ADIF export <ADIF_VER:5>3.1.4 <PROGRAMID:7>Wavelog <PROGRAMVERSION:5>1.8.8 <EOH>  <BAND:3>20m <CALL:6>DG3NAB <COUNTRY:27>Federal Republic Of Germany <CQZ:2>14  <GRIDSQUARE:6>JN47RH <MY_CQ_ZONE:1>1 <MY_ITU_ZONE:1>1 <EOR>  " }

Go to the trx-control main page