Skip to main content

xDevSM

PyPI License

Overview

The xDevSM API framework provides xApp developers with a SDK exposing simple APIs to streamline the procedures defined by different E2SM protocols, facilitating interactions between the xApp, the near-RT RIC, and the E2 termination on the RAN. It wraps and orchestrates message encoding/decoding, RMR-based communication, and SM-specific behavior. Internally, it delegates encoding and decoding tasks to the sm_framework, which defines the core logic for each Service Model (KPM, RC, and CCC).

xDevSM is built on top of ricxappframe python framework.

The architecture separates three main layers:

  1. xApp API Layer — developer-facing classes (BasexDevSMXapp, xDevSMRMRXapp, wrappers).
  2. Service Model Wrappers — expose KPM, RC, and CCC functionalities.
  3. sm_framework — performs actual encoding/decoding (internal).

⚠️ The xDevSM framework is designed to operate exclusively with the O-RAN Software Community (OSC) Near-RT RIC.
ℹ️ The current version has been tested with the OSC RIC Release J.

Supported Service Model Actions

Service Model Action Type Supported Actions
KPM (Key Performance Measurement) Measurement Actions • Common Condition-based Measurement, UE-level Measurement
RC (RAN Control) Control Actions • QoS Flow Mapping Configuration
• Slice-level PRB Quota Action (only monolithic gNBs)
• Connected Mode Mobility Control
CCC (Cell Configuration and Control) Report Actions • Cell-level RAN Configuration Reporting (REPORT Style 2, periodic event trigger) — e.g. O-NRCellDU attributes
CCC (Cell Configuration and Control) Control Actions • Cell-level O-RRMPolicyRatio control (CONTROL Style 2): per-slice min, max, and dedicated PRB ratios, tested on OCUDU

Installation

xDevSM is distributed as the xdevsm package on PyPI:

pip install xdevsm

ℹ️ The package bundles the prebuilt sm_framework encoders (.so) as package data and is published as a source distribution, so a linux-x86_64 environment and Python 3.11 are required (matching the O-RAN SC Near-RT RIC deployment target). Python 3.12+ is not supported: ricxappframe depends on ricsdl, which pins hiredis==2.0.0, and that version cannot be built on 3.12 or later.

No LD_LIBRARY_PATH setup is needed — the bundled encoders are loaded relative to the installed package. A C compiler is required, though: hiredis==2.0.0 ships no wheel for 3.11, so pip builds it from source. Slim base images therefore need gcc installed (the full python:3.11-bullseye image already has it).

For local development (tests, editable install):

git clone https://github.com/wineslab/xDevSM.git
cd xDevSM
pip install -e ".[dev]"
pytest tests/ -v

Importing

Everything lives under the top-level xdevsm package. The developer-facing classes are also re-exported from the package root for convenience:

# Convenience (recommended)
from xdevsm import xDevSMRMRXapp, XappKpmFrame, XappCccFrame, RadioBearerControl

# Or import from the fully-qualified submodules
from xdevsm.handlers.xDevSM_rmr_xapp import xDevSMRMRXapp
from xdevsm.decorators.kpm.kpm_frame import XappKpmFrame
from xdevsm.decorators.ccc.ccc_frame import XappCccFrame

Class Hierarchy


BasexDevSMXapp
    └── xDevSMRMRXapp
    └── BaseXDevSMWrapper
        ├── xAppReportService
        │   ├── XappKpmFrame
        │   └── XappCccFrame
        └── xAppControlService
                ├── RadioBearerControl
                ├── RadioResourceAllocationControl
                └── ConnectedModeMobilityControl

ℹ️ A detailed diagram is available here.


1. BasexDevSMXapp

Defines the core xApp interface that integrates xDevSM functionality with RMR. Provides the fundamental methods used by all xDevSM-based xApps.

Base class implementing the RMR communication layer. It provides generic send(), receive(), and terminate() methods for message passing between xApps and the Near-RT RIC.

Method Description
handle(xapp, summary, sbuf) Method called by the ricxappframe. Entry point for processing received messages (Indication and RIC CONTROL Messages). Should be overridden by subclasses. Must **not** free sbuf` — see inbound buffer ownership.
send(self, *args, **kwargs) Sends a message via RMR after encoding. Input depends on the underlying E2SM.
terminate() Gracefully stops the xApp.
get_ran_function_description(json_ran_info) Uses the sm_framework to decode the RAN function description depending on the SM.

3. xDevSMRMRXapp

Purpose: Extends BasexDevSMXapp to provide additional functionality specific to the xDevSM architecture.

Key Methods:

Method Description
register_handler(handler) Registers callback handlers.
register_shutdown(handler) Registers a shutdown handler for cleanup tasks.
get_ran_info() Returns E2 node-related encoded information.
rmr_free(sbuf) Frees an RMR message buffer. Overrides ricxappframe's so that freeing the message currently being dispatched is idempotent — see below.

This class is used as the base class for wrapper components.

Inbound buffer ownership

ricxappframe allocates a fresh 4 KiB C buffer for every message it receives and transfers ownership to the caller; it never frees it. xDevSM owns that buffer: xDevSMRMRXapp releases it once the handler chain has returned, whether the chain returned normally or raised.

What this means when writing a handler:

  • Do not free sbuf. It is released for you. Handlers written against xDevSM ≤ 0.1.3 that call xapp.rmr_free(sbuf) keep working — rmr_free makes the first release of the in-flight buffer win and the framework's own a no-op — but new code should not. Freeing the same buffer twice is still a double free, as it always was.
  • rmr_rts before returning is fine. Returning to sender does not free the buffer, and the release happens after your handler returns.
  • Do not retain sbuf past handle(). It is invalid once the chain returns. The decoded payload is already in summary as Python objects, which are safe to keep.
  • Buffers you allocate yourself are yours to free; rmr_free passes those straight through.

4. BaseXDevSMWrapper

Purpose: Provides a composition interface that connects Service Model–specific APIs (KPM, RC, etc.) with an instance of xDevSMRMRXapp. This allows to decorate the xApp with Service Model realted behavior.

Attributes:

  • xapp_handler — instance of BasexDevSMXapp.

Usage: This class is not used directly but extended by RIC service bases (xAppReportService, xAppControlService) and then by Service Model–specific decorators (e.g. XappKpmFrame, RadioResourceAllocationControl) that expose the actual APIs.


5. XappKpmFrame

Purpose: Implements the external API for the Key Performance Measurement (KPM) Service Model.

Internally, it uses encoding and decoding classes from the sm_framework to handle message serialization before E2AP wrapping and RMR transmission.

Common Operations:

  • Encode KPM Subscription Requests.
  • Decode and Parse received KPM Indications.

Example:

xapp_gen = xDevSMRMRXapp(...)
kpm_api = XappKpmFrame(xapp_handler)
kpm_api.subscribe(gnb=self.selected_gnb, 
                ev_trigger=ev_trigger_tuple, 
                func_def=func_def_sub_dict, 
                ran_period_ms=1000, 
                sst=self.sst, sd=
                self.sd)

6. XappCccFrame

Purpose: Implements the external API for the Cell Configuration and Control (CCC) Service Model (ORAN-E2SM-CCC, RAN Function OID 1.3.6.1.4.1.53148.1.1.2.4, SM ID 149). Like XappKpmFrame, it is a REPORT-type decorator and extends xAppReportService, mirroring the KPM lifecycle (subscribe → indication decode → callback).

Unlike KPM and RC, E2SM-CCC uses a JSON wire encoding rather than ASN.1, so the CCC encoders/decoders in sm_framework/py_oran/ccc/ are pure-Python and never cross into the native .so libraries.

Common Operations:

  • Encode CCC Subscription Requests — periodic Event Trigger (Format 3) + cell-level Action Definition (Format 2, REPORT Style 2).
  • Decode and parse received CCC Indications via CccIndicationHeader / CccIndicationMessage.

Supported REPORT style:

Style Description
REPORT Style 2 — Cell Level Reports RAN Configuration Structures (e.g. O-NRCellDU) and a selected set of attributes (arfcnDL, bSChannelBwDL, bWPList, …) per cell.

Example:

xapp_gen = xDevSMRMRXapp("0.0.0.0", route_file=args.route_file)

ccc_xapp = XappCccFrame(xapp_gen,
                        logger=xapp_gen.logger,
                        server=xapp_gen.server,
                        xapp_name=xapp_gen.get_xapp_name(),
                        rmr_port=xapp_gen.rmr_port,
                        http_port=xapp_gen.http_port,
                        pltnamespace=xapp_gen.get_pltnamespace(),
                        app_namespace=xapp_gen.get_app_namespace())

# Wire callbacks
xapp_gen.register_handler(ccc_xapp.handle)
ccc_xapp.register_ind_msg_callback(handler=indication_callback)   # (hdr, msg, meid, sub_id)
ccc_xapp.register_sub_fail_callback(handler=sub_failed_callback)

# Subscribe to a periodic cell-level REPORT on O-NRCellDU
ccc_xapp.subscribe(gnb=selected_gnb,
                   ran_period_ms=1000,
                   ran_cfg_structure_name="O-NRCellDU",
                   attributes=["arfcnDL", "bSChannelBwDL", "bWPList"])

# or the one-call helper for those three target attributes:
ccc_xapp.subscribe_arfcn_bw_bwps(gnb=selected_gnb, ran_period_ms=1000)

ℹ️ The indication callback signature is handler(ind_hdr, ind_msg, meid, sub_id). Iterate the reported cells/structures with ind_msg.cells() / ind_msg.iter_structures().

CccRrmPolicyRatioControl

CccRrmPolicyRatioControl sends the E2SM-CCC cell-level control (CONTROL Style 2, Header Format 1, Message Format 2) for the O-RRMPolicyRatio structure. It sets the PRB share of a slice in one cell, so it needs no UE ID. It extends xAppControlService and uses send_policies() instead of send(), because the JSON encoding has no ASN.1 function definition.

  • find_ccc_function_id(json_ran_info) returns the CCC RAN function ID from the e2mgr information of the E2 node. It accepts the OID 1.3.6.1.4.1.53148.1.1.2.4 and the OID 1.3.6.1.4.1.53148.1.6.2.4 that OCUDU announces.
  • send_policies() checks every slice, then sends all slices in one control, so the cell applies them together. A control for two or more slices is larger than 1 KB and needs the xDevSM ricxappframe patches (patch 004).
  • Each slice needs dedicated_ratio <= min_ratio <= max_ratio, and the min_ratio of the slices in one call must sum to at most 100 (TS 28.541). dedicated_ratio defaults to 0.
  • The Old Values of each slice carry its resource type and member, so the E2 node can find the policy to change. They leave out the old ratios, which the xApp does not read.
  • Known OCUDU limits: it reads rRMPolicyDedicatedRatio 0 as missing and fails the control (pass dedicated_ratio=1 or more), and it applies only the min and max ratios, only to slices in cell_cfg: slicing.
  • The callbacks of register_control_ack_suc_callback() and register_control_ack_fail_callback() receive a CccControlAck for a RIC Control Acknowledge or Failure. Its outcome is a CccControlOutcome, the JSON E2SM-CCC Control Outcome of the message. outcome.structures() lists each structure with applied, its applied_values (the currentValuesOfAttributes) or its failure_reason. A failure also carries cause, the E2AP Cause as (choice, value). A message that does not decode reaches the callback as the RMR summary. Decoding needs the xDevSM ricxappframe patches (python -m xdevsm.ricxappframe_patches).
from xdevsm import CccRrmPolicyRatioControl
from xdevsm.sm_framework.py_oran.ccc.ccc_decoder import find_ccc_function_id
from xdevsm.sm_framework.py_oran.ccc.ccc_encoder import RrmPolicySlice

gnb, gnb_info = xapp_gen.get_selected_e2node_info(None)
ctrl = CccRrmPolicyRatioControl(xapp_gen,
                                logger=xapp_gen.logger,
                                server=xapp_gen.server,
                                xapp_name=xapp_gen.get_xapp_name(),
                                rmr_port=xapp_gen.rmr_port,
                                http_port=xapp_gen.http_port,
                                mrc=xapp_gen._mrc,
                                pltnamespace=xapp_gen.get_pltnamespace(),
                                app_namespace=xapp_gen.get_app_namespace(),
                                mcc="001", mnc="01",
                                nci=0x3954000,  # 36-bit NR Cell Identity
                                function_id=find_ccc_function_id(gnb_info))
xapp_gen.register_handler(ctrl.handle)
ctrl.send_policies(gnb.inventory_name,
                   [RrmPolicySlice(sst=1, sd="000001", min_ratio=1, max_ratio=10, dedicated_ratio=1)],
                   resource_type="PRB_DL")

7. xAppReportService

Purpose: Provides the base class for Report-type Service Models. Handles subscription management, indication message routing, and decoding.

Common Responsibilities:

  • Build and send E2 subscription requests.
  • Route incoming indication messages to registered callbacks.
  • Interface with sm_framework for decoding RAN function descriptions.

Specializations:

Subclass Description
XappKpmFrame Implements KPM-specific subscription and indication handling.
XappCccFrame Implements CCC-specific (Cell Configuration and Control) subscription and indication handling over a JSON encoding.

8. xAppControlService

Purpose: Provides the base class for the Radio Control (RC) Service Model. Defines shared functionality across different RC control operations.

Common Responsibilities:

  • Initialize and validate RC messages.
  • Interface with sm_framework for encoding and decoding.
  • Offer helper methods for constructing Control Requests.
  • Handle RIC Control Acknowledge and Failure messages.

Specializations:

Subclass - Style Description Control Action Id Support
RadioBearerControl - 1 Handles bearer-level control (QoS, bearer setup/release). (2) QoS flow mapping configuration
RadioResourceAllocationControl - 2 Manages resource allocation (e.g., PRB or scheduling). (6) Slice-level PRB quota
ConnectedModeMobilityControl - 3 Manages handover and mobility-related control procedures. (1) Handover control

Each subclass defines Service Model–specific operations and message structures, invoking the appropriate encoder/decoder from sm_framework.rc.

ℹ️ Control parameters can be modified using getter and setter methods.

Example: Radio Bearer Control Initialization

xapp_gen = xDevSMRMRXapp("0.0.0.0", route_file=args.route_file)

rc_xapp = RadioBearerControl(xapp_gen,
                                logger=logger,
                                server=xapp_gen.server,
                                xapp_name=xapp_gen.get_xapp_name(),
                                rmr_port=xapp_gen.rmr_port,
                                http_port=xapp_gen.http_port,
                                mrc=xapp_gen._mrc,
                                pltnamespace=xapp_gen.get_pltnamespace(),
                                app_namespace=xapp_gen.get_app_namespace(),
                                # control parameters
                                drb_id=args.drb_id,
                                qos_flow_id=args.qos_flow_id,
                                qos_flow_mapping_indication=args.qos_flow_mapping_indication
                                )

Example: Radio Resource Allocation Control

xapp_gen = xDevSMRMRXapp("0.0.0.0")
rc_xapp = RadioResourceAllocationControl(xapp_gen,
                                        logger=logger,
                                        server=xapp_gen.server,
                                        xapp_name=xapp_gen.get_xapp_name(),
                                        rmr_port=xapp_gen.rmr_port,
                                        http_port=xapp_gen.http_port,
                                        mrc=xapp_gen._mrc,
                                        pltnamespace=xapp_gen.get_pltnamespace(),
                                        app_namespace=xapp_gen.get_app_namespace(),
                                        # control parameters
                                        plmn_identity="00F110",
                                        sst=1,
                                        sd=1,
                                        min_prb_policy_ratio=10,
                                        max_prb_policy_ratio=70,
                                        dedicated_prb_policy_ratio=5
                                        )

Example: Connected Mode Mobility Control

xapp_gen = xDevSMRMRXapp("0.0.0.0")
rc_xapp = ConnectedModeMobilityControl(xapp_gen,
                                        logger=logger,
                                        server=xapp_gen.server,
                                        xapp_name=xapp_gen.get_xapp_name(),
                                        rmr_port=xapp_gen.rmr_port,
                                        http_port=xapp_gen.http_port,
                                        mrc=xapp_gen._mrc,
                                        pltnamespace=xapp_gen.get_pltnamespace(),
                                        app_namespace=xapp_gen.get_app_namespace(),
                                        # control parameters
                                        plmn_identity="00F110",
                                        nr_cell_id="00000000000000000000111000000001"
                                        )

9. Service Model Encoder/Decoder

The sm_framework provides the internal logic for encoding and decoding messages according to the KPM, RC, and CCC Service Models. The xDevSM decorators are organized by RIC service direction: xAppReportService and xAppControlService are the generic bases for report- and control-style services, and any service model (KPM, RC, CCC, ...) plugs in by extending the appropriate base — for example XappKpmFrame and XappCccFrame extend xAppReportService, and RadioResourceAllocationControl extends xAppControlService.

ℹ️ KPM and RC serialize through ctypes bindings to the native .so libraries, whereas CCC (E2SM-CCC) uses a pure-Python JSON codec in sm_framework/py_oran/ccc/.

[ xApp code ] → [ xDevSM API ] → [ sm_framework (encode/decode) ] → [ E2AP + RMR ]

Developers using xDevSM do not directly call sm_framework; it is fully managed by the wrapper classes.


10. Example xApps

For end-to-end examples of KPM, RC, and CCC xApps built on top of this API, see:

xDevSM-xapps-examples

This repository contains working implementations that demonstrate:

  • How to set-up an xApp based on xDevSM.
  • Registration of handlers.
  • Sending and receiving encoded Service Model messages.

The CCC basic xApp (ccc_xapp.py) is a minimal reference: it subscribes to a periodic O-NRCellDU REPORT (Style 2 / Event Trigger Format 3) and pretty-prints every incoming indication (cell identity, frequencies, SSB, BWP list, …).


11. Extending the API

To support a new Service Model (E2SM):

  1. Implement the encoder/decoder in sm_framework/<new_sm>/.
  2. Create a new wrapper subclass (e.g., XappNewSMFrame) extending BaseXDevSMWrapper.
  3. Implement SM-specific methods (e.g., send_<msg>(), handle_<msg>()).
  4. Register handlers for the new message types in your xApp.

12. Latency instrumentation (latrec)

xDevSM can record per-stage latency data for the E2AP/E2SM-DAPP legs it owns (indication decode, control encode, and the E2AP framing/send around it), using latrec, the ring-recorder format shared with libe3 and the rest of the E2/E3 stack. It is off by default.

  • Enable by setting LATREC_DIR to a writable directory before starting the xApp process. Each stamping thread writes one <role>.<tid>.latrec ring file there (role xdevsm).
  • Size the rings with LATREC_ENTRIES_LOG2_XDEVSM (or the stack-wide LATREC_ENTRIES_LOG2), as a power-of-two exponent between 12 and 28; the default is 18, i.e. 256K records ≈ 8 MiB per thread.
  • Disable by leaving LATREC_DIR unset. Every stamp site then costs a module-level check and a no-op call — tens of nanoseconds, no locks and no allocation, but not literally zero. Run scripts/latrec_bench.py to measure both paths on your own hardware; it reports enabled and disabled cost side by side.
  • The writer (xdevsm._latrec.writer) is a self-contained, pure-Python module with no xdevsm-specific dependencies, so it can be reused as-is by other pure-Python components that need the same mechanism.
  • Rings are read with libe3's own tooling (tools/latrec_reader.py / tools/latrec2csv.py); the stage identifiers this package stamps mirror libe3/include/libe3/latrec.h (see xdevsm/_latrec/stages.py).

13. Logging

The framework configures the xApp's logger from the controls block of the xApp descriptor (the JSON at CONFIG_FILE), so verbosity and destination are set externally rather than in code. Each key can be overridden by an environment variable, which lets a Deployment change them without rebuilding the image.

controls key Env override Values Default
log_level LOG_LEVEL DEBUG, INFO, WARNING, ERROR INFO
log_stdout LOG_STDOUT boolean true
log_file LOG_FILE path; empty means no file unset
{
  "controls": {
    "log_level": "ERROR",
    "log_stdout": false,
    "log_file": "/tmp/xapp.log"
  }
}
  • Precedence is environment → controls → default. An unrecognised level falls back to INFO rather than raising, so a typo in a descriptor cannot stop an xApp from starting.
  • ERROR is the quietest setting available — mdclogpy's severity enum has no OFF.
  • Settings are applied in xDevSMRMRXapp.__init__ before the routing table, HTTP server and subscriptions are set up, so log_level governs the startup logs too.
  • With log_stdout false, the container writes nothing to stdout, so kubectl logs is empty and log_file becomes the only record — point it at a mounted volume if it needs to outlive the pod.
  • The logger is shared with ricxappframe, so these settings cover its output as well as this framework's.

14. Other Sources

A detailed step-by-step tutorial for setting up a deployment to begin working with xDevSM is available here.

How To Cite

If you use xDevSM, please reference the following paper:

A.Feraudo, S. Maxenti, A. Lacava, P. Bellavista, M. Polese, and T. Melodia, "xDevSM: Streamlining xApp Development With a Flexible Framework for O-RAN E2 Service Models," Proceedings of the 18th ACM Workshop on Wireless Network Testbeds, Experimental evaluation & Characterization (WiNTECH), November, 2024.

License

This project is licensed under Apache License Version 2.0 - see License File for more details.

Organizations

Wireless Networks and Embedded Systems Lab
Mobile Middleware Research Group

Metadata

Release files for xdevsm 0.1.8

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for xdevsm 0.1.8
File Size Uploaded Provenance Actions
xdevsm-0.1.8.tar.gz 5.6 MB With provenance Details for xdevsm-0.1.8.tar.gz

Release files / xdevsm-0.1.8.tar.gz

Download URL xdevsm-0.1.8.tar.gz
Size 5.6 MB
Tags Source
SHA-256 checksum
How to use checksums
c415d2139704ab7db80d505303437ab310d97517a11770201ad3edefde107dea
BLAKE2b-256 checksum
How to use checksums
2c7d0cc714f46b3625343a9ba72abe080fbe6da8582a01714bae5d9549a439e0
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

Security for xdevsm 0.1.8

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

1 file in this release has been uploaded with provenance metadata.

Attestation for xdevsm-0.1.8.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 16, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page