Installing trx-control

The easiest and fastest way to install trx-control is by installing a prebuilt binary package for your Linux distribution.

If you are using macOS or Windows, the recommended way to use trx-control is to install a desktop virtualization software like VMware Desktop / Fusion or VirtualBox and to install a minimal Linux system and trx-control in it.

Installing on Debian / Ubuntu

First install the GPG public key that is used to sign the repository:

$ sudo curl -o /etc/apt/trusted.gpg.d/trx-control.asc \
        https://trx-control.msys.ch/pub/repos/trx-control.asc

Then add a repository file, substitute <codename> by the codename of your Linux distribution (e.g. jammy, bookworm etc.) and <arch> by your CPU architecture (amd64, arm64):

$ sudo tee /etc/apt/sources.list.d/trx-control.list << EOF
deb [arch=<arch>] https://trx-control.msys.ch/pub/repos/apt/ <codename> stable
EOF
Distribution Repository name Available architectures

Debian 14.0 (testing)

forky

amd64, arm64

Debian 13.4 (stable)

trixie

amd64, arm64

Debian 12.13 (oldstable)

bookworm

amd64, arm64

Ubuntu 26.04

questing

amd64, arm64

Ubuntu 24.04

noble

amd64, arm64

Ubuntu 22.04

jammy

amd64, arm64

Then install trx-control using apt:

$ sudo apt update
$ sudo apt install trx-control

Installing on Red Hat / AlmaLinux / Rocky Linux / Fedora

First install the trx-control repository package:

Distribution Repository package Available architectures

Fedora 44

fedora-44

x86_64, aarch64

Fedora 43

fedora-43

x86_64, aarch64

Red Hat 10 / AlmaLinux 10 / Rocky Linux 10

alma-10

x86_64, aarch64

Red Hat 9 / AlmaLinux 9 / Rocky Linux 9

alma-9

x86_64, aarch64

Then install trx-control using dnf:

$ sudo dnf install trx-control --refresh

Installing on openSUSE Tumbleweed / openSUSE Leap

First install the trx-control repository package:

Distribution Repository package Available architectures

openSUSE Tumbleweed

opensuse-tumbleweed

x86_64, aarch64

openSUSE Leap 16.0

opensuse-leap-16.0

x86_64, aarch64

Then install trx-control using zypper:

$ sudo zypper install trx-control

Running trx-control

The main component of trx-control is trxd(8), a server process that runs in the background and controls the transeivers and other devices. Besides controlling devices it also provides several extensions, e.g. a memory system, a logbook, callsign lookup in hamqth or qrz, a DX cluster client etc.

trx-control clients connect over the network to trxd and exchange messages in JSON format. The connection can either be made over plain TCP/IP sockets or Websockets.

Why trxd(8) when the binary is actually named trxd? The number in brackets simply indicates the chapter of the online manaun in which trxd is documented. To read the manual page enter $ man 8 trxd, or simply $ man trxd , as there is no other trxd manual page in any other chapter.

Starting trxd

trxd(8) is integrated with systemd. To run it, use systemctl:

$ sudo systemctl start trxd

If you want to start and permanently enable trxd, use the following command

$ sudo systemctl enable --now trxd

Should you ever want to run trxd in the foreground, e.g. for debugging your setup, stop any running background trxd process and use the option -d to tell trxd to no daemonize (i.e. not run in the background) and maybe -v to increase the verbosity level. -v can be used repeatetly.

$ sudo systemctl stop trx
$ trxd -d -v
Make sure the user running the trxd(8) daemon is a member of the dialout group to enable access to serial devices.

Error logging

trxd(8) logs all errors to the system log which means that you can use journalctl(1) to inspect the log:

$ sudo journalctl -u trxd

or, if you want to have continuous output:

$ sudo journalctl -fu trxd

Using the trxctl client

When trxd is running, you can use the trxctl command to test your setup:

$ trxctl @

This will display a list of destinations you can talk to.

Read the online manual

trx-control comes with a set of manual pages, make sure to read them carefully.

Manual page Content

trx-control(7)

A general trx-control overview

trxd(8)

The trxd background process

trxctl(1)

The trxctl client

bluecat(1)

The bluecat bluetooth client utility

The trxd(8) Configuration file

trxd(8) reads its configuration from the file /etc/trxd.yaml by default. If that file does not exist, it will try to load the configuration from $HOME/.local/trx-control/trxd.yaml. A different path can be specified with the -c option on the command line. If no configuration file is found, trxd(8) will log a error message and terminate.

The configuration file must be in YAML-format (see https://yaml.org for details).

A sample configuration file can be found in /usr/share/trxd/trxd.yaml.

In the configuration file you can set global defaults like the address and port where trxd(8) should listen for incoming client connections. Transceivers are listed in the configuration by choosing an arbitrary name and specifying the correct driver. One transceiver can be designated as the default transceiver.

This configuration file will be processed using the yaml Lua module, so the local tags mentioned in https://lua.msys.ch/lua-module-reference.html#_a_note_on_yaml_tags can be used.

Connecting To Transceivers

Transceivers can be connected either over a serial line or via Bluetooth. Whether a serial line or Bluetooth is used makes a difference in device naming:

Serial line device names are an absolute path to a device, e.g. /dev/ttyUSB0, and they have the optional speed setting to indicate the bit rate.

Bluetooth device names, however, are six pairs of hex digits separated by a colon, e.g. 01:23:45:67:89:AB, and they have the optional channel setting to indicate the RFCOMM channel to be used.

Example configuration

# Example trxd(8) config file.  Note this in YAML-format.

# Run in the background
no-daemon: false

# Listen on localhost for incoming plain socket connections
bind-address: localhost
listen-port: 14285

# Listen on all interfaces for WebSocket connections
websocket:
  bind-address: 0.0.0.0
  listen-port: 14290
  path: trx-control

  # To use wss (SSL) instead of ws, define the ssl parameters.
  ssl:
    # if you define a CA root, client connections are only possible with
    # valid client certificates that have been signed by this CA
    root: server_ca.crt

    # For SSL you must define a certificate which can also contain the private
    # key
    certificate: server.pem

    # If the certificate file does not contain a private key, specify it
    # separately
    key: server.pem

  # If you don't want to announce the trx-control service using Avahi (mDNS),
  # set announce to false.  The default is to announce the service as
  # _trx-control._tcp:
  announce: true

# Log incoming connection using syslog
log-connections: true

# trxd shall run as trxd:trxd
user: trxd
group: trxd

# Store the PID of the running trxd process in trxd.pid
pid-file: trxd.pid

# Decode NMEA sentences from a GPS/Glonass/Baidu etc. receiver
nmea:
  title: NMEA Data
  description: Decode NMEA data from the Icom IC-705 transceiver
  device: /dev/ic-705-nmea
  speed: 9600

# Map USB devices to transceivers
# Make sure all fields are strings, not numbers!
# Devices without a destination are masked out
device-map:
  -
    # Yaesu transceivers using the CAT delimited protocol are autodetected
    vendor: 10c4
    product: ea70
    interface: '00'
    speed: 38400
    destination: yaesu-cd-autodetect
  -
    vendor: 2166
    product: 9023
    speed: 38400
    destination: kenwood-th-d75e
  -
    vendor: '0c26'
    product: '0036'
    interface: '00'
    destination: icom-ic-705

# Static list of our transceivers
transceivers:
  ft-897:
    title: Yaesu FT-897
    description: The FT-897 connected over USB
    device: /dev/ttyUSB2
    speed: 38400
    trx: yaesu-ft-897

    # This is the default transceiver in case the client does not explicitely
    # select a transceiver by name.
    default: true

  # An ICOM IC-705 connected over Bluetooth serial (must be paired first)
  ic-705:
    title: ICOM IC-705
    description: IC-705 connected over Bluetooth
    device: 01:23:45:67:89:AB
    channel: 3
    trx: icom-ic-705
    # Optionally set the controller and transceiver address.
    configuration:
      controllerAddress: 0xe0
      transceiverAddress: 0xa4
    audio:
      input: audio_in
      output: audio_out

extensions:
  ping:
    script: ping

  memory:
    script: memory
    configuration:
      connStr: dbname=trx-contol
      datestyle: German

  logbook:
    script: logbook
    configuration:
      connStr: dbname=trx-contol
      datestyle: German

  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

  hamqth:
    script: hamqth
    configuration:
      username: MYCALLSIGN
      password: sicrit

  qrz:
    script: qrz
    configuration:
      username: MYCALLSIGN
      password: sicrit

  tasmota:
    script: tasmota
    configuration:
      address: 192.168.4.1

Please note that title and description are optional.

Devices and Extensions

Transceivers

trx-control supports the following transceivers, more will be added over time:

Brand Model(s)

Connect Systems Inc.

CS7000-M17, CS70000-M17 GPS, CS7000-M17 PLUS

ICOM

IC-705

JVC Kenwood

TH-D75E, TH-D75A

Yaesu

FT-710, FT-817, FT-857, FT-891, FT-897, FT-991a, FTX-1

A special simulator transceiver driver exists for development and testing purposes.

GPIO

Brand Model(s)

bmcm

USB-PIO / OR8 (attached to USB-PIO)

GPS/NMEA

Any GPS/Glonass/BeiDou etc. receiver that emits fix data as NMEA sentences.

Extensions

Name Purpose / Comments

config

Access the trxd(8) configuration (read only)

dxcluster

Get DX (or SOTA) cluster spots in real time or query the last n spots

hamqth

Lookup callsigns the HamQTH.com database

logbook

A simple logbook for QSOs using a PostgreSQL database

memory

Manage memories and memory groups

ping

Check if the trxd(8) service is alive

qrz

Lookup callsigns in the QRZ.com database (requires a QRZ.com subscription for full functionality)

tasmota

Control power plugs with the Tasmota alternative firmware