Add README.md for the nr-ue-nas-simulator

2026-03-20 16:35:08 +05:30
parent ac2749022b
commit 03ba636b04
2 changed files with 88 additions and 0 deletions
@@ -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.
@@ -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.