courses

Two Radios at Once: the CaribouLite HAT

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:

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:

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:

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:

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:

  1. The kernel module did not build. CaribouLite ships its own smi_stream_dev, which replaces the in-tree bcm2835_smi_dev to add streaming. Three ordinary API changes broke it: vmalloc/vfree no longer arriving transitively, class_create() losing its owner argument in 6.4, and platform_driver.remove becoming void-returning in 6.11.
  2. 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.
  3. config.txt was 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/smi exists before you configure anything.
  4. A library was built but never installed. Upstream links the Soapy plugin against libiir under EXCLUDE_FROM_ALL, which drops its install rules, so make install succeeds and leaves a plugin that cannot dlopen().
  5. The Python bindings lie about one call. Passing a plain dict to SoapySDR.Device() silently loses the dict’s values, producing IndexError: map::at from 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

References


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, check patch_smi.py against 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 community transmission_fix branch may have drifted or disappeared. The transmit results on this page were taken against that branch at head beaf032, with the bitstream built locally and patch_smi.py applied 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: k and d are 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-run calibrate.py rather 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 commit b98ee08 (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.