Embedded FreeDV for Raspberry Pi (and others)

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

Published: 2018-05-29

Updated: 2018-06-19

Figure 1 - Hardware Flow
Diagram

Figure 2 - Example Audio
Interface Circuit

Figure 3 - Software Flow
Diagram

Figure 4 - Prototype

Figure 5 - Prototype
Indicator LEDs

The FreeDV project provides an open-source digital voice modem, specifically designed for amateur radio use. The GUI software is fairly lightweight, and can even run on newer versions of the Raspberry Pi. However, not all users of the mode will want to use a PC or a GUI application, no matter how small or simple, to operate on the air.

The FreeDV software is well-factored, with the core codec being available as a stand-alone library, called codec2. The library offers a tight interface for the purpose of embedding the codec in other software products. In fact, the FreeDV team even offers a stand-alone "box" which embeds a DV modem in a portable low-power device for operating without a general purpose computer. Such a device could easily be used for mobile or portable operation, or for "shacks" without a computer.

The SM1000 device is very cool, but it's a little bit pricey for someone who just wants to tinker with the mode. Even though it is open-source, it appears to be designed mainly to support FreeDV, so it's really more of an "all-in" solution for serious users. Since the codec2 API is available as free software, I decided to use a Raspberry Pi as the base for a kit device that offers similar functionality to the SM1000. This allows people who have spare RasPi devices to experiment with the mode in an embedded device, but on a smaller budget. The RasPi's rich set of hardware I/O leaves plenty of room for extensibility and experimentation, especially for people who prefer to build and tinker.

As it turns out, the FreeDV API is extremely lightweight, and has all the features needed to operate without a GUI. Even when run on an original version 1 RasPi, which is a slow device indeed, the software described below can run the default 1600 mode with plenty of resources to spare. The software should run on any Raspberry Pi device, from the original devices, clear up to the current (and very fast by comparison) RasPi 3B+.

I'm calling the kit SmallDV.

Kit Description

The hardware required for the kit is quite simple, by design. The idea is to minimize the overall hardware required, and then also use as little custom hardware as possible. A flow diagram is shown in Figure 1. The kit uses a Raspberry Pi as the core. The little computer does all of the DSP, while also controlling a small amount of outboard hardware to control the radio PTT, and route the audio. It can optionally drive some LEDs to use for monitoring the operation of the device.

Using an DV adapter with an analog radio requires four audio connections:

Microphone
Speaker or Headphones
Radio Transmit Audio
Radio Recieve Audio

The FreeDV software requires two sound devices to provide the four needed connecitons. However, most voice operation in the amateur radio world is half-duplex, which means that half of each soundcard is always idle, plus the software has to do extra work to match the two cards' sampling rates. At any given time, all that is needed is one sound input and one output.

As a result, the SmallDV kit uses a single sound device, and uses a single DPDT relay to connect the input and output to the appropriate functions, as needed. The software can also use the sound card's mixer device to allow different audio levels to be configured for each of the four functions.

An example interface circuit can be seen in Figure 2. The interface can easily be built onto a small protoboard. The V+ voltage in the circuit should match the coil of the relay being used. I chose an appropriate 5VDC small-signal relay with a current draw low enough to be comfortably powered by the +5V rail of the RasPi.

The software to run the device is in two parts, and a flow diagram is shown in Figure 3. The first part is a very small utility called fdvcore. It connects to the sound device and does the FreeDV encoding and decoding. Its C++ code is small, minimal, and fast, so as to perform all the DSP with the best efficiency possible. The smalldv program, written in Python, is responsible for handling configuration, managing fdvcore, adjusting mixer levels at each T/R transition, and controlling GPIO and audio routing. This division allows fdvcore to be fast, and mostly independent of other functions, while the main smalldv program allows for rapid development, and easy modification by hobbyists. Since Python is the main prototyping language used by Raspberry Pi enthusiasts, it makes the kit friendly to people familiar with the RasPi environment.

The smalldv program has a socket listener, that can be used to configure and control the SmallDV kit. This means that the SmallDV embedded device can be controlled from any number of user interfaces, including simple text mode connections, web applications, etc. This makes placing a custom UI on top of the kit simple. At a bare minimum, the kit can be configured through no more than telnet.

An early prototype is shown in Figure 4. It implements the interface circuit shown in Figure 2. It uses a specific USB sound device, which has been tested by the Adafruit team to work well with Raspberry Pi and its standard set of drivers. It also has only one input and output, which makes the level configuration simple. The device is available through Adafruit or their resellers like Digikey and Mouser.

Current Features

The current version of the software supports the 1600 and 700 mode variants of the FreeDV modem. The desired mode can be changed at runtime via the TCP control interface.

The kit supports several features via GPIO pins on the Raspberry Pi:

A PTT input button. This should be connected to a high-quality, momentary pushbutton to be used by the user to control T/R switching. The RasPi GPIO library doesn't support software debouncing, so an RC debouncing circuit should be used with this button.
A PTT output for connection to the radio. This should be used to drive an open-collector or open-drain circuit. This GPIO signal is also used to drive a DPDT relay for audio routing. An example of both functions is shown in Figure 2.
An LED for SYNC indication, which works much like a "carrier detect" indication, showing that the modem has locked onto a received signal.
An LED for CLIP indication, which warns the user that the received audio level from the receiver (during RX) or from the microphone (during TX) is too high.
A tuning indicator made from three LEDs, which can show five different deviation states; this can be used as an aid for tuning signals on an SSB receiver.

Figure 5 shows the LED indicators for the most recent prototype.

The polarities used for the various GPIO functions, and the range of the tuning indicator can be configured in the smalldv script, supporting a wide range of hardware configurations.

The smalldv program can also adjust the input and output audio levels for the software mixer controls of the sound device. As the modem performs each T/R transition, the mixer can adjust the input and output levels to support the new devices connected to each audio connection of the sound card. E.g., the drive level required for the transmitter is probably not the same as that required to drive the headphones, but they share the same audio output device through a relay. So when the modem switches between receive and transmit, the mixer adjusts the output level to match the device to be connected to the sound card output, so that correct levels are maintained. The same is done for the input connection.

Four different level combinations are configurable, two each for transmit and receive. This enables the kit to perform all level management in software, without any external hardware. That said, a kit builder who prefers setting levels externally with trimmers can do so. The default levels for all functions is 100% unless changed — just right for adjusting with external hardware. The headphone/speaker volume level is one that is particularly well-suited for external hardware control.

The smalldv program runs a TCP listener that accepts connections from other programs on the same device. This allows any number of different user interfaces to attach to the supervisor, to configure and operate the device. The TCP interface uses a line-oriented interface, with simple commands separated from each other by newlines. Each command consumes one line, and the response from the software will consume one line. The command interface has a number of configuration and status verbs, such as:

VERSION: Requests the version of the fdvcore process.
VOLTX: Requests or sets the radio transmit audio level
VOLRX: Requests or sets the radio receive audio level
VOLPH: Requests or sets the volume of the headphones or speaker.
VOLMIC: Requests or sets the volume of the microphone input.
TEXT: Request or set the out-of-band text that is sent during transmission.
TX: Provide a boolean value indicating whether to be in TX (1) or RX (0) mode. This is a software T/R control, which can operate in addition to the hardware PTT input on Raspbery Pi.
CLIP: Request a boolean value that indicates whether clipping has occurred since the last CLIP command.
FRAMES: Request the number of data frames processed.
DF: Request the frequency offset of the received signal. This can be used to drive a tuning indicator.
SNR: Request the signal-to-noise ratio of the received signal.
SYNC: Request a boolean value indicating whether the receiver is synchronized to the received signal.
STAT: Request a pair of values, which are the combination of the SYNC and SNR commands.
QUIT: Close the TCP connection.
SHUTDOWN: Close the TCP and shutdown the SmallDV modem.
MODEM: Read or set the Codec2 encoding to use. Valid values include 1600, 700, 700B, 700C, and when linked against the Codec2 0.8 library, 700D.

An example exchange, between client (C) and server (S) might look like this:

C: VERSION
S: OK:VERSION=fdvcore 1.0
C: TX
S: OK:TX=0
C: VOLPH
S: OK:VOLPH=100
C: VOLPH=75
S: OK:VOLPH=75
...

Whenever the modem configuration is changed, the settings are persisted to a file, which is ideal for an "appliance" style device. All software components run as a background service. This allows the software to be started and run without any display at all.

Software Downloads

The software for the project is available in source form, below. Building the software on Linux (including RasPi) requires some prerequisites:

The build-essential meta-package.
The libsndfile1 library and libsndfile1-dev development headers.
A recent version of RtAudio by Gary Scavone.
A recent version of the Codec2 library from the FreeDV website.

This project is still in-progress, but the core functions are working. And that is enough for a kit, which is the point. I will continue to develop the kit for my own uses, and add new features, but the software is available here for those who would like to experiment with embedding FreeDV on inexpensive hardware.

All software and firmware is released under the terms of the GPL version 3. This keeps the products freely available to end-users, but also ensures that people who use this code in their own projects will re-release their improvements to the public. This way, the amateur radio community will have free access to any improvements that might go into any commercial product based on the software or firmware.

SmallDV 1.0 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

2018-05-29 - Initial release.
2018-06-01 - Add support for tuning indicator.
2018-06-02 - Add support for SYNC LED output.
2018-06-08 - Fix bug in RX audio path in fdvcore.
2018-06-10 - More improvements to efficiency, and fix bugs in fdvcore's PASS and MUTE modes.
2018-06-14 - Fix bugs in the filter class used for resampling.
2018-06-19 - Fix buffer limit to better support 700D.

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