dapps 0.2.0__tar.gz → 0.2.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dapps
-Version: 0.2.0
+Version: 0.2.2
 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>
@@ -19,9 +19,9 @@ Requires-Python: >=3.12
 Requires-Dist: asn1tools
 Requires-Dist: typing_extensions
 Requires-Dist: numpy
-Requires-Dist: pyzmq
 Requires-Dist: sigmf
 Requires-Dist: jsonschema>=4.18.0
+Requires-Dist: protobuf>=4.21
 Provides-Extra: api
 Requires-Dist: influxdb_client; extra == "api"
 Provides-Extra: cnn
@@ -31,6 +31,7 @@ Requires-Dist: flask; extra == "gui"
 Requires-Dist: flask-sock; extra == "gui"
 Requires-Dist: flask-cors; extra == "gui"
 Requires-Dist: matplotlib; extra == "gui"
+Requires-Dist: pyzmq; extra == "gui"
 Provides-Extra: network
 Requires-Dist: pysctp; extra == "network"
 Provides-Extra: all
@@ -39,6 +40,7 @@ Requires-Dist: flask; extra == "all"
 Requires-Dist: flask-sock; extra == "all"
 Requires-Dist: flask-cors; extra == "all"
 Requires-Dist: matplotlib; extra == "all"
+Requires-Dist: pyzmq; extra == "all"
 Requires-Dist: influxdb_client; extra == "all"
 Requires-Dist: libiq; extra == "all"
 Description-Content-Type: text/markdown
@@ -49,6 +51,35 @@ A complete tutorial on how to deploy a dApp can be found on the [OpenRAN Gym web
 
 ## Installation
 
+### Prerequisite: libe3 Python bindings (`libe3py`)
+
+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:
+
+```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')"
+```
+
+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,
+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)
 
 ```
@@ -121,8 +152,8 @@ 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:**
 
@@ -134,10 +165,13 @@ This dApp implements a spectrum sharing use case discussed in [our paper](https:
 
 **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:**
 
@@ -237,7 +271,7 @@ spear-openairinterface5g/openair2/E3AP/service_models/<sm_name>_sm/
 
 For dApp-side (when `--target dapp` or `both`):
 ```
-spear-dApp/src/<sm_name>/
+dApp-library/src/<sm_name>/
 ├── __init__.py
 ├── <sm_name>_dapp.py       # Main dApp implementation
 └── defs/

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

@@ -4,6 +4,35 @@ A complete tutorial on how to deploy a dApp can be found on the [OpenRAN Gym web
 
 ## Installation
 
+### Prerequisite: libe3 Python bindings (`libe3py`)
+
+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:
+
+```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')"
+```
+
+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,
+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)
 
 ```
@@ -76,8 +105,8 @@ 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:**
 
@@ -89,10 +118,13 @@ This dApp implements a spectrum sharing use case discussed in [our paper](https:
 
 **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:**
 
@@ -192,7 +224,7 @@ spear-openairinterface5g/openair2/E3AP/service_models/<sm_name>_sm/
 
 For dApp-side (when `--target dapp` or `both`):
 ```
-spear-dApp/src/<sm_name>/
+dApp-library/src/<sm_name>/
 ├── __init__.py
 ├── <sm_name>_dapp.py       # Main dApp implementation
 └── defs/

dapps-0.2.2/VERSION

@@ -0,0 +1 @@
+0.2.2

{dapps-0.2.0 → dapps-0.2.2}/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.2.2/examples/__init__.py

@@ -0,0 +1,3 @@
+"""Runnable dApp examples, shipped in the wheel so they can be launched with
+``python -m examples.spectrum_dapp`` / ``python -m examples.simple_dapp`` from an
+installed ``dapps`` package (e.g. the OAI rfsim CI driving the real dApp)."""

{dapps-0.2.0 → dapps-0.2.2}/examples/simple_dapp.py

@@ -13,7 +13,7 @@ import argparse
 import threading
 import time
 
-from e3interface.e3_connector import E3LinkLayer, E3TransportLayer
+from e3interface.e3_transport import E3LinkLayer, E3TransportLayer
 from simple.simple_dapp import SimpleDApp
 
 
@@ -101,7 +101,7 @@ if __name__ == "__main__":
         "--encoding",
         type=str,
         default="asn1",
-        choices=["asn1", "json"],
+        choices=["asn1", "json", "protobuf"],
         help="Encoding format (default: asn1)",
     )
     parser.add_argument(

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

@@ -8,12 +8,18 @@ import threading
 import time
 import logging
 
-from e3interface.e3_connector import E3LinkLayer, E3TransportLayer
+from e3interface.e3_transport import E3LinkLayer, E3TransportLayer
 from spectrum.spectrum_dapp import (
     SpectrumSharingDApp,
     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
 
 LOG_DIR = '/tmp/'
@@ -37,18 +43,27 @@ 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
+    ]
+    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}')
 
@@ -56,7 +71,7 @@ def main(args):
     # 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:
         detector = AdaptiveThresholdDetector(
@@ -95,13 +110,14 @@ 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,
+        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 +207,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 +234,18 @@ 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('--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,25 +258,24 @@ 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'],
+                        choices=['asn1', 'json', 'protobuf'],
                         help="Wire encoding for Spectrum-* envelopes (default: asn1).")
     parser.add_argument('--no-sensing-only', dest='sensing_only',
                         action='store_false', default=True,

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

@@ -19,13 +19,23 @@ 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"
+# (asn1tools is still required for the in-Python service-model codecs.)
 dependencies = [
     "asn1tools",
     "typing_extensions",
     "numpy",
-    "pyzmq",
     "sigmf",
     "jsonschema>=4.18.0",
+    # protobuf E3SM codec path (spectrum/simple SMs); >=4.21 for FieldDescriptor
+    # .has_presence and the current generated-code format.
+    "protobuf>=4.21",
 ]
 
 authors = [
@@ -43,7 +53,7 @@ Source = "https://github.com/wineslab/dApp-library"
 [project.optional-dependencies]
 api = ["influxdb_client"]
 cnn = ["libiq"]
-gui = ["flask", "flask-sock", "flask-cors", "matplotlib"]
+gui = ["flask", "flask-sock", "flask-cors", "matplotlib", "pyzmq"]
 network = ["pysctp"]
 all = [
     "pysctp",
@@ -51,6 +61,7 @@ all = [
     "flask-sock",
     "flask-cors",
     "matplotlib",
+    "pyzmq",
     "influxdb_client",
     "libiq",
 ]
@@ -68,10 +79,13 @@ wheel.packages = [
     "src/dapp",
     "src/e3interface",
     "src/spectrum",
-    "src/nvidia",
     "src/simple",
     "src/iq_saver",
     "src/visualization",
+    # Ship the runnable examples so they can be launched from the installed
+    # wheel via `python -m examples.<name>` (e.g. the OAI rfsim CI driving the
+    # real spectrum dApp) instead of a hand-rolled launcher.
+    "examples",
 ]
 
 # Include the libiqsaver C++ tree and the root CMake in the sdist so

{dapps-0.2.0 → dapps-0.2.2}/src/dapp/dapp.py

@@ -10,7 +10,6 @@ from abc import ABC, abstractmethod
 import threading
 import time
 from e3interface.e3_interface import E3Interface
-from e3interface.e3_encoder import AsnE3Encoder, JsonE3Encoder
 from e3interface.e3_logging import dapp_logger
 
 class DApp(ABC):
@@ -30,16 +29,14 @@ class DApp(ABC):
         self.dapp_version = dapp_version
         self.vendor = vendor
         self.e3ap_protocol_version = e3ap_protocol_version
-        self.encoding_method = encoding_method        
-        match self.encoding_method:
-            case "asn1":
-                encoder = AsnE3Encoder()
-            case "json":
-                encoder = JsonE3Encoder()
-            case _:
-                raise ValueError(f"Unsupported encoding method: {self.encoding_method}")
-
-        self.e3_interface = E3Interface(encoder=encoder, link=link, transport=transport)
+        self.encoding_method = encoding_method
+        if encoding_method not in ("asn1", "json", "protobuf"):
+            raise ValueError(f"Unsupported encoding method: {encoding_method}")
+
+        # libe3 owns E3AP (transport + wire encoding); the encoding string is
+        # passed straight through and must match the gNB E3Configuration.
+        self.e3_interface = E3Interface(
+            link=link, transport=transport, encoding=encoding_method)
         self.stop_event = threading.Event()
 
         dapp_logger.info(f'Using {link} and {transport}')
@@ -146,7 +143,15 @@ class DApp(ABC):
         return scheduled
 
     @abstractmethod
-    def _handle_xapp_control(self, dapp_identifier: int, data: bytes):
+    def _handle_xapp_control(self, dapp_identifier: int, data: bytes, sequence_id: int = 0):
+        """Handle a control addressed to this dApp by an xApp.
+
+        ``sequence_id`` is the correlation id of the xApp procedure. Echo it on
+        the control re-issued to the RAN so the RAN can report back when the
+        decision reached the air. Implementations written before the id existed
+        may still take two arguments; E3Interface detects that and calls them
+        the old way.
+        """
         # This in the future might become a class
         pass