DEVCAL(1)

DEVCAL(1) 🎀 User Manuals 🎀

okay so bestie, gather round, because this one is devcal — an FM deviation calibration utility for the SvxLink system — and it's genuinely one of those tools where if you read the whole page you come out the other side a changed person. let's get into it 💅

---

✨ NAME ✨

devcal — An FM deviation calibration utility for the SvxLink system

---

🌸 SYNOPSIS 🌸

devcal [-?|--help] [-h|--usage] [-f|--modfqs=frequencies in Hz]
       [-d|--caldev=deviation in Hz] [-m|--maxdev=deviation in Hz]
       [-H|--headroom=Headroom in dB] [-r|--rxcal] [-F|--flat] [-M|--measure]
       [-w|--wide] [-a|--audiodev=type:dev] <config file> <config section>

---

💖 DESCRIPTION 💖

so devcal is the utility you use to calibrate the input and output sound levels (aka the deviation) on an FM SvxLink system. the whole dream here is that you should be able to calibrate multiple parts of a SvxLink system to the exact same sound levels. why do we care? because:

• a system rocking multiple receivers will then have the same sound level on all of them, no cap 🫶
• for a repeater, it means the audio being retransmitted is at the same level as the received audio ✨
• for an EchoLink system, it guarantees that audio received by the local node is at a proper level to be retransmitted on remote EchoLink nodes — and the other way around 🌈

also, an RTL2832U based DVB-T USB dongle can be used to measure deviation, and devcal can also be used to calibrate the receiving frequency correction for one of those dongles. iconic.

deviation calibration can be done both with and without a DVB-T USB dongle. both methods are described below, so keep scrolling bestie 💜

---

🦋 OPTIONS 🦋

• -?, --help — print a help message and exit. simple. clean. periodt.
• -h, --usage — display a brief help message and exit. (yes it's different from --help, we don't make the rules)
• -f, --modfqsfrequencies in Hz — use this command line option to set at what frequencies you want to calibrate the deviation. separate multiple frequencies using commas. the default frequency is 1000Hz.
• -d, --caldev=deviation in Hz — the deviation value at where to perform the calibration. the default value of 2404,8Hz may seem strange but it will be explained below (spoiler: Bessel nulls 👀).
• -m, --maxdev=deviation in Hz — the maximum deviation used on the channel. this is the deviation value where transmitters start to limit the deviation so as not to cause interference in neighbouring channels. the default value is 5000Hz.
• -H, --headroom=headroom in dB — the headroom is the margin to add above the maximum deviation level. adding a headroom will allow SvxLink to handle levels above the maximum deviation level without causing immediate distortion. the default is 6dB, which means SvxLink can handle twice the specified maximum deviation. if both maxdev and headroom are left at their default, this will mean that SvxLink can handle 10kHz deviation without distortion.

⚠️ changing the headroom causes a lot of different effects so don't do that unless you are prepared to deal with the problems. for example, increasing the headroom will cause the TX level to get lower and the RX level to get higher, which then must be compensated. the announcement levels will get lower so they also need to be compensated. the EchoLink RX/TX levels will get unbalanced and at the moment there is no way to fix that. 😭

• -r, --rxcal — specify this command line option to perform receiver calibration.
• -t, --txcal — specify this command line option to perform transmitter calibration.
• -F, --flat — perform calibration on a transmitter or receiver that has a flat frequency response (no pre- or de-emphasis). if the transceiver has flat frequency response but you have enabled pre-/de-emphasis in SvxLink, this option should NOT be specified. 🫣
• -M, --measure — the measurement mode requires the use of a RTL2832U based DVB-T USB dongle and will measure the received deviation.
• -w, --wide — use wide FM (broadcast) instead of narrow band FM.
• -a, --audiodev=type:dev — use this command line option to set an audio device to use for playing back the received audio. the default is to use "alsa:default". disable audio output by setting the audio device to the empty string (i.e. --audiodev="").

---

🌈 CALIBRATING AN RTL2832U BASED DVB-T USB DONGLE 🌈

okay so all RTL2832U based DVB-T USB dongles require calibration so that the specified receiving frequency is correct. most dongles are way off in frequency. 50-60ppm is not uncommon which translates to more than 20kHz on 434MHz. 💀

most dongles are sensitive to temperature change, so start by plugging the dongle into the computer and let it warm up for like 15 minutes before doing the calibration. give it a little spa moment, it's earned it 🧖

devcal needs a receiver configuration file to work, so such a file must be created before this utility can be used. read the Ddr Receiver Section and the Wideband Receiver Section in the svxlink.conf(5) manual page for information on how to set it up.

a first coarse calibration should be done in wideband mode so that the calibration carrier is easy to find. you can use any FM carrier to calibrate on that you know is correct in frequency. it does not matter if the carrier is modulated or not. use your own transceiver or a repeater for example. if the frequency calibration is unknown for the transmitter being used, it may be wise to test with multiple transmitters. the command line may look like this:

devcal -Mw /path/to/svxlink.conf RxRtl

the utility will print, among other things, the carrier frequency error. it may look something like:

Tone dev=7.30  Full bw dev=39198.90  Carrier freq err=-27713.53(-64ppm)

we ignore the first two values for now and concentrate on the carrier frequency error. the -64ppm mean that the dongle is receiving the transmitted carrier about 27kHz below the set frequency. to compensate for this, set the FQ_CORR configuration variable in the wideband receiver configuration section to 64. do another measurement to verify that the received carrier frequency is now closer to the expected one. 🔥

now we can do the final calibration in narrow band mode. remove the "w" command line option from the command above and do another measurement. adjust FQ_CORR until a value around 0ppm is shown. slay. 💅

---

💜 CALIBRATING THE TRANSMITTER 💜

in order to calibrate the transmitted deviation we need a way to measure it. there are multiple methods to do that. if you have a deviation meter you're in luck, but most people do not own one of those. fortunately there are other ways. 🫶

one way is to use a RTL2832U based DVB-T dongle with the devcal utility. first calibrate the DVB-T dongle according to the instructions in the previous section. the devcal utility can then be used in measurement mode to measure the transmitted FM deviation. the measurement mode is activated using the "-M" command line option. use the "-f" command line option to specify the audio frequency to calibrate at if the default of 1000Hz need to be changed.

another way to measure FM deviation without a deviation meter is to use the Bessel null method. it makes use of the fact that the FM carrier will go down to zero power for certain combinations of modulation frequency and deviation. the deviation divided by the modulation frequency gives something called the modulation index. Bessel nulls occur at specific modulation indexes where the first one is at 2.4048. so, if we choose the deviation to 2404.8Hz and the modulation frequency to 1000Hz we should get a Bessel null when the transmitter is calibrated. these are the default modulation parameters in devcal. ✨ (see? we told you the weird default would be explained)

so how can we detect when the carrier power goes down to zero? if you own some form of spectrum analyzer the spectrum can be watched to see when the carrier falls down to zero. if you own a CW receiver that covers the frequency of interest you can use that to listen to the carrier. start devcal in transmitter calibration mode using a command looking like the one below.

devcal -t /path/to/svxlink.conf Tx1

in another window, start the alsamixer utility or some other utility to adjust the audio output level. set the output level to zero. go back to the devcal window and press 0 to set MASTER_GAIN to zero. press T to start transmitting. since we set the sound output level to zero, only a carrier will be transmitted. adjust the CW receiver to center on the carrier. use the narrowest filter that the receiver supports. now start increasing the audio output level in alsamixer. listen to the tone to find the first minimum. use the +/- keys in deval to fine tune the output level to a minimum. you have now found the calibration values for the transmitter. the printed value of MASTER_GAIN should be entered into the configuration section for the transmitter. 👑

---

🎀 CALIBRATING THE RECEIVER 🎀

to calibrate the receiver we need a transmitter with a known calibration. if possible, the transmitter that was calibrated above can be used. if it's not possible, another transmitter can be calibrated in the same way to be used as a calibration transmitter. start the devcal utility something like this:

devcal -r /path/to/svxlink.conf Rx1

start alsamixer in another window and adjust the input level to get as close as possible to the expected deviation. use the 0, + and - keys to adjust PREAMP to fine tune the deviation that is shown. when satisfied, enter the PREAMP value into the configuration file in the receiver section. 🌸

---

part 1 of 2, bestie — there's more coming, don't go anywhere 🦋

✨ EXAMPLE: CALIBRATING USING A DVB-T USB DONGLE ✨

Okay bestie, here's the whole vibe of how the calibration procedure might actually go down — using a DVB-T USB dongle and some arbitrary transmitter, like a lil handie transceiver. 🎀

Your calibration transmitter (a handie, in this case) has to be able to send some form of modulated tone for this to work, no cap. The 1750Hz tone burst that tons of transmitters ship with? Iconic choice. You can also use a DTMF tone, but the results aren't as good as a single tone, apparently. 😭 If you're going the DTMF route, try the code "A" (1633Hz) or "3" (1477Hz). In this example though, we're doing the 1750Hz tone burst, periodt.

Step one: use the DVB-T dongle to measure the deviation of the 1750Hz tone.

devcal -M -f1750 /path/to/svxlink.conf RxRtl

Start transmitting with the calibration transmitter and wait for the values to stablilize (yes bestie, hold still, let it cook 🫶). Take a note of the value for "tone dev" — it might be something like 3200Hz, which is what we'll use in the example below. Leave deval running since we'll need it later on. 👑

Next: on the system being calibrated, start the receiver calibration.

devcal -r -f1750 /path/to/svxlink.conf Rx1

Transmit using the calibration transmitter and adjust the input level using alsamixer and PREAMP to the correct level for "tone dev". 💅

Make sure devcal is started in measurement mode, like when the deviation on the calibration transmitter was measured above. Then, on the system being calibrated, start the transmitter calibration.

devcal -t -f1750 -d3200 /path/to/svxlink.conf Tx1

That 3200 was the one we measured in the first step — swap it for your own measurements, obviously. 🦋 Adjust the output level using alsamixer and MASTER_GAIN to get the correct reading for "tone dev".

Wanna check the calibration? Use devcal in measurement mode to measure the deviation on the transmitter when it's retransmitting a received signal. For a repeater, that's easy-peasy — just transmit on the receive frequency using the calibration transmitter. The deviation measurement should show the correct value being retransmitted. For a simplex link, the parrot can be used to achieve the same thing. 🦜✨

NOTE: The retransmitted deviation may not be exactly the same for some transceivers. This is an issue that remains to find the cause of. 😭 (not me being haunted by an unsolved mystery)

---

🌈 ENVIRONMENT 🌈

• ASYNC_AUDIO_NOTRIGGER — set this environment variable to 1 if you get an error about ioctl: Broken pipe during devcal startup when using OSS audio. 💀
• ASYNC_AUDIO_ALSA_ZEROFILL — set this environment variable to 0 to stop the Alsa audio code from writing zeros to the audio device when there is no audio to write available. 🎧
• ASYNC_AUDIO_UDP_ZEROFILL — set this environment variable to 1 to enable the UDP audio code to write zeros to the UDP connection when there is no audio to write available. 📡

---

👑 AUTHOR 👑

Tobias Blomberg (SM0SVX) <sm0svx at svxlink dot org> — the legend herself. 🙌

---

💀 REPORTING BUGS 💀

Bugs should be reported using the issue tracker at https://github.com/sm0svx/svxlink. 🐛

Questions about SvxLink should not be asked using the issue tracker — nope, not the vibe. Instead use the group set up for this purpose at groups.io: https://groups.io/g/svxlink 🫶

---

💖 SEE ALSO 💖

svxlink(1), remotetrx.conf(5), svxlink.conf(5), siglevdetcal(1) — go read your sisters, bestie, they ate. 📚✨

---

and that's the whole page, bestie!! 🎀 this lil manual page is from the Linux crew, dated AUGUST 2021, and it's filed under DEVCAL(1) — slay, calibrate, and go touch some grass. 💅🦋