A Software Modem for FT8

Matt Roberts - matt-at-kk5jy-dot-net

Published: 2023-02-23

Updated: 2023-03-09

Have you ever wanted to run FT8 but without the WSJT-X graphical user interface? Have you ever wanted to put your own uesr interface on FT8? Have you ever wanted software for FT8 that allows for unlimited custom scripting of your QSOs? Have you ever wanted a super-lightweight FT8 application for your embedded, mobile, or remote operation?

That's what this project is about.

FT8 and its little brother FT4 are quite active on the bands. The widely-used reference software for these modes is WSJT-X. It gets the job done, but it has some serious drawbacks for power users.

Heavy user interface, that is a bit cluttered, and not intuitive.
Very limited support for scripting and automation. The UDP API allows some actions to be performed from outside the application, but the protocol is not well-documented.
Limited command-line tools, and no command-line modulator.

After spending far too much time trying to operate WSJT-X remotely, I decided it was time for a command-line version of the software.

This project is a command-line software modem for FT8. The input and output are newline-delimited lines of text, which will be very familiar to Linux users. The input lines are used to transmit frames, and the output lines are the decoded frames, with a few status messages mixed in. That forms the core of the application.

This turns FT8 into another pipeline utility, that can be scripted and managed in any way desired, just like any other command-line utility.

The Building Blocks

The WSJT-X package includes a few command-line utilities that are able to decode the various modes from WAV files or from shared memory. There are also utilities to encode message text into keying symbols, but no command-line modulator. The good news is that this is enough to build a working modem with just a very small amount of management code. In particular, the jt9 utility is used for decoding, while the ft8code and ft4code utilities are used for encoding.

The jt9 program isn't just a command-line decoding utility — it is the decoder used by WSJT-X in real time to decode several modes, including FT8 and FT4. So by leveraging that program, we get all the benefits of the latest decoder from the official WSJT-X team, with the same performance as the full application.

The encoders are a different story. WSJT-X doesn't include a command-line modulator, only encoders. These take user text (like "CQ KK5JY EM16") and compute the symbols to be converted to MFSK audio. So the modem uses these utilities to get they symbol sequence for transmission, but then uses custom code to generate MFSK audio from them.

The only encoder installed by a source build is the FT8 verison. The FT4 version is built in the 2.5 and later releases, but it is not installed. So to use FT4 with the modem, the ft4code utility has to be hand copied from the build into the system path.

Operation Description

The modem runs the jt9 utility in FT8 or FT4 mode, feeding it one time slot of audio from the sound device. The output of JT9 is cleaned up, then the decodes are sent to standard output. Each new timeslot, the sound card audio is captured, and fed to a running jt9 instance. A new instance is started for each timeslot, which means that decoding can overlap between slots, if needed. This is handy if running on a slow CPU.

Transmitting frames is handled similarly, by sending the audio frequency and message text to standard input. The text is passed through ft8code or ft4code, which generates the MFSK keying symbols. Those symbols are passed to a modulator, which generates the MFSK tones, and wave-shapes the start, stop, and keying transitions. The wave-shaping reduces the level of keying sub-bands and key clicks, which results in a cleaner output signal.

The Interface

As described above, the ft8modem interface is simple — received decodes are read from the program's output, and transmitted frames are sent to the program's input. There are also some status messages that are sent to the program output. These take the form of INFO: or ERR: messages, or TX: messages showing when the program needs the transmitter running. Received decode lines are prefixed with D:. There may be more messages added later to aid in scripting.

Transmitting is done by writing an audio frequency value, a space, and then whatever text is to be sent to standard input. Each line is a new transmission. The modem will make sure to wait until the next time slot to begin transmission.

The ft8modem program takes up to three arguments. These are the mode ("ft8" or "ft4"), the sound device number, and optionally the decoding depth. The sound device must support 48kHz sampling, which is decimated to 12kHz for the jt9 utility. Run the ft8modem program with no arguments to see a list of sound devices available.

Where is CAT Control?

There are obviously some features not described here — things like auto-sequence and QSO management. Since this is a pipeline tool, those are features to be implemented by other tools. That's the idea of a pipeline — you connect different utilities together to make them work the way you want them to work.

For example, to add CAT control and split operation, there is an example utility in the folder called ft8cat. This is another pipeline tool that runs the modem, then connects to a local instance of the rigctld from the hamlib project, which connects to the radio to control it.

A sample command line might be:

   ./ft8cat -s ./ft8modem ft8 0

...which sets the mode to FT8, and begins decoding on the first sound device.

The -s option tells ft8cat to enable split operation during transmission. This allows the modulator to generate tones near the higher end of the analog passband, even when working a station low in the passband. The VFOB is carefully set to make the transmission happen on the audio frequency intended. This allows the filtering in the radio to eliminate distortion generated by overdriving the audio stage.

The ft8cat utility also adds some status output messages, including FA: and FB:, that can be used in higher-level scripts to know the current dial frequencies. This is important for logging and remote monitoring.

As the project progresses, I will probably add some scripts here to demonstrate QSO management. The main idea is to put a few well-defined tasks in each utility. Then you add functionality by chaining those utilities together. Since the software is divided into small modules, it allows maximum flexibility in how you connect them together.

In its current state, the modem is a reasonably complete solution for scripting operations.

More to Come

The ft8modem code is in bench-testing. The FT8 and FT4 modes are both working between computers in the same room. The application is ready for extended testing and development of higher-level scripts for QSO management.

The package also includes an ft8encode utility for generating FT8 and FT4 WAV files. This allows even more flexibility in how a custom pipeline can be set up, with transmit and receive running as separate programs.

The core applications are written in C++, which is intended to keep them light and fast. The higher level utilities will probably be written in Python, because it is universal in Linux distributions and make it easy to quickly write control logic.

If you are interested in helping with more testing, please send me an email.

ft8modem Downloads (Click Here)

Click the link above to download software packages. The source is being released under the GPL version 3, which is also available on the download page.

Release History

2023-03-09 - Fix more bugs.
2023-03-07 - Fix bugs.
2023-02-25 - Added the ft8cat utility.
2023-02-23 - Initial beta release.

Copyright (C) 2023 by Matt Roberts, KK5JY. All Rights Reserved.