Northern
Utah
WebSDR

Nothern Utah WebSDR Logo - A skep with a Yagi 		Using Configuration files in KA9Q-Radio


Important:

This document represents an effort on my part to understand the operation of "ka9q-radio" and is not intended to be authoritative.

As such, this is a work in progress and will certainly contain many "blank spots" and errors.  What it is intended to do is to help the new user along and start to get the "feel" of how the pieces go together.

Please read EVERY document in the /docs directory of the "ka9q-radio" git - and refer back when you see something you don't understand!

For more information about ka9q-radio, go here:
Using KA9Q-Radio - link

This page has much more information about the internal workings of ka9q-radio and other examples of its use.


Configuration files used by ka9q-radio

ka9q-radio requires a number of configuration files and with these, one may define a bewildering assortement of virtual receivers and modes.  The authoritative document on this subject is "ka9q-radio.md" found in the /docs subdirectory of the .git, located at:  https://github.com/ka9q/ka9q-radio/blob/main/docs/ka9q-radio.md

There are several different types of configuration files that are needed:
 There is a lot of overlap between these as the same types of parameters can appear in several places - particularly when a default configuration is defined (e.g. sample rate, mode) but you wish to override this (say, in a receiver configuration) to use something different.

IMPORTANT - Back up your .conf files!

As of the time of this writing (June, 2023) the default configuration files WILL BE OVERWRITTEN every time you do an update/make of ka9q-radio.  Both the files in the home "~/ka9q-radio" and "/etc/radio" directories can be overwritten.

What this means is that if you modify the original configuration files (e.g "/etc/radio/rx888d.conf", "/etc/radio/radiod@hf.conf" - and those in the "ka9q-radio directory) you will LOSE those modifications when you do an update.

When you make changes to ANY configuration file, be sure to save a copy elsewhere, and be prepared to restore it after you do updates.

It is on the list of future updates to change this behavior.



Sections of .conf files

The .conf files are broken into various sections where different sets of parameters may be defined.  For example, in those used by "radiod", the first section is the "[global]" section where one may specify a default mode and output sample rate - but also parameters related to the handling of the FFT algorithm being used to process the raw data from the receiver hardware.

In many .conf files, the next sections are used to define aspects related to that file.  For example, in the "radiod" .conf files, sections are defined in order to place groups of frequencies in similar categories:  For example, if you wanted to monitor WWV propagation, you might create a "[WWV]" section where you place all of the virtual receivers that demodulated WWV frequencies, another section where you have defined virtual receivers for the WSPR frequencies, etc.  In the "modes.conf" file, you might use these individual sections where you define various modes (e.g. [usb], [am], etc.)

Example of a radio hardware .conf file

Note:  The working versions of these files are located in the /etc/radio directory.  They will exist in the "ka9q-radio" directory as well, but if you make changes to those files, nothing will happen - ONLY the changes that you make to the files in /etc/radio will have an effect!

To check:  It appears that the files in /etc/radio may get overwritten when updated from github and/or when one invokes the Makefile.

Let us consider the file "rx888d.conf":

[g5rv]
# ka9q customized
description = "G5RV RX888"
firmware = SDDC_FX3.img
samprate = 64800000    ;  2^8 * 3^4 * 5^5
# needs fftw3 wisdom and/or fft-threads >= 4 and some buffer tuning
# seems to lose data in the network path
# forward FFT for 129,600,000 Hz, 20ms and overlap = 5 is 3240000
#samprate = 129600000    ;  2^9 * 3^4 * 5^5
iface = eth0               ; force primary interface, avoid wifi
status = rx888-status.local
data = rx888-pcm.local
ssrc = 10
;gain = 1.5 ; dB
gain = 10 ;dB - near floor of NF curve, still not too high for my G5RV
gainmode = high ; higher gain range

Note:  For the radio hardware configuration file, a number of the parameters are specific to the receive hardware being used and their availability and usefulness will vary depending on that hardware.  For example, the rx888d does not have a tuned frequency like other hardware (e.g. airsply, RTL-SDR dongle, SDRPlay) as it - when used on HF - can simply "inhale" the entire spectrum, making "tuning" irrelevant.

In the above we see the heading of the section [g5rv]:  This name is arbitrary and in this case, it refers to a hypothetical antenna and the configuration one might use with that antenna.  If you want to experiment with different hardware configurations, you can add additional sections below this.

In this case, this configuration file is invoked as:  

./rx888d g5rv

or, as a services, as:

systemctl start rx888d@g5rv.service

About the fields:
 More than one configuration

It is possible to have more than one configuration within this .conf file.  For example, if you were experimenting with different gain values, antennas, or sample rates, you could define such.  For example, if you wanted to have a section called "[dipole]", you would simply repeat the configuration under the [g5rv] section and make the desired changes, and when you invoked it you would simply substitute "g5rv" for "dipole" as follows:

./rx888d dipole

or, as a services, as:

systemctl start rx888d@dipole.service


Example of a "radiod" configuration file

While the "hardware" configuration file is specific to the SDR hardware in question, the "radiod" configuration is not.  This provides a layer of abstraction in that as long as your raw data from the receiver contains the frequency-related signal data that we want, the configuration and operation of "radiod" is more or less agnostic to your receiver hardware.  In other words, if you were to have configured a set of receiver configurations with an Airspy, RTL-SDR or SDRPlay receiver, you can likely replace it with an RX888 and make few - if any - changes.

As an example, let is consider the file "radiod@hf.conf" a piece at a time.

ALL radiod configuration files MUST start with a "global" section - and consider this example:

[global]
overlap = 5
blocktime = 20
input = rx888-status.local
samprate = 12000
mode = usb
status = hf.local
fft-threads = 4

This is the only section of a radiod configuration file that may be specific to the receiver hardware in that one might use different "overlap" or "blocktime" values with much lower sample rates.  Taking each line:
 The next several parameters are optional in the "global" section.
 There are a few other parameters discussed in the "docs/ka9q-radio.md" file that are either rarely used or not (yet) fully supported.

After the "[global]" section

One of the most powerful aspects of the way ka9q-radio works is that after the initial "work" on the FFT is done, extracting signal from the resulting data is almost "free"-  in terms of CPU power by comparison.

What this means is that in our example of a 64.8 Msps sample rate, we have already ingested and partially processed every signal across the VLF, LF, MF and HF spectrum, and that it takes relatively little extra processing power to demodulate it in some way.  In other words, a modest Intel i5 or i7 processor, with an RX888 you can receive and demodulate hundreds of individual frequencies simultaneously.

As noted elsewere on these pages, the resulting received data is conveyed using Multicast:  The more traditional way of having a separate audio channel (how would you use and define hundreds audio streams in ALSA/Pulsaudio/Pipewire?) simply doesn't apply here - and using Multicast means that the "one to many" model may be easily implemented.  Since multicast is UDP and connectionless, they can simply be "listened to" on the LAN by any number of clients without incurring any additional load whatsoever on the server.

For example, if we were do demodulate, individually, every WSPR, FT-8, FT-4, SSTV, WWV and CHU frequency simultaneously and also have a 96 kHz chunk of the CW band for each of the HF bands for, say, a CW skimmer, all of that "audio" data would be available to any and all computers on the same LAN as the computer hosting the receiver hardware - and since Multicast is a "broadcast", more than one computer on the LAN could use that same data.  (Note that Multicast data cannot be easily conveyed across the Internet or wireless connections and some types of LANs bounded by routers/switches - but that's a topic for the network admins!)

In the sections of the radiod .conf file after the [global] section we can define virtual receivers individually - or as groups of receivers of similar content.  Consider the following example from the same "radiod@hf.conf" file:

[WWV]
data = wwv-pcm.local
mode = am
freq = "2500k 5000k 10000k 15000k 20000k 25000k"

Here we have defined six virtual receivers tuned to the WWV/H frequencies of 2.5, 5, 10, 15, 20 and 25 MHz and overriding the earlier default of "usb" in the [global] section, specifying the use of AM for this group of receivers.  All six of these receivers are conveyed on a single multicast stream called "wwv-pcm.local" as defined by the data parameter - so how does one specify how to extract each one?  Mentioned in the "rx888d.conf" file is the "ssrc" and here we use that parameter to specify the sub-stream carrying the individual frequency.

By default, ka9q-radio will assign the ssrc as the digits within the frequency parameter.  For example, if we want to listen to the 10 MHz WWV audio, we would remove the "k" from the frequency and use an ssrc of 10000 to extract it from the multicast stream called "wwv-pcm.local":  See the example for the "pcmcat" and "pcmrecord" commands in "KA9Q-Radio Command Overview" file for the use of the multicast name and ssrc.

In above example we also see that we have selected mode "am", overriding the default in the [global] section.  If you wish to have a new "mode", this may be defined in "modes.conf" - see below.

More on the "freq" parameter and how it defines the related ssrc

In the example above we have defined the frequency in kHz, with 2.5 MHz being 2500 kHz, or "2500k".  It is also permissible to define it in Hz, as in "2500000" or as MHz, as in "2m5".  Also mentioned was the fact that the ssrc - which is needed to identify the sub-stream with a particular receiver - uses the string of characters - letters removed - to construct the ssrc - so one must be careful as the following examples illustrate, each correctly defining a 2.5 MHz receive frequency - but in diffrent ways:
 What the above tells you is that you must be careful and consistent in the way you define frequencies so that your SSRC can be easily divined from them.

Practically speaking, you would represent the frequencies in each group in the same way so you would never be likely to have name conflict:  You also would not specify two identical instances of the same receive frequency, anyway, since as a multicast stream, multiple users/computers could intercept it!  Finally, if you did need to specify another instance of WWV in another receiver groups - say, one to "hear" the audio and another to monitor signal strength - the ssrc would not overlap, anyway, as that "other" group would have a different multicast address!

Comments:
In some cases you might want a large number of frequencies in a single section - an example being wanting to create a section called "2MRPT" where you might specify the frequency of every 2 meter repeater output on the band and have all of the outputs of these virtual receivers conveyed by a single multicast stream. While it might be possible to enter all of these on a single "freq" line, the parser (in "libiniparser" library) actually does have a limit on the length of the line. (Question:  What is this limit?)

To spread out a long list of frequencies onto multiple lines - which can also make it easier to manage and read - but having multiple lines using the "freq" heading is not  permitted.  A work-around exists:  There are ten "aliases" of the "freq" field and these are "freq0" through "freq9", allowing your long list of frequencies to be placed on multiple lines as if there was a single line.  Note:  You can actually have 11 "freq" lines as you can use "freq", then "freq0", "freq1" and so-on.


The "default" or "prototype" receiver:

At the very end of the "radiod@hf.conf" file we note the following definition:

[HF MANUAL]
data = hf-pcm.local
freq = 0

When "freq" is zero, we have a special case:  This creates a "protype" receiver that can be summoned into existance when, via the "control" program, we specifiy an previously-unused ssrc.  Using the "control" program (see "KA9Q-Radio Command Overview") we can configure this receiver to any frequency, mode or bandwidth covered by the SDR hardware.

Optional parameters

The above shows a minimal example of what can be defined, but there are other parameters that may be included to define a receiver group:

The "modes.conf" file

Mentioned previously, one can arbitrarily define "modes" in ka9q-radio.  In this context, a mode can be any combination of:
 There are, no doubt, other cases where one might wish to define a "mode" for a specific application - the limit being mostly that of your imagination.

The "modes.conf" file contains a number of pre-defined modes, and we'll discuss of of these below.
Important note about squelch operation in FM and PM modes:
In the "FM" and PM modes, the squelch is always enabled and as of the time of this writing, it cannot be completely disabled.  What this means is that if you define an FM receiver and NO signal is present, "radiod" will not output any audio data.

In other words, unless a virtual FM or PM receiver detects a signal that opens the squelch, no multicast audio will be generated for that receiver and you will see/hear nothing at all from it!


PM (Phase Modulation)
As mentioned above, on amateur radio the mode that we call "FM" is really "PM" (Phase Modulation).  In short, PM may be generated on an FM transmitter by boosting the audio at a rate of 6 dB/octave - which is to say that a given amplitude of tone at 1 kHz which causes +/- 2 kHz of deviation will, with a 2 kHz tone at that same amplitude will cause +/- 4 kHz of deviation.  Doing this "boosting of highs" cleverly reduces one of the unfortunate aspects of "true" FM:  When a signal gets weaker, it's is the high audio frequencies that get noisy first.  By making the high frequency component of the audio "louder" during transmit means that as the signal gets weaker and the noise starts to encroach, those high frequencies - being "pre-boosted" - will survive above the noise level better with weaker signals.

On the receive end, the highs are "un-boosted" by precisely the same amount as they were boosted on transmit.  By doign this we not only restore the frequency response to its original level ("PM" audio on a "true" FM receiver sounds very tinny and shrill) but as the signal gets weaker and the noise appears in the high frequency audio, this, too, is reduced - improving the apparent signal-noise of the signal.

Within the modes.conf file we see the following entry for PM - which, again, is the mode that we use on VHF and UHF:
[pm]
demod = fm
samprate = 24000
low =  -8000
high = +8000
squelchtail = 0
threshold-extend = yes ; PM assumes voice mode, so enable this

Note:  De-emphasis is enabled by default in ka9q-radio - see the comments about this in the [fm] section, below

Breaking this down:
See the "comment" section at the bottom of the "NFM" section, below for a note about the setting for de-emphasis in "PM" mode.


Now let us look at the "Narrow FM" entry in the modes.conf file:

[nfm]
demod = fm
samprate = 24000
low =  -6250
high = +6250
deemph-tc = 0
deemph-gain = 0
threshold-extend = no ; don't interfere with packet, digital, etc

Let's take a look at the differences between [pm] and [nfm]:
 You might ask "If we don't use 'true' FM on amateur radio, why have this?".  This would be true for analog voice, but you would use "true" FM for many digital voice modes like D-Star, C4FM (Yaesu Fusion) and FSK (e.g. that used for 9600 baud packet) and similar which do NOT use pre-emphasis.  Because of the possiblity that the "threshold-extend" can slightly mess up the signal - something that we wouldn't notice when listening to voice - we turn it off to keep it as pristine as conditions allow.

Comment:

You might wonder why in "true FM" mode we explicitly disable the de-emphasis while in "PM" mode we don't specify anything at all?  As it turns out, in the ka9q-radio code there are default value set for "deemph-tc" and "deemph-gain" which are 530.5 microseconds (which translates to 300 Hz) and 12 dB, respectively.

What this means is that in the [pm] definition, above, our de-emphasis begins at about 300 Hz, rolling off at 6 dB/octave above that frequency - and the "deemph-gain" is 12 dB to boost the audio to make it "sound" like the right loudness as the rolling-off by the de-emphasis necessarily reduces the amplitude of the upper audio frequencies.  Since most amateur transmitters filter out voice below 300 Hz, anyway, we won't really miss it - particularly because control tones like subaudible and DCS signals reside in the frequencies below 300 Hz and are typically filtered out on receive by modern radios.

It may seem to be a bit confusing to have the default for "fm" actually being appropriate for "pm" - and it confused me initially, but it makes sense since "pm" would be more-commonly used for VHF/UHF amateur communications than "true FM".

Now let's look at a USB mode definition:

[usb]
demod = linear
samprate = 12000
low =    +50
high = +3000

Additional parameters in "modes.conf":

In addition to the above, there are quite a few parameters that can be used to configure a "mode".  For examples of the use of some of these, please take a look at the "modes.conf" file.  In the section below, you will see some of the parameters that have already been discussed, offered here for completeness.

The "id.txt" file

Note:  Unlike other configuration files, this resides in the same directory from which "radiod" is called.

This file contains a list of frequencies or more precisely, a list of SSRC values with an accompanying description in the format on each line, comment lines begun with a hash (#):

# <your comment here>
<ssrc>   <description>

As in:

#2 meter repeater output frequencies
146620  W7SP Farnsworth Peak (SLC)
146700  KC7IIB Ensign Peak  (SLC)

The format couldn't be simpler!

A word about ssrc and frequency descriptions:

As noted again and again in the documention, the "ssrc" value is automatically derived from the frequency value by removing everything but the digits - but its exact representation will depend on how you defined the frequency in the relevant radiod ".conf" file.

For example, here are some sample frequency descriptions - all for the same frequency of 14.234 MHz - but with DIFFERENT ssrc values:
 As you can see, it is imperative that your frequency definitions are consistent.

There are some "gotcha's", however.  Let's presume that you have defined several frequencies with exact kHz boundaries - perhaps a repeater output - but then you find out that there's a repeater running 2.5 kHz deviation on 145.1375 MHz.  Previously, you may have defined frequencies like 146.520 MHz (the U.S. national simplex frequency) as "146m520" which results in an SSRC of "146520". which has six digits.  The possible issue arises when you define the frequency of 145.1375 MHz as "145m1375" which has an SSRC of "1451375" which has seven digits.

The to most obvious options are:



Please note:
This document is a work in progress and the function of many of these auxiliary programs is not (yet) understood by the author - particularly the descriptions that begin with "Source code says..." or contain the words "To Do".

TO DO:


For more information about ka9q-radio, go here:
Using KA9Q-Radio - link

This page has much more information about the internal workings of ka9q-radio and other examples of its use.

Additional information:
 Back to the Northern Utah WebSDR landing page