From 89e003a78f34038ca15bf2950751be45d7849e14 Mon Sep 17 00:00:00 2001 From: Claude Date: Fri, 15 May 2026 06:07:38 +0000 Subject: [PATCH] Documentation refresh after the librx888 ABI sync + audio demo MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit PR #6 grew through several rounds of fixes and the surrounding docs ended up out of date. This pass walks every doc file and brings it back in line with what actually ships: README.md - Drop the "pre-alpha" / "-DWITH_RX888=ON gates a silent block" paragraph; v0.2 is in. - rx888-tools link points at ringof/, not ka9q/. - Block parameter table: samprate default 32e6 (was 64.8e6). - Stream tags / status messages are clearly marked as planned for a follow-up, not currently emitted. - grc-demo entrypoint description matches reality (AM BCB audio flowgraph + PulseAudio passthrough, not the old hf_waterfall + --device /dev/snd). - Status section reflects v0.1/v0.2 shipped + v0.3 in flight. examples/README.md - am_bcb_audio_demo block diagram now includes the chan_decim=10 stage we added; audio_decim is 4 (not the stale 40). - audio.sink note describes the ALSA-pulse-plugin routing through the host's PulseAudio, not --device /dev/snd. MANIFEST.md - Real author / copyright / license / repo / tags instead of the gr_modtool template placeholders. docs/PLAN.md - Live status snapshot at the top: librx888 shipped, gr-rx888 v0.2 shipped, sanitizers green, what's next. Original plan body preserved unchanged. docs/README.rx888 - Was a gr_modtool template that imported `rx888` instead of `gnuradio.rx888`. Replaced with a brief, correct C++/Python import recipe and a pointer to the example flowgraphs. docker/grc-demo.sh - Header comment updated: PulseAudio socket bind-mount is the audio recipe now, --device /dev/snd was the failed prior path. include/gnuradio/rx888/source.h - Doxygen example for `samprate` shows 32e6 / 135e6 (the firmware-supported values), not 64.8e6. tests/mock/CMakeLists.txt - LIBRX888_INCLUDE_DIRS dropped the stale ${CMAKE_SOURCE_DIR}/tests/librx888 entry (that dir was deleted when librx888 went upstream). No code behavior changes. Verified locally with -DWITH_RX888_MOCK=ON build + ctest — both qa_source and qa_source_mock pass. --- MANIFEST.md | 34 ++++++++++++--------- README.md | 52 ++++++++++++++++----------------- docker/grc-demo.sh | 8 +++-- docs/PLAN.md | 11 +++++++ docs/README.rx888 | 34 ++++++++++++++++----- examples/README.md | 22 +++++++++----- include/gnuradio/rx888/source.h | 3 +- tests/mock/CMakeLists.txt | 3 +- 8 files changed, 107 insertions(+), 60 deletions(-) diff --git a/MANIFEST.md b/MANIFEST.md index ea5347a..528389d 100644 --- a/MANIFEST.md +++ b/MANIFEST.md @@ -1,17 +1,25 @@ -title: The RX888 OOT Module -brief: Short description of gr-rx888 -tags: # Tags are arbitrary, but look at CGRAN what other authors are using +title: gr-rx888 — RX888 mk II SDR Source +brief: GNU Radio source block for the RX888 mk II direct-sampling 16-bit / up-to-130 MSPS HF digitizer +tags: - sdr + - hf + - rx888 + - direct-sampling + - librx888 author: - - Author Name + - Dave Goncalves copyright_owner: - - Copyright Owner 1 -license: -gr_supported_version: # Put a comma separated list of supported GR versions here -#repo: # Put the URL of the repository here, or leave blank for default -#website: # If you have a separate project website, put it here -#icon: # Put a URL to a square image here that will be used as an icon on CGRAN + - Free Software Foundation, Inc. +license: GPL-3.0-or-later +gr_supported_version: v3.10 +repo: https://github.com/ringof/gr-rx888 --- -A longer, multi-line description of gr-rx888. -You may use some *basic* Markdown here. -If left empty, it will try to find a README file instead. +A GNU Radio out-of-tree module that exposes the RX888 mk II SDR as a +single `rx888.source` block via the `librx888` streaming library. +Streams real int16 ADC samples to float32 with int16/32768 scaling; +parameters cover sample rate, RF attenuator, AD8370 VGA, ADC dither, +output-randomization, and reference oscillator. + +Pre-built example flowgraphs ship in `examples/` (AM Broadcast Band +receiver with audio out, full-spectrum diagnostic view), plus a +self-contained Docker image and a host preflight + smoketest script. diff --git a/README.md b/README.md index ad3ecf3..20296b2 100644 --- a/README.md +++ b/README.md @@ -4,14 +4,10 @@ GNU Radio out-of-tree module for the **RX888 mk2** direct-sampling digitizer — a 16-bit, up-to-130 MSPS ADC with an HF-tuned analog front end, exposed as a single GR source block. -Pre-alpha. The block scaffold is in place; the librx888 backend is -landing separately in [`rx888-tools`](https://github.com/ka9q/rx888-tools) -and is gated by the CMake option `-DWITH_RX888=ON` (off by default). -With `WITH_RX888=OFF` the block builds, installs, and emits silence so -flowgraphs can be wired up against the final API. - -See [`docs/PLAN.md`](docs/PLAN.md) for the design rationale, scope, -and how this module relates to ka9q-radio, rx888-tools, and the FX3 +v0.2 — the block streams real samples from real hardware via +[`librx888`](https://github.com/ringof/rx888-tools). See +[`docs/PLAN.md`](docs/PLAN.md) for the design rationale, scope, and +how this module relates to ka9q-radio, rx888-tools, and the FX3 firmware. ## Block @@ -20,18 +16,18 @@ firmware. | Parameter | Type | Default | Meaning | |-------------|------|---------|----------------------------------------| -| `samprate` | real | 64.8e6 | ADC sample rate (Hz) | -| `atten` | real | 0 | RF step attenuator (dB) | -| `vga_gain` | real | 0 | VGA gain (dB) | +| `samprate` | real | 32e6 | ADC sample rate (Hz); firmware-supported: 32e6, 135e6 | +| `atten` | real | 0 | RF step attenuator (dB), 0–31.5 in 0.5 dB steps | +| `vga_gain` | real | 0 | VGA gain (dB), AD8370 (auto low/high range) | | `dither` | bool | False | ADC dither | | `rand` | bool | True | ADC output-randomization decode | -| `reference` | real | 27e6 | Reference oscillator (Hz) | +| `reference` | real | 27e6 | Reference oscillator (Hz, advisory) | -Stream tags emitted on output 0: `rx_rate`, `rx_atten`, `rx_vga_gain`, -`rx_time`. - -Async message port `status` carries: `usb_overflow`, `host_overflow`, -`device_gone`, `firmware_version`, `clock_locked`. +Planned for a follow-up release: stream tags (`rx_rate`, `rx_atten`, +`rx_vga_gain`, `rx_time`) and an async `status` message port +(`usb_overflow`, `host_overflow`, `device_gone`, `firmware_version`, +`clock_locked`). The block currently exposes the configuration knobs +above but does not yet emit those metadata channels. ## Build @@ -68,17 +64,18 @@ sudo ldconfig If your laptop has the wrong GR version or you want a known-good build to ship on a USB stick for the booth, there's a self-contained container in [`docker/`](docker/) that bundles librx888 + GR 3.10 + -this module. One command runs the CLI smoke test: +this module + the helper scripts. One command runs the CLI smoke test: ```sh docker/build.sh docker run --rm -it --privileged -v /dev/bus/usb:/dev/bus/usb gr-rx888:latest ``` -There's also a `grc-demo` entrypoint that launches the bundled HF -waterfall flowgraph with X11 forwarding. See [`docker/README.md`](docker/README.md) -for both modes, plus the host-side prep (`usbfs_memory_mb`, udev -rules) the container can't do for you. +The `grc-demo` entrypoint launches the AM BCB receiver flowgraph +(audio out via host PulseAudio/PipeWire) with X11 forwarding. See +[`docker/README.md`](docker/README.md) for the full run line +(audio + X11 + USB), plus the host-side prep (`usbfs_memory_mb`, +udev rules) the container can't do for you. ## At the bench @@ -104,10 +101,13 @@ See [`examples/README.md`](examples/README.md). ## Status -- v0.1 — scaffold + block stub. No hardware I/O. -- v0.2 — librx888 link, streaming pipeline, stream tags + status messages. -- v0.3 — three example flowgraphs (`hf_receiver_demo`, `raw_recorder`, - `spectrogram_demo`). +- **v0.1 (shipped)** — `gr_modtool` scaffold + `rx888.source` block stub. +- **v0.2 (shipped)** — links `librx888`; streams real int16 samples through + an SPSC ring to `work()`; six block parameters wire through to the + device; ASan / TSan / valgrind clean. +- **v0.3 (in flight)** — stream tags (`rx_rate`, `rx_atten`, etc.) and + the async `status` message port; switch to the upcoming typed-setter + firmware API (see [`docs/firmware-api-plan.md`](docs/firmware-api-plan.md)). ## License diff --git a/docker/grc-demo.sh b/docker/grc-demo.sh index dfc4c04..8efd3c3 100755 --- a/docker/grc-demo.sh +++ b/docker/grc-demo.sh @@ -18,9 +18,11 @@ rx888_preflight --quiet || { } # Default to the AM BCB receiver demo — tunable slider + waterfall + -# PSD + audio out. Needs --device /dev/snd on the docker run line for -# host speakers to hear it; falls back to silent visualization if -# audio isn't accessible. +# PSD + audio out. Needs the host's PulseAudio socket bind-mounted +# into the container for the speakers to hear it: +# -v /run/user/$(id -u)/pulse:/tmp/pulse:ro -e PULSE_SERVER=unix:/tmp/pulse/native +# Without it the flowgraph still starts but audio.sink fails to open. +# See docker/README.md for the full run line. # # For the wide-spectrum diagnostic view (no audio, no tuner): # gnuradio-companion /opt/gr-rx888/examples/hf_waterfall_demo.grc diff --git a/docs/PLAN.md b/docs/PLAN.md index 7aea737..ec891e1 100644 --- a/docs/PLAN.md +++ b/docs/PLAN.md @@ -1,5 +1,16 @@ # Plan: librx888 + gr-rx888 +> **Status snapshot (live):** +> - `librx888` has shipped in [`rx888-tools`](https://github.com/ringof/rx888-tools). +> ABI: 9 public `rx888_*` symbols. Firmware blob pinned via +> `rx888-tools/firmware/VERSION`. +> - `gr-rx888` v0.2 has shipped — `rx888.source` streams real samples +> through librx888 with full ASan / TSan / valgrind coverage. +> - Booth-ready examples (`am_bcb_audio_demo.grc`, etc.) and a +> Docker image with audio + USB passthrough are in tree. +> - Next: stream tags, `status` message port, typed firmware API +> (see [`firmware-api-plan.md`](firmware-api-plan.md)). + A pair of minimal, composable artifacts that let GNU Radio (and any other consumer with a C linker) use the RX888mk2 as a 16-bit, 130 MSPS direct-sampling digitizer with an HF-tuned analog front end. diff --git a/docs/README.rx888 b/docs/README.rx888 index bb4ce9c..cb6d40b 100644 --- a/docs/README.rx888 +++ b/docs/README.rx888 @@ -1,11 +1,29 @@ -This is the rx888-write-a-block package meant as a guide to building -out-of-tree packages. To use the rx888 blocks, the Python namespaces -is in 'rx888', which is imported as: +gr-rx888 — GNU Radio block for the RX888 mk II direct-sampling SDR. - import rx888 +Provides one source block, gr::rx888::source, which streams real +int16 ADC samples from the device via librx888 and converts them to +float32 in the range [-1.0, 1.0). -See the Doxygen documentation for details about the blocks available -in this package. A quick listing of the details can be found in Python -after importing by using: +Python import: - help(rx888) + from gnuradio import rx888 + src = rx888.source(samprate=32_000_000, + atten=0.0, vga_gain=0.0, + dither=False, rand=True, + reference=27e6) + +C++ include: + + #include + auto src = gr::rx888::source::make(32e6, 0.0, 0.0, + false, true, 27e6); + +Pre-built example flowgraphs live under share/gnuradio/grc/examples +(installed) or examples/ (source tree): + + am_bcb_audio_demo.grc Tunable AM BCB receiver with audio out + am_bcb_demo.grc Same tuner, no audio (visualization only) + hf_waterfall_demo.grc Full 0-16 MHz diagnostic view + +See the top-level README for build and bench setup, examples/README.md +for flowgraph details, and docs/PLAN.md for the design rationale. diff --git a/examples/README.md b/examples/README.md index 41f3ae3..039f112 100644 --- a/examples/README.md +++ b/examples/README.md @@ -12,17 +12,25 @@ rx888.source (32 MS/s real) → float_to_complex (imag = 0) → freq_shift_cc (-center_freq, retunes live) → rational_resampler_ccc (decim=16) → 2 MS/s complex - ├→ qtgui_waterfall_sink_c + qtgui_freq_sink_c - └→ analog.am_demod_cf (audio_decim=40, 5 kHz LPF) → 50 kHz real + ├→ qtgui_waterfall_sink_c + qtgui_freq_sink_c (±1 MHz around tune) + └→ rational_resampler_ccc (decim=10) → 200 kHz complex + → analog.am_demod_cf (audio_decim=4, 3 kHz audio LPF) → 50 kHz real → rational_resampler_fff (24/25) → 48 kHz → multiply_const_ff (volume slider) - → audio.sink (ALSA default device) + → audio.sink (ALSA default → pulse plugin → host PulseAudio) ``` -Use this inside the Docker image via `docker run --device /dev/snd ... grc-demo` -(see `docker/README.md`). The `--device /dev/snd` flag is required for -the host's speakers to hear the audio — without it the flowgraph -still starts but `audio.sink` errors out. +The extra decim stage before `am_demod_cf` keeps the block's +internal `optfir.low_pass` Parks-McClellan design inside a sane +numerical range — going directly from 2 MS/s to 50 kHz audio asks +for several thousand filter taps and pm_remez bails. + +Use this inside the Docker image via the audio + X11 + USB run line +in [`../docker/README.md`](../docker/README.md). The container's +`audio.sink` writes to ALSA's `default` device, which is wired +through the pulse plugin to the host's PulseAudio/PipeWire — no +contention for `/dev/snd`. Skip the pulse bind-mount and the audio +sink still fails to open at start. ## `am_bcb_demo.grc` — silent tuner variant diff --git a/include/gnuradio/rx888/source.h b/include/gnuradio/rx888/source.h index 504a9d6..75d9852 100644 --- a/include/gnuradio/rx888/source.h +++ b/include/gnuradio/rx888/source.h @@ -38,7 +38,8 @@ class RX888_API source : virtual public gr::sync_block /*! * \brief Construct an rx888 source. * - * \param samprate ADC sample rate in Hz (e.g. 64.8e6, 130e6). + * \param samprate ADC sample rate in Hz. Firmware-supported + * values: 32e6, 135e6. * \param atten RF attenuator setting in dB (front-end step attenuator). * \param vga_gain VGA gain in dB. * \param dither Enable ADC dither. diff --git a/tests/mock/CMakeLists.txt b/tests/mock/CMakeLists.txt index ca39c6d..465a24f 100644 --- a/tests/mock/CMakeLists.txt +++ b/tests/mock/CMakeLists.txt @@ -38,8 +38,7 @@ target_compile_options(rx888_mock PRIVATE -fvisibility=default) # Surface the variables the top-level CMakeLists.txt expects, mirroring # what pkg_check_modules(LIBRX888 ...) would set. set(LIBRX888_LIBRARIES rx888_mock PARENT_SCOPE) -set(LIBRX888_INCLUDE_DIRS ${CMAKE_SOURCE_DIR}/tests/librx888 - ${CMAKE_CURRENT_SOURCE_DIR} PARENT_SCOPE) +set(LIBRX888_INCLUDE_DIRS ${CMAKE_CURRENT_SOURCE_DIR} PARENT_SCOPE) set(LIBRX888_LIBRARY_DIRS ${CMAKE_CURRENT_BINARY_DIR} PARENT_SCOPE) set(LIBRX888_CFLAGS_OTHER "" PARENT_SCOPE)