From 50e6cd44afccfe9bb0121f914e8224659aab3ee3 Mon Sep 17 00:00:00 2001 From: Robert Schmidt Date: Mon, 16 Feb 2026 17:53:03 +0100 Subject: [PATCH] Move instruction on how to configure UE to separate page Save space in the main tutorial, and group UE-specific configuration in one page. Add a reference where to find UE-related configuration information. --- doc/NR_SA_Tutorial_OAI_nrUE.md | 38 +++++---------- doc/runmodem-nrue.md | 87 ++++++++++++++++++++++++++-------- 2 files changed, 79 insertions(+), 46 deletions(-) diff --git a/doc/NR_SA_Tutorial_OAI_nrUE.md b/doc/NR_SA_Tutorial_OAI_nrUE.md index aa845965bc..4582b78ceb 100644 --- a/doc/NR_SA_Tutorial_OAI_nrUE.md +++ b/doc/NR_SA_Tutorial_OAI_nrUE.md @@ -179,39 +179,23 @@ uicc0 = { } ``` -| **Parameter** | **Description** | **Default Value** | -|---------------|-----------------|-------------------| -| **IMSI** | Unique identifier for the UE within the mobile network. Used by the network to identify the UE during authentication. It ensures that the UE is correctly identified by the network. | 001010000000001 | -| **key** | Cryptographic key shared between the UE and the network, used for encryption during the authentication process. | `fec86ba6eb707ed08905757b1bb44b8f` | -| **OPC** | Operator key for the Milenage Authentication and Key Agreement algorithm used for encryption during the authentication process. | Ensures secure communication between the UE and the network by matching the encryption keys. | `C42449363BBAD02B66D16BC975D77CC1` | -| **DNN** | _Deprecated_: Specifies the name of the data network the UE wishes to connect to, similar to an APN in 4G networks. | `oai` | -| **NSSAI** | _Deprecated_: Allows the UE to select the appropriate network slice, which provides different QoS. | `1` | -| **pdu_sessions** | list of PDU sessions to request | empty array (no PDU session) | +Further information about the meaning of these parameters is described in the +[dedicated nrUE configuration page](./runmodem-nrue.md). -Note that DNN and NSSAI parameters are deprecated, and `pdu_sessions` should be -used. If the `pdu_sessions` array is present, DNN and NSSAI are ignored. - -Each element within the `pdu_sessions` array takes the following parameters. -Multiple PDU sessions can be requested. - -| **Parameter** | **Description** | **Default Value** | -|---------------|-----------------|-------------------| -| `id` | ID of the PDU session to request | index of the current element (1..16) | -| `type` | Type of the PDU session to request (allowed: `IPv4`, `IPv6`, `IPv4v6`, `Ethernet` | `IPv4` | -| `dnn` | Specifies the name of the data network the UE wishes to connect to | `oai` | -| `nssai_sst` | Slice Service Type to request (1=eMBB, 2=URLLC, 3=mMTC) | `1` | -| `nssai_sd` | Slice Differentiator to request | `0xffffff` (meaning "no SD") | - -The UE configuration must match the one of the network's AMF. The nrUE can connect by default to OAI CN5G with no need to provide the configuration file. - -When running the `nr-uesoftmodem`, one can specify the nrUE configuration file using the `-O` option. E.g.: +The UE configuration must match the one of the network's AMF. When running the +`nr-uesoftmodem`, one can specify the nrUE configuration file using the `-O` +option. E.g.: ```bash sudo ./nr-uesoftmodem --rfsim --rfsimulator.[0].serveraddr 127.0.0.1 -r 106 --numerology 1 --band 78 -C 3619200000 -O ~/nrue.uicc.conf ``` -The CL option `--uicc0.imsi` can override the IMSI value in the configuration file if necessary (e.g. when running multiple UEs): `--uicc0.imsi 001010000000001`. -More details available at [ci-scripts/yaml_files/5g_rfsimulator/README.md](../ci-scripts/yaml_files/5g_rfsimulator/README.md). +The command line option `--uicc0.imsi` can override the IMSI value in the +configuration file if necessary (e.g. when running multiple UEs): `--uicc0.imsi +001010000000001`. + +More details can also be found at +[ci-scripts/yaml_files/5g_rfsimulator/README.md](../ci-scripts/yaml_files/5g_rfsimulator/README.md). **Note:** From tag `2024.w45`, OAI nrUE runs by default in standalone (SA) mode. In earlier versions the default mode was non-standalone (NSA). diff --git a/doc/runmodem-nrue.md b/doc/runmodem-nrue.md index f08c82ac69..636ce12888 100644 --- a/doc/runmodem-nrue.md +++ b/doc/runmodem-nrue.md @@ -34,7 +34,56 @@ With the **RFsimulator** (on the same machine), just add the option `--rfsim` to UE capabilities can be passed according to the [UE Capabilities](#UE-Capabilities) section. -A detailed tutorial is provided at this page [NR_SA_Tutorial_OAI_nrUE.md](./NR_SA_Tutorial_OAI_nrUE.md). +## Configuration file + +The UE can be provided a configuration file on the command line using `-O +`. At the very least, the configuration file should always contain +information on IMSI, key, and PDU session to use for the information: + +```shell +uicc0 = { + imsi = "001010000000001"; + key = "fec86ba6eb707ed08905757b1bb44b8f"; + opc = "C42449363BBAD02B66D16BC975D77CC1"; + pdu_sessions = ({ dnn = "oai"; nssai_sst = 1; }); +} +``` + +| **Parameter** | **Description** | **Default Value** | +|---------------|-----------------|-------------------| +| **IMSI** | Unique identifier for the UE within the mobile network. Used by the network to identify the UE during authentication. It ensures that the UE is correctly identified by the network. | 001010000000001 | +| **key** | Cryptographic key shared between the UE and the network, used for encryption during the authentication process. | `fec86ba6eb707ed08905757b1bb44b8f` | +| **OPC** | Operator key for the Milenage Authentication and Key Agreement algorithm used for encryption during the authentication process. | Ensures secure communication between the UE and the network by matching the encryption keys. | `C42449363BBAD02B66D16BC975D77CC1` | +| **DNN** | _Deprecated_: Specifies the name of the data network the UE wishes to connect to, similar to an APN in 4G networks. Use `pdu_sessions` instead. | `oai` | +| **NSSAI** | _Deprecated_: Allows the UE to select the appropriate network slice, which provides different QoS. Use `pdu_sessions` instead. | `1` | +| **pdu_sessions** | list of PDU sessions to request | empty array (no PDU session) | + +Note that DNN and NSSAI parameters are deprecated, and `pdu_sessions` should be +used. If the `pdu_sessions` array is present, DNN and NSSAI are ignored. + +Each element within the `pdu_sessions` array takes the following parameters. +Multiple PDU sessions can be requested. + +| **Parameter** | **Description** | **Default Value** | +|---------------|-----------------|-------------------| +| `id` | ID of the PDU session to request | index of the current element (1..16) | +| `type` | Type of the PDU session to request (allowed: `IPv4`, `IPv6`, `IPv4v6`, `Ethernet` | `IPv4` | +| `dnn` | Specifies the name of the data network the UE wishes to connect to | `oai` | +| `nssai_sst` | Slice Service Type to request (1=eMBB, 2=URLLC, 3=mMTC) | `1` | +| `nssai_sd` | Slice Differentiator to request | `0xffffff` (meaning "no SD") | + +For instance, to request two PDU sessions with user-defined IDs, you could +use. + +``` +uicc0 = { + # ... + pdu_sessions = ( + { id=1; dnn = "oai.ipv4"; type = "IPv4", nssai_sst = 1; }, + { id=2; dnn = "oai.ipv6"; type = "IPv6", nssai_sst = 1; }, + ); +} +``` ### Optional NR-UE command line options @@ -62,6 +111,24 @@ You can view all available options by typing: ./nr-uesoftmodem --help ``` +### UE Capabilities + +The `--uecap_file` option can be used to pass the UE Capabilities input file (path location + filename), e.g.`--uecap_file ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/uecap_ports1.xml` for 1 layer or e.g. `--uecap_file ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/uecap_ports2.xml` for 2 layers. + +This option is available for the following combinations of operation modes and gNB/nrUE softmodems: + +| Mode | Executable | Description | +|------------|----------------|-----------------------------------------------------| +| SA | nr-uesoftmodem | Send UE capabilities from the UE to the gNB via RRC | +| phy-test | nr-softmodem | Mimic the reception of UE capabilities by the gNB | +| do-ra | nr-softmodem | Mimic the reception of UE capabilities by the gNB | + +e.g. + +```shell +sudo ./nr-uesoftmodem -r 106 --numerology 1 --band 78 -C 3319680000 --ue-nb-ant-tx 2 --ue-nb-ant-rx 2 --uecap_file /opt/oai-nr-ue/etc/uecap.xml +``` + ## NR UE: Configure multiple RF-frontends (RUs) Multiple RF-frontends (also called RUs) can be defined for the nr-uesoftmodem. @@ -159,24 +226,6 @@ Current Limitations: - Each RU and cell can be used by only one UE (no RU sharing implemented, yet). - The sampling rates of all RUs must be the same. -### UE Capabilities - -The `--uecap_file` option can be used to pass the UE Capabilities input file (path location + filename), e.g.`--uecap_file ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/uecap_ports1.xml` for 1 layer or e.g. `--uecap_file ../../../targets/PROJECTS/GENERIC-NR-5GC/CONF/uecap_ports2.xml` for 2 layers. - -This option is available for the following combinations of operation modes and gNB/nrUE softmodems: - -| Mode | Executable | Description | -|------------|----------------|-----------------------------------------------------| -| SA | nr-uesoftmodem | Send UE capabilities from the UE to the gNB via RRC | -| phy-test | nr-softmodem | Mimic the reception of UE capabilities by the gNB | -| do-ra | nr-softmodem | Mimic the reception of UE capabilities by the gNB | - -e.g. - -```shell -sudo ./nr-uesoftmodem -r 106 --numerology 1 --band 78 -C 3319680000 --ue-nb-ant-tx 2 --ue-nb-ant-rx 2 --uecap_file /opt/oai-nr-ue/etc/uecap.xml -``` - ## Specific OAI modes ### phy-test setup with OAI UE