¶ Spectrum Visualization with RFNoC Fosphor
This tutorial demonstrates FPGA-accelerated spectrum visualization on a USRP-2974 using the RFNoC Fosphor block and GNU Radio Companion (GRC).
¶ Overview
RFNoC Fosphor is an FPGA-accelerated spectrum visualization block that runs directly on 3rd-generation USRP devices (X310-based). It is the hardware-accelerated counterpart to gr-fosphor, which uses the CPU/GPU instead. Because the FFT and histogram processing happen in the FPGA, the host CPU is largely freed for other tasks.
This tutorial loads a custom FPGA bitstream on a USRP-2974 node in the COSMOS testbed, opens the provided RFNoC Fosphor GRC flowgraph, and runs it to produce a live spectrum display. Remote GUI access to the node is required; two methods are covered: Chrome Remote Desktop and X11 forwarding via MobaXterm.
¶ Learning outcomes
After completing this tutorial you will be able to:
- Understand the difference between CPU/GPU-based (gr-fosphor) and FPGA-based (RFNoC Fosphor) spectrum visualization.
- Load a custom RFNoC FPGA bitstream onto a USRP-2974 and verify its blocks with
uhd_usrp_probe. - Launch a GRC flowgraph on a testbed node using remote GUI access (Chrome Remote Desktop or X11 forwarding).
- Run the RFNoC Fosphor spectrum display and adjust center frequency and bandwidth interactively.
- Diagnose and fix the
usrp_x310_fpga_HG.lvbitxmissing-image error.
¶ At a glance
| Difficulty | Intermediate |
| Estimated time | 60 min |
| Domain / sandbox | COSMOS SB1 (console.sb1.cosmos-lab.org) or COSMOS BED |
| Topic group | SDR & GNU Radio |
| Last verified | Not re-tested (migrated 2026-06-20) |
¶ Prerequisites
Background knowledge
- Familiarity with the COSMOS getting-started workflow.
- Basic GNU Radio Companion usage.
- Basic UHD concepts (USRP probe, RFNoC).
Account & access
- A COSMOS account — register here.
- An approved reservation on the domain above — see Make a reservation.
- SSH access to the domain console — see SSH access.
- Remote GUI access to the node (Chrome Remote Desktop or MobaXterm with X11 forwarding) — see Chrome Remote Desktop setup.
¶ Resources required
Devices / nodes
| Resource | Role | Qty | Notes |
|---|---|---|---|
| sdr2-s1-lg1 | RFNoC Fosphor host | 1 | USRP-2974 on COSMOS SB1; alternatively sdr2-md1 on COSMOS BED |
Disk images
| Image | Load onto | Provides |
|---|---|---|
| rfnoc_fosphor_uhd4_4.ndz | sdr2-s1-lg1 | UHD 4.4, GNU Radio, GRC, RFNoC Fosphor FPGA bitstream, Chrome Remote Desktop server, desktop environment |
Software components
| Component | Version | Source |
|---|---|---|
| UHD | 4.4.0.0 | preinstalled in rfnoc_fosphor_uhd4_4.ndz |
| GNU Radio / GRC | 3.11.0.0 (git-848-g6fd69852) | preinstalled in rfnoc_fosphor_uhd4_4.ndz |
| RFNoC Fosphor FPGA bitstream | usrp_x310_fpga_XG.lvbitx | /usr/local/share/fosphor_bit/ (in image) |
| Chrome Remote Desktop server | TODO: verify | preinstalled in rfnoc_fosphor_uhd4_4.ndz |
| MobaXterm (optional, on client PC) | 20.6+ | mobaxterm.mobatek.net |
Spectrum / RF / special
The USRP-2974 is an integrated SDR unit; no external cabling is required for this tutorial. The spectrum display works over the air on whatever RF is present in the environment. Ensure your reservation covers the USRP-2974 node.
¶ Topology
A single USRP-2974 node (sdr2-s1-lg1 on SB1, or sdr2-md1 on BED) runs both the FPGA RFNoC Fosphor block and the GRC host application. The node is accessed from the COSMOS console (console.sb1.cosmos-lab.org) via SSH. A GUI session is established to the node either via Chrome Remote Desktop or X11 forwarding.
¶ Setup
-
Reserve the resources (see Prerequisites) and log into the console:
ssh <username>@console.sb1.cosmos-lab.org -
Make sure the node is off before imaging:
omf tell -a offh -t sdr2-s1-lg1 -
Load the RFNoC Fosphor image:
omf load -i rfnoc_fosphor_uhd4_4.ndz -t sdr2-s1-lg1 -
Turn the node on and check the status:
omf tell -a on -t sdr2-s1-lg1omf stat -t sdr2-s1-lg1
¶ Instructions
¶ Step 1 — Establish remote GUI access
A graphical windowing environment is required to use GRC. Choose one of the two methods below.
¶ Option A: Chrome Remote Desktop
Set up Chrome Remote Desktop access to the SDR node as described at /wiki/public/getting-started/remoteaccess/chromeremotedesktop.
The remaining steps in this tutorial can be run inside the remote desktop terminal.
¶ Option B: MobaXterm with X11 forwarding
Set up a MobaXterm SSH session directly to the SDR node, using the console as a jump host:
- Remote host:
sdr2-s1-lg1.sb1.cosmos-lab.org - Username:
root - Advanced SSH settings: enable X11 forwarding
- Network settings (jump host): gateway host =
console.sb1.cosmos-lab.org, username = your COSMOS username
When the session opens you should see:
┌────────────────────────────────────────────────────────────────────┐
│ • MobaXterm 20.6 • │
│ (SSH client, X-server and networking tools) │
│ │
│ ➤ SSH session to root@sdr2-s1-lg1.sb1.cosmos-lab.org │
│ • SSH gateway : ✔ (myusername@console.sb1.cosmos-lab.org) │
│ • SSH compression : ✔ │
│ • SSH-browser : ✔ │
│ • X11-forwarding : ✔ (remote display is forwarded through SSH) │
│ • DISPLAY : ✔ (automatically set on remote server) │
│ │
│ ➤ For more info, ctrl+click on help or visit our website │
└────────────────────────────────────────────────────────────────────┘
Last login: Fri Dec 11 04:49:36 2020 from 10.106.0.21
root@sdr2-s1-lg1:~#
Alternatively, log into the SDR from the console with X11 forwarding:
ssh native@sdr2-s1-lg1 -Y
¶ Step 2 — Verify the RFNoC Fosphor FPGA bitstream
The custom USRP-2974 FPGA image used for this tutorial is located at:
/usr/local/share/fosphor_bit/usrp_x310_fpga_XG.lvbitx
Verify that the RFNoC Fosphor block is present by probing the USRP:
uhd_usrp_probe --args="resource=RIO0"
Confirm that the Fosphor RFNoC block appears in the probe output.
¶ Step 3 — Run the RFNoC Fosphor GRC application
Open the Fosphor flowgraph with GNU Radio Companion:
gnuradio-companion /usr/local/share/gnuradio/examples/uhd/rfnoc_fosphor.grc
Expected console output:
native@sdr2-md1:/usr/local/share/fosphor_bit$ gnuradio-companion /usr/local/share/gnuradio/examples/uhd/rfnoc_fosphor.grc
<<< Welcome to GNU Radio Companion v3.11.0.0git-848-g6fd69852 >>>
Block paths:
/home/native/.local/state/gnuradio
/usr/local/share/gnuradio/grc/blocks
Loading: "/usr/local/share/gnuradio/examples/uhd/rfnoc_fosphor.grc"
>>> Done
Generating: "/tmp/rfnoc_fosphor.py"
Executing: /usr/bin/python3 -u /tmp/rfnoc_fosphor.py
Press the Run button in GRC to start the spectrum display. Use the sliders at the top and bottom of the window to adjust the center frequency and bandwidth.
¶ Verification
uhd_usrp_probe --args="resource=RIO0"lists the RFNoC Fosphor block without errors.- GRC opens
rfnoc_fosphor.grcand generates/tmp/rfnoc_fosphor.pywithout import errors. - After pressing Run, a live spectrum display window appears showing real-time RF activity.
- Moving the center frequency and bandwidth sliders updates the display.
¶ Cleanup
omf tell -a offh -t sdr2-s1-lg1
(No omf save needed unless you modified the image.)
¶ Troubleshooting
| Symptom | Likely cause | Fix |
|---|---|---|
RuntimeError: Could not find the image 'usrp_x310_fpga_HG.lvbitx' |
UHD expects HG bitstream but only XG is present (e.g. after imaging ceiling X310 nodes such as node18-20 on the grid) | Create a symlink: sudo ln -s /usr/local/share/fosphor_bit/usrp_x310_fpga_XG.lvbitx /usr/local/share/fosphor_bit/usrp_x310_fpga_HG.lvbitx |
| GRC window does not appear | X11 forwarding not active | Confirm -Y flag in SSH, or use Chrome Remote Desktop instead |
uhd_usrp_probe fails to find the device |
USRP-2974 not initialized / node still booting | Wait for omf stat to show node online; retry probe |
Full error message for the missing FPGA image:
Generating: "/tmp/rfnoc_fosphor.py"
Executing: /usr/bin/python3 -u /tmp/rfnoc_fosphor.py
[INFO] [UHD] linux; GNU C++ version 11.4.0; Boost_107400; UHD_4.4.0.0-33-g4a77791c
[INFO] [X300] X300 initialization sequence...
[INFO] [X300] Connecting to niusrpriorpc at localhost:5444...
Traceback (most recent call last):
File "/tmp/rfnoc_fosphor.py", line 287, in <module>
main()
File "/tmp/rfnoc_fosphor.py", line 264, in main
tb = top_block_cls()
File "/tmp/rfnoc_fosphor.py", line 72, in __init__
self.rfnoc_graph = uhd_rfnoc_graph = uhd.rfnoc_graph(uhd.device_addr(",type=x300,resource=RIO0"))
RuntimeError: EnvironmentError: IOError: Could not find the image 'usrp_x310_fpga_HG.lvbitx' in the image directory /usr/local/share/fosphor_bit/
For more information regarding image paths, please refer to the UHD manual.
>>> Done (return code 1)
Cause: UHD attempts to load a bitstream named usrp_x310_fpga_HG.lvbitx but only usrp_x310_fpga_XG.lvbitx exists in /usr/local/share/fosphor_bit/.
Fix: Create a symlink so UHD finds the file under the expected name:
sudo ln -s /usr/local/share/fosphor_bit/usrp_x310_fpga_XG.lvbitx /usr/local/share/fosphor_bit/usrp_x310_fpga_HG.lvbitx
¶ References
- RFNoC Fosphor FOSDEM 2015 slides
- gr-fosphor (CPU/GPU version)
- COSMOS USRP-2974 hardware page
- COSMOS getting started
- Chrome Remote Desktop setup
- SSH access
Author(s): COSMOS team · Last verified: Not re-tested (migrated 2026-06-20) · Tested image/release: rfnoc_fosphor_uhd4_4.ndz / UHD 4.4.0.0 · Tags: sdr, gnuradio, rfnoc, fosphor, usrp, usrp-2974, spectrum