xDevSM
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:
- xApp API Layer — developer-facing classes (
BasexDevSMXapp,xDevSMRMRXapp, wrappers). - Service Model Wrappers — expose KPM, RC, and CCC functionalities.
- 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_frameworkencoders (.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:ricxappframedepends onricsdl, which pinshiredis==2.0.0, and that version cannot be built on 3.12 or later.No
LD_LIBRARY_PATHsetup is needed — the bundled encoders are loaded relative to the installed package. A C compiler is required, though:hiredis==2.0.0ships no wheel for 3.11, so pip builds it from source. Slim base images therefore needgccinstalled (the fullpython:3.11-bullseyeimage 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 callxapp.rmr_free(sbuf)keep working —rmr_freemakes 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_rtsbefore returning is fine. Returning to sender does not free the buffer, and the release happens after your handler returns.- Do not retain
sbufpasthandle(). It is invalid once the chain returns. The decoded payload is already insummaryas Python objects, which are safe to keep. - Buffers you allocate yourself are yours to free;
rmr_freepasses 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 ofBasexDevSMXapp.
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 withind_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 OID1.3.6.1.4.1.53148.1.1.2.4and the OID1.3.6.1.4.1.53148.1.6.2.4that 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 themin_ratioof the slices in one call must sum to at most 100 (TS 28.541).dedicated_ratiodefaults 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
rRMPolicyDedicatedRatio0 as missing and fails the control (passdedicated_ratio=1or more), and it applies only the min and max ratios, only to slices incell_cfg: slicing. - The callbacks of
register_control_ack_suc_callback()andregister_control_ack_fail_callback()receive aCccControlAckfor a RIC Control Acknowledge or Failure. Itsoutcomeis aCccControlOutcome, the JSON E2SM-CCC Control Outcome of the message.outcome.structures()lists each structure withapplied, itsapplied_values(the currentValuesOfAttributes) or itsfailure_reason. A failure also carriescause, 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_frameworkfor 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_frameworkfor 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
.solibraries, whereas CCC (E2SM-CCC) uses a pure-Python JSON codec insm_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:
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):
- Implement the encoder/decoder in
sm_framework/<new_sm>/. - Create a new wrapper subclass (e.g.,
XappNewSMFrame) extendingBaseXDevSMWrapper. - Implement SM-specific methods (e.g.,
send_<msg>(),handle_<msg>()). - 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_DIRto a writable directory before starting the xApp process. Each stamping thread writes one<role>.<tid>.latrecring file there (rolexdevsm). - Size the rings with
LATREC_ENTRIES_LOG2_XDEVSM(or the stack-wideLATREC_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_DIRunset. 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. Runscripts/latrec_bench.pyto 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 noxdevsm-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 mirrorlibe3/include/libe3/latrec.h(seexdevsm/_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 toINFOrather than raising, so a typo in a descriptor cannot stop an xApp from starting. ERRORis the quietest setting available —mdclogpy's severity enum has noOFF.- Settings are applied in
xDevSMRMRXapp.__init__before the routing table, HTTP server and subscriptions are set up, solog_levelgoverns the startup logs too. - With
log_stdoutfalse, the container writes nothing to stdout, sokubectl logsis empty andlog_filebecomes 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)
| 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 logSecurity 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 logA 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.