dapps 0.2.1__tar.gz → 0.2.2__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: dapps
-Version: 0.2.1
+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>
@@ -71,6 +71,15 @@ 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)
 
 ```
@@ -143,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:**
 
@@ -156,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:**
 

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

@@ -24,6 +24,15 @@ 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)
 
 ```
@@ -96,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:**
 
@@ -109,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:**
 

dapps-0.2.2/VERSION

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

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

@@ -14,6 +14,12 @@ 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
 
 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,23 +258,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).")

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

@@ -20,7 +20,10 @@ 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:
+# 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.)
@@ -76,7 +79,6 @@ wheel.packages = [
     "src/dapp",
     "src/e3interface",
     "src/spectrum",
-    "src/nvidia",
     "src/simple",
     "src/iq_saver",
     "src/visualization",

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

@@ -143,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
 

{dapps-0.2.1 → dapps-0.2.2}/src/e3interface/e3_interface.py

@@ -1,7 +1,9 @@
+import inspect
 import queue
 import threading
 import time
 
+from . import latrec
 from .e3_logging import e3_logger
 from .libe3_agent import (
     Libe3Agent,
@@ -23,6 +25,34 @@ POLL_TIMEOUT_MS = 100
 SETUP_WAIT_MS = 6000
 
 
+def _accepts_sequence_id(callback) -> bool:
+    """True if ``callback`` takes the trailing correlation id.
+
+    Cached on the function object: this runs per xApp control, and
+    inspect.signature() is not cheap. A callback that takes *args is assumed to
+    want it.
+    """
+    cached = getattr(callback, "_e3_accepts_seq", None)
+    if cached is not None:
+        return cached
+    try:
+        params = inspect.signature(callback).parameters
+        accepts = (
+            len([p for p in params.values()
+                 if p.kind in (p.POSITIONAL_ONLY, p.POSITIONAL_OR_KEYWORD)]) >= 3
+            or any(p.kind is p.VAR_POSITIONAL for p in params.values())
+        )
+    except (TypeError, ValueError):
+        # Builtins and C callables have no introspectable signature; assume the
+        # older two-argument form, which is what every dApp shipped before.
+        accepts = False
+    try:
+        callback._e3_accepts_seq = accepts
+    except AttributeError:
+        pass
+    return accepts
+
+
 class E3Interface:
     """Singleton E3AP interface, backed by the libe3 dApp session (``libe3py``).
 
@@ -218,6 +248,7 @@ class E3Interface:
     def _inbound_connection(self):
         """Batched drain of libe3 inbound events into the callback dispatchers."""
         e3_logger.info("Start inbound loop")
+        latrec.open_ring("dapp.inbound")
         last_dropped = 0
         try:
             while not self.stop_event.is_set():
@@ -228,11 +259,16 @@ class E3Interface:
                     try:
                         kind = ev.kind
                         if kind == EVENT_INDICATION:
+                            if latrec.ENABLED:
+                                latrec.ctx_set(ev.trace_seq)
                             self._handle_indication_data(
                                 ev.dapp_id, ev.ran_function_id, ev.get_payload())
                         elif kind == EVENT_XAPP_CONTROL:
+                            if latrec.ENABLED:
+                                latrec.ctx_set(ev.request_id or ev.trace_seq)
                             self._handle_xapp_control_data(
-                                ev.dapp_id, ev.ran_function_id, ev.get_payload())
+                                ev.dapp_id, ev.ran_function_id, ev.get_payload(),
+                                ev.sequence_id)
                         elif kind == EVENT_SUBSCRIPTION_RESPONSE:
                             self._handle_subscription_response({
                                 'dAppIdentifier': ev.dapp_id,
@@ -269,6 +305,7 @@ class E3Interface:
     def _outbound_connection(self):
         """Drain the outbound queue and forward each message through libe3."""
         e3_logger.info("Start outbound loop")
+        latrec.open_ring("dapp.outbound")
         try:
             while not self.stop_event.is_set():
                 try:
@@ -283,23 +320,32 @@ class E3Interface:
                 try:
                     e3_logger.debug("Outbound queue has got '%s', %s", msg, data)
                     rc = SUCCESS
+                    # libe3 stamps the producer's key into EMIT_ENTER from this
+                    # thread's context; reset it so an ack does not inherit a
+                    # stale one.
+                    latrec.ctx_set(data.get("latSeq", 0))
                     match msg:
                         case "control":
                             rc = self.agent.send_control(
-                                data["ranFunctionId"], data["controlId"], data["actionData"])
+                                data["ranFunctionId"], data["controlId"], data["actionData"],
+                                data.get("sequenceId", 0))
                         case "subscription":
                             self._send_subscription(data)
                         case "ack":
                             rc = self.agent.send_message_ack(data["requestId"], data["positive"])
                         case "report":
-                            rc = self.agent.send_report(data["ranFunctionId"], data["reportData"])
+                            rc = self.agent.send_report(
+                                data["ranFunctionId"], data["reportData"],
+                                data.get("sequenceId", 0))
                         case "release":
                             rc = self.agent.release()
                         case _:
                             e3_logger.error("Unrecognized outbound message: %r; dropping", msg)
                             continue
 
-                    if rc != SUCCESS:
+                    # A send returns the assigned message id (positive) on success
+                    # and a negative ErrorCode on failure.
+                    if rc < 0:
                         e3_logger.error("libe3 %s send failed (ErrorCode=%s)", msg, rc)
                 except Exception:
                     e3_logger.exception(
@@ -390,31 +436,42 @@ class E3Interface:
         else:
             e3_logger.warning(f"No indication callback registered for dApp {dapp_identifier}")
 
-    def _handle_xapp_control_data(self, dapp_identifier, ran_function_id, xapp_control_data):
+    def _handle_xapp_control_data(self, dapp_identifier, ran_function_id, xapp_control_data,
+                                  sequence_id=0):
         e3_logger.debug(
-            "Received xAppControlAction: dApp=%s, ranFunc=%s, payload=%d bytes",
-            dapp_identifier, ran_function_id, len(xapp_control_data),
+            "Received xAppControlAction: dApp=%s, ranFunc=%s, payload=%d bytes, seq=%s",
+            dapp_identifier, ran_function_id, len(xapp_control_data), sequence_id,
         )
         with self._callback_lock:
             callbacks = list(self.xapp_control_callbacks.get(dapp_identifier, []))
         if callbacks:
             e3_logger.debug(f"Launch {len(callbacks)} xApp control callback(s) for dApp {dapp_identifier}")
             for callback in callbacks:
-                callback(dapp_identifier, xapp_control_data)
+                # Callbacks predating the correlation id take two arguments. Decide
+                # from the signature rather than catching TypeError, which would
+                # re-invoke a callback that raised one of its own.
+                if _accepts_sequence_id(callback):
+                    callback(dapp_identifier, xapp_control_data, sequence_id)
+                else:
+                    callback(dapp_identifier, xapp_control_data)
         else:
             e3_logger.warning(f"No xApp control callback registered for dApp {dapp_identifier}")
 
-    def schedule_control(self, dappId: int, ranFunctionId: int, controlId: int, actionData: bytes = b""):
+    def schedule_control(self, dappId: int, ranFunctionId: int, controlId: int, actionData: bytes = b"",
+                         sequenceId: int = 0):
         self.outbound_queue.put(('control', {
             'ranFunctionId': ranFunctionId,
             'controlId': controlId,
             'actionData': actionData,
+            'sequenceId': sequenceId,
+            'latSeq': latrec.ctx(),
         }))
 
     def schedule_report(self, dappId: int, ranFunctionId: int, reportData: bytes):
         self.outbound_queue.put(('report', {
             'ranFunctionId': ranFunctionId,
             'reportData': reportData,
+            'latSeq': latrec.ctx(),
         }))
 
     def add_subscription_callback(self, dapp_id: int, callback):

dapps-0.2.2/src/e3interface/latrec.py

@@ -0,0 +1,78 @@
+"""latrec stamping for the dApp, through libe3's own recorder.
+
+libe3 owns the ring format, the stage catalog and the on/off decision (a build
+option, LIBE3_ENABLE_LATREC; there is no runtime switch). This module only binds
+the per-thread stamping calls and turns them into plain no-ops when the installed
+libe3py was built without the recorder. Stage ids come from libe3py, never from a
+local table, so they cannot drift from the catalog.
+
+Rings are per thread: a thread must ``open_ring`` before its stamps and
+``ctx_set`` calls take effect. Threads that never open one stamp nothing.
+"""
+
+try:
+    import libe3py as _l
+except ImportError:  # pragma: no cover - environment dependent
+    _l = None
+
+
+def _recorder_built_in() -> bool:
+    # A build without the recorder compiles latrec_seq_next() to a constant 0.
+    if _l is None or not hasattr(_l, "latrec_tstamp_py"):
+        return False
+    try:
+        return _l.latrec_seq_next_py() != 0
+    except Exception:
+        return False
+
+
+ENABLED = _recorder_built_in()
+
+_U64 = 0xFFFFFFFFFFFFFFFF
+
+
+def _id(name: str) -> int:
+    return getattr(_l, name, 0)
+
+
+DECODE_E3SM_BEGIN = _id("LATREC_DECODE_E3SM_BEGIN")
+DECODE_E3SM_DONE = _id("LATREC_DECODE_E3SM_DONE")
+PROCESS_DONE = _id("LATREC_PROCESS_DONE")
+CREATE_OUTPUT = _id("LATREC_CREATE_OUTPUT")
+ENCODE_E3SM_BEGIN = _id("LATREC_ENCODE_E3SM_BEGIN")
+ENCODE_E3SM_DONE = _id("LATREC_ENCODE_E3SM_DONE")
+APPLY_POLICY_DONE = _id("LATREC_APPLY_POLICY_DONE")
+
+PDU_INDICATION = _id("PduType_INDICATION_MESSAGE")
+PDU_XAPP_CONTROL = _id("PduType_XAPP_CONTROL_ACTION")
+PDU_CONTROL = _id("PduType_DAPP_CONTROL_ACTION")
+PDU_REPORT = _id("PduType_DAPP_REPORT")
+
+
+def _noop_stamp(seq, stage, aux=0, aux2=0):
+    return None
+
+
+def _noop(_arg):
+    return None
+
+
+def _zero():
+    return 0
+
+
+if ENABLED:
+    _tstamp = _l.latrec_tstamp_py
+
+    def stamp(seq, stage, aux=0, aux2=0):
+        _tstamp(seq, stage, int(aux) & _U64, int(aux2) & _U64)
+
+    open_ring = _l.latrec_tls_open_as_py
+    ctx_set = _l.latrec_ctx_set_py
+    ctx = _l.latrec_ctx_py
+    seq_next = _l.latrec_seq_next_py
+    set_output_dir = _l.latrec_set_output_dir_py
+else:
+    stamp = _noop_stamp
+    open_ring = ctx_set = set_output_dir = _noop
+    ctx = seq_next = _zero