A couple years ago, after I heard about the CaribouLite on CrowdSupply, I pre-ordered one.
I've dabbled in SDR with an RTL-SDR v3 for a few years, even using one with nrsc5 to listen to baseball games OTA because of silly MLB blackout restrictions.
But low-cost SDRs like the RTL-SDR v3 are receive-only, and have a limited frequency range, and lower quality RF filtering, so it can be frustrating if you're trying to work with lower-power RF... or trying to transmit at all!
So the CaribouLite's hackable FPGA, the open source firmware, and it's much better frequency range (30 MHz up to 6 GHz) combined with TX capabilities to make it enticing.
Well, I received my CaribouLite back in March... of 2023. And it was sitting in my 'RF' box since then. I decided to pull it out and plug it into a Pi to see how it works or if it's worth the extra $100 I spent on it over another RTL-SDR v3!
Video
I also published a video showing the CaribouLite in action—though the rest of this blog post after the video embed covers setup and usage in more detail:
Choosing a Pi
This being a Raspberry Pi HAT—and one that relies on a Broadcom SoC feature that's not well documented (SMI), you have to use it with a Pi. The Pi has to have a 40-pin GPIO header, and it also can't be a Pi 5—since that uses the RP1 chip for GPIO access, and doesn't give you direct SMI integration into the Broadcom SoC :(
But a Pi 4 is still plenty powerful enough—honestly even a Pi 3 B+ or Pi Zero 2 would work in many scenarios—so I went with a 1 GB Pi 4, which currently costs $35 (and people say Pis are so expensive!).
I flashed the latest 64-bit Pi OS 12 ('Bookworm') onto a microSD card, and plugged in the CaribouLite to the GPIO header.
Installing CaribouLite Drivers on Pi OS Bookworm
Following Caribou Labs' guide for setting up the driver necessary to communicate with CaribouLite for software like Soapy SDR and GQRX (among others), I found there were two additional patches required to get the driver to work on Debian 12/Bookworm.
So here are all the commands I ran to install it:
# Clone CaribouLite repository to the Pi.
git clone https://github.com/cariboulabs/cariboulite.git
cd cariboulite
# Apply patch for Bookworm: https://github.com/cariboulabs/cariboulite/pull/210
curl -L https://patch-diff.githubusercontent.com/raw/cariboulabs/cariboulite/pull/210.patch | git apply -v
# Apply patch to fix compile error: https://github.com/cariboulabs/cariboulite/pull/176
# (THIS WILL FAIL—SEE MY NOTE FOR INSTRUCTIONS HOW TO APPLY IT MANUALLY:
# - https://github.com/cariboulabs/cariboulite/pull/176#issuecomment-2596019689)
curl -L https://github.com/cariboulabs/cariboulite/pull/176.patch | git apply -v
# Run the installer.
./install.sh
# During installation, it will prompt "Did not find SoapySDRUtil"
# Enter 'y'
The compilation will take a few minutes (at least, it did on my Pi 4), then it will install drivers and link a number of libraries on the system for CaribouLite to work on the Pi.
On my installation, it flagged two warnings at the end:
3. I2C-VC Configuration... Warning
To communicate with CaribouLite EEPROM, the i2c_vc device needs to be enabled
Please add the following to the /boot/firmware/config.txt file: 'dtparam=i2c_vc=on'
4. SPI1-3CS Configuration... Warning
To communicate with CaribouLite Modem, FPGA, etc, SPI1 (AUX) with 3CS needs to be to be enabled
Please add the following to the /boot/firmware/config.txt file: 'dtoverlay=spi1-3cs'
So add those options by editing the config.txt file, with sudo nano /boot/firmware/config.txt. Add these lines above the dtparam=audio=on line:
# CaribouLite
dtparam=i2c_vc=on
dtoverlay=spi1-3cs
Save that file, and reboot. Once rebooted, make sure smi_stream_dev is loaded:
pi@pi4-sdr:~ $ lsmod | grep smi
smi_stream_dev 16384 2
bcm2835_smi 20480 1 smi_stream_dev
Updating issues with xtrx-dkms
After running CaribouLite's installer, I noticed my apt operations would bail out after trying to update xtrx-dkms:
Setting up xtrx-dkms (0.0.1+git20190320.5ae3a3e-3.2) ...
Removing old xtrx-0.0.1+git20190320.5ae3a3e-3.2 DKMS files...
Deleting module xtrx-0.0.1+git20190320.5ae3a3e-3.2 completely from the DKMS tree.
Loading new xtrx-0.0.1+git20190320.5ae3a3e-3.2 DKMS files...
Building for 6.6.51+rpt-rpi-v8
Building initial module for 6.6.51+rpt-rpi-v8
Error! Bad return status for module build on kernel: 6.6.51+rpt-rpi-v8 (aarch64)
Consult /var/lib/dkms/xtrx/0.0.1+git20190320.5ae3a3e-3.2/build/make.log for more information.
Looking in that log, I found the same error indicated by the CaribouLite compile error:
/var/lib/dkms/xtrx/0.0.1+git20190320.5ae3a3e-3.2/build/xtrx.c:1523:35: note: in expansion of macro ‘THIS_MODULE’
1523 | xtrx_class = class_create(THIS_MODULE, CLASS_NAME);
| ^~~~~~~~~~~
It looks like that error is fixed as of early 2024. See commit d218d3e in myriadrf/xtrx_linux_pcie_drv: xtrx.c: fix build error with kernel 6.4.
But getting that patched into the 0.0.1+git20190320.5ae3a3e-3.2 version in Debian Bookworm may be a little annoying. I haven't looked into this much, I'm just ignoring it for now, because other apt operations and installs still work, it just always errors out on this package.
Remote SDR via SoapySDR
If you want to access the CaribouLite across the network from another computer (I typically launch GQRX on my Mac at my desk), launch SoapySDRServer:
sudo systemctl start SoapySDRServer.service
You can check on the status of the service with status instead of start, or observe the logs in real time with:
sudo journalctl --follow -u SoapySDRServer.service
I was able to use both frequency/antenna options:
- HiF (High Frequency): 30 MHz-6 GHz
- S1G (Sub-1 GHz): 389.5-510 MHz and 779-1020 MHz
During operation, while I was streaming the SDR over to GQRX on my Mac, btop showed between 50-150 Mbps of bandwidth, and CPU activity was around 15-20% (pretty low system load). While not streaming, load is practically nothing.
I could even see 2.4 GHz WiFi traffic on my local network, which was operating on channel 6 (2437 MHz center frequency):
If you want SoapySDRServer to be running at boot, run:
sudo systemctl enable SoapySDRServer.service
One thing I did notice: I initially had both WiFi and Ethernet enabled on the Pi 4 while I was testing. Even though the WiFi connection could put through at least 100 Mbps with no problem, it messed up the SDR stream, to the point I would hear very choppy audio when decoding anything in GQRX.
To fix that, I disabled WiFi (you could use nmtui, but I used nmcli instead):
sudo nmcli radio wifi off
Local SDR with GQRX
I also wanted to test SDR software directly on the Pi, so I installed GQRX:
sudo apt install gqrx-sdr
After installation, open up GQRX and control it on the Pi the same as you would any computer.
I had two issues with the apt version of GQRX:
- It seems after getting some data, the UI would freeze, though the CPU indicated it was still decoding the signal. So maybe an issue with CaribouLite's driver + Debian packaged GQRX?
- If I went anywhere near higher FFT/decoding quality settings, the Pi's CPU would either max out one core (single thread), or use a high amount of CPU resources to try rendering things...
So it may be better to run the SDR UI on another machine or via a Web UI, so the Pi doesn't have to render everything! I'm guessing the Pi 5 would cope much better, as it has 2-3x faster performance both per core and multicore.
SDR Web UI
I may also install OpenWebRX so I can have the Pi host a little Web UI SDR interface, instead of having to run SDR software either directly on the Pi, or remotely on another computer.
For some additional CaribouLite tutorials, like using it for ADS-B reception with a Pi Zero, check out David Michaeli's YouTube channel.
Comments
This is neat! I've been thinking about setting up an SDR listening station at home. I hadn't heard of the CaribouLite though before and I'm intrigued by it being a transceiver. Have you transmitted with this on the amateur bands? I'm also really keen to dive into the M17 protocol one of these days, and am curious if the CaribouLite could be used for this.
TX isn't quite as refined on the CaribouLite but should work okay. I haven't been testing that side of it yet, but hope to soon. Right now I'm working on an HF loop RX antenna though, hopefully I can explore sub-30 MHz with that, we'll see!
I needed to use a older PiOS (Lite) Bookworm with Kernel 6.1 first then I got "smi_stream_dev" loaded. Tried to downgrade the kernel on the newest bookworm 6.6 but no success. Anyhow it works now, thanks for the guide!
I think it's advisable to turn off both wifi and bluetooth in the /boot/firmware/config.txt file which should be the closest thing to removing it on a hardware level: dtoverlay=disable-bt and dtoverlay=disable-wifi (NB: with dashes not underscores, which I think I did wrong in my youtube comment, sorry).
Have you had a look at installation.md instead of the README.md on the Cariboulite Git? It looks like Bookworm added a few problems.
" Note: Major issues with the newly published distro bookworm - the required kernel modules cannot compile agains the latest 6.1.0 'bookworm' distribution. We noticed that the kernel-headers in the latest rapsberry-pi image distributions do not agree with the mainline linux kernel modules compilation process. Same issues exist with other kernel modules compilations in other projects. This issue needs to be further inspected. Therefore we suggest using the latest bullseye distribution bullseye 6.1.21-*. See details bellow. "
That comment (and indeed most of the information in the repo currently) is a bit old, the last commit was a while ago.
See the two patches I mention in my setup guide—those are necessary to get the CaribouLite kernel module to compile against the latest 6.6.y Raspberry Pi OS kernel in Bookworm.
I know this because my setup is currently running on Bookworm, with all the latest updates :)
I've tried this about 6 times tonight. The first patch succeeds but the second one always throws an error. I can make, and run, but if I try to connect to it remotely Soapy crashes. So far, still plugging away but nothing seems to work yet. I've even tried to follow their bookworm installation guide on this RP 4 with 4g ram and a fresh OS installs.
Can you post any of soapy's errors to that issue (and also the output for the failing patch)?
I should have grabbed the error before I followed your info at https://github.com/cariboulabs/cariboulite/pull/176 (which I only just now discovered.) I had to manually edit the smi_steam_dev.c file in /driver and then run the make install script again. This time, no errors and Soapy worked w/o crashing. It appears that that manual change in smi_stream_dev.c is necessary.
Ah makes sense! I have updated the note in my instructions above since I had forgotten I even indicated to 'See my notes' — you have to apply the patch manually for now, or maybe we can get a new branch / PR up there or the one that's up there adjusted...
Fantastic. Thanks for the tutorial and responsiveness. Your work is of great value to me.
I tried setting this up on a pi 0 w and a pi4. while everything compiled and loaded I saw a lot of dma misses in the kernel log output. Trying to use it over the ethernet and wifi remotely. Is there something I misconfigured causing this issue?
Thanks.
Great guide! I've been messing with this HAT for a year or so now and have just recently gotten it to work. If anyone else is using a rpi zero 2 w, I would recommend using the legacy RPiOS (10-22-2024) release since it's not working so well with kernel 6.6.
If you apply the two patches in my guide above, it should work with 6.6.y, on the latest Pi OS Bookworm release.
Giving this another try; the first patch applies fine, but the second gives the following:
Yep - that's what happens to me, too. I followed the guide down to the letter and it fails every time.
In the same boat. Can't get it to work.. Has anyone found a solution?
See the other reply thread above; you have to apply the second patch manually for now.
Sorry, I can't really follow all the "manual patching" stuff, so I'm just going to see about going back to an older Raspberry Pi OS to get it working. I am a bit surprised it seems like this project is kinda a few years old and hasn't been poked much, based on the github dates, so not surprised The Future™ broke things, but...
Success with an older OS! Let me share what I scavenged and did to get it working on Raspian Bullseye.
I managed to find that someone had put some info on the CaribouLite github about getting it to work with a specific version (Bullseye) here: https://github.com/cariboulabs/cariboulite/commit/745ad287038eef297b0e7…
That got me as far as compiling and running the test programs and getting the Pi to talk to the hat successfully. However, it was missing the software for talking to the device over the net, and in Jeff's blog post where he talks about running the service, the SoapySDRServer.service was simply not present on the system. I did a general Google to start from scratch on "how to get this running" and managed to find this post pretty easily, fortunately: https://github.com/cariboulabs/cariboulite/discussions/98
There it discusses pulling the git repository for SoapySDR server. Combining that info with Jeff's commands to get the service running (although I think the above link has them as well), I was able to install gqrx via Homebrew on my Mac and see the Caribou automagically upon running it, just as Jeff had. That's as far as I've gotten -- just connected via gqrx and I'm seeing/hearing info come in. Hope this helps others, and I have a feeling once a dev pays attention to Jeff's notes about patching, we can more easily get it running in the latest OS.
Indeed! I hope they don't just give up on the CaribouLite because it is a neat little project, certainly makes for a compact powerful SDR with an inexpensive Pi Zero 2W or Pi 4!
Ordering this off of crowdsupply it "recommended" (it was the first option it gave when you added the Caribou to your cart) a Raspberry PI Zero, do you think this will still work with the even lower specs vs the Pi Zero 2? I guess I'll find out in a few days when it arrives but I'm thinking I should just the better PI.
Got it working on a Pi Zero following this guide and this updated instruction set: https://github.com/cariboulabs/cariboulite/blob/main/installation.md I was then was able to get Soapy chatting with GPRX on my mac 😄
I'm curious if you have any recommendations for doing spectrum analysis on mac through soapy? I'd love to see the state of the 5.6-5.9ghz spectrum for sniffing out drone video interference at races. GQRX automatically connects, but I couldn't get any other SDR software to see this device, or anything running on the pi to pick up the interface.
This product has had an extremely painful birth. A lot was promised by the developers - a lot of headaches ensued for a long time. Do NOT buy it unless you're prepared to do a lot of detailed fault-finding and you are totally OK with diving deep into the inner workings of Rapsberry Pis. Software installation is simply a nightmare - viz. you own experience! Despite lots of helpful advice online from boffins who had managed to bend the firmware into shape somehow, I was still unable to get it running reliably after numerous attempts. It's been lying in a box for a year, and will probably be disposed of as 'electronic waste' one day ...
Thanks, Jeff, for looking into this. The board had been on my desk for over a year and I could not get it running.
I took a fresh minimal Bookworm install on the Pi Zero 2W, followed your instructions and got about as far as the below ending up with pages and pages of Python compile errors.
I would really love to see this working and maybe you can lend the devs a hand to clean up their code. What a world it would be where you could just compile the code without manually applying patches, etc.
Maybe you have an idea on the below. Thanks again for your help!
Hi Jeff, thanks for doing this. I got _started_, but some issues.
I have brand new 4GB Raspberry Pi 4b with RPiOS (Bookworm) I downloaded today. I installed the one without the desktop and extra apps because I usually use X11 from my main Linux box to connect. The Pi is working fine after I installed my usual collection of APT packages.
I followed your path precisely, and had to upgrade Linux kernel to newest and THEN run install.sh again to get the SMI streaming driver to work with the kernel. This is now obvious that it had to be this way.
My problem: When I run gqrx on main Linux box (very big AMD machine) via 1GbE connection to the Pi (also 1GbE), I get choppy/stuttery audio with a repeating pattern of gaps no matter how I change sample rate (which I think I have gathered is supposed to be 4,000,000 and decimation (which I have tried all values of). Changing sample rate to 2M or adding more decimation changes the frequency and duration of the audio chops. The waterfall chops at the same rate as the audio, so I think it's a DSP sample-gathering issue from the Caribou FPGA, causing zeros to be burped into the bubbles in the sampling pipeline for missing data.
You could maybe help a bit if you add your sample rate (no menu of options at least for me and my gqrx) and your decimation level. But I suspect I have something more that is wrong.
Do you or anyone on this board have any ideas about what I'm doing wrong? Thanks in advance!
One thing to check quickly is the network path—first, are you connected through the same switch, or possibly through a router/firewall/VLAN that might be causing any packet delays or queueing?
Second, is the Pi (or your PC) connected to both wired Ethernet and WiFi at the same time? Try disabling one of the two connections if so, that caused stuttering for me.
FYI I found that CubicSDR worked much better for me than gqrx, but the UI of CubicSDR, while much more general and powerful, is a little buggy and hard to figure out. RTFM helped a lot. At one point I - unknowningly - had four "demodulators" which made me crazy. Getting down to one was key to getting anything to work for me.
Ah; I'm also starting to experiment with SDR++, which seems to run a little faster for me than Gqrx. There are so many SDR UIs now, heh... should probably do an overview of them!
Jeff, should the patches and install work well on VERSION="11 (bullseye)" on a pi 3 B+ or should I pickup a small pi 4?
tnx. Bradshaw, Buzzards Bay, MA