Skip to main content

What CNS OCUDU Adds to OCUDU

CNS OCUDU is Cognitive Network Solutions' downstream distribution of upstream OCUDU — the gNB of the Racora platform. It adds capabilities on top of upstream in service of an AI-native radio access network. This document records what is added relative to stock OCUDU, organized into four parts:

  1. Interfaces and integrations — open interfaces and reference integrations that connect OCUDU to a broader RAN platform.
  2. Primitives — discrete OCUDU improvements: 3GPP / O-RAN / FAPI procedure implementations, framework additions, and small fixes, each a self-contained change.
  3. End-to-end features — operator-facing capabilities built by composing primitives.
  4. Upstreamed — capabilities that began here and are now in upstream OCUDU.

CNS OCUDU tracks OCUDU dev.

1. Interfaces and Integrations​

RANN-P — Internal gNB Intelligence Interface​

An in-process interface from CU-CP to a downstream intelligence consumer. Measurement reports are hooked at the point of L3 decoding and exported as flat per-UE per-cell per-timestamp records — the same decoded data the control plane uses for its own mobility decisions.

The adapter is non-invasive: when no consumer is configured, the control plane behaves identically to upstream. A file sink is the production transport in this implementation; a Flight (Apache Arrow over gRPC) sink header is included for reference but is not compiled due to a known fmt symbol conflict between Arrow C++ and OCUDU.

The JSONL wire format is a golden-pinned cross-repo contract: the serializer lives in one pure function (lib/rann_p/rann_p_json.h, to_json_line()), byte-compared against a committed fixture (tests/unittests/rann_p/golden/) whose copies also live in the racora and cuip repos, diffed centrally by racora CI. A format change is a deliberate act — regenerate the fixture and fan it out.

Implementation: lib/rann_p/, lib/cu_cp/cell_meas_manager/cell_meas_manager_impl.cpp

RANN-P is the open interface for CU-CP↔intelligence-plane communication; lib/rann_p/ is one implementation of it, and the notifier hook in cell_meas_manager is generic.

OpenTelemetry Observability Integration​

Native OpenTelemetry tracing and log forwarding in OCUDU process binaries. Process-level TracerProvider and LoggerProvider bootstrap via OTLP HTTP, span emission at workflow boundaries, cross-coroutine context propagation, and a srslog-to-OTLP tee that forwards every log line to an OpenTelemetry collector.

Build-gated on ENABLE_CNS_OTEL (default ON). When OFF, all calls compile to no-ops against the header-only opentelemetry-cpp API; the SDK, the OTLP exporter, and their protobuf/curl dependencies are not built.

Implementation: lib/cns_observability/, cmake/modules/cns_otel.cmake

2. Primitives​

DU Cell Runtime Parameter Mutation (PCI)​

Plumbs an optional PCI mutation through the DU parameter config request: du_cell_param_config_request gains a pci_mod field and the request validation accepts it, so the pci_set WebSocket command (below) has a typed path into du_param_config_procedure.

The apply step — swapping the PCI of a deactivated cell via MAC cell destroy-recreate — is interface plumbing: the procedure accepts the request without changing the cell. PCI is baked into the MAC ssb_assembler at construction and has no live setter, so the apply requires a destroy-recreate of the MAC cell, which is only safe on a deactivated cell.

Implementation: include/ocudu/du/du_high/du_manager/du_configurator.h, lib/du/du_high/du_manager/procedures/du_param_config_procedure.cpp

Log File force_flush Configuration​

Exposes the existing fetch_file_sink::force_flush capability through YAML and CLI. Default false — no behavior change. Opt-in true for live debugging where the libstdc++ ~8 KB stdlib buffer otherwise hides events for many minutes on quiet networks.

Implementation: apps/helpers/logger/logger_appconfig.h, apps/helpers/logger/logger_appconfig_cli11_schema.cpp, apps/helpers/logger/logger_appconfig_yaml_writer.cpp

PCAP Real-Time Per-PDU Flush​

Flush after every PDU write in the backend pcap writer. Without this, capture files appear empty during live capture and cannot be consumed by real-time monitoring. Performance cost is negligible: pcap writes are off the critical path and signaling traces are infrequent.

Implementation: lib/pcap/backend_pcap_writer.cpp, lib/pcap/pcap_file_writer.cpp

Docker ZMQ Build/Runtime Dependencies​

Adds libzmq3-dev (build) and libzmq5 (runtime) to the Debian/Ubuntu install function. Without these, ZMQ radio — the standard testing transport for OCUDU-based stacks — is not available in prebuilt Docker images even though CMake defaults ENABLE_ZEROMQ=ON.

Implementation: docker/scripts/install_docker_dependencies.sh

CU-CP Standalone JSON Metrics Plumbing​

One fix in the standalone ocucp initialization path so JSON metrics can be published over the WebSocket: a top-level metrics.enable_json enables the remote_control server's metrics subscription, the way the monolithic gnb already behaves. Standalone mode only.

Implementation: apps/cu_cp/cu_cp.cpp

DU pci_set WebSocket Command​

A DU pci_set command ({"cells": [{"plmn", "nci", "pci"}]}) dispatches to the cell runtime parameter mutation plumbing above through the result-carrying remote-command interface upstream OCUDU has had since the cell state commands (ocudu/ocudu !863). The DU sib_update command that previously appeared here is upstream OCUDU now; the CU-CP cell management commands are upstream too — see "Upstreamed" below.

Implementation: apps/units/flexible_o_du/o_du_high/du_high/commands/du_high_remote_commands.cpp, apps/units/flexible_o_du/o_du_high/o_du_high_unit_factory.cpp

Container Images for the Racora Platform​

.gitlab/ci/racora.yml builds and publishes the two images the Racora platform bundles: gnb (CNS OCUDU's CU-CP / CU-UP / DU / gNB binaries, built with MARCH=x86-64-v3) and open5gs (the reference 5G core, built from upstream Open5GS source by docker/open5gs/Dockerfile). A push to cns/main republishes the rolling :cns-main tags; a git tag vX.Y.Z publishes immutable tags. Both pushes are gated by a boot smoke test, and the gnb build additionally needs the RANN-P golden-fixture check. The stage is additive to and independent of the upstream pipeline.

Implementation: .gitlab/ci/racora.yml, docker/open5gs/

3. End-to-End Features​

AI-Native Measurement Export​

Composes the RANN-P platform integration with the cell_meas_manager notifier hook. Every CU-CP measurement report is forwarded as a flat per-UE per-cell per-timestamp record to a downstream intelligence consumer, providing the raw observation stream needed for graph-based learning over the radio access network.

Distributed Tracing across the gNB​

Composes the OpenTelemetry platform integration with span hooks placed at workflow boundaries: all fourteen CU-CP WS remote commands (the five cell state commands, the seven mobility configuration commands, and the two handover triggers — each emitting cucp.<cmd>.execute with its identity attributes and an outcome/error classification), the DU cell-stop procedure, and the F1AP gNB-CU Configuration Update TX procedure (CU-CP F1AP layer). The synchronous section of the mobility manager annotates the active trigger span with mobility.trigger_outcome, classifying the failure behind the command's generic rejection (unknown UE, unknown target cell); the bounded executor dispatch distinguishes queue-full/timeout from genuine rejections via dispatch.failure. Cross-coroutine context propagation chains the spans so a single operator action (e.g., cell_lock) renders as one continuous trace across all gNB process boundaries, and a W3C traceparent carried in the WS payload parents the command span under the caller's trace. Span naming and attribute conventions: the Racora span schema.

4. Upstreamed​

Capabilities that began life in this catalog and are now upstream OCUDU. They are no longer CNS additions; CNS OCUDU simply tracks them.

  • CU-driven graceful cell stop and runtime MIB mutation — the bar → release UEs → deactivate stop sequence over the F1AP gNB-CU Configuration Update and runtime MIB cellBarred / intraFreqReselection mutation. Merged upstream 2026-07-23 and 2026-08-13 (ocudu/ocudu !862, !864).
  • Runtime SIB content update — the sib_update WebSocket command (PLMN, TAC, SIB1, SIB3 parameter changes at runtime). Merged upstream 2026-05-19 (ocudu/ocudu !620).
  • CU-CP logical cells and cell state commands — the logical cell registry with per-cell administrative state, the shared cells: configuration section, and the cell_lock / cell_unlock / cell_bar / cell_unbar / cell_status WebSocket commands. Merged upstream 2026-09-03 (ocudu/ocudu !863).
  • Runtime mobility configuration — a runtime mobility configuration API on the cell measurement manager (cell, neighbor, and report-config add/update/remove with measurement-object maintenance and UE meas-config updates at the next RRC reconfiguration) plus the mobility_cell_set / mobility_cell_remove / mobility_neighbor_add / mobility_neighbor_remove / mobility_report_config_set / mobility_report_config_remove / mobility_periodic_report_set / trigger_handover / trigger_conditional_handover WebSocket commands. Merged upstream 2026-09-28 (ocudu/ocudu !1371).
  • FAPI P5 cell lifecycle for the monolithic DU — MAC drives FAPI START / STOP per cell, a real upper_phy_operation_controller gates slot indications per sector, and an init-time bypass resolves the DU-high / DU-low init race in a single process, so every cell state transition — boot, runtime deactivate, runtime activate — follows the same FAPI lifecycle contract whether the DU is monolithic or split-6. Merged upstream 2026-10-01 (ocudu/ocudu !745).
  • gNB-DU Configuration Update absorption — CU-CP-side handling of the DU-initiated F1AP configuration update (TS 38.473 §8.2.4, Served_Cells_To_Modify_List). Upstream implemented its own handling (upstream commit 46143f1c4a, 2026-09-23); the implementation that lived here is retired.