This guide is intended for developers who want to integrate trx-control with their own software, e.g. logging or contesting software.
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
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.
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 |
|
to |
Select a destination |
Controlling Transceivers
Parameters in italic are optional.
Request | Purpose | Parameters | Response |
---|---|---|---|
get-info |
Request information about a transceiver |
name frequencyRange operatingModes |
|
set-frequency |
Set the operating frequency |
frequency |
|
get-frequency |
Get the operating frequency |
frequency |
|
set-mode |
Set the operating mode |
mode band |
|
get-mode |
Get the operating mode |
mode band |
|
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 status frequency 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 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, |
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 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 id name supplement descr The following entries are only present when entry is set to type rx tx shift mode |
|
getMemoryGroup |
Get the entries of a specific memory group |
group |
Identical to the getTopLevel request |
addMemoryGroup |
Add a new memory group |
name supplement descr |
id |
addMemory |
Add a new memory entry |
name supplement descr rx tx shift mode |
id |
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 |
An array containing the following fields: callsign nick qth country adif itu cq grid adr_city adr_zip adr_country adr_adif lotw eqsl qsl email picture latitude longitude continent utc_offset source |
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 |
An array containing the following fields: call name fname addr2 country source |
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 |
An array named spotter frequency spotted message time |
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 |
|
power |
Set power state |
state |
power |