trx control

trx-control

trx-control is a modern and extensible software system for Linux to control amateur radio equipment, e.g. transceivers, GPIO-pins etc. It easily integrates with third-party software or online systems with optional extensions that are written in the easy to learn Lua programming language. It is modular by design and was created with the user in mind.

It is recommended that new users read The trx-control User Guide which is available in HTML, PDF and EPUB format after getting an overview of what trx-control is on this page.

trx-control is Under Active Development

Be aware that trx-control is under active development. Things may change in incompatible ways. We strive, however, to keep the documentation and this website up to date.

If you find any inconsistencies, errors or bugs, please file a PR on the Github page (see Source Code).

Project Goals

  • Create an open and easily extensible system to control mainly transceivers, but also other hardware, and integrate with third-party software.

  • Make it easy to add support for new transceivers or other devices.

  • Provide an easy to implement, and, easy to use client/server protocol based on the exchange of JSON-formatted data over the network.

  • Use a multi-language approach where the core of the system is written in C whereas extensions and drivers can be written in the easy to learn Lua programming language, lowering the entry barrier a lot.

  • No programming skills are needed to add new transceivers if they use one of the already supported CAT protocols.

  • Use a multithreaded, asynchronous approach at the core of the software.

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.

What is included?

trx-control mainly consists of trxd(8), a daemon to control the transceivers and other hardware, and, trxctl(1), a command line utility to access trxd(8), and, bluecat(1), a tool to help with the configuration of bluetooth connections.

trx-control comes with protocol drivers for common transceiver brands, configurations for a variety of transceiver models, a bunch of extensions, and, complete documentation online as well as in the form on manual pages.

Using trx-control from client software

Software that wants to make use of trxd(8) should implement the trx-control client/server protocol and talk to trxd(8) over the network, either over raw IP sockets or WebSockets.

(trxd(8) listens on port 14285 by default for incoming connections over raw sockets and can optionally listen for WebSocket connections. It supports both IPv4 and IPv6.)

See The trx-control Integration Guide (PDF, EPUB) for all information regarding the client/server protocol, the extensions etc.

Adding new transceivers

Transceivers are controlled using protocol drivers written in the Lua programming language. Properties of a specific transceiver are defined in YAML format. New transceivers can be added by adding a protocol driver (if needed) and a transceiver defintion.

See The trx-control Developer Guide (PDF, EPUB) for all information needed to write protocol drivers and the documentation of all Lua modules included with trx-control.

See https://lua.org for more information on Lua.

System Overview

At the core of a trx-control installation is trxd(8), the daemon that handles clients (IPv4 and IPv6) and controls the devices and extensions by exchanging JSON-formatted data with the clients and talking to the transceivers and other devices over whatever interface they use. All communication between the clients and trxd(8) is either done using NDJSON packages over a plain TCP/IP socket or JSON packages over a WebSocket.

Multiple clients can simultaneously connect to trxd(8), controlling an unlimited number of transceivers, GPIO pins, and, extensions:

diag overview

trxd(8) supports transceivers that can automatically send status updates (e.g. Yaesu FT-710 etc.) as well as transceivers that require polling (e.g. older Yaesu FT-897 etc.)

Devices and Extensions

Transceivers

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

Brand Model(s)

Connect Systems Inc.

CS7000-M17, CS7000-M17 PLUS

ICOM

IC-705

JVC Kenwood

TH-D75E, TH-D75A

Yaesu

FT-710 / FT-817 / FT-897 / FT-991a

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

wavelog

Lookup and store data in wavelog (https://wavelog.org).

The trx-control User Guide

The trx-control User Guide is intended to help with the setup and configuration of trx-control.

The trx-control Integration Guide

The trx-control Integration Guide documents integrating trx-control into your own software or writing a client that uses trx-control.

The trx-control Developer Guide

The trx-control Developer Guide documents how to develop new transceiver drivers or extensions.

trx-control Application Notes

This is a loose collection of application and device notes.

trx-control Client App

trx-control

The trx-control protocol is open for anyone do develop a client or integrate trx-control into their own software. Nevertheless we do provide a client app aimed at mobile devices.

The trx-control client app is available in the Google Play Store as well as in the Apple App Store.

The app in the Apple Play Store will eventually be replaced by a new app written entirely using SwiftUI.

Im App Store laden

Now at Google Play
(Google Play and the Google Play Logo are trademarks of Google LLC.)

Information Material

From Supporting Elephants to Controlling Shortwave Transceivers: 15 Years of Lua. A recording of a talk during the "Celebrating 30-years of Lua" special edition Lua Workshop 2023 in Rio de Janeiro:

Presentation slides from the "Software Defined Radio & Amateur Radio" devroom that I co-organised at FOSDEM 2024 in Brussels:

Presentation slides from the Dreiländereck-Sysop-Treffen 2024:

Video and slides from a trx-control presentation I gave in may at HB9AG, my local club:

Flyers and cards:

Print the flyers on A4 paper in landscape mode and fold them twice from the outside inwards so that the title is on top and the page with the address is on the back.

Social Media

Bluesky

Follow HB9SSB on Bluesky: @hb9ssb.bsky.social

Matrix Room

There is a Matrix chat room #trx-control:matrix.org to discuss trx-control: #trx-control:matrix.org

Source Code

trx-control is open source software licensed under the MIT license. You can access the source code on GitHub at https://github.com/hb9ssb/trx-control

Frequently Asked Questions

Can I run trx-control on Windows?

While trx-control requires a Linux system to run on, it can as well be used on Windows. Install the Windows Subsystem for Linux (WSL) and install the prebuilt binary packages for the Linux distribution you did choose and install in WSL.

Another option might be to use a desktop virtualizer like VirtualBox or VMWare Workstation (both are free) or running it in a container, e.g. using Docker Desktop.

Can I run trx-control in a container?

Yes, just make sure to properly setup networking and access to USB devices. Also, if service advertising using mDNS is to be used to announce the Websocket service, then the network within in the container has to be correctly configured so that mDNS packages are passed (port 5353/udp).