dapps 0.2.2__tar.gz → 0.3.0__tar.gz

dapps-0.3.0/.github/workflows/test.yml

@@ -0,0 +1,38 @@
+name: Run tests
+
+on:
+  pull_request:
+    branches:
+      - main
+
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    if: github.repository != 'wineslab/dApp-library'
+    steps:
+      - uses: actions/checkout@v6
+
+      - name: Set up Python
+        uses: actions/setup-python@v6
+        with:
+          python-version: "3.12"
+
+      - name: Install build prerequisites
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake swig nlohmann-json3-dev libzmq3-dev libprotobuf-dev protobuf-compiler
+
+      # libe3py (a dependency) is built against an installed libe3 of the same version.
+      - name: Install libe3
+        env:
+          GH_TOKEN: ${{ github.token }}
+        run: |
+          ver=$(python3 -c "import re; print(re.search(r'libe3py>=([0-9.]+)', open('pyproject.toml').read()).group(1))")
+          gh release download "$ver" --repo wineslab/libe3 --pattern "libe3_${ver}_amd64.deb" --dir "$RUNNER_TEMP"
+          sudo apt-get install -y "$RUNNER_TEMP/libe3_${ver}_amd64.deb"
+
+      - name: Install package (editable, with test deps)
+        run: pip install -e ".[all]" pytest
+
+      - name: Run tests
+        run: pytest tests/ -v

{dapps-0.2.2 → dapps-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dapps
-Version: 0.2.2
+Version: 0.3.0
 Summary: A library for creating and connecting dApps to Open RAN units.
 Keywords: dApps,O-RAN,5G,cellular,networks
 Author-Email: Andrea Lacava <thecave003@gmail.com>
@@ -16,6 +16,7 @@ Project-URL: Package, https://pypi.org/project/dapps/
 Project-URL: Source, https://github.com/wineslab/dApp-library
 Project-URL: Bug Tracker, https://github.com/wineslab/dApp-library/issues
 Requires-Python: >=3.12
+Requires-Dist: libe3py<0.3,>=0.2.3
 Requires-Dist: asn1tools
 Requires-Dist: typing_extensions
 Requires-Dist: numpy
@@ -51,30 +52,34 @@ A complete tutorial on how to deploy a dApp can be found on the [OpenRAN Gym web
 
 ## Installation
 
-### Prerequisite: libe3 Python bindings (`libe3py`)
+### Prerequisite: libe3
 
 All **E3AP** operations (transport, setup handshake, subscribe, indication/control
 framing, and the ASN.1/JSON/Protobuf wire encoding) are handled by
 [**libe3**](https://github.com/wineslab/libe3); this library keeps only the
 **E3SM** (service-model) encode/decode in Python — the same split OAI uses on the
-RAN side. You must therefore install libe3 with its Python bindings **into the
-same interpreter/venv** that runs the dApp, *before* installing this package:
+RAN side. Install libe3 once, like any other library (it asks for `sudo`), at the
+same version as the `libe3py` this package pulls in:
 
 ```bash
-cd ~/libe3
-./build_libe3 --install --enable-swig \
-  --cmake-opt "-DLIBE3_ENABLE_ASN1=ON -DLIBE3_ENABLE_JSON=ON"
-python3 -c "import libe3py; print('libe3py OK')"
+git clone --branch 0.2.3 https://github.com/wineslab/libe3 && cd libe3
+./build_libe3 -I                          # build dependencies, once
+./build_libe3 --all-encodings --install   # -> /usr/local
 ```
 
+Its Python binding, `libe3py`, is a dependency of this package: pip builds it
+against the installed libe3 when you install the dApp library, in any virtual
+environment and without `sudo`.
+
 The dApp's `--link` / `--transport` / `--encoding` must match the gNB's
 `E3Configuration`. See [libe3's `swig/README.md`](https://github.com/wineslab/libe3/blob/main/swig/README.md)
 for the binding architecture.
 
 #### Latency recording (optional)
 
-Per-stage latency records (latrec) come from libe3 itself: build the bindings with
-`--cmake-opt "-DLIBE3_ENABLE_LATREC=ON"` and the dApp stamps its E3SM decode,
+Per-stage latency records (latrec) come from libe3 itself: install libe3 with
+`--cmake-opt "-DLIBE3_ENABLE_LATREC=ON"`, then rebuild the binding
+(`pip install --force-reinstall --no-cache-dir libe3py`), and the dApp stamps its E3SM decode,
 processing, output creation, E3SM encode and xApp-policy apply stages into libe3's
 rings, joinable with libe3's own by `tools/latrec2csv.py`. There is no runtime
 switch; against a binding built without it every stamp is a no-op. See libe3's
@@ -160,6 +165,7 @@ This dApp implements a spectrum sharing use case discussed in [our paper](https:
 - `--energy-gui` - Enable the energy spectrum visualization GUI
 - `--iq-plotter-gui` - Enable the I/Q constellation plotter GUI
 - `--demo-gui` - Enable the demonstration GUI showing real-time spectrum occupancy
+- `--ctrl-port N` - Dashboard control port on loopback (default 5570 with `--demo-gui`, off otherwise; `0` disables). See `src/spectrum/README.md`, "Dashboard control"
 - `--show-controls` - Show tunable controls (sampling threshold) in the dashboard GUI. Only meaningful with `--demo-gui`
 - `--ground-truth LABEL` - Initial ground truth label written into IQ annotations (only used with `--save-iqs`). Updatable at runtime via the dashboard GUI when `--demo-gui` is also set. When no PRBs are detected the label is forced to `no_rfi` regardless of what is set
 

{dapps-0.2.2 → dapps-0.3.0}/README.md

@@ -4,30 +4,34 @@ A complete tutorial on how to deploy a dApp can be found on the [OpenRAN Gym web
 
 ## Installation
 
-### Prerequisite: libe3 Python bindings (`libe3py`)
+### Prerequisite: libe3
 
 All **E3AP** operations (transport, setup handshake, subscribe, indication/control
 framing, and the ASN.1/JSON/Protobuf wire encoding) are handled by
 [**libe3**](https://github.com/wineslab/libe3); this library keeps only the
 **E3SM** (service-model) encode/decode in Python — the same split OAI uses on the
-RAN side. You must therefore install libe3 with its Python bindings **into the
-same interpreter/venv** that runs the dApp, *before* installing this package:
+RAN side. Install libe3 once, like any other library (it asks for `sudo`), at the
+same version as the `libe3py` this package pulls in:
 
 ```bash
-cd ~/libe3
-./build_libe3 --install --enable-swig \
-  --cmake-opt "-DLIBE3_ENABLE_ASN1=ON -DLIBE3_ENABLE_JSON=ON"
-python3 -c "import libe3py; print('libe3py OK')"
+git clone --branch 0.2.3 https://github.com/wineslab/libe3 && cd libe3
+./build_libe3 -I                          # build dependencies, once
+./build_libe3 --all-encodings --install   # -> /usr/local
 ```
 
+Its Python binding, `libe3py`, is a dependency of this package: pip builds it
+against the installed libe3 when you install the dApp library, in any virtual
+environment and without `sudo`.
+
 The dApp's `--link` / `--transport` / `--encoding` must match the gNB's
 `E3Configuration`. See [libe3's `swig/README.md`](https://github.com/wineslab/libe3/blob/main/swig/README.md)
 for the binding architecture.
 
 #### Latency recording (optional)
 
-Per-stage latency records (latrec) come from libe3 itself: build the bindings with
-`--cmake-opt "-DLIBE3_ENABLE_LATREC=ON"` and the dApp stamps its E3SM decode,
+Per-stage latency records (latrec) come from libe3 itself: install libe3 with
+`--cmake-opt "-DLIBE3_ENABLE_LATREC=ON"`, then rebuild the binding
+(`pip install --force-reinstall --no-cache-dir libe3py`), and the dApp stamps its E3SM decode,
 processing, output creation, E3SM encode and xApp-policy apply stages into libe3's
 rings, joinable with libe3's own by `tools/latrec2csv.py`. There is no runtime
 switch; against a binding built without it every stamp is a no-op. See libe3's
@@ -113,6 +117,7 @@ This dApp implements a spectrum sharing use case discussed in [our paper](https:
 - `--energy-gui` - Enable the energy spectrum visualization GUI
 - `--iq-plotter-gui` - Enable the I/Q constellation plotter GUI
 - `--demo-gui` - Enable the demonstration GUI showing real-time spectrum occupancy
+- `--ctrl-port N` - Dashboard control port on loopback (default 5570 with `--demo-gui`, off otherwise; `0` disables). See `src/spectrum/README.md`, "Dashboard control"
 - `--show-controls` - Show tunable controls (sampling threshold) in the dashboard GUI. Only meaningful with `--demo-gui`
 - `--ground-truth LABEL` - Initial ground truth label written into IQ annotations (only used with `--save-iqs`). Updatable at runtime via the dashboard GUI when `--demo-gui` is also set. When no PRBs are detected the label is forced to `no_rfi` regardless of what is set
 

dapps-0.3.0/VERSION

@@ -0,0 +1 @@
+0.3.0

dapps-0.3.0/examples/hackathon_policy.py

@@ -0,0 +1,27 @@
+"""Starting point of the RAN control dApps hackathon: write your policy here.
+
+Run it with::
+
+    python3 -m examples.spectrum_dapp --link zmq --transport tcp --encoding-method asn1 \\
+        --control -ru rfsim --num-prbs 106 --center-freq 3619200000 --e \\
+        --policy examples.hackathon_policy:MyPolicy
+"""
+
+from spectrum.policy import BaselinePolicy, Observation, Policy
+
+
+class MyPolicy(Policy):
+    """Return the set of PRBs to block; the PRBs you leave out are released.
+
+    ``obs.prb_power_db`` has one level per PRB (dB, relative to the gNB's FFT counts),
+    ``obs.power_db`` one per subcarrier, ``obs.valid`` marks what was measured, and
+    ``self.history`` holds the previous observations. State lives on ``self``.
+    """
+
+    def update(self, obs: Observation) -> set[int]:
+        # TODO: replace this with your own policy.
+        return set()
+
+
+class ReferencePolicy(BaselinePolicy):
+    """A working but simple policy to compare against: ``--policy examples.hackathon_policy:ReferencePolicy``."""

{dapps-0.2.2 → dapps-0.3.0}/examples/spectrum_dapp.py

@@ -21,9 +21,13 @@ from spectrum.ru_profiles import (
     uncalibrated_keys,
 )
 from spectrum.threshold_detector import StaticThresholdDetector, AdaptiveThresholdDetector
+from spectrum.policy import PolicyDetector, load_policy
 
 LOG_DIR = '/tmp/'
 
+# Not 5560: that is where a co-resident C++ dApp serves its dashboard control.
+DEFAULT_CTRL_PORT = 5570
+
 def stop_program(time_to_wait, dapp: SpectrumSharingDApp):
     time.sleep(time_to_wait)
     print(f"[INFO] Timer elapsed after {time_to_wait} seconds")
@@ -56,6 +60,8 @@ def main(args):
     uncalibrated = [
         key for key in uncalibrated_keys(args.ru)
         if getattr(args, key, None) is None
+        # a --policy decides the blacklist itself; the threshold is not used
+        and not (args.policy and key == 'noise_floor_threshold')
     ]
     if uncalibrated:
         print(f"[WARNING] Profile '{args.ru}' has no calibrated value for "
@@ -65,7 +71,8 @@ def main(args):
     # carefully calibrated.
     noise_floor_threshold = settings['noise_floor_threshold']
 
-    print(f'Threshold is {noise_floor_threshold}')
+    if not args.policy:
+        print(f'Threshold is {noise_floor_threshold}')
 
     # ------------------------------------------------------------------
     # Build the detection strategy explicitly so the example is the
@@ -73,7 +80,14 @@ def main(args):
     # ------------------------------------------------------------------
     fft_size = compute_fft_size(settings['num_prbs'], args.e)
 
-    if args.use_adaptive_noise_floor:
+    if args.policy:
+        detector = PolicyDetector(
+            load_policy(args.policy),
+            fft_size=fft_size,
+            num_prbs=settings['num_prbs'],
+        )
+        print(f"[INFO] Detector: PolicyDetector | policy: {args.policy}")
+    elif args.use_adaptive_noise_floor:
         detector = AdaptiveThresholdDetector(
             snr_threshold_db=noise_floor_threshold,
             fft_size=fft_size,
@@ -98,6 +112,12 @@ def main(args):
             f" | window: {args.average_over_frames} frames"
         )
 
+    # Dashboard control: on with --demo-gui at the default port, off otherwise.
+    # An explicit --ctrl-port that cannot be bound is fatal; the default is not.
+    ctrl_port = args.ctrl_port
+    if ctrl_port is None:
+        ctrl_port = DEFAULT_CTRL_PORT if args.demo_gui else 0
+
     dapp = SpectrumSharingDApp(
         detector=detector,
         save_iqs=args.save_iqs,
@@ -110,6 +130,8 @@ def main(args):
         viz_web_port=args.viz_web_port,
         viz_zmq_port=args.viz_zmq_port,
         external_viz=args.external_viz,
+        ctrl_port=ctrl_port,
+        ctrl_port_required=args.ctrl_port is not None and ctrl_port > 0,
         center_freq=settings['center_freq'],
         num_prbs=settings['num_prbs'],
         e_sampling=args.e,
@@ -234,6 +256,10 @@ if __name__ == "__main__":
                         help="ZMQ port the dApp publishes on / the visualizer reads (default 5559)")
     parser.add_argument('--external-viz', action='store_true', default=False,
                         help="Don't spawn the visualizer; publish to an already-running one")
+    parser.add_argument('--ctrl-port', type=int, default=None,
+                        help=f"Dashboard control port (loopback). Default {DEFAULT_CTRL_PORT} "
+                             "with --demo-gui, off otherwise; 0 disables. With --external-viz, "
+                             "point the visualizer's --ctrl-port at it.")
     parser.add_argument('--num-prbs', type=int, default=None,
                         help="Number of PRBs (default: from --ru)")
     parser.add_argument('--num-subcarrier-spacing', type=int, default=None,
@@ -300,6 +326,11 @@ if __name__ == "__main__":
                              "require fully-clean slots (equivalent to "
                              "--strict-sensing).")
 
+    parser.add_argument('--policy', type=str, default=None, metavar='MODULE:CLASS',
+                        help="Decide the PRB blacklist with a spectrum.policy.Policy subclass "
+                             "(e.g. examples.hackathon_policy:MyPolicy) instead of a threshold "
+                             "detector. Overrides --use-adaptive-noise-floor.")
+
     # --- Optional sensing-policy toggle ----------------------------- #
     # Drives the gNB's masked UL TDA selector via spectrum_sm ctrl_id=2.
     # Disabled by default (toggle-period=0); set --toggle-period to a

{dapps-0.2.2 → dapps-0.3.0}/pyproject.toml

@@ -19,15 +19,14 @@ classifiers = [
 ]
 license = "Apache-2.0"
 license-files = ["LICENSE"]
-# NOTE: E3AP transport is provided by libe3's Python bindings (`libe3py`),
-# which are not on PyPI. **libe3 >= 0.2.0 is required**: 0.2.0 added the
-# correlation id that DAppSession.send_report() now takes as a mandatory
-# argument, so an older binding fails at the E3 setup handshake against a
-# matching gNB. Install them into this environment with:
-#   cd ~/libe3 && ./build_libe3 --install --enable-swig \
-#     --cmake-opt "-DLIBE3_ENABLE_ASN1=ON -DLIBE3_ENABLE_JSON=ON"
+# E3AP transport is libe3's Python binding, `libe3py` (on PyPI). pip builds it
+# against the libe3 installed on the machine, which must be the same version:
+# install libe3 once first (`./build_libe3 --all-encodings --install`, see
+# https://github.com/wineslab/libe3). The 0.2 series is required: 0.2.0 made the
+# correlation id a mandatory argument of DAppSession.send_report().
 # (asn1tools is still required for the in-Python service-model codecs.)
 dependencies = [
+    "libe3py>=0.2.3,<0.3",
     "asn1tools",
     "typing_extensions",
     "numpy",

dapps-0.3.0/src/dapp/control_server.py

@@ -0,0 +1,126 @@
+"""ZMQ REP server for the dashboard's control channel.
+
+The subcarrier dashboard proxies every control click as one JSON request
+(``{"cmd": ...}``) over a REQ socket and waits at most 2 s for one JSON reply.
+This module only moves JSON: the semantics live in the handlers a dApp
+registers, so it knows nothing about spectrum sensing.
+
+Binds loopback only. The socket is bound in the constructor, so a port that is
+already in use is reported to the caller before anything else is started.
+"""
+
+from __future__ import annotations
+
+import json
+import threading
+from typing import Callable
+
+from e3interface.e3_logging import dapp_logger
+
+Handler = Callable[[dict], dict]
+
+_POLL_MS = 200
+
+
+class ControlBindError(RuntimeError):
+    """The control port could not be bound (typically: already in use)."""
+
+
+class ControlServer:
+    """REP server; one daemon thread, one reply per request, always."""
+
+    def __init__(self, port: int, host: str = "127.0.0.1",
+                 tick: Callable[[], None] | None = None) -> None:
+        import zmq  # lazy: pyzmq is an optional extra
+
+        self._zmq = zmq
+        self._handlers: dict[str, Handler] = {}
+        self._tick = tick
+        self._stop = threading.Event()
+        self._thread: threading.Thread | None = None
+        self._ctx = zmq.Context()
+        self._sock = self._ctx.socket(zmq.REP)
+        self._sock.setsockopt(zmq.LINGER, 0)
+        try:
+            if int(port) == 0:
+                # let the OS pick: there is no window between choosing a free port and binding it
+                port = self._sock.bind_to_random_port(f"tcp://{host}")
+            else:
+                self._sock.bind(f"tcp://{host}:{int(port)}")
+        except zmq.ZMQError as exc:
+            self._sock.close(0)
+            self._ctx.term()
+            raise ControlBindError(
+                f"cannot bind control port tcp://{host}:{port}: {exc}") from exc
+        self.host = host
+        self.port = int(port)
+
+    def register(self, cmd: str, handler: Handler) -> None:
+        self._handlers[cmd] = handler
+
+    def start(self) -> None:
+        if self._thread is not None:
+            return
+        self._thread = threading.Thread(
+            target=self._loop, name="dapp_ctrl", daemon=True)
+        self._thread.start()
+
+    def stop(self) -> None:
+        self._stop.set()
+        if self._thread is not None:
+            self._thread.join(timeout=2.0)
+            self._thread = None
+        try:
+            self._sock.close(0)
+            self._ctx.term()
+        except Exception:
+            pass
+
+    def dispatch(self, raw: str) -> dict:
+        """Turn one request string into a reply dict (never raises)."""
+        try:
+            req = json.loads(raw)
+        except ValueError as exc:
+            return {"ok": False, "error": f"parse: {exc}"}
+        if not isinstance(req, dict):
+            return {"ok": False, "error": "parse: request must be a JSON object"}
+        cmd = req.get("cmd")
+        handler = self._handlers.get(cmd) if isinstance(cmd, str) else None
+        if handler is None:
+            return {"ok": False, "error": f"unknown cmd: {cmd}"}
+        try:
+            reply = handler(req)
+        except ValueError as exc:
+            return {"ok": False, "error": str(exc)}
+        except Exception as exc:
+            dapp_logger.exception("control handler %r failed", cmd)
+            return {"ok": False, "error": f"internal: {exc}"}
+        return reply
+
+    def _loop(self) -> None:
+        zmq = self._zmq
+        poller = zmq.Poller()
+        poller.register(self._sock, zmq.POLLIN)
+        while not self._stop.is_set():
+            if self._tick is not None:
+                try:
+                    self._tick()
+                except Exception:
+                    dapp_logger.exception("control tick failed")
+            if not dict(poller.poll(_POLL_MS)):
+                continue
+            try:
+                raw = self._sock.recv_string()
+            except zmq.ZMQError:
+                continue
+            reply = self.dispatch(raw)
+            try:
+                self._sock.send_string(json.dumps(reply))
+            except (zmq.ZMQError, TypeError, ValueError):
+                # An unserialisable reply must still be answered, or the REP
+                # socket stays in the "must send" state and wedges.
+                try:
+                    self._sock.send_string(json.dumps(
+                        {"ok": False, "error": "internal: bad reply"}))
+                except zmq.ZMQError:
+                    pass

{dapps-0.2.2 → dapps-0.3.0}/src/e3interface/libe3_agent.py

@@ -8,12 +8,10 @@ drives. Service-model (E3SM) payloads stay opaque here as ``bytes`` and are
 encoded/decoded in the dApp subclasses (spectrum/simple), mirroring the OAI
 split where libe3 handles E3AP and the SM handles encode/decode.
 
-``libe3py`` is provided by installing libe3 with the SWIG bindings enabled::
+``libe3py`` comes from PyPI (a dependency of this package) and is built against
+the libe3 installed on the machine; install libe3 once first::
 
-    ./build_libe3 --install --enable-swig \
-        --cmake-opt "-DLIBE3_ENABLE_ASN1=ON -DLIBE3_ENABLE_JSON=ON"
-
-Import it into the same interpreter/venv that runs the dApp.
+    ./build_libe3 --all-encodings --install
 """
 
 from __future__ import annotations
@@ -64,13 +62,15 @@ def _libe3py_is_current() -> bool:
 LIBE3PY_USABLE = LIBE3PY_AVAILABLE and _libe3py_is_current()
 
 _BUILD_CMD = (
-    "  cd ~/libe3 && ./build_libe3 --install --enable-swig "
-    '--cmake-opt "-DLIBE3_ENABLE_ASN1=ON -DLIBE3_ENABLE_JSON=ON"'
+    "  # once, in a libe3 checkout of the same version (https://github.com/wineslab/libe3):\n"
+    "  ./build_libe3 -I && ./build_libe3 --all-encodings --install\n"
+    "  # then, in this environment:\n"
+    "  pip install --force-reinstall --no-cache-dir libe3py"
 )
 
 _IMPORT_HINT = (
-    "libe3py is not importable. Build and install the libe3 Python bindings "
-    "into this environment:\n" + _BUILD_CMD
+    "libe3py is not importable. Install libe3, then its Python binding into "
+    "this environment:\n" + _BUILD_CMD
 )
 
 _VERSION_HINT = (
@@ -78,7 +78,7 @@ _VERSION_HINT = (
     "E3Event.sequence_id). That release made the correlation id a mandatory "
     "argument of DAppSession.send_report(), so this binding cannot complete "
     "the E3 setup handshake against a matching gNB -- the run fails with "
-    "'RAN refused Setup'. Rebuild and reinstall the bindings:\n" + _BUILD_CMD
+    "'RAN refused Setup'. Install libe3 and libe3py of the 0.2 series:\n" + _BUILD_CMD
 )
 
 # ErrorCode.SUCCESS is 0 in libe3.

dapps-0.3.0/src/spectrum/README.md

@@ -0,0 +1,104 @@
+# Spectrum dApp pipeline — from gNB radio to browser waterfall
+
+The spectrum dApp senses the uplink, optionally blacklists PRBs on the gNB, and
+streams a live subcarrier-power waterfall to a browser. It talks to the gNB over
+E3 (libe3) and reads bulk IQ / sensing ranges from POSIX shared memory.
+
+## Data flow
+
+```
+gNB PHY ── L1-KPM SM (RF=2) ──► E3 indication: shm pointer + validSymbolMask
+   │                              └► dApp reads IQ from /e3_ran_buffers (FP16)
+   └─ Spectrum SM (RF=1) ──► E3 indication: shm ref (shmWriteIdx, nRanges)
+                                  └► dApp reads ranges from /e3_l2_sensing ring
+dApp: magnitude ─► detector (masked adaptive noise floor) ─► PRB blacklist control (RF=1)
+   └► ZMQ PUB (per-slot u8 power) ─► subcarrier_visualizer.py ─► browser (WebGL2 waterfall)
+```
+
+## Service models (both ASN.1/APER and JSON)
+
+- **RF=2 L1-KPM** — per-slot IQ telemetry. The indication carries an shm
+  reference (`/e3_ran_buffers`, `fhBufferIndex`, `fhWriteIndex`), `sfn`/`slot`,
+  and `validSymbolMask` (14-bit UL-symbol bitmap). IQ layout is
+  `[ant=4][sym=14][prb=273][sc=12]` FP16. See `e3_ran_buffers_reader.py`.
+- **RF=1 Spectrum** — sensing-range telemetry + PRB-block / sensing-policy
+  control. The `Spectrum-SensingIndication` references the `/e3_l2_sensing` ring
+  (`shmWriteIdx`, `nRanges`); each record is a `(start_symbol, num_symbols,
+  rb_start, rb_size)` rectangle. See `e3_l2_sensing_reader.py`.
+
+The ASN.1 grammars (`defs/e3sm_oai_l1_kpm.asn`, `defs/e3sm_spectrum.asn`) are
+copied **verbatim** from the OAI gNB so the wire stays byte-identical.
+
+## Sensing window
+
+The dApp caches the RF=1 sensing ranges by `(sfn, slot)` and applies them to the
+matching RF=2 IQ slot (`sensing_only`, default on) to build a 2D (symbol, PRB)
+keep-mask. Out-of-window columns are excluded from the adaptive noise-floor
+history (not fed as zeros), so ambient UE PRBs don't skew the floor.
+
+## Visualizer
+
+`--demo-gui` binds a ZMQ PUB and (by default) spawns the standalone
+`visualization/subcarrier/subcarrier_visualizer.py` (Flask + WebSocket + WebGL2,
+R8 textures via `texStorage2D`) on `--viz-web-port` (5001). The dApp publishes one
+multipart frame per slot (`subcarrier_power|sfn|slot|n_ant|n_sym|n_sc|u8|db_min|
+db_max|det=…|det_n=…|det_thr=…` + u8 power, plus a detection-mask frame when the
+detector has flagged PRBs); see `visualization/subcarrier_pub.py`. The render
+grid width follows the active carrier (`--num-prbs`×12 subcarriers, e.g. 1272 for
+106 PRB), so the waterfall renders on any bandwidth. Use `--external-viz` to feed
+an already-running visualizer. The dApp tells it the carrier centre and
+subcarrier spacing, so the x axis is labelled in MHz (ticks above the waterfall,
+and a PRB / subcarrier / MHz readout under the cursor); without `--center-freq`
+information the axis shows indices only.
+
+## Dashboard control (protocol v1)
+
+With `--demo-gui` the dApp also serves the dashboard's control panels on a ZMQ
+REP socket, `tcp://127.0.0.1:5570` by default. `--ctrl-port N` picks another
+port, `--ctrl-port 0` turns it off. The default port is not 5560 so it never
+collides with another dApp's control port; if it is already taken the dApp warns
+and runs without control (panels greyed), whereas an explicit `--ctrl-port` that
+cannot be bound stops the dApp. With `--external-viz`, start the visualizer with
+the same `--ctrl-port` (and `--num-prbs`).
+
+Requests are one JSON object per frame with a `"cmd"`; every reply has `"ok"`
+and, on failure, `"error"`. The dashboard waits 2 s for the reply.
+
+| cmd | request | effect |
+|---|---|---|
+| `caps` | – | what this dApp supports: detector kind, per-field availability and the reason when a field is greyed out |
+| `block` | `enabled` (bool); none = query | start/stop forwarding detections to the gNB; xApp-sourced blocks stay installed |
+| `detect` | `config`: `enabled`, `granularity` (`sc`/`prb`), `threshold_db`, `hist_depth`, `embargo_secs`, `mask_with_sensing`; `{}` = query | change the active detector; all-or-nothing |
+| `viz` | `config`: `freq_gran`, `time_gran`, `agg`, `subsample_n`; `{}` = query | what the dApp publishes to the dashboard |
+| `start` / `stop` / `status` | `duration_s` (0, 86400], `notes` | SigMF recording |
+
+`mask_with_sensing` (the L1xL2 filter, `sensing_only`) masks the dashboard as well
+as the detector input: each slot's keep mask (sensing ranges and valid symbols)
+is built once and the published frame has every other cell at the floor, so the
+dashboard shows what the detector sees, slot by slot, without the UE's own
+transmissions. A slot with no sensed cell is not published.
+
+`detect` applies to the threshold detectors. Under `--policy` the policy decides
+the blocks, so only `mask_with_sensing` (the L1xL2 filter, i.e. `sensing_only`)
+can be changed; the other fields are greyed out. A static detector has no
+embargo, and its `hist_depth` is the averaging window. Granularity `prb`
+averages the 12 subcarriers of a PRB before detection and rebuilds the detector
+(history is lost); the red strip still shows the result per subcarrier. A change
+that resets the adaptive history (`hist_depth`, `granularity`) while a constant
+incumbent is already on makes that incumbent the new noise floor, so it is no
+longer detected; the adaptive floor suits bursty interference.
+
+Recording (`start`) is independent of `--save-iqs`: it writes every antenna,
+every symbol and the gNB's whole 273-PRB slot as `cf32_le`, one record per slot
+laid out `[ant][sym][prb][sc][I,Q]` (PRBs beyond the cell bandwidth are zero),
+with one annotation per slot (`sfn`, `slot`, sensing ranges, valid-symbol mask).
+A full 4-antenna slot is about 1.8 MB, so the writer runs on its own thread and
+reports `dropped` slots instead of stalling detection; `start` is refused with
+less than 2 GiB free in the log directory.
+
+## Robustness
+
+- Both shm readers detect a gNB restart (the gNB recreates the regions with a
+  new inode) and remap.
+- The FH staleness bound is derived from the ring depth in the shm header
+  (`num_fh_rows`), not a hardcoded value.