14 KiB
14 KiB
O-RAN Compliant Antenna Muting / Energy Saving Module
Overview
This module implements O-RAN WG4 compliant MIMO antenna muting for energy saving.
It follows the MPLANE-TRX-CONTROL feature defined in o-ran-uplane-conf.yang.
Architecture
┌─────────────────────────────────────────────────────────────────────────────┐
│ Control Interfaces │
│ │
│ ┌───────────────────────────┐ ┌─────────────────┐ ┌──────────────────┐ │
│ │ O-RAN M-Plane NETCONF │ │ Test Socket │ │ Future: rApp/A1 │ │
│ │ (Production/O-RAN) │ │ (Development) │ │ (Policy-based) │ │
│ │ │ │ │ │ │ │
│ │ Uses real NETCONF RPC: │ │ Simple TCP │ │ │ │
│ │ • edit-config │ │ socket on │ │ │ │
│ │ • validate │ │ port 9999 │ │ │ │
│ │ • commit │ │ │ │ │ │
│ └───────────┬───────────────┘ └────────┬────────┘ └────────┬─────────┘ │
│ │ │ │ │
│ └───────────────────────────┼────────────────────┘ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────────────┐ │
│ │ nr_antenna_state_t (Antenna State Manager) │ │
│ │ - tx_antenna_bitmask: O-RAN compliant antenna mask │ │
│ │ - rx_antenna_bitmask: O-RAN compliant antenna mask │ │
│ │ - Statistics for energy saving monitoring │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
│ │ │
│ ▼ │
│ ┌────────────────────────────────────────────────────────────────────────┐ │
│ │ PHY Layer Integration │ │
│ │ - nr_beam_precoding_with_muting(): Blanks muted antennas │ │
│ │ - Beamforming skipped for muted antennas │ │
│ │ - Output zeroed = transmission blank (O-RAN compliant) │ │
│ └────────────────────────────────────────────────────────────────────────┘ │
└─────────────────────────────────────────────────────────────────────────────┘
O-RAN Compliance
This implementation follows O-RAN Alliance specifications:
| O-RAN Element | Implementation |
|---|---|
WG4 o-ran-uplane-conf.yang |
tx-array-antenna-mask-config, rx-array-antenna-mask-config |
antenna-bitmask parameter |
nr_antenna_state_t.tx_antenna_bitmask |
MPLANE-TRX-CONTROL feature |
mplane_set_tx_antenna_mask(), mplane_set_rx_antenna_mask() |
| NETCONF edit-config/validate/commit | radio/fhi_72/mplane/antenna-control-mplane.c |
| Transmission blanking | Zeroing txdataF_BF for muted antennas |
YANG Model Paths Used
/o-ran-uplane-conf:user-plane-configuration/tx-array-antenna-mask-config
└── array-name # Reference to tx-arrays list
└── antenna-bitmask # Binary bitmask (bit N=1 means antenna N active)
/o-ran-uplane-conf:user-plane-configuration/rx-array-antenna-mask-config
└── array-name # Reference to rx-arrays list
└── antenna-bitmask # Binary bitmask
Files
Core State Management
openair1/PHY/NR_TRANSPORT/nr_antenna_state.h- Antenna state APIopenair1/PHY/NR_TRANSPORT/nr_antenna_state.c- Implementation
O-RAN M-Plane NETCONF (Production)
radio/fhi_72/mplane/antenna-control-mplane.h- O-RAN compliant NETCONF APIradio/fhi_72/mplane/antenna-control-mplane.c- NETCONF implementation using libnetconf2- Uses existing M-Plane infrastructure:
config-mplane.c,rpc-send-recv.c
Control Interface
openair1/PHY/NR_TRANSPORT/nr_antenna_control.h- Unified control interfaceopenair1/PHY/NR_TRANSPORT/nr_antenna_control.c- Backend-agnostic implementation
PHY Integration
openair1/PHY/MODULATION/beamforming.c- Modified withnr_beam_precoding_with_muting()
Usage
Production Mode: O-RAN M-Plane NETCONF
For O-RAN compliant deployments, use the NETCONF interface:
#include "radio/fhi_72/mplane/antenna-control-mplane.h"
#include "radio/fhi_72/mplane/ru-mplane-api.h"
// After establishing M-Plane connection to RU...
extern ru_session_t *ru_session; // From M-Plane init
// Check if RU supports antenna control
if (mplane_supports_trx_control(ru_session)) {
// Set TX antenna mask (0x0F = all 4 antennas active)
antenna_ctrl_result_t result = mplane_set_tx_antenna_mask(
ru_session,
"tx-array-0", // Array name from RU capabilities
0x0F, // Bitmask: bit N=1 means antenna N active
4 // Number of antennas
);
if (result != ANTENNA_CTRL_SUCCESS) {
LOG_E(PHY, "Failed to set TX mask: %s\n", antenna_ctrl_result_str(result));
}
}
Integrated with PHY Layer
#include "PHY/NR_TRANSPORT/nr_antenna_state.h"
#include "PHY/NR_TRANSPORT/nr_antenna_control.h"
// Initialize antenna state
nr_init_antenna_state(&gNB->antenna_state, 4, 4, "tx-array-0", "rx-array-0");
// Connect to M-Plane backend
nr_antenna_control_init_mplane(&gNB->antenna_state, ru_session);
// Changes via nr_set_tx_antenna_bitmask() will be synchronized to RU
nr_set_tx_antenna_bitmask(&gNB->antenna_state, 0x03); // Enable only antennas 0,1
nr_antenna_control_sync_to_ru(&gNB->antenna_state); // Push to RU via NETCONF
Development Mode: Test Socket Interface
For testing without NETCONF infrastructure:
#include "PHY/NR_TRANSPORT/nr_antenna_state.h"
#include "PHY/NR_TRANSPORT/nr_antenna_control.h"
// Initialize with 4 TX and 4 RX antennas
nr_init_antenna_state(&gNB->antenna_state, 4, 4, "tx-array-0", "rx-array-0");
// Start test socket server (NOT O-RAN compliant - logs warning)
nr_antenna_control_start_test_server(&gNB->antenna_state, 9999);
Warning: The test socket interface is for development only and is NOT O-RAN compliant.
Control Antennas via Test Interface
Connect with netcat:
nc localhost 9999
Commands:
> HELP # Show all commands
> STATUS # Show current antenna state
> MUTE TX 2 # Mute TX antenna 2
> MUTE TX 3 # Mute TX antenna 3
> SET TX MASK 03 # Set TX mask to 0x03 (antennas 0,1 active)
> SYNC # Sync to RU (M-Plane backend only)
> STATS # Show energy saving statistics
Use in Beamforming
// Original (all antennas active):
nr_beam_precoding(txdataF, txdataF_BF, fp, beam_weights, slot, symbol, aa, nb_ap, offset);
// With antenna muting support:
nr_beam_precoding_with_muting(txdataF, txdataF_BF, fp, beam_weights,
slot, symbol, aa, nb_ap, offset,
&gNB->antenna_state);
Building with M-Plane Support
To build with O-RAN M-Plane NETCONF support:
cd openairinterface5g/cmake_targets
./build_oai --ninja --gNB --nrUE -w ORAN_FH -t MPLANE
# Or manually:
cmake .. -DENABLE_ORAN_FH=ON -DORAN_FH_VARIANT=MPLANE
make -j$(nproc)
Dependencies for M-Plane:
- libnetconf2 >= 2.1.25
- libyang >= 2.1.4
- libssh
Testing with rfsimulator
Prerequisites
- Build OAI:
cd openairinterface5g/cmake_targets
./build_oai --ninja --gNB --nrUE -w SIMU
- Install Open5GS:
sudo add-apt-repository ppa:open5gs/latest
sudo apt update
sudo apt install open5gs
- Add subscriber to Open5GS (using mongosh):
mongosh open5gs --eval 'db.subscribers.insertOne({
imsi: "999700000000001",
security: { k: "fec86ba6eb707ed08905757b1bb44b8f", amf: "8000", opc: "C42449363BBAD02B66D16BC975D77CC1" },
slice: [{ sst: 1, default_indicator: true, session: [{ name: "internet", type: 3 }] }]
})'
Quick Test (Antenna Control Only)
The easiest way to verify the implementation is to start the gNB and test the control interface:
# Terminal 1: Start gNB
cd cmake_targets/ran_build/build
sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band78.fr1.106PRB.pci0.rfsim.conf --rfsim
# Terminal 2: Test antenna control
echo "STATUS" | nc -w 2 localhost 9999
echo "MUTE TX 0" | nc -w 2 localhost 9999
echo "STATUS" | nc -w 2 localhost 9999
echo "STATS" | nc -w 2 localhost 9999
Full Test with Open5GS
Terminal 1 - Core Network (should already be running):
# Verify Open5GS is running
systemctl status open5gs-amfd open5gs-upfd open5gs-smfd
Terminal 2 - gNB (with Open5GS-compatible config):
cd cmake_targets/ran_build/build
sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band78.2x2.rfsim.open5gs.conf --rfsim
Terminal 3 - UE:
cd cmake_targets/ran_build/build
sudo ./nr-uesoftmodem -r 106 --numerology 1 --band 78 -C 3319680000 \
--rfsim -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/ue.open5gs.conf
Terminal 4 - Antenna Control:
nc localhost 9999
> STATUS
> MUTE TX 1 # Mute antenna 1
> STATUS
> STATS
Terminal 5 - iperf (after UE attaches):
# Server on the UPF
iperf3 -s -B 10.45.0.1
# Client from UE (or use tun interface)
ping 10.45.0.1
iperf3 -c 10.45.0.1 -t 30
Using the Test Script
A convenience script is provided:
./targets/PROJECTS/GENERIC-NR-5GC/CONF/run_antenna_muting_test.sh gnb # Start gNB only
./targets/PROJECTS/GENERIC-NR-5GC/CONF/run_antenna_muting_test.sh mute # Test muting
./targets/PROJECTS/GENERIC-NR-5GC/CONF/run_antenna_muting_test.sh status # Check status
./targets/PROJECTS/GENERIC-NR-5GC/CONF/run_antenna_muting_test.sh --help # Show all options
Observing MIMO Layer Reduction
With 4x4 MIMO:
- All antennas active: Up to 4 layers possible
- 2 antennas muted: Max 2 layers
- 3 antennas muted: Max 1 layer
Throughput should decrease proportionally as antennas are muted.
API Reference
O-RAN M-Plane NETCONF API
// Set TX antenna mask via NETCONF
antenna_ctrl_result_t mplane_set_tx_antenna_mask(
ru_session_t *ru_session, // Active NETCONF session
const char *array_name, // O-RAN TX array name
uint8_t antenna_bitmask, // Bitmask (bit N=1 -> antenna N active)
uint8_t num_antennas // Number of antennas in array
);
// Set RX antenna mask via NETCONF
antenna_ctrl_result_t mplane_set_rx_antenna_mask(
ru_session_t *ru_session,
const char *array_name,
uint8_t antenna_bitmask,
uint8_t num_antennas
);
// Check if RU supports MPLANE-TRX-CONTROL feature
bool mplane_supports_trx_control(ru_session_t *ru_session);
// Result codes
typedef enum {
ANTENNA_CTRL_SUCCESS = 0,
ANTENNA_CTRL_ERR_NO_SESSION,
ANTENNA_CTRL_ERR_FEATURE_NOT_SUPPORTED,
ANTENNA_CTRL_ERR_INVALID_ARRAY_NAME,
ANTENNA_CTRL_ERR_INVALID_MASK,
ANTENNA_CTRL_ERR_NETCONF_FAILED,
ANTENNA_CTRL_ERR_VALIDATION_FAILED,
ANTENNA_CTRL_ERR_COMMIT_FAILED
} antenna_ctrl_result_t;
Unified Control Interface
// Initialize with O-RAN M-Plane NETCONF backend (production)
bool nr_antenna_control_init_mplane(nr_antenna_state_t *ant_state, void *ru_session);
// Start test socket server (development - NOT O-RAN compliant)
bool nr_antenna_control_start_test_server(nr_antenna_state_t *ant_state, int port);
// Sync local state to RU (M-Plane backend only)
bool nr_antenna_control_sync_to_ru(nr_antenna_state_t *ant_state);
// Get current backend type
nr_antenna_ctrl_backend_t nr_antenna_control_get_backend(void);
Future Work
O1 NETCONF Integration: Integrate with✅ DONEradio/fhi_72/mplane/for production O-RAN compliance- NETCONF Notifications: Subscribe to
mplane-trx-control-ant-mask-updatenotifications - rApp Development: Create Non-RT RIC rApp for policy-based antenna control
- A1 Policy Interface: Enable policy-based control from SMO
- Power Measurement: Add actual power consumption metrics (requires hardware)
References
- O-RAN WG4 M-Plane Specification (O-RAN.WG4.MP.0-v10.00)
o-ran-uplane-conf.yang- YANG model for U-plane configurationo-ran-wg4-features.yang- Feature definitions includingMPLANE-TRX-CONTROLradio/fhi_72/mplane/yang/models/- O-RAN YANG models in this repository