Add O-RAN compliant antenna muting for energy saving
Implements MPLANE-TRX-CONTROL feature from O-RAN WG4: - nr_antenna_state: TX/RX antenna bitmask management - nr_antenna_control: TCP control interface on port 9999 - Integrated into nr_feptx (TX) and nr_fep (RX) paths - Blanks transmission/reception for muted antennas Commands: MUTE TX/RX <id>, UNMUTE TX/RX <id>, STATUS, STATS
This commit is contained in:
@@ -0,0 +1,213 @@
|
||||
# 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 │
|
||||
│ ┌─────────────────┐ ┌─────────────────┐ ┌─────────────────────┐ │
|
||||
│ │ O1 (NETCONF) │ │ Test Socket │ │ Future: rApp/A1 │ │
|
||||
│ │ (Production) │ │ (Development) │ │ (Policy-based) │ │
|
||||
│ └────────┬────────┘ └────────┬────────┘ └─────────┬───────────┘ │
|
||||
│ │ │ │ │
|
||||
│ └────────────────────┼─────────────────────┘ │
|
||||
│ ▼ │
|
||||
│ ┌──────────────────────────────────────────────────────────────┐ │
|
||||
│ │ 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` |
|
||||
| `antenna-bitmask` parameter | `nr_antenna_state_t.tx_antenna_bitmask` |
|
||||
| `MPLANE-TRX-CONTROL` feature | `nr_set_tx_antenna_bitmask()` |
|
||||
| Transmission blanking | Zeroing `txdataF_BF` for muted antennas |
|
||||
|
||||
## Files
|
||||
|
||||
- `openair1/PHY/NR_TRANSPORT/nr_antenna_state.h` - Antenna state API
|
||||
- `openair1/PHY/NR_TRANSPORT/nr_antenna_state.c` - Implementation
|
||||
- `openair1/PHY/NR_TRANSPORT/nr_antenna_control.h` - Test control interface
|
||||
- `openair1/PHY/NR_TRANSPORT/nr_antenna_control.c` - Socket server for testing
|
||||
- `openair1/PHY/MODULATION/beamforming.c` - Modified with `nr_beam_precoding_with_muting()`
|
||||
|
||||
## Usage
|
||||
|
||||
### 1. Initialize Antenna State (in gNB init)
|
||||
|
||||
```c
|
||||
#include "PHY/NR_TRANSPORT/nr_antenna_state.h"
|
||||
|
||||
// Initialize with 4 TX and 4 RX antennas
|
||||
nr_init_antenna_state(&gNB->antenna_state, 4, 4, "tx-array-0", "rx-array-0");
|
||||
|
||||
// Optionally start test control server
|
||||
#include "PHY/NR_TRANSPORT/nr_antenna_control.h"
|
||||
nr_antenna_control_start(&gNB->antenna_state, 9999);
|
||||
```
|
||||
|
||||
### 2. Control Antennas via Test Interface
|
||||
|
||||
Connect with netcat:
|
||||
```bash
|
||||
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)
|
||||
> STATS # Show energy saving statistics
|
||||
```
|
||||
|
||||
### 3. Use in Beamforming
|
||||
|
||||
```c
|
||||
// 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);
|
||||
```
|
||||
|
||||
## Testing with rfsimulator
|
||||
|
||||
### Prerequisites
|
||||
|
||||
1. Build OAI:
|
||||
```bash
|
||||
cd openairinterface5g/cmake_targets
|
||||
./build_oai --ninja --gNB --nrUE -w SIMU
|
||||
```
|
||||
|
||||
2. Install Open5GS:
|
||||
```bash
|
||||
sudo add-apt-repository ppa:open5gs/latest
|
||||
sudo apt update
|
||||
sudo apt install open5gs
|
||||
```
|
||||
|
||||
3. Add subscriber to Open5GS (using mongosh):
|
||||
```bash
|
||||
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:
|
||||
|
||||
```bash
|
||||
# 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):
|
||||
```bash
|
||||
# Verify Open5GS is running
|
||||
systemctl status open5gs-amfd open5gs-upfd open5gs-smfd
|
||||
```
|
||||
|
||||
Terminal 2 - gNB (with Open5GS-compatible config):
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
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:
|
||||
```bash
|
||||
nc localhost 9999
|
||||
> STATUS
|
||||
> MUTE TX 1 # Mute antenna 1
|
||||
> STATUS
|
||||
> STATS
|
||||
```
|
||||
|
||||
Terminal 5 - iperf (after UE attaches):
|
||||
```bash
|
||||
# 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:
|
||||
```bash
|
||||
./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.
|
||||
|
||||
## Future Work
|
||||
|
||||
1. **O1 NETCONF Integration**: Integrate with `radio/fhi_72/mplane/` for production O-RAN compliance
|
||||
2. **rApp Development**: Create Non-RT RIC rApp for policy-based antenna control
|
||||
3. **A1 Policy Interface**: Enable policy-based control from SMO
|
||||
4. **Power Measurement**: Add actual power consumption metrics (requires hardware)
|
||||
|
||||
## References
|
||||
|
||||
- O-RAN WG4 M-Plane Specification
|
||||
- `o-ran-uplane-conf.yang` - YANG model for U-plane configuration
|
||||
- `o-ran-wg4-features.yang` - Feature definitions including `MPLANE-TRX-CONTROL`
|
||||
|
||||
Reference in New Issue
Block a user