Models a User Equipment (UE) in a 4G LTE network. It is a host equipped with an LTE Network Interface Card (NIC), allowing the UE to connect to an eNodeB module via the Radio Access Network (RAN) of the LTE network and communicate with any other host in the system. The UE is an INET StandardHost with the cellular NIC as an additional network interface of its link layer, so it has all the higher layers of the protocol stack, from the link layer to the application modules, and the configuration options of StandardHost (numApps, hasUdp, hasTcp, hasIpv4, hasIpv6, numEthInterfaces, etc.). Its Ethernet interfaces (eth[]) are utilized in real-time emulation mode to connect the UE to the real network (outside the simulator) via a virtual Ethernet interface.

The cellular interface comes after lo0 and the eth[] interfaces in the interface table. An address given as the UE's name (e.g. "ue[0]") resolves to the first non-loopback interface that has an address, so to an eth[] interface's address if one has an IP address; to get the address of the cellular interface, name it: "ue[0]%cellular".

The UE has one session, whose type it requests when it registers with the core network (the PDU session type of the PDU Session Establishment Request in a 5G core, the PDN type in an EPC): the sessionType parameter. The network establishes the session with that type, or rejects it with an error if its core network cannot carry it. The IP types ("IPv4", "IPv6", "IPv4v6") are carried by both core networks; "Unstructured" and "Ethernet" need a 5G core.

An Unstructured session carries opaque payload, from an application attached to the NIC directly (an UnstructuredApp in the unstructuredApp submodule vector, see numUnstructuredApps) to the server the anchor UPF's N6 end of the session is configured with (see UserPlaneNodeControl). The session has one QoS flow, the default one, on one bearer, the default DRB; it is not supported on a D2D-capable UE (hasD2D). Such a UE normally has no IP layer (hasIpv4 = false).

An Ethernet session carries Ethernet frames between the UE and the anchor UPF's Ethernet bridge (see EthernetSessionBridge), which switches them among the UPF's Ethernet sessions and its N6 Ethernet LAN; the frames cross the session without their FCS (TS 23.501 5.6.10.2). The UE's link layer is then that of an INET Ethernet node (EthernetLayer, Ieee8021qProtocol), whose Ethernet ports are the cellular NIC and the eth[] interfaces. With ethernetMode = "host", the UE is an Ethernet host: raw Ethernet applications (e.g. INET's EthernetSourceApp and EthernetSinkApp) send and receive with the NIC's MAC address. With ethernetMode = "bridge", the UE bridges (BridgingLayer) the NIC and its eth[] interfaces, whose ethg[] gates connect the devices behind it (numEthInterfaces). The QoS rules classify a frame by its headers (e.g. its 802.1Q priority); a dscpAsQfi rule does not apply to a frame. The session is not supported on a D2D-capable UE (hasD2D), and not with ROHC. Such a UE normally has no IP layer (hasIpv4 = false): nothing configures IP over the session automatically.

Usage diagram

The following diagram shows usage relationships between types. Unresolved types are missing from the diagram.

Inheritance diagram

The following diagram shows inheritance relationships for this type. Unresolved types are missing from the diagram.

Used in

Name	Type	Description
MultiCell	network	Two eNodeB cells on a shared EPC PgwStandard, joined by an X2 link, with a router and a server behind the core. Four LteUe terminals are placed two per cell, and numExtCells ExtCell cells can be added as interferers. With hasD2D, the network holds the D2dBinder that D2D-capable nodes need, so that '**.hasD2D = true' turns D2D on in the network and in all its nodes.
MultiCell_D2DMultihop	network	Five eNodeB cells, each reaching the EPC PgwStandard through a router of its own, with a further router and a server behind the core. There are no X2 links. numUe1 to numUe5 LteUe terminals attach per cell, and an EventGenerator and a MultihopD2DStatistics module sit beside them, wired to nothing.
MultiCell_X2Mesh	network	Three eNodeB cells in a full X2 mesh. Each reaches the EPC PgwStandard through a router of its own, and the server sits directly on the PgwStandard's data-network gate. numUe1, numUe2 and numUe3 LteUe terminals attach per cell, and numExtCells ExtCell cells can be added as interferers.
SingleCell	network	The minimal LTE topology: one eNodeB connected to an EPC PgwStandard, which faces a router and a server, plus numUe LteUe terminals.
SingleCell_D2D	network	SingleCell with its UEs split into three vectors, so that a configuration can address cellular terminals (ueCell), D2D transmitters (ueD2DTx) and D2D receivers (ueD2DRx) separately. The rest of the topology is the same: one eNodeB on an EPC PgwStandard, with a router and a server behind it.
SingleCell_D2DMulticast	network	SingleCell with its UEs split into cellular terminals (ueCell) and members of a D2D multicast group (ueD2D). The rest of the topology is the same: one eNodeB on an EPC PgwStandard, with a router and a server behind it.

Known subclasses

Name	Type	Description
LteCar	compound module	Defines a LteCar node as a LTE User Equipment (UE) with vehicular-like mobility. This behavior is modeled by utilizing the Veins-Inet project.
NrUe	compound module	Models a User Equipment (UE) for a 5G/LTE network. It extends the LteUe module by implementing a NrNicUe as a Network Interface Card (NIC) module. This module can be used to model a device that can connect to either a 4G eNodeB or a 5G gNodeB, or both.

Extends

Name	Type	Description
StandardHost	compound module	A comprehensive model of an IPv4/IPv6 host that provides a complete network stack with configurable application, transport, network, and link layers. It supports multiple network interfaces, protocols, and applications that can be customized through parameters.

Parameters

Name	Type	Default value	Description
displayStringTextFormat	string	""	Determines the text that is written on top of the submodule, supports displaying pars, watches, and module-specific information
hasStatus	bool	false
hasEnvironment	bool	false
osgModel	string	""	3D model for OSG visualization, no 3D model by default
osgModelColor	string	""	Tint color, no colorization by default
canvasImage	string	""	Image for canvas visualization, no image by default
canvasImageColor	string	""	Tint color, no colorization by default
recordPcap	bool	false
numPcapRecorders	int	recordPcap ? 1 : 0
numLoInterfaces	int	1
numWlanInterfaces	int	0
numEthInterfaces	int	0	Minimum number of Ethernet interfaces
numPppInterfaces	int	0	Minimum number of PPP interfaces
numTunInterfaces	int	0
numVirtInterfaces	int	0
fcsMode	string	"declared"
hasIpv4	bool	true
hasIpv6	bool	false
hasGn	bool	false
forwarding	bool	false
multicastForwarding	bool	false
hasUdp	bool	firstAvailableOrEmpty("Udp") != ""
hasTcp	bool	firstAvailableOrEmpty("Tcp", "TcpLwip", "TcpNsc") != ""
hasSctp	bool	false
hasQuic	bool	false
numApps	int	0
numUnstructuredApps	int	0
nodeType	string	"UE"
servingNodeId	int	0	The initial serving eNodeB of the UE; 0 if none
macNodeId	int	1025+simu5g_seq("LteUe_macNodeId")
sessionType	string	"IPv4"	The type of the session the UE requests (see the main comment)
ethernetMode	string	"host"	Ethernet sessions only: the UE is an Ethernet host, or a bridge for the devices on its eth[] interfaces (see the main comment)
hasEthernetSession	bool	sessionType == "Ethernet"	Do not change: whether the UE has the Ethernet link layer (see the main comment)
hasD2D	bool	false
extHostAddress	string	""
hasRniSupport	bool	false

Properties

Name	Value	Description
class	NodeBase
networkNode
labels	node
display	i=device/pocketpc

Gates

Name	Direction	Size	Description
radioIn [ ]	input	numWlanInterfaces
pppg [ ]	inout	numPppInterfaces
ethg [ ]	inout	numEthInterfaces
lteRadioIn	input		Connection to master

Unassigned submodule parameters

Name	Type	Default value	Description
status.displayStringTextFormat	string	"{stateStr}"	Determines the text that is written on top of the submodule, supports displaying pars, watches, and module-specific information
status.initialStatus	string	"UP"	TODO @signal, @statistic
environment.displayStringTextFormat	string	""	Determines the text that is written on top of the submodule, supports displaying pars, watches, and module-specific information
environment.initStage	int	0	Initialization stage for the setup command
environment.globalNamespace	bool	false	Create new network namespaces under /var/run/netns/ (Linux only)
environment.namespace	string	""	Name of the host OS network namespace (optional) (Linux only)
environment.setupCommand	string	""	A host OS system command
environment.teardownCommand	string	""	A host OS system command
pcapRecorder.displayStringTextFormat	string	"rec: %n pks"	Determines the text that is written on top of the submodule, supports displaying pars, watches, and module-specific information
pcapRecorder.verbose	bool	true	Whether to log packets on the module output
pcapRecorder.recordEmptyPackets	bool	true	Specifies if zero length packets are recorded or not
pcapRecorder.enableConvertingPackets	bool	true	Specifies if converting packets to link type is allowed or not
pcapRecorder.pcapFile	string	""	The PCAP file to be written, suggested value: pcapFile = "${resultdir}/${configname}-#${runnumber}" + fullpath() + ".pcap"
pcapRecorder.fileFormat	string	"pcapng"
pcapRecorder.snaplen	int	65535	Maximum number of bytes to record per packet
pcapRecorder.timePrecision	int	6	Time precision in recorded file. pcap supports only 6 (usec) or 9 (nanosec), pcapng supports more values (see 'if_tsresol' option in pcapng file format).
pcapRecorder.dumpBadFrames	bool	true	Enable dump of frames with hasBitError
pcapRecorder.moduleNamePatterns	string	"wlan[*] eth[*] ppp[*]"	Space-separated list of sibling module names to listen on
pcapRecorder.sendingSignalNames	string	"transmissionEnded"	Space-separated list of outbound packet signals to subscribe to
pcapRecorder.receivingSignalNames	string	"receptionEnded"	Space-separated list of inbound packet signals to subscribe to
pcapRecorder.dumpProtocols	string	"ethernetmac ppp ieee80211mac"	Space-separated list of protocol names as defined in the Protocol class
pcapRecorder.packetFilter	object	"*"	Which packets are considered, matches all packets by default
pcapRecorder.helpers	string	""	Usable PcapRecorder::IHelper helpers for accept packettype and store/convert packet as specified linktype currently available: "inet::AckingMacToEthernetPcapRecorderHelper"
pcapRecorder.alwaysFlush	bool	false	Flush the pcapFile after each write to ensure that all packets are captured in case of a crash
interfaceTable.displayStringTextFormat	string	"{numInterfaces} interfaces"	Determines the text that is written on top of the submodule, supports displaying pars, watches, and module-specific information
interfaceTable.displayAddresses	bool	false	Whether to display IP addresses on links
cb.displayStringTextFormat	string	"processed {numProcessedPackets} pk ({processedTotalLength})"	Determines the text that is written on top of the submodule, supports displaying pars, watches, and module-specific information
cb.interfaceTableModule	string		Module path to the InterfaceTable module
cb.forwardServiceRegistration	bool	true
cb.forwardProtocolRegistration	bool	true
cb.interfaceMapping	object	{}	Maps network interface names to connected submodule names (e.g. {"eth0": "bridging"}), overrides automatically learned dispatching; * overrides all learned network interfaces, ? overrides default
cb.serviceMapping	object	{}	Maps protocols to connected submodule names (e.g. {"ethernetmac": "bridging"}), overrides automatically learned dispatching; * overrides all learned services, ? overrides default
cb.protocolMapping	object	{}	Maps protocols to connected submodule names (e.g. {"ipv4": "bridging"}), overrides automatically learned dispatching; * overrides all learned protocols, ? overrides default
bl.displayStringTextFormat	string	"processed {numProcessedPackets} pk ({processedTotalLength})"	Determines the text that is written on top of the submodule, supports displaying pars, watches, and module-specific information
bl.interfaceTableModule	string		Module path to the InterfaceTable module
bl.forwardServiceRegistration	bool	true
bl.forwardProtocolRegistration	bool	true
bl.interfaceMapping	object	{}	Maps network interface names to connected submodule names (e.g. {"eth0": "bridging"}), overrides automatically learned dispatching; * overrides all learned network interfaces, ? overrides default
bl.serviceMapping	object	{}	Maps protocols to connected submodule names (e.g. {"ethernetmac": "bridging"}), overrides automatically learned dispatching; * overrides all learned services, ? overrides default
bl.protocolMapping	object	{}	Maps protocols to connected submodule names (e.g. {"ipv4": "bridging"}), overrides automatically learned dispatching; * overrides all learned protocols, ? overrides default
li.displayStringTextFormat	string	"processed {numProcessedPackets} pk ({processedTotalLength})"	Determines the text that is written on top of the submodule, supports displaying pars, watches, and module-specific information
li.interfaceTableModule	string		Module path to the InterfaceTable module
li.forwardServiceRegistration	bool	true
li.forwardProtocolRegistration	bool	true
li.interfaceMapping	object	{}	Maps network interface names to connected submodule names (e.g. {"eth0": "bridging"}), overrides automatically learned dispatching; * overrides all learned network interfaces, ? overrides default
li.serviceMapping	object	{}	Maps protocols to connected submodule names (e.g. {"ethernetmac": "bridging"}), overrides automatically learned dispatching; * overrides all learned services, ? overrides default
li.protocolMapping	object	{}	Maps protocols to connected submodule names (e.g. {"ipv4": "bridging"}), overrides automatically learned dispatching; * overrides all learned protocols, ? overrides default
eth.bitrate	double
nl.displayStringTextFormat	string	"processed {numProcessedPackets} pk ({processedTotalLength})"	Determines the text that is written on top of the submodule, supports displaying pars, watches, and module-specific information
nl.interfaceTableModule	string		Module path to the InterfaceTable module
nl.forwardServiceRegistration	bool	true
nl.forwardProtocolRegistration	bool	true
nl.interfaceMapping	object	{}	Maps network interface names to connected submodule names (e.g. {"eth0": "bridging"}), overrides automatically learned dispatching; * overrides all learned network interfaces, ? overrides default
nl.serviceMapping	object	{}	Maps protocols to connected submodule names (e.g. {"ethernetmac": "bridging"}), overrides automatically learned dispatching; * overrides all learned services, ? overrides default
nl.protocolMapping	object	{}	Maps protocols to connected submodule names (e.g. {"ipv4": "bridging"}), overrides automatically learned dispatching; * overrides all learned protocols, ? overrides default
tn.displayStringTextFormat	string	"processed {numProcessedPackets} pk ({processedTotalLength})"	Determines the text that is written on top of the submodule, supports displaying pars, watches, and module-specific information
tn.interfaceTableModule	string		Module path to the InterfaceTable module
tn.forwardServiceRegistration	bool	true
tn.forwardProtocolRegistration	bool	true
tn.interfaceMapping	object	{}	Maps network interface names to connected submodule names (e.g. {"eth0": "bridging"}), overrides automatically learned dispatching; * overrides all learned network interfaces, ? overrides default
tn.serviceMapping	object	{}	Maps protocols to connected submodule names (e.g. {"ethernetmac": "bridging"}), overrides automatically learned dispatching; * overrides all learned services, ? overrides default
tn.protocolMapping	object	{}	Maps protocols to connected submodule names (e.g. {"ipv4": "bridging"}), overrides automatically learned dispatching; * overrides all learned protocols, ? overrides default
at.displayStringTextFormat	string	"processed {numProcessedPackets} pk ({processedTotalLength})"	Determines the text that is written on top of the submodule, supports displaying pars, watches, and module-specific information
at.interfaceTableModule	string		Module path to the InterfaceTable module
at.forwardServiceRegistration	bool	true
at.forwardProtocolRegistration	bool	true
at.interfaceMapping	object	{}	Maps network interface names to connected submodule names (e.g. {"eth0": "bridging"}), overrides automatically learned dispatching; * overrides all learned network interfaces, ? overrides default
at.serviceMapping	object	{}	Maps protocols to connected submodule names (e.g. {"ethernetmac": "bridging"}), overrides automatically learned dispatching; * overrides all learned services, ? overrides default
at.protocolMapping	object	{}	Maps protocols to connected submodule names (e.g. {"ipv4": "bridging"}), overrides automatically learned dispatching; * overrides all learned protocols, ? overrides default
macTable.agingTime	double
macTable.forwardingTableFile	string

Source code

//
// Models a User Equipment (UE) in a 4G LTE network. It is a host equipped with
// an LTE Network Interface Card (NIC), allowing the UE to connect to an ~eNodeB module via the
// Radio Access Network (RAN) of the LTE network and communicate with any other host in the system.
// The UE is an INET ~StandardHost with the cellular NIC as an additional network
// interface of its link layer, so it has all the higher layers of the protocol stack,
// from the link layer to the application modules, and the configuration options of
// ~StandardHost (numApps, hasUdp, hasTcp, hasIpv4, hasIpv6, numEthInterfaces, etc.).
// Its Ethernet interfaces (eth[]) are utilized in real-time emulation mode to connect
// the UE to the real network (outside the simulator) via a virtual Ethernet interface.
//
// The cellular interface comes after lo0 and the eth[] interfaces in the interface
// table. An address given as the UE's name (e.g. "ue[0]") resolves to the first
// non-loopback interface that has an address, so to an eth[] interface's address
// if one has an IP address; to get the address of the cellular interface, name it:
// "ue[0]%cellular".
//
// The UE has one session, whose type it requests when it registers with the core
// network (the PDU session type of the PDU Session Establishment Request in a 5G
// core, the PDN type in an EPC): the sessionType parameter. The network establishes
// the session with that type, or rejects it with an error if its core network cannot
// carry it. The IP types ("IPv4", "IPv6", "IPv4v6") are carried by both core
// networks; "Unstructured" and "Ethernet" need a 5G core.
//
// An Unstructured session carries opaque payload, from an application attached to
// the NIC directly (an ~UnstructuredApp in the unstructuredApp submodule vector, see
// numUnstructuredApps) to the server the anchor UPF's N6 end of the session is
// configured with (see ~UserPlaneNodeControl). The session has one QoS flow, the
// default one, on one bearer, the default DRB; it is not supported on a D2D-capable
// UE (hasD2D). Such a UE normally has no IP layer (hasIpv4 = false).
//
// An Ethernet session carries Ethernet frames between the UE and the anchor UPF's
// Ethernet bridge (see ~EthernetSessionBridge), which switches them among the UPF's Ethernet
// sessions and its N6 Ethernet LAN; the frames cross the session without their FCS
// (TS 23.501 5.6.10.2). The UE's link layer is then that of an INET Ethernet node
// (EthernetLayer, Ieee8021qProtocol), whose Ethernet ports are the cellular NIC and the
// eth[] interfaces. With ethernetMode = "host", the UE is an Ethernet host: raw Ethernet
// applications (e.g. INET's EthernetSourceApp and EthernetSinkApp) send and receive with
// the NIC's MAC address. With ethernetMode = "bridge", the UE bridges (BridgingLayer)
// the NIC and its eth[] interfaces, whose ethg[] gates connect the devices behind it
// (numEthInterfaces). The QoS rules classify a frame by its headers (e.g. its 802.1Q
// priority); a dscpAsQfi rule does not apply to a frame. The session is not supported
// on a D2D-capable UE (hasD2D), and not with ROHC. Such a UE normally has no IP layer
// (hasIpv4 = false): nothing configures IP over the session automatically.
//
module LteUe extends StandardHost
{
    parameters:
        @display("i=device/pocketpc");

        //# Apps
        int numUnstructuredApps = default(0);  // Number of apps attached to the cellular NIC directly (0 or 1), for a UE whose session is of type Unstructured

        //# Node specs
        string nodeType = "UE";  // DO NOT CHANGE
        int servingNodeId = default(0); // The initial serving eNodeB of the UE; 0 if none
        int macNodeId = default(1025+simu5g_seq("LteUe_macNodeId"));
        string sessionType @enum("IPv4","IPv6","IPv4v6","Ethernet","Unstructured") = default("IPv4");  // The type of the session the UE requests (see the main comment)
        string ethernetMode @enum("host","bridge") = default("host");  // Ethernet sessions only: the UE is an Ethernet host, or a bridge for the devices on its eth[] interfaces (see the main comment)
        bool hasEthernetSession = sessionType == "Ethernet";  // Do not change: whether the UE has the Ethernet link layer (see the main comment)

        //# D2D support: selects the D2D-capable NIC variant (see the cellularNic submodule).
        //# An explicit cellularNic.typename in the ini file still overrides this.
        bool hasD2D = default(false);

        //# External Ethernet interfaces
        string extHostAddress = default("");

        bool hasRniSupport = default(false);
        cellularNic.mac.collectorModule = hasRniSupport ? "^.^.ueCollector" : "";
        cellularNic.rrc.connectionControl.hasCollector = hasRniSupport;

        mobility.typename = default("StationaryMobility");

        //# the link layer of an Ethernet session; otherwise only the eth[] interfaces of
        //# emulation mode have a link-layer protocol (EthernetEncapsulation)
        ethernet.typename = default(hasEthernetSession ? "EthernetLayer" : sizeof(ethg) > 0 ? "EthernetEncapsulation" : "");
        ethernet.hasSocketSupport = default(true);
        ethernet.*.promiscuous = default(ethernetMode == "bridge");
        ieee8021q.typename = default(hasEthernetSession ? "Ieee8021qProtocol" : "");
        bridging.typename = default(hasEthernetSession && ethernetMode == "bridge" ? "BridgingLayer" : "");
        bridging.macTableModule = default(absPath(".macTable"));
        eth[*].typename = default(hasEthernetSession ? "LayeredEthernetInterface" : "ExtLowerEthernetInterface");

    gates:
        input lteRadioIn @directIn;     // Connection to master

    submodules:
        cellularNic: <default(hasD2D ? "LteNicUeD2D" : "LteNicUe")> like IUeCellularNic {
            nodeType = parent.nodeType;
            sessionType = parent.sessionType;
            @display("p=600,975");
        }
        macTable: <default("MacForwardingTable")> like IMacForwardingTable if hasEthernetSession && ethernetMode == "bridge" {
            @display("p=125,880;is=s");
        }
        unstructuredApp[numUnstructuredApps]: <default("UnstructuredApp")> like IApp {
            @display("p=1125,75,row,150");
        }

        //# UeStatsCollector - for MEC
        ueCollector: UeStatsCollector if hasRniSupport {
            @display("p=125,960;is=s");
        }

    connections allowunconnected:
        // the payload of an Unstructured session goes to and from the NIC with no
        // transport or network layer in between
        for i=0..numUnstructuredApps-1 {
            unstructuredApp[i].socketOut --> nl.in++;
            unstructuredApp[i].socketIn <-- nl.out++;
        }

        cellularNic.upperLayerOut --> li.in++;
        cellularNic.upperLayerIn <-- li.out++;

        //#
        //# Connections between LTE/NR NIC and the radio medium
        //#
        cellularNic.radioIn <-- lteRadioIn;
}

File: src/simu5g/nodes/LteUe.ned

---

This documentation is released under the Creative Commons license