bladeRF-fsk(1)

📦 version 0.2025.10, in debian bookworm, debian trixie, ubuntu jammy, ubuntu noble, ubuntu questing, ubuntu resolute, ubuntu stonking

💖 NAME 💖

bladeRF-fsk — the command line fsk application, bestie! That's bladeRF-fsk(1) if you're being formal about it (section 1, we stan a numbered section), and it's a Nuand joint. 🫶

✨ DESCRIPTION ✨

Okay so, the bladeRF-fsk project is a simple frequency shift keying (FSK) based software modem that's implemented entirely on the host PC side, in C code. No cap. 🧚

It uses libbladeRF to transmit/receive samples with a bladeRF device. And here's the cute part: a USB 3.0 port is not required when using this modem. So your sad lil USB 2.0 port can come too. 🎀

The project also contains a MATLAB/Octave simulation/implementation of the physical layer (PHY) portion of the modem. Fancy. Iconic. 💅

The top level bladeRF-fsk C program demonstrates the functionality of the modem in a simple bladeRF-to-bladeRF data transfer program. It can transmit/receive both:

  • text — like a chat program 💬
  • binary files — like a file transfer program 📁

…with a raw link rate of 250 kbps. To properly demonstrate the program, two instances of the program must be run with two separate bladeRF devices. And no, bestie, loopback is not supported. 😭

🦋 The modulation tea 🦋

The modem modulates with continuous-phase frequency shift keying (CPFSK). Baseband I/Q CPFSK samples are sent to the bladeRF device, inside which they are converted from digital to analog, mixed with quadrature RF carriers, and transmitted through the air. ✈️✨ Received signals get mixed with quadrature RF carriers to downconvert to baseband I/Q, sampled with an ADC, and sent to the host PC program over the USB connection.

🔥 What the layers are giving 🔥

The physical layer code features:

  • an FIR low-pass filter
  • power normalization
  • preamble correlation for signal detection
  • CPFSK modulation/demodulation
  • scrambling

The link layer code features:

  • framing
  • error detection via CRC32 checksums
  • guaranteed delivery of frames via acknowledgements and retransmissions
⚠️ Real talk though: this project is meant to be an experimental example and should not be treated as a rigorous modem. It's giving "fun little demo", not "certified telecom equipment". Adjust your expectations accordingly, bestie. 💀

🌈 EXAMPLES 🌈

To run the top-level bladeRF-fsk program with defaults, type into a terminal:

bladeRF-fsk

To see a list of configuration options and how to set them, type:

bladeRF-fsk -h
🍓 NOTE: On Windows 10, if you are running two instances of the program on the same PC, you must specify the bladeRF serial number with the -d option, due to Issue #484 (https://github.com/Nuand/bladeRF/issues/484). Example:
bladeRF-fsk -d *:serial=4e

💜 Defaults & deets 💜

By default the program:

  • uses the first available bladeRF device
  • gets TX input from stdin
  • writes RX output to stdout
  • uses a default set of transmit/receive frequencies and gains

Gains may need to be tweaked for a good connection with another bladeRF running bladeRF-fsk. 👑 To transfer files, use the -i and -o options. If using stdin for tx data, the program will transmit data line-by-line.

The program runs until it gets an EOF in its TX input. That's the vibe check that ends the party. 🎈

🎀 Example: Transferring Files 🎀

  1. Be sure two bladeRF devices are plugged into your PC (or two separate PCs) with TX and RX antennas attached. 📡📡
  2. Run bladeRF-fsk on one of the devices (receiver), with the output RX file specified:
bladeRF-fsk -r 904M -t 924M -o rx.jpg
  1. Run bladeRF-fsk on the other device (sender), with opposite frequencies and the input TX file specified:
bladeRF-fsk -r 924M -t 904M -i puppy.jpg
  1. The file will begin transferring, and progress will be printed in the terminal for the sending device. 🐶➡️✨
  2. Once the transmission is complete, press [CTRL-D] on Linux/OSX or [CTRL-Z then ENTER] on Windows to stop the program on the receiving end.
💀 If the sending device does not get any response from the receiving device, it will quit the program. Try increasing the gains and run it again. (Not me, not the gains — the gains. 😭)

💀 KNOWN LIMITATIONS 💀

  1. The program does not currently support the use of an XB-200 transverter expansion board to transmit/receive at frequencies below 300MHz. In order to add XB-200 support, a new configuration option as well as functions from the "Expansion boards" section of the libbladeRF API would need to be added to the source code. So… PRs welcome, bestie? 👀
  2. The program is currently unable to perform two file transfers in both directions simultaneously. And like, there are two reasons why:
    • Reason #1: The program runs until it gets an EOF in its TX input, meaning whichever side finishes transmitting its file first will quit and stop receiving. An EOF bit would need to be added to the link layer packet format in order to stop this behavior.
    • Reason #2: The program doesn't seem to perform well during these simultaneous file transfers, and usually loses connection. Further investigation is required to debug this. 🕵️♀️💅

👀 SEE ALSO 👀

And that's the whole page, babes! 🌸 This manual came to you from BLADERF, version 2017.07, dated 2017.07 — and yeah, it's the bladeRF-fsk(1) page, mwah. 💋 Go forth and fsk responsibly. 🦋💖

📦 where this page comes from