How it works
The whole RSP driver stack has been reverse engineered and rewritten in the open, from the firmware on the receiver up to the API that applications call. It was done for one reason: so the community can understand the stack, maintain it, and keep improving it.
Every layer below is written up in the project's documentation, alongside the code and the tests. Nothing is a black box any more, so anyone can pick up a layer and work on it.
The layers
| Layer | What it does | What OpenRSP provides |
|---|---|---|
| 1. USB bridge firmware | An 8051 microcontroller in the receiver's USB bridge chip. The driver uploads its firmware each time the receiver is plugged in. | New open-source firmware, written from a specification of how the original behaves. It uses the same upload protocol and fixes seven bugs found in the original. Builds with the free SDCC compiler and is checked in a simulator against the original. |
| 2. USB protocol | The vendor control requests that write registers, read device information and start and stop the stream, plus the layout of the isochronous and bulk sample packets. | A complete, documented description of the protocol, and an implementation whose control traffic is byte-identical to the original's in every recorded test session. |
| 3. Tuner and front end | Programming the tuner over its serial bus: frequency synthesis, bands, IF filters, LNA states and gain reduction, and each model's front-end features such as notch filters, bias-T and antenna selection. | Per-model implementations with the same gain tables and register sequences, for all seven RSP models. |
| 4. Stream processing | Turning USB packets into I/Q samples: unpacking, low-IF down-conversion, decimation, DC offset and I/Q imbalance correction, and power and overload estimation. | Fixed-point code that is bit-exact with the original, with optional AVX2, AVX-512 and NEON versions that give identical results. |
| 5. AGC | The automatic gain control loop that adjusts gain reduction from the measured signal power. | The same control loop, verified decision by decision against recordings of the original, plus a fix for a case where the original AGC stops working. |
| 6. Device service | The background process that finds receivers, checks them, uploads the firmware, owns the USB connection, streams, and watches its clients' heartbeats. | A service with the same behaviour, the same install layout and the same systemd unit, that never contacts the network and shuts down cleanly. |
| 7. Library-to-service protocol | How the API library and the service talk: shared-memory blocks for commands, parameters and the sample ring, and named locks and semaphores. Applications write their settings straight into memory the service owns, so the layout itself is part of the API. | A matching implementation on Linux, Windows and macOS, plus an Android version that lets the OpenRSP driver app serve other apps. |
| 8. Application API | The sdrplay_api_* functions, structures and callbacks that applications
use. |
An API- and ABI-identical library and its own headers. Existing applications work unchanged; see Compatibility. |
Because the layers are separate, they can be mixed: OpenRSP's library works with the vendor's service and the other way round. That makes it possible to test each layer on its own against the original, and it lets users move over one piece at a time.
Built for further development
Reverse engineering the stack was the hard part. Now that it is open, it can move forward in ways that were not possible before:
- New platforms. Android and iPadOS already work. Other systems need only a thin platform layer for USB, shared memory and locking.
- Bug fixes. Crashes, hangs and the AGC lock-up in the original have already been fixed, and anyone can now find and fix the next one.
- Performance. The service already uses less CPU than the original, and there is more to gain.
- Firmware. The bridge firmware is open source, so it can be studied, fixed and extended too.
A large test suite comes with the code: replayed USB sessions, bit-exact DSP and AGC vectors, a USB emulator of every RSP model that runs in a virtual machine, and tests that run real applications. A change can be checked against the original's recorded behaviour before it goes anywhere near a receiver.
Get involved
Contributions of every size are welcome. Some useful places to start:
- Test an experimental model. If you own an RSP1, RSP2, RSPdx or RSPdx-R2, a report of what works and what does not is the most valuable thing you can send.
- Test Windows or ARM Linux with a receiver attached. These builds pass their unit tests but have not yet streamed from real hardware. On macOS, Intel Macs still need testing with a receiver.
- Write apps. Android and iPad apps can now use RSP receivers. The Client Demo is a starting point.
- Optimise. The DC-offset filter is the biggest remaining CPU cost, and hand-written vector versions are an open task.
- Review and document. Read the protocol notes, check them against your own hardware, and improve them.
The code and documentation will be published soon, with details on this site.