Documentation refresh: align first-read docs with what shipped in PR #6

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 <authors@email.address>
+  - Dave Goncalves <davegoncalves@gmail.com>
 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: <module_website> # If you have a separate project website, put it here
-#icon: <icon_url> # 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.

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
 

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

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.

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 <gnuradio/rx888/source.h>
+    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.

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
 

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.

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)