W8 - oran-ntn + FlexRIC bridge¶

Gallery¶

Space O-RAN Near-RT RIC over a 66-satellite constellation

Conflict-free xApp control - 71,967 E2 actions, 0 conflicts

FlexRIC E2 bridge driving ns-3 from real xApps over SCTP

TS 28.552 canonical KPM metrics, measured off the PHY

oran-ntn is the ns3-ntn-toolkit module that brings the O-RAN disaggregated RAN control architecture to non-terrestrial networks: a multi-tier RIC (real-time, Near-RT, and on-board Space-RIC), E2AP-style termination with canonical E2SM-KPM and E2SM-RC service models, A1 policy ingest, and a conflict-managed xApp framework, all driven by KPIs measured in-band on a real mmwave NR NTN data plane. It is the toolkit's space-O-RAN testbed: RIC control loops act on per-UE SINR and TBLER measured off an actual SpectrumPhy + MAC + HARQ/AMC + RLC/PDCP + RRC + EPC stack flying SGP4 satellite orbits, not on synthetic KPI generators.

Why it matters. Studying O-RAN over satellite means answering where the RIC should live, how feeder-link latency bounds the control loop, and whether xApps still converge when KPM travels one slant-range delay each way. oran-ntn is an open-source ns-3 testbed that makes RIC placement, payload architecture, and the E2 latency budget first-class measurable variables, with every KPM row tagged by provenance (phy-trace vs geometry-budget) so there are no hidden synthetic KPIs behind a control result.

What it simulates¶

Multi-tier RIC. A real-time RIC (OranNtnRtRic) co-located with the O-DU whose control loop is hard-bounded below the O-RAN 10 ms RT limit (a loop period at or above 10 ms refuses to start) and acts on per-UE SINR/TBLER measured from the live stack; the WG3 OranNtnNearRtRic kernel with xApp lifecycle, E2 termination, an OranNtnSdl shared-data layer, and metrics aggregation; and an on-board OranNtnSpaceRic that enters autonomous mode on feeder-link outage.
xApp framework with conflict management. The flagship scenario runs five xApps simultaneously (HO Predict, Beam Hop, Slice Manager, Doppler Comp, TN-NTN Steering), all derived from OranNtnXappBase, with an OranNtnConflictManager offering PRIORITY_BASED, TEMPORAL, and MERGE resolution strategies and a conflict_log.csv audit trail. Additional advanced xApps (interference management, energy harvest, predictive allocation, multi-connectivity, ISAC, THz beam/RIS/spectrum) ship in the same directory.
RIC placement as an experiment variable. OranNtnRicPlacement sites the RIC on-board the satellite, on a HAPS, at a ground gateway, or in the ground cloud, and derives the one-way E2 latency from the live slant range plus site terms, binding an OranNtnE2Node's feeder delay to the real SGP4 / TR 38.811 mobility geometry.
E2 interface and KPM telemetry. An E2AP-style subscription/indication path (OranNtnE2Node / OranNtnE2Termination) with delay-modeled indications and RC actions (one feeder delay on the measurement uplink, one on the control downlink via ReceiveRcAction()), optionally aligned to the Near-RT RIC control-loop tick. Canonical KPM measurement and label IDs emit a stable kpm_canonical.csv; KPM / RC / CCC / ephemeris service models sit behind a plugin ABI (OranNtnServiceModelRegistry), including E2SM-RC Style 3 connected-mode mobility.
A1 policy. OranNtnA1PolicyManager / OranNtnA1Adapter ingest orbit-aware constellation policies from a Non-RT RIC against an OSC-aligned A1 policy schema registry (JSON schemas in a1-policies/).
Cross-domain SMO. OranNtnNwdaf per-slice analytics with an SLA-risk score from measured KPM, OranNtnTpnController transport-path ranking and per-slice switching, and OranNtnCrossDomainSmo, one closed loop coordinating RAN quota, transport path, and edge compute.
Payload, fronthaul split, platform, and role switch. NtnFhSplitModel (Opt 2 / 7.2a / 7.2b / Opt 8 with one-way latency bounds and fronthaul-rate multipliers, plus ChooseBestSplit()), NtnPlatformSpec (UAV / HAPS / LEO / MEO / GEO classes with latency bands and enforceable UAV endurance), and OranNtnRoleSwitch (regenerative-payload role elevation RU to RU+DU to full gNB on measured battery, fronthaul-latency, and failure triggers with a real service-interruption window).
AI-native inference. OranNtnOnnxXapp loads .onnx models exported from the toolkit gym environments and infers on live measured feature vectors; ONNX Runtime is auto-detected at configure time, with a transparent heuristic fallback so every example still runs.
Disaggregated gNB. CU/DU/RU split with per-entity E2 termination via OranNtnSplitGnbEntity, OranNtnF1Interface, and OranNtnOfhInterface, built with OranNtnSplitGnbHelper.

Standards & references¶

O-RAN ALLIANCE. WG3 Near-Real-Time RIC and E2 (E2AP-style subscription/indication, E2SM-KPM, E2SM-RC including Style 3 connected-mode mobility); WG2 Non-RT RIC and A1 policy with an OSC-aligned schema registry; WG4 fronthaul split options (Opt 2 / 7.2a / 7.2b / Opt 8). The ASN.1 Aligned-PER codec for E2AP / E2SM-KPM / E2SM-RC and FlexRIC-compatible field names support external RIC bridging.
3GPP. TS 28.552 canonical KPM measurement names (emitted as kpm_canonical.csv and per-slice KPM via the AI flow monitor); TR 38.801 / O-RAN WG4 fronthaul functional splits; TR 38.811 NTN UE mobility classes and TR 38.821-style NTN link-budget evaluation over live geometry; QoS flows carry S-NSSAI / 5QI slice identity in-band.
Transport realism (read before citing E2 results). E2AP-over-SCTP is not simulated; E2 indications and RC actions are delay-modeled simulator events, the same substitution ns-3 mainline applies to S1-AP / X2-AP. Wire-level E2 (E2AP/ASN.1-PER over real SCTP) via the FlexRIC bridge is gated on the FlexRIC Docker run; the bridge transport stub is not yet connected to the in-sim E2 nodes.

Use cases¶

RIC placement study. Measure control-loop reaction time across on-board, gateway, and cloud RIC siting, with both legs of the loop riding the E2 latency of the chosen placement derived from live slant range (oran-ntn-ric-placement-ab).
Closed-loop RIC traffic control. An mMIMO precoder xApp consumes per-second E2-KPM and issues an E2SM-RC BEAM_SWITCH back through ReceiveRcAction(), recovering measured SINR/TBLER/goodput one feeder delay later (oran-ntn-ric-controlled-traffic).
Payload architecture comparison. Measure one-way delay per satellite payload (transparent / O-RU / O-RU+O-DU / full gNB) and check feeder delay against fronthaul-split feasibility, surfacing why LEO latencies rule out lower-PHY splits (oran-ntn-payload-options-ab).
Cross-domain slice adaptation. Watch URLLC one-way delay climb as a serving satellite recedes, then snap back when NWDAF + SMO + the TPN controller re-route to a rising satellite (oran-ntn-cross-domain-slice).
Post-disaster emergency communication. A gateway failure elevates the satellite to a full on-board gNB via role switch while the SMO protects a dedicated emergency slice (SST=5) by throttling eMBB quota (oran-ntn-emergency-communication).
Platform latency validation. Verify measured user-plane RTT against each platform class's latency band across UAV / HAP / LEO / MEO / GEO (ntn-platform-latency-validation).

Run it¶

# Real-stack flagship: Near-RT RIC + xApps driven by measured mmwave NR NTN PHY KPM
./ns3 run "oran-ntn-real-stack-scenario --duration=30 --numUes=6"

# Closed RIC control loop: E2SM-RC BEAM_SWITCH recovers measured goodput (compare --xapp=1 vs 0)
./ns3 run "oran-ntn-ric-controlled-traffic --simSeconds=40 --xapp=1"

# RIC placement A/B: control-loop reaction time per placement over live E2 latency
./ns3 run "oran-ntn-ric-placement-ab --simSeconds=40 --placement=cloud"

Test suites: ./test.py -s oran-ntn (core RIC / SM / A1 / Space-RIC), ./test.py -s oran-ntn-multi-tier-ric (RT-RIC bound, placement geometry, cross-domain loop, ONNX fallback), and ./test.py -s oran-ntn-ws4 (payload delay ladder, FH-split feasibility, endurance, role switch).