From 03ba636b04289b83b14d59a4b11b080b6a8add6d Mon Sep 17 00:00:00 2001 From: Rakesh Mundlamuri Date: Mon, 9 Mar 2026 14:17:21 +0530 Subject: [PATCH] Add README.md for the nr-ue-nas-simulator --- doc/README.md | 1 + tests/nr-ue-nas-simulator/README.md | 87 +++++++++++++++++++++++++++++ 2 files changed, 88 insertions(+) create mode 100644 tests/nr-ue-nas-simulator/README.md diff --git a/doc/README.md b/doc/README.md index 13a9669f76..745fc700a7 100644 --- a/doc/README.md +++ b/doc/README.md @@ -124,6 +124,7 @@ The other SDRs (AW2S, LimeSDR, ...) have no READMEs. - Component tests are under `tests/`. Currently, the following component tests are supported - A simple CU-UP tester, see the corresponding [README.md](../tests/nr-cuup/README.md). - A CU-NRPPA tester, see the corresponding [README.md](../tests/nr-cu-nrppa/README.md). + - A UE NAS tester, see the corresponding [README.md](../tests/nr-ue-nas-simulator/README.md). - [TESTBenches.md](./TESTBenches.md) lists the CI setup and links to pipelines - The CI setup uses a [custom framework](../ci-scripts/README.md) to run end-to-end tests. diff --git a/tests/nr-ue-nas-simulator/README.md b/tests/nr-ue-nas-simulator/README.md new file mode 100644 index 0000000000..b1af0e1e21 --- /dev/null +++ b/tests/nr-ue-nas-simulator/README.md @@ -0,0 +1,87 @@ +This is a simple standalone tester for 5G UE NAS signaling and NGAP messages. It connects to the AMF to perform NGAP and NAS encoding/decoding and validates the UE Registration and PDU Session Establishment processes without the overhead of a full Radio Access Network (PHY/MAC/RLC). + +[[_TOC_]] + +# Motivation +- This tester is a lightweight, deterministic tool to **test the UE NAS layer directly**. +- Developers can easily inject specific NAS messages depending on the use-case. +- Developers can validate custom NAS/NGAP messages without the need to implement complete RRC/MAC etc procedures. + +# Overview +From a schematic point of view, the tester and Core Network interaction looks like this: +``` + +-------+ + | AMF | + +-------+ + | + NGAP/NAS | (N1/N2) + | + +-------+ + |tester | (nr-ue-nas-simulator-test) + +-------+ + +``` + +The tester is designed to validate the integration of NAS and NGAP messages required for a 5G Standalone (SA) UE to attach to the network. It acts as a simulated gNB and a UE, bridging NAS messages directly into NGAP payloads and connecting to the 5G Core Network's AMF. + +The following messages are integrated and tested: + +* **NGAP:** NG Setup Request/Response, Initial UE Message, Downlink NAS Transport, Uplink NAS Transport, Initial Context Setup Request/Response, PDU Session Resource Setup Request/Response, UE Context Release Command/Complete. + +* **NAS (5GMM/5GSM):** Registration Request/Accept/Complete, Authentication Request/Response, Security Mode Command/Complete, PDU Session Establishment Request/Accept, Deregistration Request/Accept. + +* **RRC (Custom):** Forwards the uplink/downlink NAS messages directly between UE and AMF. + +A test scenario is fixed to these steps: +1. The 5G Core Network is deployed via Docker. +2. The tester connects to the AMF and establishes the NGAP connection (NG Setup). +3. The tester automatically triggers an Initial UE Registration Request. +4. Authentication and NAS Security Mode procedures are completed. +5. The tester requests and successfully establishes an IPv4 PDU Session. +6. The tester finally initiates deregistration request and exits succesfully. + +# Usage +To run this test, you need to set up the Core Network and build the tester. + +**1. Core Network Deployment** + +Pull the required Docker images for the OAI 5G Core: + + docker pull oaisoftwarealliance/ims:latest + docker pull oaisoftwarealliance/oai-amf:develop + docker pull oaisoftwarealliance/oai-nrf:develop + docker pull oaisoftwarealliance/oai-smf:develop + docker pull oaisoftwarealliance/oai-udr:develop + docker pull oaisoftwarealliance/oai-upf:develop + docker pull oaisoftwarealliance/oai-udm:develop + docker pull oaisoftwarealliance/oai-ausf:develop + +Deploy the network using the docker compose file: + + cd doc/tutorial_resources/oai-cn5g + docker compose -f docker-compose.yaml up -d + +At the end of all experiments, you can also undeploy the network with: + docker compose -f docker-compose.yaml down -t 0 + +**2. Building the Tester** + +You can build the tester as follows: + + cd ~/openairinterface5g + mkdir build && cd build && cmake .. -GNinja && ninja nr-ue-nas-simulator-test + +**3. Running the Tester** + +Start the tester with the dedicated configuration file: + + openairinterface5g/build$ LD_LIBRARY_PATH=. ./tests/nr-ue-nas-simulator/nr-ue-nas-simulator-test -O ../tests/nr-ue-nas-simulator/test.conf + +# Limitations +- The tester is limited to a fixed flow: Initial Attach -> PDU Session -> Deregistration. +- The tester doesnt create a GTP tunnel after PDU session and uses a harcoded teid. + +# Future Enhancements +- A real GTP tunnel can be created to test various data related functionalities like QoS. +- Simulate the actual UE RRC layer, i.e., forwarding the CellGroupConfig, have the UE apply that (without actually using it). +- Make it scriptable to test custom message implementations.