dapps 0.2.1__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.1 → dapps-0.3.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dapps
-Version: 0.2.1
+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,26 +52,39 @@ 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: 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
+`docs/latrec.md`.
+
 ### Python package installation (recommended)
 
 ```
@@ -143,23 +157,27 @@ This dApp implements a spectrum sharing use case discussed in [our paper](https:
 
 **Spectrum Sensing Configuration:**
 
-- `--noise-floor-threshold` - Set the noise floor threshold (in dB) for determining the presence of incumbents and for detecting the PRBs affected. If not specified, will be auto-detected based on environment
-- `--ota` - Specify if the setup is Over-The-Air (OTA) or on Colosseum testbed for using a precalculated noise floor threshold. If `--noise-floor-threshold` is specified, this parameter is ignored
+- `--noise-floor-threshold` - Set the noise floor threshold (in dB) for determining the presence of incumbents and for detecting the PRBs affected. If not specified, the `--ru` profile value is used
+- `--ru` / `-ru` - Radio-unit profile (default: `usrp`) seeding the defaults of `--num-prbs`, `--num-subcarrier-spacing`, `--center-freq`, `--noise-floor-threshold`, `--fp16-beta`, `--sample-rate` and `--max-samples-per-file`. Explicit flags always win. Profiles: `usrp` (alias `x310`), `x410`, `x310-3p58`, `colosseum`, `foxconn`, `foxconn-273`, `benetel`, `rfsim`; see `src/spectrum/ru_profiles.py`. Settings a profile does not calibrate fall back to generic defaults with a warning. This replaces the former `--ota` flag
 
 **Visualization Options:**
 
 - `--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
 
 **Radio Configuration:**
 
-- `--num-prbs` - Number of Physical Resource Blocks in the channel (default: 106)
-- `--num-subcarrier-spacing` - Subcarrier spacing in kHz. Use 30 for FR1 (sub-6 GHz) (default: 30)
+- `--num-prbs` - Number of Physical Resource Blocks in the channel (default: from `--ru`, 106 for `usrp`)
+- `--num-subcarrier-spacing` - Subcarrier spacing in kHz. Use 30 for FR1 (sub-6 GHz) (default: from `--ru`, 30)
 - `--e` - Enable 3/4 FFT sampling mode. Set this flag if the gNB was started with the `-E` option
-- `--center-freq` - Center frequency in Hz (default: 3.6192e9, which is 3.6192 GHz)
+- `--center-freq` - Center frequency in Hz (default: from `--ru`, 3.6192e9 for `usrp`)
+- `--sample-rate` - Front-end (ADC) sample rate in Hz, written as the SigMF `core:sample_rate` (default: from `--ru`; the occupied bandwidth when the profile has none)
+- `--fp16-beta` - FP16 IQ rescale factor, must match the gNB build/config (default: from `--ru`, 1/128 for USRPs and 1/2048 otherwise)
+- `--max-samples-per-file` - SigMF segment length in samples (default: one second of the write rate, `num_prbs * 12 * SCS`)
 
 **Execution Control:**
 

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

@@ -4,26 +4,39 @@ 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: 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
+`docs/latrec.md`.
+
 ### Python package installation (recommended)
 
 ```
@@ -96,23 +109,27 @@ This dApp implements a spectrum sharing use case discussed in [our paper](https:
 
 **Spectrum Sensing Configuration:**
 
-- `--noise-floor-threshold` - Set the noise floor threshold (in dB) for determining the presence of incumbents and for detecting the PRBs affected. If not specified, will be auto-detected based on environment
-- `--ota` - Specify if the setup is Over-The-Air (OTA) or on Colosseum testbed for using a precalculated noise floor threshold. If `--noise-floor-threshold` is specified, this parameter is ignored
+- `--noise-floor-threshold` - Set the noise floor threshold (in dB) for determining the presence of incumbents and for detecting the PRBs affected. If not specified, the `--ru` profile value is used
+- `--ru` / `-ru` - Radio-unit profile (default: `usrp`) seeding the defaults of `--num-prbs`, `--num-subcarrier-spacing`, `--center-freq`, `--noise-floor-threshold`, `--fp16-beta`, `--sample-rate` and `--max-samples-per-file`. Explicit flags always win. Profiles: `usrp` (alias `x310`), `x410`, `x310-3p58`, `colosseum`, `foxconn`, `foxconn-273`, `benetel`, `rfsim`; see `src/spectrum/ru_profiles.py`. Settings a profile does not calibrate fall back to generic defaults with a warning. This replaces the former `--ota` flag
 
 **Visualization Options:**
 
 - `--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
 
 **Radio Configuration:**
 
-- `--num-prbs` - Number of Physical Resource Blocks in the channel (default: 106)
-- `--num-subcarrier-spacing` - Subcarrier spacing in kHz. Use 30 for FR1 (sub-6 GHz) (default: 30)
+- `--num-prbs` - Number of Physical Resource Blocks in the channel (default: from `--ru`, 106 for `usrp`)
+- `--num-subcarrier-spacing` - Subcarrier spacing in kHz. Use 30 for FR1 (sub-6 GHz) (default: from `--ru`, 30)
 - `--e` - Enable 3/4 FFT sampling mode. Set this flag if the gNB was started with the `-E` option
-- `--center-freq` - Center frequency in Hz (default: 3.6192e9, which is 3.6192 GHz)
+- `--center-freq` - Center frequency in Hz (default: from `--ru`, 3.6192e9 for `usrp`)
+- `--sample-rate` - Front-end (ADC) sample rate in Hz, written as the SigMF `core:sample_rate` (default: from `--ru`; the occupied bandwidth when the profile has none)
+- `--fp16-beta` - FP16 IQ rescale factor, must match the gNB build/config (default: from `--ru`, 1/128 for USRPs and 1/2048 otherwise)
+- `--max-samples-per-file` - SigMF segment length in samples (default: one second of the write rate, `num_prbs * 12 * SCS`)
 
 **Execution Control:**
 

dapps-0.3.0/VERSION

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

{dapps-0.2.1 → dapps-0.3.0}/docs/ground_truth_labeling.md

@@ -44,9 +44,9 @@ I/Q recording is only active when `--save-iqs` is passed. Without it, `--ground-
 ## Commands
 
 > [!NOTE]
-> `--ota` sets the noise floor to 20 dB, a value calibrated for the X310 USRP. That default
-> is **ignored** whenever `--noise-floor-threshold` is explicitly provided — the explicit value
-> always takes precedence regardless of `--ota`.
+> `--ru usrp` (the default) sets the noise floor to 20 dB, a value calibrated for the X310 USRP.
+> That default is **ignored** whenever `--noise-floor-threshold` is explicitly provided — the
+> explicit value always takes precedence regardless of `--ru`.
 
 The commands below use 53 dB as the noise floor threshold, which matches both the Colosseum
 testbed and the Foxconn RU calibration. Center frequency is 3.75 GHz with 106 PRBs.

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.1 → dapps-0.3.0}/examples/spectrum_dapp.py

@@ -14,10 +14,20 @@ from spectrum.spectrum_dapp import (
     compute_fft_size,
     make_periodic_toggle_callback,
 )
+from spectrum.ru_profiles import (
+    DEFAULT_RU,
+    RU_CHOICES,
+    resolve_ru_settings,
+    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")
@@ -37,28 +47,47 @@ def main(args):
             "--time-window/--moving-avg-window/--extraction-window flags."
         )
 
-    # This value really depends on the RF conditions and the RU used and
-    # should be carefully calibrated.
-    if args.noise_floor_threshold:
-        print('Using custom configuration')
-        noise_floor_threshold = args.noise_floor_threshold
-    else:
-        if args.ota:
-            print('Using OTA configuration')
-            noise_floor_threshold = 20
-        else:  # Colosseum
-            print('Using Colosseum configuration')
-            noise_floor_threshold = 53
+    settings = resolve_ru_settings(args.ru, {
+        'num_prbs': args.num_prbs,
+        'num_subcarrier_spacing': args.num_subcarrier_spacing,
+        'center_freq': args.center_freq,
+        'noise_floor_threshold': args.noise_floor_threshold,
+        'fp16_beta': args.fp16_beta,
+        'front_end_sample_rate': args.sample_rate,
+        'max_samples_per_file': args.max_samples_per_file,
+    })
+    print(f"Using radio-unit profile '{args.ru}': {settings}")
+    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 "
+              f"{', '.join(uncalibrated)}; using generic defaults")
+
+    # The noise floor depends on the RF conditions and the RU and should be
+    # 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
     # authoritative place for detector configuration.
     # ------------------------------------------------------------------
-    fft_size = compute_fft_size(args.num_prbs, args.e)
+    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,
@@ -83,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,
@@ -95,13 +130,16 @@ def main(args):
         viz_web_port=args.viz_web_port,
         viz_zmq_port=args.viz_zmq_port,
         external_viz=args.external_viz,
-        center_freq=args.center_freq,
-        num_prbs=args.num_prbs,
+        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,
-        num_subcarrier_spacing=args.num_subcarrier_spacing,
+        num_subcarrier_spacing=settings['num_subcarrier_spacing'],
         sampling_threshold=args.sampling_threshold,
-        max_samples_per_file=args.max_samples_per_file,
-        fp16_beta=args.fp16_beta,
+        max_samples_per_file=settings['max_samples_per_file'],
+        fp16_beta=settings['fp16_beta'],
+        front_end_sample_rate=settings['front_end_sample_rate'],
         sensing_only=args.sensing_only,
         strict_sensing=args.strict_sensing,
         min_sensing_symbols=args.min_sensing_symbols,
@@ -191,16 +229,21 @@ if __name__ == "__main__":
                         help="Send PRB-block control messages to the gNB when "
                              "PRBs are detected above the noise threshold")
     parser.add_argument('--noise-floor-threshold', type=int, default=None,
-                        help="Detection threshold in dB (static) or dB above noise floor (adaptive)")
+                        help="Detection threshold in dB (static) or dB above noise floor (adaptive); "
+                             "default: from --ru")
     parser.add_argument('--use-adaptive-noise-floor', action='store_true', default=False,
                         help="Use per-bin median noise floor estimation instead of a fixed threshold")
     parser.add_argument('--embargo-timeout-secs', type=float, default=10.1,
                         help="Hold time in seconds for embargoed PRBs after last detection (adaptive mode)")
     parser.add_argument('--average-over-frames', type=int, default=64,
                         help="Number of frames to average before each decision")
-    parser.add_argument('--ota', action='store_true', default=False,
-                        help="Use OTA threshold (20 dB) instead of Colosseum (53 dB). "
-                             "Ignored when --noise-floor-threshold is set.")
+    parser.add_argument('--ru', '-ru', type=str, default=DEFAULT_RU,
+                        choices=RU_CHOICES,
+                        help="Radio-unit profile seeding the defaults of --num-prbs, "
+                             "--num-subcarrier-spacing, --center-freq, "
+                             "--noise-floor-threshold, --fp16-beta, --sample-rate and "
+                             "--max-samples-per-file. Explicit flags always win. "
+                             f"Default: {DEFAULT_RU}.")
     parser.add_argument('--energy-gui', action='store_true', default=False,
                         help="Enable energy spectrum visualization")
     parser.add_argument('--iq-plotter-gui', action='store_true', default=False,
@@ -213,14 +256,22 @@ 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('--num-prbs', type=int, default=106,
-                        help="Number of PRBs")
-    parser.add_argument('--num-subcarrier-spacing', type=int, default=30,
-                        help="Subcarrier spacing in kHz (FR1 = 30)")
+    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,
+                        help="Subcarrier spacing in kHz (FR1 = 30; default: from --ru)")
     parser.add_argument('--e', action='store_true', default=False,
                         help="Enable 3/4 FFT sampling (OAI -E flag for USRPs)")
-    parser.add_argument('--center-freq', type=float, default=3.6192e9,
-                        help="RF center frequency in Hz")
+    parser.add_argument('--center-freq', type=float, default=None,
+                        help="RF center frequency in Hz (default: from --ru)")
+    parser.add_argument('--sample-rate', type=float, default=None, metavar='HZ',
+                        help="Front-end (ADC) sample rate in Hz, written as the SigMF "
+                             "core:sample_rate (default: from --ru; when the profile has "
+                             "none, the occupied bandwidth)")
     parser.add_argument('--timed', type=int, default=0, metavar='SECONDS',
                         help="Stop automatically after SECONDS (0 = run indefinitely)")
     parser.add_argument('--model', type=str, default='',
@@ -233,23 +284,22 @@ if __name__ == "__main__":
                         help="Samples to retain after CNN energy peak detection")
     parser.add_argument('--sampling-threshold', type=int, default=5,
                         help="Render a new dashboard frame every N IQ batches (visualization only, does not affect IQ delivery or recording)")
-    parser.add_argument('--max-samples-per-file', type=int, default=46_080_000,
+    parser.add_argument('--max-samples-per-file', type=int, default=None,
                         help="Rotate the SigMF capture file once a segment reaches "
-                             "this many true IQ samples (default 46080000). Each "
+                             "this many true IQ samples (default: one second of the "
+                             "dApp's write rate, num_prbs * 12 * SCS). Each "
                              "indication is kept whole, so a segment may exceed the "
                              "threshold by up to one indication's worth of samples. "
-                             "Segment wall-clock duration depends on the capture rate. "
                              "Only used with --save-iqs.")
     parser.add_argument('--ground-truth', type=str, default='', metavar='LABEL',
                         help="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.")
-    parser.add_argument('--fp16-beta', type=float, default=1.0 / 2048.0,
-                        help="FP16 IQ rescale factor; MUST match the gNB "
-                             "E3Configuration.fp16_beta (the reader rescales by "
-                             "1/beta). Default 1/2048 matches the gNB code default; "
-                             "the X410 sample conf overrides it to 0.0078125 (1/128).")
+    parser.add_argument('--fp16-beta', type=float, default=None,
+                        help="FP16 IQ rescale factor; MUST match the gNB build/config "
+                             "(the reader rescales by 1/beta). Default from --ru: "
+                             "1/128 for USRPs, 1/2048 otherwise.")
     parser.add_argument('--encoding-method', type=str, default='asn1',
                         choices=['asn1', 'json', 'protobuf'],
                         help="Wire encoding for Spectrum-* envelopes (default: asn1).")
@@ -276,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.1 → dapps-0.3.0}/pyproject.toml

@@ -19,12 +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. 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",
@@ -76,7 +78,6 @@ wheel.packages = [
     "src/dapp",
     "src/e3interface",
     "src/spectrum",
-    "src/nvidia",
     "src/simple",
     "src/iq_saver",
     "src/visualization",

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