Two Radios at Once: the CaribouLite HAT
- Why this matters
- The board
- The tool
- What your receiver invents
- Both radios at once
- Transmitting: when the rules stop being advice
- There is no sandbox on 70 cm
- Narrow on purpose
- Worked example: an identified transmission
- Three things the hardware does that the API does not mention
- Confirmed with an external receiver: it does not radiate
- Narrowing it down: the RF front end is fine
- What it actually points at
- A fix exists, and was never merged
- Building the fix, and what it takes
- The sync bit flips
- Confirmed on the air: +62.3 dB
- Proving the modulation survives, not just the power
- What the output looks like — and a measurement to distrust
- The trap: I measured my own receiver
- The RF gain really is inert — and it is a one-line bug
- One more thing the rate sweep found
- Cleaning up the output: the carrier and the image
- Three ways this measurement lies
- What the correction is worth
- The hardware has its own trim, and it is six bits
- Searching the trim codes, and why one run cannot do it
- The two corrections are not in the same basis
- What to actually run
- It does not survive a reboot
- Making it stick
- Listening before transmitting, and the third artifact test
- Where the real work was
- Key takeaways
- References
Why this matters
Most of the radio work in this course points one receiver at one band and asks what is there. That is the right first move, and it quietly assumes something that is often false: that the interesting behaviour happens in one place.
It usually does not. A sub-GHz sensor talks to a hub; the hub talks to the cloud over WiFi. A key fob transmits at 433 MHz; the car it opens is running BLE at 2.4 GHz. Thread and Matter devices commission over one radio and operate over another. When you watch one band you see one half of a conversation, and the half you cannot see is usually where the decision gets made.
The CaribouLite is a $119 Raspberry Pi HAT with two independent receivers, one sub-GHz and one that reaches 6 GHz. That makes it a cheap way to watch both halves. It is also, for our purposes, something more useful: a board whose quirks force you to confront the difference between a signal that is really there and a signal your receiver invented. That distinction matters far beyond this HAT.
This page is about what the hardware does and what it fools you into believing.
The tool and the full enablement procedure live in
cariboulite/ with its
operator’s manual.
The board
Two radios hang off a single Microchip AT86RF215 transceiver, with a Lattice iCE40 FPGA moving samples into the Pi:
| Radio | Front end | RX tuning |
|---|---|---|
| S1G | AT86RF215 sub-GHz | 389.5–510 MHz and 779–1020 MHz |
| HiF | AT86RF215 2.4 GHz + RFFC5072 mixer | 1 MHz – 6 GHz |
13-bit samples, up to 4 Msps, half duplex. Both radios can transmit, which on most of that range you may not legally do — see Transmitting legally on the rflink page; the rules are the same.
Two things in that table deserve attention before you tune anything.
S1G is not one range. There is a hole between 510 and 779 MHz. Ask for 600 MHz and you get an error, not a nearby frequency — which is the correct behaviour, and still surprising the first time. The two windows exist because the AT86RF215’s sub-GHz section is built for the 433, 868, and 915 MHz ISM allocations and the bands around them, not for continuous coverage.
HiF only reaches 6 GHz on some boards. The AT86RF215’s 2.4 GHz section natively covers 2385–2495 MHz. Everything else in that 1 MHz – 6 GHz figure comes from a Qorvo RFFC5072 mixer that is fitted only to the FULL version. The cheaper ISM version has the same transceiver and no mixer. Ask the EEPROM which one you are holding:
$ tr -d '\0' < /proc/device-tree/hat/product
CaribouLite RPI Hat
product_id 0x0001 is system_type_cariboulite_full; 0x0002 is ISM.
Note also that the plugin advertises HiF from 1 MHz while the project documents the board as 30 MHz – 6 GHz. Below 30 MHz you are outside what the vendor claims, which is not the same as it working.
The tool
cariboulite_demo.py exercises both radios: it enumerates them, prints their
capabilities, captures IQ from each, and analyses the spectrum. It is
receive-only — the transmitter is never keyed — so it is safe to run with
antennas connected.
Worked example: both radios, three captures
$ ./cariboulite_demo.py
SoapySDR 0.8.1-5+b2 / API 0.8.0
found 2 radio(s): HiF, S1G
HiF CaribouLite HiF[eb9c2541]
S1G CaribouLite S1G[eb9c2540]
==============================================================================
S1G radio (AT86RF215 sub-GHz) @ 433.9200 MHz
==============================================================================
antennas: TX/RX Sub1GHz
RX tuning: 389.5000 MHz - 510.0000 MHz | 779.0000 MHz - 1.0200 GHz
tuned: 433.9199 MHz (requested 433.9200 MHz, error -0.1 kHz)
config: 2 Msps, gain 39 dB manual, antenna 'TX/RX Sub1GHz'
stream MTU: 131072 samples
drained 131072 samples in 0.112 s (queue drain, NOT an RF rate)
sustained rate: 2.000 Msps over 1.0 s (configured 2, 100.0%)
RMS level: -51.6 dBFS
peak |IQ|: 0.0038 (1.0 == clipping)
DC/LO spur: 29.8 dB above median (zero-IF LO leakage; expected)
strongest peak: 433.6074 MHz (-0.312 MHz from centre, DC notch excluded)
peak prominence: 76.9 dB above median
spectrum (432.9199 MHz .. 434.9199 MHz):
| . ..:::--=:.@..:-:.. |
-109 dB -32 dB
RESULT: PASS -- radio streamed and spectrum looks sane
...
==============================================================================
SUMMARY
==============================================================================
test frequency result detail
S1G radio (AT86RF215 sub-GHz) 433.9199 MHz PASS -51.6 dBFS, peak +76.9 dB, 2.00 Msps
HiF radio (2.4 GHz native) 2.4370 GHz PASS -56.3 dBFS, peak +23.0 dB, 2.00 Msps
HiF radio (mixer path) 1.0900 GHz PASS -45.6 dBFS, peak +31.9 dB, 2.00 Msps
3/3 passed
Both radios exercised successfully.
The third case is the one with teeth. 1090 MHz is outside the AT86RF215’s native 2385–2495 MHz window, so it is reachable only through the mixer. Passing at 2.437 GHz proves the radio works; passing at 1090 MHz proves the mixer does. Testing only the easy frequency would let a half-broken FULL board look healthy.
What your receiver invents
Here is the lesson worth taking away from this board, and it generalises to every direct-conversion radio you will ever use.
The first version of this tool reported the single strongest bin in the spectrum. Every test found a powerful carrier. Every test was wrong.
The AT86RF215 is a zero-IF, or direct-conversion, receiver: it mixes the signal you want straight down to baseband using a local oscillator at the tuned frequency. That is cheap and compact, and it has a structural consequence — any leakage from that oscillator into the signal path lands at exactly 0 Hz baseband, which is to say exactly where you tuned. Combine it with DC offset in the ADC and you get a permanent spike in the middle of your own passband, here 26–30 dB above the noise floor.
A naive peak detector finds that spike every single time and calls it a signal. The fix is to measure it and exclude it:
DC/LO spur: 29.8 dB above median (zero-IF LO leakage; expected)
strongest peak: 433.6074 MHz (-0.312 MHz from centre, DC notch excluded)
Three tests that tell artifacts from signals
You do not have to guess. Change one variable and watch what moves:
| Change | Real signal | LO/DC artifact | Digital artifact |
|---|---|---|---|
| Retune the centre | stays at its absolute frequency | follows the centre | stays put |
| Change the sample rate | stays at its absolute frequency | stays at centre | moves with the rate |
spur_check.py runs the first test:
$ ./spur_check.py S1G 434.52e6 435.12e6
### tuned centre peak absolute peak offset prominence
### 434.5200 MHz 434.5200 MHz +0.0000 MHz 26.5 dB
### 435.1199 MHz 435.1199 MHz +0.0000 MHz 26.4 dB
The peak’s offset from centre is pinned at zero no matter where you tune. That is leakage, conclusively.
Apply the same discipline to the 76.9 dB spike in the worked example, and it comes out the other way: it sits at 433.6074 MHz and reads identically at 1, 2, and 4 Msps. Real carrier, really on the bench. The same arithmetic that condemns one peak exonerates the other, which is the point — the test does the work, not your intuition about how strong a signal “looks”.
This matters well beyond one HAT. HackRF has the same problem, which is why rflink deliberately places its signal 300 kHz away from the tuned centre rather than on it. If you take one habit from this page: before you believe a peak, move something and see whether it moves too.
Both radios at once
They do work simultaneously — and not at full speed. Opening both, draining both, then reading round-robin for five seconds on a Pi 4B, with no overflows reported at any setting:
| Configured each | Delivered each | Aggregate |
|---|---|---|
| 1 Msps | 0.667 Msps (67%) | 1.333 Msps |
| 2 Msps | 1.000 Msps (50%) | 2.000 Msps |
| 4 Msps | 2.000 Msps (50%) | 4.000 Msps |
At 2 and 4 Msps each radio gets exactly half of what it asked for, and the
1 Msps row only looks like an exception. listSampleRates() advertises
0.4, 0.5, 0.667, 0.8, 1.0, 1.333, 2, and 4 Msps, but measured against the wall
clock the board clamps every request below 4e6/3 up to 4e6/3:
| Requested | Reported by driver | Measured |
|---|---|---|
| 0.4, 0.5, 0.8, 1.0 Msps | 1.3333 Msps | 1.333 Msps |
| 1.3333, 2, 4 Msps | as requested | as requested |
So asking for 1 Msps each really runs the pair at 1.333 Msps, halved to 0.667
apiece. The rule is uniform after all: each radio delivers half the actual
rate, and the aggregate equals the actual rate. The lesson is not about
halving, it is that listSampleRates() offers rates this board will not use —
getSampleRate() reports the clamp honestly, so read it back, and measure if
it matters. A frequency axis built from the rate you asked for is wrong by
up to 3.3x, and every absolute frequency you derive from it is fiction.
The practical reading: for watching a sub-GHz device and its 2.4 GHz hub at the same time, ask for twice the sample rate you actually need, and verify you are getting it.
Transmitting: when the rules stop being advice
Everything above is receiving, where the only thing you can get wrong is your
own conclusions. Transmitting is different. The CaribouLite’s sub-GHz radio
covers 389.5–510 MHz, which means it covers the 70 cm amateur band, and the
moment you key it you are operating a transmitter under Part
97 —
licence, identification, band plan, and all. cariboulite_tx_demo.py is built
around that rather than bolted onto it:
- it refuses to run without
--callsign, and sends that call in CW before and after every transmission, because 47 CFR 97.119(a) requires identification “at the end of each communication, and at least every 10 minutes during a communication”. If a payload would run longer than nine minutes between IDs, the script refuses that too; - it checks the band plan against the whole occupied span, not the centre frequency; and
- it defaults to the lowest power the hardware supports, about −14 dBm.
There is no sandbox on 70 cm
Look at the ARRL band plan for 420–450 MHz and you will not find an “experimental, do what you like” slice. Every segment is spoken for:
| Segment | Assigned use | The demo |
|---|---|---|
| 432.00–432.07 | EME (Earth-Moon-Earth) | refuses |
| 432.07–432.10 | weak-signal CW | refuses |
| 432.10–432.30 | mixed-mode and weak-signal (432.10 is the calling frequency) | refuses |
| 432.30–432.40 | propagation beacons | refuses |
| 432.40–433.00 | mixed-mode and weak-signal work | refuses |
| 435.00–438.00 | satellite only, internationally | refuses |
| 433.00–435.00 | auxiliary/repeater links | warns |
| 445.00–447.00 | aux/control links, repeaters, and simplex (local option) | warns |
The weak-signal segments get a refusal rather than a warning for a reason: those are the parts of the band where people deliberately work each other at the noise floor, and a test carrier that is merely inconvenient in a repeater segment is destructive there. The demo’s default of 445.500 MHz sits in the shared local-option block, which explicitly includes simplex — the least objectionable home for a bench test, though still locally coordinated, so it is a default and not a recommendation.
Two further traps the script encodes. First, 420–430 MHz is not allocated to amateurs north of Line A (47 CFR 97.303(f)), which runs roughly parallel to and south of the Canadian border — irrelevant in Portland, disqualifying in Bellingham. Second, this is a zero-IF transmitter, so it leaks a carrier at the tuned frequency whether you want one or not. Generate your signal at a baseband offset and you radiate in two places, and the band check has to cover both:
occupied span : 445.49 MHz .. 445.502 MHz (signal + LO leakage)
Checking only the wanted signal is how you put a carrier in the satellite segment while believing you were clear of it.
Narrow on purpose
The board will happily stream 4 Msps. A 4 MHz-wide signal centred at 432 MHz would cover the EME, weak-signal, beacon and satellite segments simultaneously. The demo therefore sends a CW identification occupying about 90 Hz and a 2-FSK burst at 1000 baud with ±1 kHz deviation — roughly 3.4 kHz occupied — and prints both figures before it keys up. Both waveforms get raised-cosine edges: a hard-keyed carrier splatters, because the step discontinuity spreads energy far either side of where you meant to put it.
Worked example: an identified transmission
$ ./cariboulite_tx_demo.py --callsign AD7KM
call sign : AD7KM
identification: 'DE AD7KM' in CW at 20 WPM, sent before and after
payload : 'CARIBOULITE 70CM TEST DE AD7KM'
emission : 445.5 MHz
radio tuned to: 445.49 MHz (+10 kHz baseband offset)
LO leakage at : 445.49 MHz (zero-IF; unavoidable, weak)
duration : 10.14 s total
CW ID : 92 Hz occupied (99% power)
FSK burst : 1000 baud, +/-1000 Hz dev, 3351 Hz occupied
TX gain : 0 -> about -14 dBm (driver clamps to -14..+14)
occupied span : 445.49 MHz .. 445.502 MHz (signal + LO leakage)
NOTE: 445 MHz-447 MHz is auxiliary and control links, repeaters and simplex (local option)
KEYING TRANSMITTER
tuned : 445.49 MHz (error -80.0 Hz), gain readback 5
transmitted : 4057600 samples in 10.34 s (waveform 10.14 s)
transmitter off, identified at both ends.
--dry-run builds and measures the waveform, runs the band check, and
transmits nothing, which is how you should develop against this script.
Three things the hardware does that the API does not mention
writeStream() does not apply back-pressure. It accepted a 4.62-second
waveform in 0.02 seconds and returned success for every sample. Tear the
stream down after that and most of your transmission never reaches the air.
The fix is to pace writes against the wall clock and then wait out the
buffered tail; the demo reports elapsed time against waveform length so you
can see it working (10.34 s for a 10.14 s waveform, above) and warns if the
two diverge.
The documented gain mapping is wrong. The plugin converts Soapy TX gain to
cariboulite_radio_set_tx_power(gain - 18) and comments that gain 0 gives
−18 dBm, but that function clamps the sub-GHz radio to [−14, +14] dBm. Gain 0
is therefore about −14 dBm (40 µW) and gain 31 about +13 dBm (20 mW).
The board cannot hear itself. This was worth establishing properly, because it determines whether you can verify your own transmission:
| Transmitter | Receiver | TX gain | Samples received |
|---|---|---|---|
| S1G | HiF | 0 | none at all |
| HiF | S1G | 0 | 188 416 (≈38 ksps, 2% of rate), no tone detected |
| HiF | S1G | 10, 20, 31 | none at all |
Both radios receive simultaneously perfectly well, so the SMI bus carries two streams without difficulty — but any meaningful transmit power blanks the receive path completely. Verifying your own signal requires a second, independent receiver. Plan for that before you design an experiment around transmit.
Confirmed with an external receiver: it does not radiate
The demo’s own output cannot tell you whether anything left the antenna, and the board cannot hear itself, so this was settled with a HackRF Pro on a separate machine. The answer is the uncomfortable one.
Nothing was detected. At the default −14 dBm and again at full +13 dBm, with the HackRF tuned 200 kHz off to keep the emission clear of its own DC spur, three approaches all came back empty:
| Method | Result |
|---|---|
| baseline vs transmit capture | 2.3 dB at the expected bin, vs 3.1 dB with nothing transmitting |
| difference spectrum over the whole 2 MHz | no rise attributable to the keying |
| on/off keying inside one continuous capture, 3 bursts | +0.46 dB at the emission bin, uncorrelated with the key |
The last method matters because the first two are not trustworthy here: the local noise floor moved 10 dB between two captures taken minutes apart, which swamps any weak signal. Keying the transmitter on and off inside a single capture removes that, and the power trace at the emission frequency wandered independently of the keying.
That alone would not convict the board — the two machines might simply be too far apart. So the link was tested in reverse, with the HackRF transmitting keyed CW and the CaribouLite listening:
t_s delta_dB keyed
6.92 1.04 .
7.68 20.15 .
8.45 22.66 T
...
16.06 -4.34 T <- an inter-character gap in the CW
21.40 -0.08 T
22.16 -0.11 .
+16.4 dB mean lift, 20.9 sigma, and the dips inside the keyed windows are the gaps between CW characters. The path works and the CaribouLite’s receiver works. The same path, driven in the other direction by a transmitter the API reports as +13 dBm, produced nothing measurable.
The conclusion is that this board’s I/Q transmit path is not radiating.
activateStream returns 0, writeStream consumes every sample, the gain
reads back, the timing matches the waveform — and none of that is evidence
of RF.
Narrowing it down: the RF front end is fine
The same plugin has a second transmit path. setupStream accepts a CW=1
argument, which makes the driver take its cw_output branch instead of the
I/Q one. That branch overrides the modem’s DAC with constant I/Q values and
emits a bare carrier, with no SMI streaming involved at all. Keying it on and
off in Morse — which doubles as the station identification — and watching
445.500 MHz on the HackRF:
key-down mean -59.30 dB, key-up mean -70.19 dB
LIFT +10.89 dB
correlation between key state and received level: r = +0.693
The CW branch radiates. So the synthesiser, the PA, the antenna switch, and the antenna all work. Only the path that carries sampled I/Q to the modem fails. Four things were then ruled out, each rebuilt and re-measured against the HackRF with the same three-burst protocol:
| Change | Result |
|---|---|
uncomment the cmd_tx transition at cariboulite_radio.c:1223 |
+0.49 dB, 0.5 sigma — no |
also set .tx_control_with_iq_if = false, so the explicit state command gates TX |
+0.34 dB, 0.4 sigma — no |
force-reprogram the FPGA with the repo’s firmware/top.bin |
+0.21 dB, 0.3 sigma — no |
| pristine upstream code against the freshly programmed FPGA | +0.21 dB, 0.3 sigma — no |
That commented-out line is worth seeing, because it looks exactly like the bug and is not:
caribou_smi_set_driver_streaming_state(&radio->sys->smi, smi_stream_tx_channel);
caribou_fpga_set_smi_ctrl_data_direction (&radio->sys->fpga, 0);
//cariboulite_radio_set_modem_state(radio, cariboulite_radio_state_cmd_tx);
The CW branch ends with that exact call live; the I/Q branch has it commented out. Restoring it changes nothing measurable, so it is a symptom of unfinished work rather than the cause.
What it actually points at
In the I/Q branch the modem’s DAC is fed from its LVDS I/Q interface, which the FPGA has to drive from the SMI bus. Receive works, so modem → FPGA → SMI → Pi is wired up; transmit needs the reverse.
The FPGA sources are in the repository, under firmware/, and the transmit
path is there: lvds_tx.v exists, smi_ctrl.v exposes TX FIFO ports
(o_tx_fifo_push, o_tx_fifo_pushed_data, i_tx_fifo_full), and top.v
instantiates lvds_tx and wires it to those ports. The shipped top.bin was
rebuilt as recently as commit 1b34c56, and the history is full of transmit
work — “added TX channel to the FPGA firmware”, “update lvds tx verilog”,
“update and adapted firmware for tx”. So the datapath is not missing.
It is broken in a specific, documented way. Upstream
issue #189,
“AT86RF215 input IQ sync not reached on LVDS interface during TX”, reports
that the modem’s IQIFC2.SYNC status bit never becomes 1 while transmitting:
Status 'Is synchronized to incoming I/Q': 0
The modem never locks onto the I/Q stream the FPGA is sending it, so the DAC
is never fed and nothing is emitted — exactly the behaviour measured here.
Enabling the modem’s internal loopback does reach sync, which is why the
CW=1 path (which bypasses the LVDS stream entirely and overrides the DAC
with constants) radiates while the streaming path does not. The issue has
been open since February 2024, and a user reported the same thing again on
2 November 2025.
A fix exists, and was never merged
The reporter traced it — “The bug was in the fpga code. Now it’s syncing” —
and opened
PR #197, “Transmission of arbitrary waveforms”:
34 commits touching the FPGA, the kernel driver, and the library. It was
closed unmerged, silently, on 5 August 2025, with no review comments. The
central piece is a new firmware/lvds_clock_sync.v, alongside substantial
rewrites of lvds_tx.v, smi_ctrl.v, and top.v, a +292-line change to
driver/smi_stream_dev.c, and a standalone tx_test tool — the I/Q transmit
test upstream has never had.
The work is still alive outside the project, on the transmission_fix branch
of matteoserva/cariboulite,
48 commits ahead of upstream main and last touched in November 2026. It
cross-builds from an x86-64 host and ships top.bin, flash_fpga,
tx_test, and the kernel module. Note that it deletes the prebuilt
bitstream: you have to rebuild it with yosys, nextpnr-ice40, and
icepack, and flash it after every power cycle.
So the honest status is: upstream CaribouLite does not transmit modulated
I/Q, and the maintainers have not taken the fix that makes it work. For a
70 cm transmit exercise on stock software, use the HackRF (as
rflink does); the stock board’s usable transmit capability is
an unmodulated keyed carrier via CW=1. The band-plan, identification,
occupied-bandwidth, and write-pacing logic in the demo is correct either way,
and is the right scaffolding to keep if you do flash the community branch.
Building the fix, and what it takes
The branch was built and run on this board. It works. The honest version of “it works” takes a few paragraphs, because three obstacles sit between the documented build and a transmitting radio, and none of them is mentioned in the branch’s own instructions.
The bitstream builds cleanly on the host. make firmware runs yosys,
nextpnr-ice40, and icepack and meets timing at the 80 MHz constraint. No Pi
involved, and nothing to hand-hold. That part is genuinely fine.
make tx_test cannot work from a clean tree. The tool compiles
cariboulite_setup.c, which #includes cariboulite_fpga_firmware.h — a
generated file holding the bitstream as a C array. Nothing in the documented
flow generates it: the top-level firmware target builds top.bin only, not
the build target that runs generate_bin_blob. The header is in
.gitignore, so a fresh clone never has it. Generate it by hand, from the
bitstream you just built:
gcc -O2 -o /tmp/generate_bin_blob software/utils/generate_bin_blob.c
mkdir -p firmware/h-files
/tmp/generate_bin_blob firmware/top.bin cariboulite_firmware \
firmware/h-files/cariboulite_fpga_firmware.h
cp firmware/h-files/cariboulite_fpga_firmware.h software/libcariboulite/src/
The checked-in software/utils/generate_bin_blob is an x86-64 binary, so on
the Pi it must be rebuilt from source anyway.
The kernel module does not compile on a current kernel. The Pi here runs 6.18.50, and the driver is written against something older than 6.4:
error: too many arguments to function 'class_create'
error: initialization of 'void (*)(struct platform_device *)' from
incompatible pointer type 'int (*)(struct platform_device *)'
Both are the same breakages the stock driver has — class_create() lost its
owner argument in 6.4, and platform_driver.remove became void-returning in
6.11 — so patch_smi.py fixes them, with
its anchors re-indented for this branch’s tabs. The shims are guarded on
LINUX_VERSION_CODE, so the result still builds on older kernels.
With those two patches the whole set builds: top.bin on the host,
flash_fpga, tx_test, and smi_stream_dev.ko natively on the Pi.
The sync bit flips
This is the measurement that matters, and it is a one-line diff in the tool’s own output. With the new bitstream but the stock driver still loaded:
rf state 3
Status 'Is synchronized to incoming I/Q': 0
With the branch’s driver loaded as well:
rf state 3
Status 'Is synchronized to incoming I/Q': 0
rf state 4
Status 'Is synchronized to incoming I/Q': 1
rf state 3 → 4 is TXPREP → TX, and the sync bit reaches 1. That is the
exact bit issue #189
reports as permanently stuck at 0. Note that both halves are needed: the
rewritten FPGA alone does not fix it, which is why flashing the bitstream and
skipping the kernel module gets you nowhere.
Confirmed on the air: +62.3 dB
The same protocol that measured the stock path at +0.21 dB. One continuous 95-second HackRF Pro capture; three 12-second transmit bursts with silence between them; a bin-by-bin comparison of transmit windows against idle ones. The transmitted signal is a complex tone offset +250 kHz from the CaribouLite’s carrier, so the emission lands at 445.500 MHz while the carrier sits at 445.250 MHz — far enough apart that LO leakage and a DC spur cannot be mistaken for the signal. That matters: every false positive earlier on this page was a spur at the tuned centre.
380 blocks x 2785 bins; 128 transmit, 204 idle
bin-to-bin rise: mean +4.34 dB, std 4.29 dB
at the emission (445.499585 MHz): +62.22 dB (14.5 sigma)
largest anywhere (445.499585 MHz): +62.22 dB
time profile at the emission bin: transmit +61.60 dB, idle -0.70 dB
LIFT +62.30 dB (idle scatter 0.82 dB -> 76.4 sigma)
The strongest riser in the whole 340 kHz analysis band is the emission itself, 415 Hz from where it was predicted — about three FFT bins, which is the frequency offset between two uncalibrated TCXOs. The envelope tracks the key exactly:
0.1s rx | :@@@%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%%@%@%
key |..................TTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTTT...
23.9s rx | %@@%%%%%%%%%%%%%%%%%%%%
key |............................................TTTTTTTTTTTTTTTTTTT
Compare the four stock-code attempts, which came in at +0.49, +0.34, +0.21, and +0.21 dB against an idle scatter of the same size. This is not a marginal improvement on a null result; it is the difference between no transmitter and a transmitter.
Proving the modulation survives, not just the power
A 62 dB lift says energy appeared. It does not say the waveform arrived. Those are different claims, and only the second one makes the board useful.
So the next transmission was the station identification itself — DE AD7KM
keyed in Morse at 15 WPM as an amplitude-keyed tone, generated as I/Q
samples, sent through the fixed datapath, and then decoded back off the air
by the HackRF as an independent receiver:
envelope at 445.500000 MHz: floor -9.9 dB, peak 49.4 dB, contrast 59.3 dB
recovered elements: -.. . / .- -.. --... -.- --
decoded : DE AD7KM
expected : DE AD7KM
MATCH
That closes the loop end to end: host → file → SMI → FPGA → LVDS → modem → PA → antenna → air → HackRF → decoder, with the content intact. It also satisfies 97.119 for the session, which is the point of picking the callsign as the test waveform.
One trap worth repeating, because it cost a run: the first attempt at this
generated the Morse sample-by-sample in a Python loop and piped it to
tx_test. At 2 Msps the stream is 8 MB/s and a per-sample Python loop manages
a fraction of that, so the transmitter underran mid-element. The signal was
there — 60.9 dB of contrast — but the decode came back NEE EE E E T NEEE N.
The failure looked like a radio problem and was a struct.pack problem.
Generate with numpy, or write a file and stream that.
What the output looks like — and a measurement to distrust
Working is not the same as clean, so the next step was a spectrum. With the receiver tuned off to the side so the wanted tone, the carrier, and the image all land clear of each other and of the HackRF’s own DC spur, averaged over 518 FFTs of 32768 points, it came out like this:
| component | frequency | level | relative |
|---|---|---|---|
| wanted tone | 445.499548 MHz | 84.4 dB | 0.0 dB |
| carrier (LO leakage) | 445.249548 MHz | 51.8 dB | −32.7 dBc |
| image (I/Q imbalance) | 444.999548 MHz | 43.5 dB | −40.9 dBc |
| worst other spur | 445.101416 MHz | 71.1 dB | −13.4 dBc |
| noise floor (median) | — | 16.4 dB | −68.0 dB |
A spur at −13.4 dBc is alarming, and it survived the obvious check — compare the transmit window against the idle tail of the same recording and it rises 52.8 dB when the transmitter keys, so it is not something that was already on the bench:
strongest bins that appear only while transmitting:
445.499548 MHz (+65.9 dB vs idle, +250.0 kHz from carrier) <- wanted
445.101416 MHz (+52.8 dB vs idle, -148.1 kHz from carrier)
445.897620 MHz (+46.6 dB vs idle, +648.1 kHz from carrier)
444.703345 MHz (+40.4 dB vs idle, -546.2 kHz from carrier)
Keep that table in view, because every number in it except the frequencies is wrong, and the next section is about why.
The trap: I measured my own receiver
The first version of this section reported that the board had no amplitude control at all and that its dominant spurs were third-order products at −13 dBc. Both were wrong, and the way they were wrong is the most useful thing on this page.
The measurements were taken with the HackRF’s preamp on, LNA at 32 dB, and VGA at 20 dB, looking at a signal 68 dB above the noise floor from a transmitter a few feet away. That receiver was in compression. A compressed receiver does two things that look exactly like transmitter faults: it flattens its own response, so the output stops tracking the input, and it manufactures third-order products, which appear and disappear with the signal and therefore pass the “is it ours?” test.
Repeating the identical drive sweep with the preamp off and about 22 dB less gain — ADC occupancy 71 of 127, comfortably linear — gives the opposite answer:
| digital amplitude | radiated level | linear prediction | error |
|---|---|---|---|
| 0.90 | +0.0 dB | +0.0 dB | — |
| 0.50 | −5.2 dB | −5.1 dB | 0.1 dB |
| 0.25 | −11.4 dB | −11.1 dB | 0.3 dB |
| 0.10 | −18.8 dB | −19.1 dB | 0.3 dB |
Digital amplitude works, and it is linear to within 0.3 dB over 19 dB. The fixed datapath carries the magnitude faithfully. In the same sweep the worst spur fell from −13 dBc to between −40 and −64 dBc.
The spur that survives honest measurement is unremarkable, and it stays put when the receive gain is dropped a further 16 dB, which is how you know it is the transmitter’s and not yours:
| component | at LNA 24 | at LNA 16 | verdict |
|---|---|---|---|
| LO leakage (zero-IF) | −29.0 dBc | −29.2 dBc | real |
| image (I/Q imbalance) | −36.8 dBc | −37.2 dBc | real |
| worst other spur | −35.0 dBc | −38.9 dBc | still partly mine |
LO leakage at −29 dBc and an image at −37 dBc are ordinary for an uncalibrated zero-IF transmitter with no quadrature correction. Nothing else is above −39 dBc, and the worst line at the lowest gain sits at 446.000 MHz — on the 500 kHz grid, which is this host’s own comb from the receive half of this page, not a transmit product at all.
So: the −398 kHz “third-order comb”, the inverse LO-leakage relationship, the constant-envelope datapath, the whole “it preserves phase and discards magnitude” story — all of it was an artifact of one overdriven receiver.
📏 The lesson generalises past this board. This page spends pages teaching that a receiver invents signals, and then the transmit measurements fell for a receiver inventing nonlinearity. Before attributing distortion or compression to the thing you are measuring, back the receive gain off and check that the number does not move. If it moves, it was yours. Watch ADC occupancy, not just SNR: a signal can be 70 dB above the noise and still be clipping the front end.
The RF gain really is inert — and it is a one-line bug
One finding did survive, because it was confirmed in the source rather than
only on a spectrum. Across the entire -g 0..69 range, at honest receive
gain, the radiated level moves 0.6 dB. The reason is in tx_test.c:
cariboulite_radio_set_tx_power(state.radio, 0);
-g is parsed into state.gain, range-checked, printed in the banner — and
then this line passes a hardcoded 0 to the hardware. The setting never
leaves the program. It is a userspace bug, nothing to do with the FPGA.
patch_tx_gain.py maps it the way the
Soapy plugin already does, tx_power_dbm = gain - 18, so a given -g means
the same thing in both. With that one line changed:
-g |
implied dBm | radiated level |
|---|---|---|
| 6 | −12 | +0.0 dB |
| 14 | −4 | +7.8 dB |
| 24 | +6 | +14.7 dB |
| 32 | +14 | +17.1 dB |
+17.1 dB of real control. Note that the useful span is about 26 dB, not
69: set_tx_power clamps to the channel’s actual range, −14…+14 dBm for S1G
and −12…+14 for HiF, so -g below 6 or above 32 does nothing. And the top of
the range compresses — the last 8 requested dB return 2.4 — which is the PA
running out of headroom near +14 dBm, and is the one place a real
compression story belongs.
So the corrected practical rule for this board is much better than the one it replaces:
- amplitude works — the datapath carries sample magnitude linearly, so AM, SSB, QAM, and OFDM are not excluded by anything measured here.
- power control works with the one-line patch, over roughly 26 dB, which is what “run the least power that works” needs.
- what to watch is ordinary zero-IF hygiene: carrier leakage at −26 dBc and an image at −36.5 dBc, neither corrected anywhere in the stack, plus PA compression in the last few dB of range. Both of the first two can be corrected in software, and two sections below they are — the carrier by 17–19 dB, the image by 4.
One more thing the rate sweep found
Transmit clamps sample rates to the modem’s supported set, silently, the same way receive does — and this is visible because a waveform written for one rate and clocked out at another emits its tone at the wrong frequency:
| requested | actually used | tone landed at |
|---|---|---|
| 1.400 Msps | 1.3312 Msps | +237.7 kHz instead of +250 |
| 2.000 Msps | 1.9969 Msps | +249.6 kHz |
| 3.000 Msps | 3.9951 Msps | +332.9 kHz instead of +250 |
| 4.000 Msps | 3.9937 Msps | +249.6 kHz |
Note 3 Msps, which is not a rate the AT86RF215 has: it was rounded up to 4 Msps, so the waveform played 33% fast and every frequency in it was 33% wrong. Nothing reported an error. Read back the rate you were actually given before you compute anything from it — on transmit that arithmetic lands on the air.
One row of that table needs qualifying, and the way it does is instructive. Those tone positions were measured against the nominal carrier, and a single spectral line cannot tell a sample-rate error from a frequency error — both move the tone. The calibration work below measures the carrier and the tone in the same capture, and there the spacing between them at a requested 2 Msps is 250.000 kHz to within 2.5 Hz, repeatably. So the clock really is 2.000 Msps to within tens of ppm, and the 0.4 kHz by which the tone sat low is a frequency offset of about 400 Hz — 0.9 ppm between the two radios’ references — which moves the carrier by the same amount. The 1.4 and 3 Msps rows stand unqualified: errors of 4.9% and 33% are orders of magnitude too large to be any reference offset, and that clamping is real. Measure two lines and their spacing, not one line and its position, if you want to know which kind of error you have.
Cleaning up the output: the carrier and the image
A working datapath is not a clean one. Two residuals survive, and they are the standard pair for any zero-IF transmitter:
- a carrier at the tuned frequency, from DC offset in the baseband and LO leakage in the mixer — −26 dBc here;
- an image of the wanted signal mirrored about that carrier, from gain and phase mismatch between the I and Q paths — −36.5 dBc.
Nothing in the stack corrects either. Both are fixed properties of the hardware at a given frequency and gain, so both can be cancelled by pre-distorting the samples before they are sent. Write the impairment as a widely linear function — the signal and its conjugate, each with its own gain, plus an offset:
y = α·x + β·conj(x) + D
α is the wanted path, β·conj(x) is the image, and D is the leakage. The
inverse has the same shape:
x′ = x + k·conj(x) + d, k = −β/α, d = −D/α
which in real terms is a 2×2 matrix on (I, Q) plus an offset:
I′ = (1 + kr)·I + ki ·Q + dr
Q′ = ki ·I + (1 − kr)·Q + di
iqcal.py holds that transform and nothing else;
calibrate.py measures the coefficients from
the host with the HackRF watching, and
gen_probe_sweep.py builds the
stimulus.
Three ways this measurement lies
Measuring the two coefficients turned out to be much harder than applying them, and each failure produced confident, plausible, wrong numbers.
1. Do not average a complex ratio across blocks. The obvious estimator takes the image-to-tone ratio in each FFT block and averages it, keeping phase so the correction knows which way to push. It fails, because the component frequencies are known only to within a few Hz: each block’s phase is rotated a little further than the last, and a coherent average over a hundred blocks largely cancels itself. It under-read the image by about 15 dB and returned a wrong phase, so the first closed loop built on it pushed the carrier up 13.4 dB on its first correction and diverged from there. Magnitudes do not have this problem, so the working version measures only magnitudes and recovers phase from geometry instead.
2. Trim the window, because the carrier does not stop when the samples do. The radio leaks its carrier for as long as it is in transmit, which begins before the first sample and ends after the last. Blocks holding leakage but no tone therefore sit just inside any envelope-detected window, and each one drags the tone average down and the carrier ratio up — by an amount that depends on where the capture happened to start. Measured that way, three identical transmissions reported carrier leakage of −19.8, −25.0, and −13.5 dBc, which looks exactly like unstable hardware. It is not: trimming 0.25 s inside each edge of the very same three captures gives −26.0, −26.0, and −28.6 dBc. The phantom was 11.5 dB wide and entirely mine.
3. Do not probe both corrections at once. Stepping k and d in the same
segments is a tempting economy and it corrupts the image measurement: a DC
offset puts energy on the image frequency by itself, and that energy does not
respond to k. With d = ±0.06 alongside the k probes, the extra image-band power
was as large as the impairment being measured. The mechanism is the same one
discussed later for the image itself — a product of the offset with the signal
lands at 2·f_carrier − f_tone, which is exactly the image frequency — and the
order of the nonlinearity behind it is inferred here, not measured. For the
probe design it does not matter which order it is; it matters only that the
contribution exists and is not a function of k.
What caught the third one is worth stealing. The residual amplitude is affine in the coefficient, so with probes c_i and measured power ratios y_i,
y_i = |c_i + u|² = |c_i|² + 2·Re(c_i)·Re(u) + 2·Im(c_i)·Im(u) + |u|²
which is a linear least-squares problem in (Re u, Im u, |u|²) — solvable from magnitudes alone, no phase measurement anywhere. And because |u|² is fitted independently of Re u and Im u, comparing the two costs nothing and checks the model: if the fitted |u|² does not match Re(u)² + Im(u)², the model is not describing the hardware and the answer should be thrown away. Probing k and d together put that check 2.8 dB out; separating them brought it to 0.0–1.2 dB.
So the stimulus is nine 1 s segments inside a single 11.5 s waveform, separated by silence — the same self-timing trick as the linearity sweep, for the same reason. A baseline, then four segments stepping k with d = 0, then four stepping d with k = 0. One transmission, one tuning, and every segment trimmed 0.15 s inside each edge. Sub-window analysis confirms there is no settling transient to avoid: the carrier is flat across each segment from its first 0.1 s.
What the correction is worth
At 445.680 MHz, -g 24, 2.000 Msps, from two runs agreeing to 9% on k and 20%
on d:
k = +0.00190 + 0.01767j (|k| = 0.0178, −35.0 dBc)
d = −0.02569 + 0.00879j (|d| = 0.0272)
It costs 0.38 dB of headroom, because x + k·conj(x) + d can peak at
(1 + |k|)·|x| + |d| and a waveform already at full scale would clip; the
generators scale by the reciprocal.
Verified by sending corrected and uncorrected segments in the same transmission, which is the only honest way to state an improvement — the absolute level wanders a dB or two between runs, so everything here is a ratio measured inside one window:
| segment | carrier | image |
|---|---|---|
| both off | −25.8 dBc | −36.3 dBc |
| both on | −45.1 dBc | −40.7 dBc |
| k only | −25.3 dBc (+0.5 dB) | −36.2 dBc (+0.2 dB) |
| d only | −32.6 dBc (−6.8 dB) | −38.2 dBc (−1.9 dB) |
Repeated at 14 dB lower receive gain, with the tone at −34 dBfs instead of −8 dBfs, the whole pattern holds within about 1 dB (−26.8 → −44.8 dBc carrier, −37.3 → −41.6 dBc image). That two-gain check is not optional on this page: it is the test that the receive half of it spends pages earning.
Through the ordinary production path — gen_cal_tone.py loading the saved
coefficients from ~/.cariboulite_iqcal.json by itself, against the same
waveform with --no-cal — the result is −26.5 → −43.4 dBc on the carrier
and −37.0 → −39.9 dBc on the image. One run happened to land at −63 dBc, which
says the method is not the limit; how deep the null goes depends on how closely
the day’s leakage matches the stored coefficient.
The surprise is in the third row. The quadrature correction on its own
does nothing — +0.5 dB on the carrier and +0.2 dB on the image, which is to
say nothing at all, and it repeats at both receive gains. The textbook image
correction is the one that failed; what moves the image here is d, the
offset.
That is a strange enough result to need a mechanism, and the obvious one —
that the radiated carrier is itself feeding the image — is wrong. The next
section tests it directly, by nulling the carrier 28 dB in the modem’s own
trim registers while leaving the samples alone. The image does not move at
all. So the offset that feeds the image is upstream of that trim, and only
a correction applied to the samples reaches it; the carrier you can see on the
analyser is a separate symptom of the same offset, not the cause. What fits
is a second-order product of the baseband offset with the signal, which lands
at 2·f_carrier − f_tone — exactly the image frequency. That is inference
from two measurements rather than something measured, and it is written here
as a hypothesis on purpose.
Fix the offset first either way: it is the larger win on the carrier and the only thing that touches the image.
The hardware has its own trim, and it is six bits
The AT86RF215 does correct its own LO leakage, which is why the uncorrected
figure is −26 dBc and not −10. Two registers hold it, and the chip has two
radios, so there are two pairs — at86rf215_radio.c lists both:
.RG_TXCI = 0x125, // RF09, transmit calibration, I path
.RG_TXCQ = 0x126, // RF09, transmit calibration, Q path
...
.RG_TXCI = 0x225, // RF24
.RG_TXCQ = 0x226, // RF24
Which pair is live is easy to get wrong, and getting it wrong means trimming a
radio that is not transmitting. Everything on this page runs tx_test -c 1,
and cariboulite_radio.h has cariboulite_channel_hif = 1, which
cariboulite_radio.c maps to at86rf215_rf_channel_2400mhz — so the 445.68 MHz
output comes from the 2.4 GHz radio mixed down by the RFFC5072, and the
registers being trimmed are the 0x225/0x226 pair. The sub-GHz radio could
reach 445 MHz directly (RF09 covers 389.5–510 MHz), but that is not the path
this board’s HiF channel uses.
The datasheet text carried in the driver’s own comments explains when they
are written: “At the transition process from state TRXOFF to TX the
calibration is started automatically.” Each value is masked to 6 bits —
buf[0] = cal_i & 0x3F — so the hardware’s whole correction is a 64-step trim
per path. Whether that step size is what bounds the residual is the whole
question, and it is settled two sections below.
The library does not even trust a single reading of it.
at86rf215_calibrate_device() cycles TRXOFF → TX_PREP five times, reads the
pair back each time, and keeps the median:
#define NUM_CAL_STEPS 5
...
int cal_i_med = median(cal_i, NUM_CAL_STEPS);
int cal_q_med = median(cal_q, NUM_CAL_STEPS);
With override_cal true — which it is in cariboulite_config_default.h — that
stored median is then written back on every transition into TX_PREP, TX, or RX,
replacing whatever the automatic calibration just computed. So the trim is
stable from run to run, which is exactly why a stored d can cancel the
residual at all. Whether it is also coarse is the interesting question, and
the answer turns out to be no — the median is what fails, not the resolution.
That left an obvious experiment, and it is worth running before concluding that
−26 dBc is the hardware’s floor rather than the floor of five noisy readings
and a median. The library already exposes
at86rf215_radio_set_tx_iq_calibration(), so the codes can be searched
directly.
Searching the trim codes, and why one run cannot do it
The search cannot be one code per transmission. The absolute level wanders
between runs, and worse, the quantity being improved on is re-chosen on every
transition into TX — so two runs are measuring two different baselines. Every
code therefore has to go inside one transmission.
patch_tx_cal.py adds -I/-Q to set
the pair and -S/-D to step a list of them every D samples while
streaming; sweep_txcal.py drives it from
the host, against a segmented tone with the same period, and maps segment i
to code i.
That mapping is the part to distrust, and it has to be checked rather than
assumed. tx_test switches the register when the samples have been pushed to
the driver, which runs ahead of what is radiating by the buffer depth B. A
write at segment i’s period boundary therefore takes effect while file
position i·period − B is on the air, so the stimulus needs
gap ≥ lead + B for it to land in the gap before segment i instead of inside
segment i−1. sweep_txcal.py align alternates two codes 21 dB apart and the
measured carrier must alternate in step, starting with the first — which, on
this board, it does.
−26 dBc was a mis-converged code, not a resolution limit. The modem chose I=35 Q=29. Holding I and sweeping Q found a clean minimum five codes away:
| TXCQ at I=35 | 29 (modem’s) | 31 | 33 | 34 | 35 | 37 |
|---|---|---|---|---|---|---|
| carrier | −25.9 dBc | −30.1 | −38.4 | −43.9 | −39.2 | −31.0 |
and re-sweeping I at Q=34 reached −54.1 dBc at I=35, with −38.3 one code below and −41.9 one code above. So one code step near the null is worth 5–16 dB and the trim’s own resolution supports roughly −45 dBc; the −26 dBc figure was five noisy readings and a median landing badly. Triplicated A/B inside one transmission, 35:29 against 35:34 gave 19.3 ± 0.4 dB, at an ADC occupancy of 10/127 with the tone 14 dB below the earlier runs — a free second-gain check that came out unchanged.
And the trim is a DC control only. Across about 45 swept segments,
including every one where the carrier sat below −50 dBc, the image never left
−35.8 … −37.5 dBc. That is the measurement that corrects the claim two sections
up: a 28 dB change in the radiated carrier moves the image not at all, while a
digital d moves it 13 dB with the carrier anywhere.
The two corrections are not in the same basis
Both cancel the same carrier, so the first guess — apply the good trim code
and the stored pre-distortion — is wrong, and measurably so: it returns the
carrier to −25.8 dBc, because d was measured against leakage that is no
longer there. Re-measuring d at the good code fixes the image and
re-radiates the carrier, for a reason worth doing the arithmetic on. d is an
absolute offset in units of full scale, added after amp, so on its own it
radiates a carrier at 20·log₁₀(|d|/amp). For the measured |d| = 0.00966 at
amp = 0.5 that is −34.3 dBc, and the measurement read −34.4. A d
larger than the residual it is cancelling is not a correction; it is a new
impairment.
The way out is to search the trim with that d held in every segment. Doing
it on the Q axis alone says the trade-off is unavoidable — the carrier floors
at −34.6 dBc, exactly |d|, and the null does not move. Doing it on both
axes says otherwise:
| carrier, dBc | Q=32 | Q=33 | Q=34 | Q=35 | Q=36 |
|---|---|---|---|---|---|
| I=35 | −32.0 | −33.9 | −34.6 | −33.4 | −31.3 |
| I=36 | −34.5 | −38.0 | −40.1 | −36.6 | −32.9 |
| I=37 | −34.8 | −41.6 | −57.4 | −39.3 | −34.4 |
Cancelling a d that is very nearly pure imaginary — a Q-axis offset —
required moving the I code, by two steps, with Q unchanged. The modem’s
trim does not act in the same basis as the digital baseband offsets, which is
not something either datasheet or driver mentions.
That −57.4 dBc is also a good place to be suspicious: it sat on the edge of the
grid, and the tone level varied 14.6 dB across that transmission, so it could
have been a weak segment rather than a deep null. It was not — but establishing
that needed a floor column, measuring empty spectrum 125 kHz off. The floor
runs −68 to −76 dBc at a usable receive level, which puts a −60 dBc carrier
comfortably clear of it; at -l 12 -g 10, where this board lands at ADC 3/127,
the floor is −51 dBc and every deep null reads several dB shallower than it is.
A second receive gain has to be lower, not useless.
What to actually run
Four runs, spanning ADC occupancies of 13, 32, and 66, each row a segment of the same transmission:
| configuration | carrier | image | worst spur |
|---|---|---|---|
| modem’s own code, nothing applied | −26.1 … −26.5 | −36.2 … −36.9 | −26 (stable) |
modem’s own code + digital k,d |
−39.5 … −44.8 | −39.5 … −41.1 | −40 (stable) |
| hardware code 35:34 alone | −42.5 … −53.0 | −36.2 … −36.8 | −36 (image-limited) |
36:34 + k,d re-measured there |
−39.8 … −51.6 | −48.4 … −50.5 | −49 typical |
The right default is the second row — the modem’s own trim plus the digital correction. −40 dBc on the worst spur, stable, no per-board search, and a frequency change costs only a re-measurement.
The last row is better where it matters and worse where it is measured. The
image at −49 dBc is solid across all three receive levels; the carrier null is
not, because it falls between two 6-bit codes. 37:34 read −60.5 dBc once and
−41.6 … −43.2 in the three other runs; 36:34 read −39.8 once and −48.9 … −51.6
otherwise. Typical worst spur −49 dBc, occasional −40, never worse than the
default — but it needs the patched tx_test, a two-axis search per board and
per frequency, and a willingness to re-search when the room warms up. A
deeper null is not automatically a better configuration if its depth is what
drifts. Take it if you need the image down; otherwise the default is the
honest answer.
It does not survive a reboot
Both halves of the fix are volatile, and this bit the work directly — a run the next morning transmitted nothing at all, because:
TX_TEST main@tx_test.c:351 FPGA is not programmed (CDONE low)
- run the flash_fpga tool first
The ICE40 is configured into SRAM, not flash, so a power cycle leaves it
blank; and the module reverts to the distribution’s smi_stream_dev on boot.
After any reboot you need both again:
./flash_fpga ./top.bin # no root needed
sudo insmod ~/cariboulite-txfix/release/smi_stream_dev.ko
flash_fpga and tx_test need no root on this Pi — membership in the gpio
and spi groups covers the SPI and GPIO access, and the udev rule puts
/dev/smi in group gpio. Only insmod needs it. tx_test refusing to run
on an unconfigured FPGA rather than failing silently is a small piece of good
engineering, and the only reason the cause was obvious.
Making it stick
Neither half of the fix persists on its own, and the branch provides nothing
for this, so
install-persistent.sh does it in
two pieces — one for each thing that reverts.
The module goes in as a DKMS package. The stock driver is already
installed that way, at smi-stream-dev/1.0, so the patched source is added
as 1.1 and the old version is uninstalled — only one DKMS version may
provide smi_stream_dev, or which one wins at boot depends on DKMS ordering
rather than on anything you chose. AUTOINSTALL="yes" means it rebuilds
itself against future kernels, which matters here because the thing that
needed patching in the first place was kernel API drift. The 1.0 source is
deliberately left in /usr/src, so --uninstall can put the vendor driver
back. A PROVENANCE file sits beside the source, because a future reader
finding a modified vendor driver in /usr/src deserves to know why.
The bitstream goes in as a systemd oneshot. Ordering is the whole point:
libcariboulite programs its own stock bitstream whenever it finds the
FPGA unconfigured, so if anything in userspace touches the radio before the
service runs, the fix is silently undone and you are back to a transmitter
that reports success and emits nothing. The unit is therefore
Before=multi-user.target.
The hook it runs is slightly more careful than flash_fpga top.bin:
- it waits for the SPI and GPIO nodes, up to 30 s, because udev has not
necessarily created
/dev/spidev1.0and/dev/gpiochip0by the time a service ordered afterlocal-fs.targetstarts; - it checks the output, not just the exit status, for
FPGA programming - Success, and retries up to three times; - it then rebinds the driver —
modprobe -r smi_stream_dev/modprobe bcm2835_smi/modprobe smi_stream_dev— because flash-then-load is the order the fix was verified in, and a module left in use is tolerated rather than allowed to fail the boot.
Verified by rebooting:
Nov 10 14:43:58 systemd[1]: Starting cariboulite-fpga.service...
Nov 10 14:44:00 cariboulite-fpga-boot[681]: programmed /usr/local/lib/cariboulite/top.bin (attempt 1)
Nov 10 14:44:00 cariboulite-fpga-boot[681]: driver loaded, srcversion 79D1BB13E70B21C0D581BBD
Nov 10 14:44:01 systemd[1]: Finished cariboulite-fpga.service.
Two seconds into the boot, with no manual step, and then — on the same boot,
nothing touched by hand — IQIFC2.SYNC reads 1 and the callsign transmits
and decodes back off the air at 62.4 dB of contrast. Receive is unaffected:
3/3 PASS at 2.000 Msps on both radios.
⚠️ Two caveats on that verification. It was a warm reboot, not a power cycle; the ICE40 may well hold its SRAM configuration when power is never removed, so the service reprogramming it proves the service runs, not that the FPGA had gone blank. And DKMS rebuilding against a new kernel is configuration, not observation — it has not yet been through an actual kernel upgrade on this board. The patch is version-guarded, so it should survive one; “should” is doing work in that sentence.
Listening before transmitting, and the third artifact test
The demo listens before it keys. Getting that check to tell the truth took three attempts, and the failures are more instructive than the result.
The first version tuned the receiver to the frequency it was testing and reported 34.6 dB of signal — the receiver’s own LO, exactly the artifact the receive half of this page is about. The second version notched DC and reported a peak at 432.409 MHz, which looked like a real emitter until it was swept: it sat at a fixed fraction of the sample rate near Fs/4, moving from −337 kHz at 1.333 Msps to −514 kHz at 2 Msps. A digital artifact.
That ruled out the sample clock, so the third version holds the rate fixed and moves the tuning instead, keeping only peaks whose absolute frequency does not budge. It then found four strong, genuinely fixed-frequency signals right next to the intended transmit frequency — and they were all still spurious:
445.509 MHz 34 dB above noise (on the 500 kHz grid: probably this host's own comb)
446.009 MHz 16 dB above noise (on the 500 kHz grid: probably this host's own comb)
445.526 MHz 16 dB above noise <-- near your emission
444.999 MHz 15 dB above noise (on the 500 kHz grid: probably this host's own comb)
Sampling the same windows 12 MHz apart gave it away: lines at 420.999, 433.005, 444.999, and 457.008 MHz — every one on a multiple of 500 kHz, the same pattern repeating across the band. That is a clock comb radiating from the Pi and the HAT, not traffic. It defeats the retune test for a simple reason:
The retune test proves a peak is not generated by the sampling process. It says nothing about whether the peak is generated by your own hardware.
So the table from earlier in this page needs another column, and two more rows:
| Change | Real signal | LO/DC artifact | Digital artifact | Local comb |
|---|---|---|---|---|
| Retune the centre | fixed absolute | follows centre | fixed absolute | fixed absolute |
| Change the sample rate | fixed absolute | stays at centre | moves with rate | fixed absolute |
| Check against a frequency grid | rarely exact | n/a | n/a | lands on round multiples |
| Disconnect the antenna | disappears | unchanged | unchanged | barely changes |
The last row is the decisive one and needs no code. If you cannot explain a peak, pull the antenna off. Anything that survives was never coming in through it.
Where the real work was
Almost none of the effort on this board was DSP. It was getting Linux to acknowledge the hardware at all, and it is worth seeing why, because this is what “supported” often means in practice for IoT hardware.
Upstream’s installation guide recommends Raspberry Pi OS bullseye and warns that its kernel module will not compile against bookworm’s 6.1. The bench Pi runs 6.18. Five separate problems stood between a correctly-detected HAT and a working radio:
- The kernel module did not build. CaribouLite ships its own
smi_stream_dev, which replaces the in-treebcm2835_smi_devto add streaming. Three ordinary API changes broke it:vmalloc/vfreeno longer arriving transitively,class_create()losing itsownerargument in 6.4, andplatform_driver.removebecoming void-returning in 6.11. - Two drivers wanted the same device. The in-tree and out-of-tree modules
both match device-tree compatible
brcm,bcm2835-smi-dev, and only one can bind. config.txtwas missing SPI1 and the EEPROM’s i2c bus. Interestingly the SMI overlay was not missing — the HAT EEPROM carries its own device-tree overlay that the firmware applies at boot, which is a neat trick and the reason/dev/smiexists before you configure anything.- A library was built but never installed. Upstream links the Soapy plugin
against
libiirunderEXCLUDE_FROM_ALL, which drops its install rules, somake installsucceeds and leaves a plugin that cannotdlopen(). - The Python bindings lie about one call. Passing a plain dict to
SoapySDR.Device()silently loses the dict’s values, producingIndexError: map::atfrom deep inside C++.
The operator’s manual documents every one with the
fix, and cariboulite/setup/ automates the lot. The kernel module is installed
through DKMS so a kernel upgrade rebuilds it rather than silently removing your
radio.
One security note on the install
Upstream’s udev rules include this:
SUBSYSTEM=="mem", KERNEL=="mem|kmem|port", GROUP="kmem", MODE="0666"
That makes /dev/mem world-writable — read/write access to all physical
memory, for any local user, which is root by another name. On a shared lab
machine that is not a tradeoff, it is a vulnerability.
It is also unnecessary. The library calls rpi_init(0), which is the
/dev/gpiomem path; /dev/mem is a fallback it never takes. Our setup
installs a rule covering /dev/smi alone, at GROUP="gpio", MODE="0660".
Worth internalising as a habit: vendor setup scripts are a threat model.
A driver install that quietly widens permissions on /dev/mem, adds a user to
root, or disables a hardening feature is extremely common in hardware-adjacent
projects, and nearly always goes unread. Read them before you run them, and ask
what each permission change is actually for.
Key takeaways
- A direct-conversion receiver always has a spike at the tuned frequency. It is LO leakage plus DC offset, not a signal. Any analysis that takes the strongest bin without excluding the centre will be wrong every time.
- To tell an artifact from a signal, change one variable and see what follows. Real signals hold their absolute frequency; LO artifacts follow the tuning; digital artifacts follow the sample rate. When that is not enough, pull the antenna off — whatever survives was never arriving through it.
- Your own host is an emitter. This Pi and HAT put a comb on every multiple of 500 kHz across 70 cm, at a fixed absolute frequency, which passes every test that looks only at the sampling chain.
- Measure throughput over a wall-clock window after draining buffers. Timing the first block measures how fast a queue empties, not how fast the radio samples — the first draft of this tool claimed 31 Msps from a radio set to 2.
- Dual-radio capture is real but costs bandwidth, roughly half each here. Verify rather than assume.
- Tuning ranges are not always contiguous, and advertised ranges are not always what the vendor documents. Check the EEPROM, check the plugin, check the datasheet; they disagree.
- Reading a vendor’s install script is a security exercise. This one would have handed every local user all of physical memory.
- Transmitting moves you from “my conclusions might be wrong” to “my signal is someone else’s problem”. Identify, keep the emission narrow, run the least power that works, and check the band plan against the whole occupied span — LO leakage included.
- A transmit call that returns success has not transmitted anything.
writeStream()never blocks on this plugin; pace it against the clock and confirm elapsed time matches the waveform, or most of your signal dies in a buffer. And since the board cannot receive while it transmits, confirming that anything radiated at all needs a second receiver. - On this board that check failed: an external HackRF detected nothing, on a path that carried a signal the other way at 20 sigma. Every indicator the API offers said the transmission succeeded. Verify the output of a transmitter with a receiver you trust, never with its own return codes.
- The obvious-looking bug is not always the bug. A commented-out line in the vendor driver sat exactly where the fault should have been. Restoring it, and three further changes, each measured no better than noise. A plausible mechanism is a hypothesis; only the measurement decides.
- A closed pull request is not the same as a wrong one. The fix for this board was written, published, and discarded without review comments. It builds, it flips the sync bit, and it radiates at +62 dB. Before concluding that hardware cannot do something, read the forks.
- “It works” and “the waveform arrives” are different claims. A 62 dB lift proves energy appeared where it was aimed. Only decoding the callsign back off the air proved the modulation survived the trip. Design the test so the signal has to carry content, and the content is what you check.
- Make the measurement self-timing. Two runs here were invalidated by bookkeeping, not physics: a capture that silently dropped 2.9 s of samples, and a transmitter that was not configured at all. Verify that the capture delivered every sample it was asked for, and put the structure you intend to measure inside the waveform so the analysis cannot align to the wrong window.
- Volatile state makes a fix look flaky. The FPGA is configured into SRAM and the kernel module reverts on boot, so a working transmitter stops working overnight with no change to any file. Know which parts of your stack do not survive a power cycle.
- A receiver invents nonlinearity, not just signals. The first transmit characterisation on this page concluded the board had no amplitude control and emitted −13 dBc third-order spurs. Both were the receiver in compression: preamp on, LNA 32, VGA 20, looking at a signal 68 dB above the noise. A compressed front end flattens its own response and manufactures intermodulation that appears and vanishes with the signal, so it passes the “is it ours?” test with flying colours. Back the receive gain off and re-measure; if the number moves, it was yours. Watch ADC occupancy, not SNR — a signal can sit 70 dB above the noise and still be clipping the input.
- “It transmits” is not one claim, it is several. Energy appearing where aimed, the modulation surviving the trip, amplitude being carried linearly, and the gain control working are four separate properties with four separate answers. On this board the first three hold and the fourth needed a one-line patch. Characterise a transmitter per property, not as a yes or no.
- Read the source before blaming the silicon. The gain really was inert,
and the cause was
cariboulite_radio_set_tx_power(state.radio, 0)— an argument parsed, validated, printed, and then replaced with a literal zero. No amount of spectrum analysis would have found that; one grep did. - Silent rate clamping lands on the air. 3 Msps is not a rate this modem has, so it was rounded up to 4 and the waveform played 33% fast — every frequency in it wrong by a third, with no error reported anywhere. On receive that corrupts your analysis; on transmit it puts your signal somewhere you did not intend.
- One spectral line cannot tell you which error you have. A tone in the wrong place is equally consistent with a sample-rate error and a frequency error. Measure two lines and the spacing between them: the spacing moves with the clock, the position with the reference. That distinction demoted a “2 Msps became 1.9969” finding on this page to a 0.9 ppm reference offset.
- Averaging a complex ratio is not averaging. Keeping phase feels more informative than keeping magnitude, and it silently destroyed a measurement here: with the frequency known only to a few Hz, each block’s phase rotates further than the last, so a hundred blocks average toward zero. It under-read a spur by 15 dB and inverted its phase, and the correction built on it pushed the thing it was cancelling 13 dB up. Average magnitudes; get phase from geometry.
- Fit a model that can tell you it is wrong. The impairment is affine in the correction, so a least-squares fit can estimate |u|² independently of Re u and Im u — and then the mismatch between them is a free verdict on whether the model describes the hardware. That check is what caught a probe design in which the DC offset was manufacturing the very image it was supposed to be measured alongside.
- State an improvement only from one transmission. The absolute level on this board wanders a dB or two between runs, so corrected and uncorrected belong in the same waveform, separated in time and compared as ratios. Confirm at two receive gains before believing any of it.
- The textbook correction was the one that did nothing. Quadrature pre-distortion on its own moved the image by 0.2 dB. What moves the image here is the offset correction — 13 dB of it. Fix the offset before the balance.
- Nulling a symptom is not the same as removing its cause. The obvious explanation for that was the radiated carrier feeding the image, and it is wrong: dropping the carrier 28 dB in the modem’s own trim registers leaves the image exactly where it was, while a digital offset in the samples moves it 13 dB with the carrier anywhere. The offset sits upstream of the trim, so only a correction upstream reaches it. Two impairments with one cause still need two different places to fix it.
- A hardware correction can exist, be stable, and still be badly converged. The modem trims its own LO leakage on every transition into transmit — a 6-bit register per path, from a median of five noisy readings. Searching those codes directly reached −54 dBc where the modem’s own choice gave −26, and its choice was five codes off on one axis. Six bits was never the limit; the median was. Find out what the silicon already does, and then check whether it is doing it well, before assuming its output is a floor.
- A correction has a size, and the size has to match the residual. The
pre-distortion offset is absolute, not relative, so on its own it radiates
20·log₁₀(|d|/amp)— −34 dBc for the value measured here. Applied where the residual is already smaller than that, it is not a correction but a new impairment, and the carrier gets 11.5 dB worse. The same applies to the probe step used to measure it: 26× too large and the answer comes back eight times too big. - Prefer the shallower null that stays put. The best worst-case spur available on this board needs a two-axis hardware search per frequency, and its carrier null lands between two 6-bit codes, so its depth swings 11 dB between runs while the room warms up. The configuration that is 9 dB worse on a good day is the one worth shipping, because it is the same every day.
References
- CaribouLabs, CaribouLite source and documentation — https://github.com/cariboulabs/cariboulite
- CaribouLabs, CaribouLite on Crowd Supply — https://crowdsupply.com/cariboulabs/cariboulite
- CaribouLabs, issue #189: AT86RF215 input IQ sync not reached on LVDS interface during TX — https://github.com/cariboulabs/cariboulite/issues/189
- CaribouLabs, PR #197: transmission of arbitrary waveforms (closed unmerged) — https://github.com/cariboulabs/cariboulite/pull/197
- matteoserva,
transmission_fixbranch — the unmerged transmit fix, still maintained — https://github.com/matteoserva/cariboulite/tree/transmission_fix - Microchip, AT86RF215 device family datasheet — https://ww1.microchip.com/downloads/en/DeviceDoc/AT86RF215-Data-Sheet-DS70005356B.pdf
- Qorvo, RFFC5071A/RFFC5072A wideband synthesiser and mixer — https://www.qorvo.com/products/p/RFFC5072A
- rtl-sdr.com, CaribouLite: a 30–6000 MHz 13-bit SDR HAT for the Raspberry Pi — https://www.rtl-sdr.com/cariboulite-a-30-6000-mhz-13-bit-4mhz-sdr-hat-for-the-raspberry-pi/
- Pothosware, SoapySDR wiki — https://github.com/pothosware/SoapySDR/wiki
- Raspberry Pi, Device Trees, overlays and parameters — https://www.raspberrypi.com/documentation/computers/configuration.html#device-trees-overlays-and-parameters
- Analog Devices, MT-228: receiver architectures and the zero-IF DC offset problem — https://www.analog.com/media/en/training-seminars/tutorials/MT-228.pdf
- Analog Devices, AN-1039: correcting imperfections in I/Q modulators to improve RF signal fidelity — the practical reference for LO leakage, gain and quadrature trim, and storing the coefficients — https://www.analog.com/en/resources/app-notes/an-1039.html
- L. Anttila, Digital front-end signal processing with widely-linear signal models in radio devices (PhD thesis, Tampere, 2011) — where the
x + k·conj(x)form and its estimators come from — https://trepo.tuni.fi/handle/10024/114867 - ARRL, US band plan (70 cm, 420–450 MHz) — https://arrl.org/band-plan
- 47 CFR 97.119, station identification — https://www.law.cornell.edu/cfr/text/47/97.119
- 47 CFR 97.303, frequency sharing requirements (Line A, 420–430 MHz) — https://www.law.cornell.edu/cfr/text/47/97.303
- 47 CFR Part 97, the amateur radio service — https://www.ecfr.gov/current/title-47/chapter-I/subchapter-D/part-97
- NTIA, 420.00–450.00 MHz allocation compendium — https://www.ntia.doc.gov/files/ntia/publications/compendium/0420.00-0450.00_01Feb17.pdf
Related course pages: Radio Protocols · Building a Radio Link · Watching the 2.4 GHz Band · Other IoT radios · LoRa and LoRaWAN · Thread and Matter · Tools of the Trade · Schedule
🛠️ Maintenance note: the measured figures here — the 2.000 Msps sustained rate, the 26–30 dB DC spur, the dual-radio halving table, the 433.607 MHz carrier, the 500 kHz comb, the TX power clamp, and the half-duplex table — were taken on one Pi 4B with one FULL CaribouLite and antennas on both ports, and should be re-measured rather than trusted if they stop matching lab. The comb is a property of this host and its power supply; expect a different pattern, not none. The band-plan segments are from the ARRL plan current at the time of writing and are voluntary and regionally varied — the local frequency coordinator overrides them, and the 445–447 block in particular is explicit local option, so re-check the plan rather than trusting the table baked into
cariboulite_tx_demo.py. Nothing on this page authorises anyone to transmit: that comes from a licence. The 433.607 MHz signal is whatever happens to transmit near this bench and will not be there on yours. The kernel-API patches target the 6.4 and 6.11 changes and will need revisiting as the kernel moves; if the module stops building, checkpatch_smi.pyagainst current kernel sources before assuming the board is at fault. The transmit diagnosis rests on upstream issue #189 and the unmerged PR #197: check whether either has moved — if the fix is ever merged, the “stock software does not transmit I/Q” conclusion here expires with it, and the communitytransmission_fixbranch may have drifted or disappeared. The transmit results on this page were taken against that branch at headbeaf032, with the bitstream built locally andpatch_smi.pyapplied to its driver; a later head may not need the patch, or may need a different one. The transmit numbers here — linearity to 0.3 dB, carrier leakage at −26 dBc, the image at −36.5 dBc, and about 26 dB of usable power control — were taken on one board at one frequency with the receiver deliberately held out of compression; re-check ADC occupancy before trusting any of them on other hardware. The transmit calibration coefficients are worse than useless on other hardware:kanddare specific to one board at one frequency, one gain setting, and one sample rate, and the file they live in carries those three values precisely so a stale set can be spotted. Re-runcalibrate.pyrather than copying~/.cariboulite_iqcal.json. The 17–19 dB of carrier suppression and 4 dB of image suppression were measured at 445.680 MHz and-g 24; the depth of the carrier null in particular varies run to run (−43 to −63 dBc observed) with how closely the modem’s own 6-bit trim lands on the value it was calibrated against. Note that an earlier version of this page reported the opposite conclusion from an overdriven receiver, which is why the section on that is still here. Upstream has not tagged a release, so “current” means commitb98ee08(2025-07-24) — re-check whether the libiir install bug and the SWIG dict behaviour are still present before teaching them as facts. Pricing is from the 2021 crowdfunding campaign and current retail is unconfirmed. The Pi 5 remains unsupported.