maki/openairinterface5g
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Merge remote-tracking branch 'origin/n2-handover' into integration_2025_w38 (!3334)

Browse Source 
N2 handover

This MR introduces full support for N2 handover, covering handover
decision, preparation, execution, and notification between source and
target NG-RAN nodes.

Key features:

1. Handover Decision & Preparation:
  - Implement N2 handover decision based on UE measurement reports.
  - Generate the Handover Preparation Information message, including
    RRCReconfiguration.
  - Send Handover Required message from the source NG-RAN to the AMF.
2. Handover Execution:
  - Decode and handle the Handover Request on the target NG-RAN.
  - Process the Handover Command on the source gNB, triggering
    RRCReconfiguration.
  - Initiate Handover Notify after successful completion.
3 NGAP & RRC Enhancements:
  - Implement NGAP encoding/decoding functions for Handover Required,
    Handover Request, Handover Command, Handover Failure, and Handover
    Notify (3GPP TS 38.413).
  - Adds NG-RAN Status Transfer support (UL/DL) for PDCP COUNT
    preservation during mobility:
    - support for NGAP Uplink and Downlink RAN Status Transfer messages
      (TS 38.413 §9.2.3.13-14) to enable proper PDCP COUNT value
      transfer during handover or recovery: NGAP encoding/decoding for
      RAN Status Transfer, PDCP helpers to extract and apply COUNT (HFN
      + SN) per DRB. This aligns with TS 38.300 §9.2.3.2.1 and TS 23.502
      §4.9.1.3.3, ensuring PDCP status preservation in AM.
4. Testing:
  - Introduce a Telnet command to manually trigger N2 handover using UE
    ID and neighbor PCI.
  - Add configuration file for testing N2 handover with a target gNB.
This commit is contained in:
Robert Schmidt
2025-09-18 11:57:44 +02:00
parent ef5191b610 f9f6e96d6b
commit 7227cfb320
52 changed files with 4922 additions and 286 deletions
Download Patch File Download Diff File Expand all files Collapse all files
doc/RRC/rrc-dev.md
+91 -2
View File
@@ -210,7 +210,7 @@ sequenceDiagram
end
```
## Handover
## Inter-DU Handover (F1)
The basic handover (HO) structure is as follows. In order to support various
handover "message passing implementation" (F1AP, NGAP, XnAP), RRC employs
@@ -264,6 +264,94 @@ sequenceDiagram
sdu->>cucp: F1AP UE Context Release Complete
Note over ue,tdu: UE active on target DU
```
## Inter-gNB Handover (N2)
This is an inter-NG-RAN procedure. The N2 handover specification is defined in the following documents:
* 3GPP TS 23.502, 4.9.1.3 Inter NG-RAN node N2 based handover:
- Outlines detailed handover signaling flows for N2-based handovers.
- Covers both intra-system (between 5G gNBs) and inter-system (between 5G and LTE eNBs) handovers.
* 3GPP TS 38.300, section 9 Mobility and State Transitions:
- describes mobility procedures at the NG-RAN level, depending on the RRC state.
* 3GPP TS 38.413 (NGAP), section 8.4 UE Mobility Management Procedures:
- Specifies the signaling procedures over the N2 interface.
- Includes messages like Handover Request, Handover Command, and Handover Preparation.
* 3GPP TS 38.331 (RRC): details the UE-level RRC procedures involved during handovers
### End-to-end flow
```mermaid
sequenceDiagram
participant ue as UE
participant sdu as source DU
participant scucp as source CU-CP
participant scuup as source CU-UP
participant tdu as target DU
participant tcucp as target CU-CP
participant tcuup as target CU-UP
participant amf as AMF
Note over ue,sdu: UE active on source DU
alt HO triggered through A3 event
ue->>sdu: RRC Measurement Report
sdu->>scucp: F1AP UL RRC Msg Transfer (RRC Measurement Report)
Note over scucp: Handover decision (A3 event trigger)
else Manual Trigger
Note over scucp: Handover decision (e.g., telnet)
end
Note over scucp: nr_rrc_trigger_n2_ho() ("on source CU")
scucp->>amf: HANDOVER REQUIRED
amf->>tcucp: HANDOVER REQUEST
Note over tcucp: rrc_gNB_process_Handover_Request
Note over tcucp: trigger_bearer_setup
tcucp->>tcuup: Bearer Context Setup Request
tcuup->>tcucp: Bearer Context Setup Response
Note over tcucp: rrc_gNB_process_e1_bearer_context_setup_resp
Note over tcucp: nr_rrc_trigger_n2_ho_target() ("on target CU")
Note over tcucp: nr_initiate_handover()
tcucp->>tdu: F1AP UE Context Setup Req
Note over tdu: Create UE context
tdu->>tcucp: F1AP UE Context Setup Resp (incl. CellGroupConfig)
Note over tcucp: rrc_CU_process_ue_context_setup_response() ("on target CU")
Note over tcucp: e1_send_bearer_updates()
tcucp->>tcuup: E1AP Bearer Context Modification Req
tcuup->>tcucp: E1AP Bearer Context Modification Resp
tcucp-->>tcucp: callback: ho_req_ack()
Note over tcucp: nr_rrc_n2_ho_acknowledge() ("on target CU")
tcucp->>amf: HANDOVER REQUEST ACKNOWLEDGE (data forwarding info)
amf->>scucp: HANDOVER COMMAND
scucp->>sdu: F1AP UE Context Modification Req (RRC Reconfiguration)
sdu->>ue: RRC Reconfiguration
sdu->>scucp: F1AP UE Context Modification Resp
Note over sdu: Stop scheduling UE
Note over scucp: rrc_CU_process_ue_context_modification_response()
Note over scucp: e1_send_bearer_updates()
scucp->>scuup: E1 Bearer Context Modification Req (PDCP Status Request)
scuup->>scucp: E1 Bearer Context Modification Resp (PDCP Status Info)
scucp->>amf: NG Uplink RAN Status Transfer
amf->>tcucp: NG Downlink RAN Status Transfer
tcucp->>tcuup: E1 Bearer Context Modification Req (PDCP Status Info)
tcuup->>tcucp: E1 Bearer Context Modification Resp
Note over ue: UE attachment to target DU
Note over ue,tdu: RA (Msg1 + Msg2)
ue->>tdu: RRC Reconfiguration Complete
tdu->>tcucp: F1AP UL RRC Msg Transfer (RRC Reconfiguration Complete)
tcucp-->>tcucp: callback: ho_success()
Note over tcucp: nr_rrc_n2_ho_complete() ("on target CU")
Note over tcucp: handle_rrcReconfigurationComplete() ("on target CU")
tcucp->>amf: HANDOVER NOTIFY
amf->>scucp: UE Context Release Command
note over scucp: ngap_gNB_handle_ue_context_release_command
note over scucp: rrc_gNB_process_NGAP_UE_CONTEXT_RELEASE_COMMAND
scucp->>scuup: E1 Bearer Context Release Command
scuup->>scucp: E1 Bearer Context Release Complete
Note over scucp: rrc_gNB_generate_RRCRelease
scucp->>sdu: F1 UE Context Release Command
sdu->>scucp: F1 UE Context Release Complete
note over scucp: rrc_CU_process_ue_context_release_complete
note over scucp: rrc_remove_ue
Note over ue,tdu: UE active on target DU
```
# Structures
@@ -308,7 +396,8 @@ corresponding CU.
`nr_ho_source_cu_t` contains notably a function pointer `ho_cancel` for
handover cancel. `nr_ho_target_cu_t` contains function pointers `ho_req_ack`
for handover request acknowledge and `ho_success` for handover success. As can
for handover request acknowledge, `ho_success` for handover success,
`ho_failure` for handover failure (N2 only).
be seen in the sequence diagram above, either the "target CU" or "source CU"
needs to do an operation, and a "switch" from target to source CU is done using
these function pointers. For instance, in F1, the handover request acknowledge
doc/RRC/rrc-usage.md
+21 -1
View File
@@ -99,6 +99,26 @@ the [MAC configuration](../MAC/mac-usage.md) as well for SIB configuration.
### Neighbor-gNB configuration
TBD
#### What is a gNB neighbor?
Network continuity is a key aspect of 5G. In the 5G architecture, gNB neighbors play a central role in maintaining service continuity through mechanisms such as handover and load balancing. By definition, a gNB neighbor is another gNB that can be measured and linked by the UE. If the current serving gNB is no longer optimal, the UE may connect to a neighbor gNB.
To support this behavior, the network configuration specifies additional frequencies and cells that the UE should measure. The UE reports these measurements to the network, which then decides whether or not to initiate a handover.
Neighbor types include:
- **Intra-gNB neighbors** - cells belonging to the same gNB
- **Inter-gNB neighbors** - cells belonging to different gNBs
- **Inter-RAT neighbors** - cells belonging to another RAT (e.g., LTE)
#### Required configuration parameters
To define a neighbor cell in the configuration file, the following parameters are typically needed:
- **gNB ID** - unique identifier of the gNB
- **Cell ID** - identifier of the cell within the gNB
- **Physical Cell ID** - identifier of the cell’s synchronization signal (PCI)
- **Absolute Frequency** - frequency used by the SSB (absoluteFrequencySSB)
- **Subcarrier Spacing** - numerology (e.g., 15 kHz, 30 kHz)
- **PLMN configuration** - MCC, MNC, and MNC length
- **Tracking Area Code (TAC)** - identifier of the tracking area
Refer to the [handover tutorial](../handover-tutorial.md) for more information.
doc/handover-tutorial.md
+146
View File
@@ -207,6 +207,7 @@ neighbour_list = (
physical_cellId = 1;
absoluteFrequencySSB = 643296;
subcarrierSpacing = 1; #30 KHz
band = 78;
plmn = { mcc = 001; mnc = 01; mnc_length = 2};
tracking_area_code = 1;
}
@@ -221,6 +222,7 @@ neighbour_list = (
physical_cellId = 0;
absoluteFrequencySSB = 643296;
subcarrierSpacing = 1; #30 KHz
band = 78;
plmn = { mcc = 001; mnc = 01; mnc_length = 2};
tracking_area_code = 1;
}
@@ -340,3 +342,147 @@ while true; do
sleep 15
done
```
# N2 Handover
## Run the setup
An N2 handover involves the transfer of a UE from one gNB to another via the 5G core network. Unlike F1 handover, where the CU handles the process internally between its DUs, N2 handover requires signaling through the AMF, making it a core-network-based handover.
We assume:
* Two independent gNBs connected to the same 5GC via N2 interface.
* A UE initially connected to gNB-PCI0, which will be handed over to gNB-PCI1.
* Handover is triggered by either by decision based measurement event (e.g. A3) or telnet command.
## Steps to run N2 handover with OAI UE
1. Similarly to F1 handover, UE does not support any measurement reporting and handover is triggered by
telnet command. Therefore, ensure that both gNBs and UE are built with telnet support:
```sh
./build_oai --ninja --nrUE --gNB --build-lib telnetsrv
```
Run the 5G Core Network if not already running. See [OAI CN5G tutorial](./NR_SA_Tutorial_OAI_CN5G.md).
2. Start the source gNB (gNB-PCI0) e.g.
```sh
sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band78.fr1.106PRB.pci0.rfsim.conf --telnetsrv --telnetsrv.shrmod ci --gNBs.[0].min_rxtxtime 6 --rfsim --rfsimulator.serveraddr 127.0.0.1
```
3. Start the UE e.g.
```sh
sudo ./nr-uesoftmodem -r 106 --numerology 1 --band 78 -C 3619200000 --rfsim --uicc0.imsi 001010000000001 -O ../../../ci-scripts/conf_files/nrue.uicc.conf --rfsimulator.serveraddr server
```
Ensure the UE successfully registers with the network.
4. Start the target gNB (gNB PCI1) e.g.
```sh
sudo ./nr-softmodem -O ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/gnb.sa.band78.fr1.106PRB.pci1.rfsim.conf --sa --rfsim --telnetsrv --telnetsrv.shrmod ci --gNBs.[0].min_rxtxtime 6 --rfsimulator.serveraddr 127.0.0.1
```
5. Trigger the N2 handover, e.g.
From gNB-PCI0, trigger handover on target gNB with PCI 1 for UE ID 1:
```sh
echo ci trigger_n2_ho 1,1 | nc 127.0.0.1 9090 && echo
```
where the input parameters correspond to the PCI of the neighbor call and the RRC ID of the UE.
This will initiate the N2 handover on the source gNB.
## Neighbour list and measurement configuration
Make sure the configuration file contains a neighbour list and measurement configuration, e.g. [neighbour-config-rfsim.conf](../../ci-scripts/conf_files/neighbour-config.conf). This configuration can also be present in a different file and included in the gNB configuration file with `@include "neighbour-config-rfsim.conf"`.
For each gNB there is a `neighbour_cell_configuration` linked to its serving cell ID.
The measurement configuration is based on A2 and A3 measurement events in 5G NR. These events are used by the UE to report radio conditions to the gNB. The A2 Measurement Event indicates that the serving cell’s signal quality has degraded below a defined threshold and the UE shall initiate measurement of neighboring cells. The A3 Measurement Event indicates that a neighboring cell’s signal quality is better than that of the serving cell by a certain offset and the UE shall trigger handover to a stronger neighboring cell
This is an example with comments on how to use the configuration file:
```
############################################################
# gNB-to-gNB neighbour list + measurement configuration #
# for the 2-cell rfsim setup (gNB_ID 0xe00 & 0xb00) #
############################################################
neighbour_list = (
##########################################################
# Entry USED BY gNB_ID = 0xe00 (nr_cellid = 12345678L) #
##########################################################
{
nr_cellid = 12345678L; # Serving cell of gNB 0xe00
neighbour_cell_configuration = (
{
gNB_ID = 0xb00;
nr_cellid = 720898; # Cell served by gNB 0xb00
physical_cellId = 1;
absoluteFrequencySSB= 621312;
subcarrierSpacing = 1; # 30 kHz
band = 78;
plmn = { mcc = 208; mnc = 99; mnc_length = 2 };
tracking_area_code = 1;
}
);
},
##########################################################
# Entry USED BY gNB_ID = 0xb00 (nr_cellid = 720898) #
##########################################################
{
nr_cellid = 720898; # Serving cell of gNB 0xb00
neighbour_cell_configuration = (
{
gNB_ID = 0xe00;
nr_cellid = 12345678L; # Cell served by gNB 0xe00
physical_cellId = 0;
absoluteFrequencySSB= 641280;
subcarrierSpacing = 1; # 30 kHz
band = 78;
plmn = { mcc = 208; mnc = 99; mnc_length = 2 };
tracking_area_code = 1;
}
);
}
);
############################################################
# Common NR measurement-event configuration #
############################################################
nr_measurement_configuration = {
Periodical = {
enable = 1;
includeBeamMeasurements = 1;
maxNrofRS_IndexesToReport = 4;
};
A2 = {
enable = 1;
threshold = 60;
timeToTrigger = 1;
};
A3 = (
{
cell_id = 720898; # neighbour of gNB 0xe00
offset = 10;
hysteresis = 0;
timeToTrigger = 1;
},
{
cell_id = 12345678; # neighbour of gNB 0xb00
offset = 5;
hysteresis = 1;
timeToTrigger = 2;
}
);
};
```