dapps 0.1.0__tar.gz → 0.2.0__tar.gz

{dapps-0.1.0 → dapps-0.2.0}/.github/ISSUE_TEMPLATE/new_sm.yml

@@ -77,7 +77,7 @@ body:
     id: paired_issue
     attributes:
       label: Paired libe3 issue / PR (if any)
-      placeholder: "wineslab/dApp-libe3#123"
+      placeholder: "wineslab/libe3#123"
     validations:
       required: false
 

{dapps-0.1.0 → dapps-0.2.0}/.github/PULL_REQUEST_TEMPLATE.md

@@ -30,8 +30,8 @@ Closes #
 
 These mirror what CI (`.github/workflows/test.yml`) enforces. **All boxes must be ticked before review.**
 
-- [ ] `hatch run pytest tests/ -v` passes locally on Python 3.12
-- [ ] `hatch build` succeeds (verifies packaging metadata)
+- [ ] `pytest tests/ -v` passes locally on Python 3.12 (after `pip install -e ".[all]"`)
+- [ ] `python -m build` succeeds (verifies packaging metadata and the C++/SWIG build)
 - [ ] `VERSION` file bumped per [SemVer](https://semver.org/) if the public API or wire protocol changed
 - [ ] `README.md` updated if interface, environment variables, or workflow changed
 - [ ] `CONTRIBUTING.md` updated if contributor-facing rules changed
@@ -43,7 +43,7 @@ These mirror what CI (`.github/workflows/test.yml`) enforces. **All boxes must b
 
 ## Twin-repo coordination
 
-dapps is paired with [`libe3`](https://github.com/wineslab/dApp-libe3) and [`dApp-openairinterface5g`](https://github.com/wineslab/dApp-openairinterface5g). Breaking changes to the twin repos are not accepted.
+dapps is paired with [`libe3`](https://github.com/wineslab/libe3) and [`dApp-openairinterface5g`](https://github.com/wineslab/dApp-openairinterface5g). Breaking changes to the twin repos are not accepted.
 
 - [ ] This PR does not break the E3 wire protocol, OR a paired PR exists in the affected twin repo (link below).
 

{dapps-0.1.0 → dapps-0.2.0}/.github/workflows/tag-and-release.yml

@@ -63,8 +63,14 @@ jobs:
           python-version: "3.8"
       - name: Install pypa/build
         run: python3 -m pip install build --user
-      - name: Build a binary wheel and a source tarball
-        run: python3 -m build
+      - name: Build a source tarball (sdist)
+        # sdist only: the compiled extension produces a non-portable
+        # linux_x86_64 wheel that PyPI rejects. `pip install dapps` builds the
+        # sdist on the user's machine; scikit-build-core + FetchContent pull
+        # cmake/swig/ninja/nlohmann automatically, so no system prereqs are
+        # required. Building the sdist does not compile anything, so this job
+        # needs no C++ toolchain or nlohmann/json either.
+        run: python3 -m build --sdist
       - name: Store the distribution packages
         uses: actions/upload-artifact@v4
         with:
@@ -113,7 +119,6 @@ jobs:
         with:
           inputs: |
             ./dist/*.tar.gz
-            ./dist/*.whl
       - name: Create GitHub Release
         env:
           GITHUB_TOKEN: ${{ github.token }}

{dapps-0.1.0 → dapps-0.2.0}/.github/workflows/test.yml

@@ -17,8 +17,13 @@ jobs:
         with:
           python-version: "3.12"
 
-      - name: Install hatch
-        run: pip install hatch
+      - name: Install build prerequisites
+        run: |
+          sudo apt-get update
+          sudo apt-get install -y cmake swig nlohmann-json3-dev
+
+      - name: Install package (editable, with test deps)
+        run: pip install -e ".[all]" pytest
 
       - name: Run tests
-        run: hatch run pytest tests/ -v
+        run: pytest tests/ -v

dapps-0.2.0/CMakeLists.txt

@@ -0,0 +1,22 @@
+# Root CMake — drives the Python wheel build via scikit-build-core.
+#
+# scikit-build-core invokes this file when `pip install .` / `python -m
+# build` is run. We turn on SWIG and direct the SWIG outputs into the
+# wheel's `iq_saver/` package directory. The standalone C++ install of
+# libiqsaver (pkg-config, headers under /usr/local) is driven directly
+# from the libiqsaver/ subdirectory CMake; see libiqsaver/CMakeLists.txt.
+#
+# SPDX-License-Identifier: Apache-2.0
+
+cmake_minimum_required(VERSION 3.16)
+
+# Tell libiqsaver/CMakeLists.txt to: (1) build SWIG bindings, (2) skip
+# the system-wide install logic, (3) install SWIG outputs into the
+# wheel's iq_saver/ package directory.
+set(LIBIQSAVER_ENABLE_SWIG   ON      CACHE BOOL   "" FORCE)
+set(LIBIQSAVER_BUILD_TESTS   OFF     CACHE BOOL   "" FORCE)
+set(LIBIQSAVER_PY_INSTALL_DIR "iq_saver" CACHE STRING "" FORCE)
+
+project(iqsaver_pywheel LANGUAGES CXX)
+
+add_subdirectory(libiqsaver)

{dapps-0.1.0 → dapps-0.2.0}/CONTRIBUTING.md

@@ -49,16 +49,16 @@ The following are **mandatory** for every contribution. PRs that do not meet the
 
 - All PRs must use `.github/PULL_REQUEST_TEMPLATE.md` and complete every checklist item.
 - The following CI workflow must be green on the latest commit before review:
-  - **`Run tests`** (`.github/workflows/test.yml`) — runs `hatch run pytest tests/ -v` on Python 3.12.
+  - **`Run tests`** (`.github/workflows/test.yml`) — installs the package via `pip install -e ".[all]"` and runs `pytest tests/ -v` on Python 3.12.
 - The following local checks must be reported in the PR description as run by the contributor (mirroring CI):
-  - `hatch run pytest tests/ -v` passes.
-  - `hatch build` succeeds.
+  - `pytest tests/ -v` passes (after `pip install -e ".[all]"`).
+  - `python -m build` succeeds (the build backend is scikit-build-core; this also verifies the C++/SWIG extension compiles).
   - `VERSION` file bumped per [SemVer](https://semver.org/) when public API or wire protocol changes.
   - `README.md` and/or `CONTRIBUTING.md` updated when contributor- or user-facing behavior changes.
 
 ### Service Models and twin-repo coordination
 
-This repository is part of a framework that includes [`libe3`](https://github.com/wineslab/dApp-libe3) (the gNB-side E3 agent) and [`dApp-openairinterface5g`](https://github.com/wineslab/dApp-openairinterface5g) (the OAI fork). PRs that change the E3 wire protocol or add a new Service Model must come with a paired PR in the affected twin repo, linked from the PR description.
+This repository is part of a framework that includes [`libe3`](https://github.com/wineslab/libe3) (the gNB-side E3 agent) and [`dApp-openairinterface5g`](https://github.com/wineslab/dApp-openairinterface5g) (the OAI fork). PRs that change the E3 wire protocol or add a new Service Model must come with a paired PR in the affected twin repo, linked from the PR description.
 
 ## Code of Conduct
 

dapps-0.2.0/MANIFEST.in

@@ -0,0 +1,6 @@
+include VERSION
+include README.md
+include LICENSE
+include CMakeLists.txt
+recursive-include libiqsaver *
+recursive-include src/visualization/templates *

{dapps-0.1.0 → dapps-0.2.0}/PKG-INFO

@@ -1,44 +1,46 @@
 Metadata-Version: 2.4
 Name: dapps
-Version: 0.1.0
+Version: 0.2.0
 Summary: A library for creating and connecting dApps to Open RAN units.
-Project-URL: Homepage, https://openrangym.com/o-ran-frameworks/dapps
-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
-Author-email: Andrea Lacava <thecave003@gmail.com>
+Keywords: dApps,O-RAN,5G,cellular,networks
+Author-Email: Andrea Lacava <thecave003@gmail.com>
 License-Expression: Apache-2.0
 License-File: LICENSE
-Keywords: 5G,O-RAN,cellular,dApps,networks
 Classifier: Development Status :: 4 - Beta
 Classifier: Programming Language :: Python
 Classifier: Programming Language :: Python :: 3.12
 Classifier: Programming Language :: Python :: Implementation :: CPython
 Classifier: Programming Language :: Python :: Implementation :: PyPy
+Project-URL: Homepage, https://openrangym.com/o-ran-frameworks/dapps
+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: asn1tools
-Requires-Dist: jsonschema>=4.18.0
+Requires-Dist: typing_extensions
 Requires-Dist: numpy
 Requires-Dist: pyzmq
 Requires-Dist: sigmf
-Requires-Dist: typing-extensions
-Provides-Extra: all
-Requires-Dist: flask; extra == 'all'
-Requires-Dist: flask-socketio; extra == 'all'
-Requires-Dist: influxdb-client; extra == 'all'
-Requires-Dist: libiq; extra == 'all'
-Requires-Dist: matplotlib; extra == 'all'
-Requires-Dist: pysctp; extra == 'all'
+Requires-Dist: jsonschema>=4.18.0
 Provides-Extra: api
-Requires-Dist: influxdb-client; extra == 'api'
+Requires-Dist: influxdb_client; extra == "api"
 Provides-Extra: cnn
-Requires-Dist: libiq; extra == 'cnn'
+Requires-Dist: libiq; extra == "cnn"
 Provides-Extra: gui
-Requires-Dist: flask; extra == 'gui'
-Requires-Dist: flask-socketio; extra == 'gui'
-Requires-Dist: matplotlib; extra == 'gui'
+Requires-Dist: flask; extra == "gui"
+Requires-Dist: flask-sock; extra == "gui"
+Requires-Dist: flask-cors; extra == "gui"
+Requires-Dist: matplotlib; extra == "gui"
 Provides-Extra: network
-Requires-Dist: pysctp; extra == 'network'
+Requires-Dist: pysctp; extra == "network"
+Provides-Extra: all
+Requires-Dist: pysctp; extra == "all"
+Requires-Dist: flask; extra == "all"
+Requires-Dist: flask-sock; extra == "all"
+Requires-Dist: flask-cors; extra == "all"
+Requires-Dist: matplotlib; extra == "all"
+Requires-Dist: influxdb_client; extra == "all"
+Requires-Dist: libiq; extra == "all"
 Description-Content-Type: text/markdown
 
 # dApp Library
@@ -60,10 +62,41 @@ The dApp can be found in the `examples` directory or it can be downloaded from t
 Clone the repository and install it manually with:
 
 ```
-hatch build
+pip3 install -e ".[all]"
+```
+
+Building a distributable sdist / wheel:
+
+```
+pip install build
+python -m build         # produces dist/*.tar.gz and dist/*.whl
 pip3 install "dist/*.tar.gz[all]"
 ```
 
+The wheel build uses [scikit-build-core](https://scikit-build-core.readthedocs.io/) to compile the bundled C++ extension (see *libiqsaver* below). System prerequisites: a C++17 compiler, CMake ≥ 3.16, SWIG ≥ 4.0, and [`nlohmann/json`](https://github.com/nlohmann/json) (≥ 3.11). On Debian/Ubuntu: `apt install cmake swig nlohmann-json3-dev`.
+
+### libiqsaver — standalone C++ library
+
+The `iq_saver` Python package wraps **libiqsaver**, a SigMF-compliant IQ-sample writer written in C++. The same library is also usable directly from C++ projects. To install it system-wide:
+
+```
+cd libiqsaver
+mkdir build && cd build
+cmake .. -DCMAKE_BUILD_TYPE=Release
+sudo make install
+```
+
+After install:
+
+```
+pkg-config --cflags --libs libiqsaver
+# or, in CMake:
+find_package(libiqsaver REQUIRED)
+target_link_libraries(my_app PRIVATE iqsaver::iqsaver)
+```
+
+The standalone install (headers under `${CMAKE_INSTALL_PREFIX}/include/iqsaver`, library and pkg-config under `${CMAKE_INSTALL_LIBDIR}`) is independent of `pip install dapps` — both can coexist on the same machine.
+
 ### Launch the Spectrum Sharing dApp example
 
 OAI should start _before_ running the dApp

{dapps-0.1.0 → dapps-0.2.0}/README.md

@@ -17,10 +17,41 @@ The dApp can be found in the `examples` directory or it can be downloaded from t
 Clone the repository and install it manually with:
 
 ```
-hatch build
+pip3 install -e ".[all]"
+```
+
+Building a distributable sdist / wheel:
+
+```
+pip install build
+python -m build         # produces dist/*.tar.gz and dist/*.whl
 pip3 install "dist/*.tar.gz[all]"
 ```
 
+The wheel build uses [scikit-build-core](https://scikit-build-core.readthedocs.io/) to compile the bundled C++ extension (see *libiqsaver* below). System prerequisites: a C++17 compiler, CMake ≥ 3.16, SWIG ≥ 4.0, and [`nlohmann/json`](https://github.com/nlohmann/json) (≥ 3.11). On Debian/Ubuntu: `apt install cmake swig nlohmann-json3-dev`.
+
+### libiqsaver — standalone C++ library
+
+The `iq_saver` Python package wraps **libiqsaver**, a SigMF-compliant IQ-sample writer written in C++. The same library is also usable directly from C++ projects. To install it system-wide:
+
+```
+cd libiqsaver
+mkdir build && cd build
+cmake .. -DCMAKE_BUILD_TYPE=Release
+sudo make install
+```
+
+After install:
+
+```
+pkg-config --cflags --libs libiqsaver
+# or, in CMake:
+find_package(libiqsaver REQUIRED)
+target_link_libraries(my_app PRIVATE iqsaver::iqsaver)
+```
+
+The standalone install (headers under `${CMAKE_INSTALL_PREFIX}/include/iqsaver`, library and pkg-config under `${CMAKE_INSTALL_LIBDIR}`) is independent of `pip install dapps` — both can coexist on the same machine.
+
 ### Launch the Spectrum Sharing dApp example
 
 OAI should start _before_ running the dApp

dapps-0.2.0/VERSION

@@ -0,0 +1 @@
+0.2.0

{dapps-0.1.0 → dapps-0.2.0}/docs/ground_truth_labeling.md

@@ -63,7 +63,7 @@ The detector flags any PRB whose power exceeds a fixed absolute threshold.
 
 **Interactive:**
 ```bash
-hatch run python examples/spectrum_dapp.py \
+python3 examples/spectrum_dapp.py \
   --link zmq --transport ipc \
   --save-iqs \
   --control \
@@ -77,7 +77,7 @@ hatch run python examples/spectrum_dapp.py \
 
 **CI/CD:**
 ```bash
-hatch run python examples/spectrum_dapp.py \
+python3 examples/spectrum_dapp.py \
   --link zmq --transport ipc \
   --save-iqs \
   --control \
@@ -96,7 +96,7 @@ after the last detection before being released.
 
 **Interactive:**
 ```bash
-hatch run python examples/spectrum_dapp.py \
+python3 examples/spectrum_dapp.py \
   --link zmq --transport ipc \
   --save-iqs \
   --control \
@@ -112,7 +112,7 @@ hatch run python examples/spectrum_dapp.py \
 
 **CI/CD:**
 ```bash
-hatch run python examples/spectrum_dapp.py \
+python3 examples/spectrum_dapp.py \
   --link zmq --transport ipc \
   --save-iqs \
   --control \

{dapps-0.1.0 → dapps-0.2.0}/examples/spectrum_dapp.py

@@ -9,7 +9,11 @@ import time
 import logging
 
 from e3interface.e3_connector import E3LinkLayer, E3TransportLayer
-from spectrum.spectrum_dapp import SpectrumSharingDApp, compute_fft_size
+from spectrum.spectrum_dapp import (
+    SpectrumSharingDApp,
+    compute_fft_size,
+    make_periodic_toggle_callback,
+)
 from spectrum.threshold_detector import StaticThresholdDetector, AdaptiveThresholdDetector
 
 LOG_DIR = '/tmp/'
@@ -23,17 +27,15 @@ def stop_program(time_to_wait, dapp: SpectrumSharingDApp):
 
 def main(args):
     if args.model:
-        try:
-            from libiq.classifier.cnn import Classifier
-        except ModuleNotFoundError:
-            print(
-                "Optional dependencies to run this example are not installed.\n"
-                "Fix this by running:\n\n"
-                "    pip install libiq  # OR\n"
-                "    pip install dapps[cnn] (minimal) # OR\n"
-                "    pip install dapps[all] (preferred)\n"
-            )
-            exit(-1)
+        # CNN signal classification is not wired into SpectrumSharingDApp; a
+        # classifier= kwarg would fall through to **kwargs and be dropped, so
+        # --model (and --time-window/--moving-avg-window/--extraction-window)
+        # would silently do nothing. Fail loudly instead.
+        raise SystemExit(
+            "--model (CNN signal classification) is not supported by "
+            "SpectrumSharingDApp; remove --model and the associated "
+            "--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.
@@ -81,16 +83,6 @@ def main(args):
             f" | window: {args.average_over_frames} frames"
         )
 
-    classifier = None
-    if args.model:
-        classifier = Classifier(
-            time_window=args.time_window,
-            input_vector=fft_size,
-            moving_avg_window=args.moving_avg_window,
-            extraction_window=args.extraction_window,
-            model_path=args.model,
-        )
-
     dapp = SpectrumSharingDApp(
         detector=detector,
         save_iqs=args.save_iqs,
@@ -100,14 +92,21 @@ def main(args):
         energyGui=args.energy_gui,
         iqPlotterGui=args.iq_plotter_gui,
         dashboard=args.demo_gui,
-        classifier=classifier,
+        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,
         e_sampling=args.e,
         num_subcarrier_spacing=args.num_subcarrier_spacing,
         sampling_threshold=args.sampling_threshold,
+        max_samples_per_file=args.max_samples_per_file,
+        fp16_beta=args.fp16_beta,
+        sensing_only=args.sensing_only,
+        strict_sensing=args.strict_sensing,
+        min_sensing_symbols=args.min_sensing_symbols,
+        encoding_method=args.encoding_method,
         ground_truth=args.ground_truth,
-        show_controls=args.show_controls,
         dapp_name="SpectrumSharing",
         dapp_version="1.0.0",
         vendor="WinesLab",
@@ -137,7 +136,29 @@ def main(args):
                 )
     time.sleep(1)
 
-    dapp.send_subscription_request()
+    if not dapp.send_subscription_request():
+        # send_subscription_request returns True only if the gNB accepted both
+        # the L1-KPM (RF=2) and Spectrum (RF=1) subscriptions; anything else
+        # means the dApp would run deaf, so abort with a non-zero exit.
+        dapp.stop()
+        raise SystemExit("[FATAL] gNB did not accept the dApp subscriptions; aborting")
+
+    # Optional sensing-policy toggle.  When --toggle-period > 0, installs
+    # a periodic on/off toggle that flips the gNB's masked UL TDA
+    # selector via spectrum_sm ctrl_id=2.  Operator must have configured
+    # additional_ul_tdas in the gNB (e.g. "0:7") for the scheduler to
+    # have a short TDA to switch to.  See examples/README or the gNB
+    # boot log ([additional] tag) to verify.
+    if args.toggle_period > 0:
+        print(f"[INFO] Installing sensing-policy toggle: "
+              f"period={args.toggle_period}s "
+              f"n_slots={args.toggle_n_slots} "
+              f"mask_when_on=0x{args.toggle_mask:04x}")
+        dapp.set_sensing_policy_logic(make_periodic_toggle_callback(
+            period_s=args.toggle_period,
+            n_slots=args.toggle_n_slots,
+            mask_when_on=args.toggle_mask,
+        ))
 
     if args.timed:
         timer = threading.Thread(target=stop_program, args=(args.timed, dapp), daemon=False)
@@ -167,7 +188,8 @@ if __name__ == "__main__":
     parser.add_argument('--save-iqs', action='store_true', default=False,
                         help="Save I/Q samples to SigMF files")
     parser.add_argument('--control', action='store_true', default=False,
-                        help="Send PRB blacklist control messages to the gNB")
+                        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)")
     parser.add_argument('--use-adaptive-noise-floor', action='store_true', default=False,
@@ -184,7 +206,13 @@ if __name__ == "__main__":
     parser.add_argument('--iq-plotter-gui', action='store_true', default=False,
                         help="Enable IQ time-domain plotter")
     parser.add_argument('--demo-gui', action='store_true', default=False,
-                        help="Enable dashboard visualization")
+                        help="Publish per-slot subcarrier power to the visualizer")
+    parser.add_argument('--viz-web-port', type=int, default=5001,
+                        help="Visualizer web UI port (default 5001)")
+    parser.add_argument('--viz-zmq-port', type=int, default=5559,
+                        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,
@@ -205,14 +233,68 @@ 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,
+                        help="Rotate the SigMF capture file once a segment reaches "
+                             "this many true IQ samples (default 46080000). 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('--show-controls', action='store_true', default=False,
-                        help="Show tunable controls (sampling threshold) in the dashboard GUI. "
-                             "Only meaningful with --demo-gui.")
+    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('--encoding-method', type=str, default='asn1',
+                        choices=['asn1', 'json'],
+                        help="Wire encoding for Spectrum-* envelopes (default: asn1).")
+    parser.add_argument('--no-sensing-only', dest='sensing_only',
+                        action='store_false', default=True,
+                        help="Disable the sensing-window filter. By default the dApp uses the "
+                             "sensing ranges from the Spectrum SM (RF=1) to slice the detector "
+                             "input to sensing-PUSCH cells; passing this flag uses every cell.")
+    parser.add_argument('--strict-sensing', dest='strict_sensing',
+                        action='store_true', default=False,
+                        help="Stricter sensing filter: drop any slot whose sensing window "
+                             "doesn't cover the full slot (i.e. any UE PUSCH was granted "
+                             "in that slot). Eliminates UE CP/spectral bleed at the cost "
+                             "of a sparser waterfall under heavy UE traffic. Requires "
+                             "--sensing-only (the default).")
+    parser.add_argument('--min-sensing-symbols', type=int, default=1,
+                        help="Minimum number of kept symbols required to emit the slot to "
+                             "the dashboard. Default 1: display every slot that has any "
+                             "sensing symbol — keeps the waterfall scrolling even under "
+                             "heavy UE UL where the MAC scheduler leaves only one free "
+                             "symbol per slot. Set to 2 to drop the typical \"only sym 13 "
+                             "survived\" partial-sensing slots (evens out brightness at "
+                             "the cost of dashboard freezes under load). Set to 14 to "
+                             "require fully-clean slots (equivalent to "
+                             "--strict-sensing).")
+
+    # --- 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
+    # positive value to enable.  Requires additional_ul_tdas (e.g. "0:7")
+    # on the gNB so the scheduler has a short TDA to switch to.
+    parser.add_argument('--toggle-period', type=float, default=0.0,
+                        metavar='SECONDS',
+                        help="Toggle the gNB sensing policy on/off every N seconds "
+                             "(0 = disabled, default).  When > 0, alternates between "
+                             "installing the mask (active) and clearing it (deactivate).  "
+                             "Requires additional_ul_tdas configured on the gNB.")
+    parser.add_argument('--toggle-n-slots', type=int, default=20,
+                        help="numb_slots_frame of the gNB for the per-slot mask "
+                             "(mu=1 -> 20).  Must match the gNB exactly or the gNB "
+                             "will NACK the policy with an n_slots mismatch.")
+    parser.add_argument('--toggle-mask', type=lambda s: int(s, 0), default=0x3F80,
+                        metavar='HEX',
+                        help="14-bit symbol bitmap applied uniformly to every slot "
+                             "when the toggle is active (default 0x3F80 = syms 7..13).")
 
     args = parser.parse_args()
     print("Start dApp")