gr-rx888 — Docker quickstart

1Plug the RX888 into a USB-3 port

Use the supplied USB-3 cable. On the laptop, pick a blue USB port — that's USB-3 (5 Gbps). Black USB-2 ports will not deliver enough bandwidth and streaming will fail.

The little LED on the RX888 should glow. Leave it plugged in for every step below.

2Open a terminal and verify it's there

Open Terminal (Ctrl+Alt+T on most Ubuntu desktops). Then ask Linux what's on the USB bus:

lsusb | grep -i 04b4

You should see a line containing 04b4:00f1 (firmware loaded) or 04b4:00f3 (bootloader — it'll be flashed automatically the first time the container runs). 04b4 is the Cypress USB vendor ID; the RX888's FX3 chip uses it. If you see nothing, the cable or the port is the problem — try a different blue port.

3Install Docker

Docker is a tool that runs a pre-packaged environment containing GNU Radio, the RX888 driver, and everything else you'd otherwise have to build by hand. On Ubuntu, install the version from the distro repos:

sudo apt update
sudo apt install -y docker.io

By default docker needs sudo on every command. Add yourself to the docker group so you can skip that forever:

sudo usermod -aG docker $USER

4Log out and back in

Group membership only takes effect on a fresh login session. The command you just ran will not work yet — you have to log out of your desktop and log back in (or reboot the machine). Once you've logged back in, open a new Terminal and confirm you're in the docker group:

groups | tr ' ' '\n' | grep docker

It should print docker. If nothing prints, log out again or reboot — the group really does need a new session.

5Run Docker's hello-world test

Before we touch any radio code, confirm Docker itself is healthy by running its tiny built-in test container:

docker run --rm hello-world

You should see a friendly multi-line banner that begins with "Hello from Docker!" and explains what just happened. If instead you see permission denied while trying to connect to the Docker daemon socket, you skipped Step 4 — log out, log back in, and try again.

6Raise the kernel's USB buffer limit

At 32 MS/s the RX888 fills the kernel's default USB transfer buffer faster than userspace can drain it. The symptom is LIBUSB_ERROR_NO_MEM from the driver. The fix is one line:

sudo sh -c 'echo 1000 > /sys/module/usbcore/parameters/usbfs_memory_mb'

This raises the cap from the default 16 MB to 1 GB. It's not persistent — the value resets at every reboot. To make it permanent, add usbcore.usbfs_memory_mb=1000 to your kernel command line. For first-time bring-up, the one-shot above is fine.

7Clone gr-rx888

sudo apt install -y git
git clone https://github.com/ringof/gr-rx888.git
cd gr-rx888

Stay in this gr-rx888 directory for the rest of the steps.

8Build the Docker image

docker/build.sh

This runs docker build against the recipe in docker/Dockerfile. It downloads Ubuntu 24.04, GNU Radio 3.10, the RX888 firmware blob, and compiles librx888 and gr-rx888 from source. First run takes 5–15 minutes depending on your bandwidth. Subsequent runs are instant (cached).

When it finishes, list your images to confirm:

docker images

You should see a gr-rx888 row with tag latest.

9Let Docker draw on your screen

GNU Radio Companion is a graphical application. The container needs permission to open windows on your desktop:

xhost +local:docker

(Run xhost -local:docker after the demo to revoke that.)

10Run the AM Broadcast Band demo

The image's grc-demo command opens the bundled AM receiver flowgraph in GRC. The long-looking command below is one logical line that passes USB, audio, and display sockets into the container:

docker run --rm -it --privileged \
  -v /dev/bus/usb:/dev/bus/usb \
  -v /run/user/$(id -u)/pulse:/tmp/pulse:ro \
  -e PULSE_SERVER=unix:/tmp/pulse/native \
  -e DISPLAY=$DISPLAY \
  -v /tmp/.X11-unix:/tmp/.X11-unix \
  gr-rx888:latest grc-demo

You'll see a few preflight checks (USB-3 link, firmware, device permissions) scroll past, then a GNU Radio Companion window opens with am_bcb_audio_demo.grc loaded.

11Execute the flowgraph

1. In GRC, click the Execute button — the ► play icon in the toolbar (or press F6).
2. A second window opens with a waterfall, a PSD plot, a Tune slider (540–1700 kHz) and a Volume slider.
3. Drag the Tune slider until you hit a strong AM station — the waterfall will show a bright vertical line. Adjust Volume.

Other entrypoints

• … gr-rx888:latest (no argument) → CLI smoketest: one second of samples, prints PASS/FAIL. Good for bench bring-up.
• … gr-rx888:latest shell → interactive bash inside the container with rx888_stream, rx888_preflight, and gnuradio-companion on the PATH.

!Troubleshooting

sudo sh -c 'echo 1000 > /sys/module/usbcore/parameters/usbfs_memory_mb'