How michele-segata/simu5g works
Simu5G is an OMNeT++/INET-based simulation library for LTE, NR, and MEC user-plane studies. The repo is organized more like a reusable protocol stack and scenario library than a single application: the core C++ modules live under src/, while simulations/, emulation/, showcases/, and tutorials/ provide ready-made network topologies and experiments.
The main architectural boundary is the protocol stack. From top to bottom, user traffic enters application modules in src/apps/ (VoIP, CBR, VoD, alerting, MEC-specific apps), then flows through packet-flow and bearer mapping in src/stack/packetFlowManager/ and src/stack/ip2nic/, then through PDCP/RRC, RLC, MAC, PHY, and finally into the radio/channel layer in src/world/radio/. This stack is implemented as a mix of C++ classes and NED compound/simple modules, with packet definitions in .msg files.
The radio access network is split by generation and node type. LTE/NR base station and UE NICs are defined in src/stack/ and src/nodes/NR/, with separate modules for eNodeB, gNodeB, UE, D2D-capable variants, carrier aggregation, dual connectivity, handover, and scheduling. A good diagram should show the stack as layered modules attached to node types rather than as one monolithic “network” block.
The physical and MAC layers are where most radio behavior is modeled. src/stack/phy/ includes realistic and dummy channel models, feedback generation, and air-frame packet handling. src/stack/mac/ includes HARQ buffers/processes, AMC, schedulers, allocation modules, conflict graph logic, and support for multiple numerologies and TDD/FDD. These subsystems feed each other tightly: PHY feedback influences AMC/scheduling, and MAC scheduling determines transport over PHY.
The medium and propagation model is centralized in src/world/radio/ and src/stack/phy/ChannelModel/. ChannelControl/LteChannelControl manage who can hear whom and route transmissions through the modeled radio world, while the channel model computes path loss, fading, shadowing, and interference. This is the main infrastructure boundary between simulated nodes and the shared wireless environment.
Core network behavior is intentionally lightweight and user-plane focused. src/corenetwork/gtp/ contains the PGW/UPF-side GTP user and serializers, while src/corenetwork/trafficFlowFilter/ handles traffic flow classification. The README makes clear that control plane and EPS bearer modeling are not implemented; “connections” are used instead, so diagrams should not include full LTE/5G control-plane signaling.
Inter-cell coordination is modeled through X2 and related stack managers. src/x2/ provides X2 application client/server roles and message serializers, while src/stack/hand overManager/, src/stack/dualConnectivityManager/, and src/stack/compManager/ implement handover, dual connectivity, and CoMP coordination logic. These modules form a lateral control path between base stations rather than a vertical packet path.
MEC is a major subsystem with its own internal platform. Under src/nodes/mec/ and src/apps/mec/, the repo defines a MEC orchestrator, virtualisation infrastructure manager, MEC platform, service registry, and services like RNI and location services. External or user apps communicate through HTTP-like messages, socket managers, and application descriptors, so a diagram should separate MEC host infrastructure from the simulated UE-side MEC apps.
There are multiple dedicated MEC application families. The code under src/apps/mec/, src/apps/mecRequestResponseApp/, and src/apps/mec/RealTimeVideoStreamingApp/ maps to the scenario folders in simulations/NR/mec/ and emulation/mec/. These scenarios show different deployment styles: single host, multi-host, multi-operator, request/response, RNIS tests, and external UE/MEC app execution.
Traffic generation and background load are explicit subsystems, not incidental test data. src/stack/backgroundTrafficGenerator/ and src/nodes/backgroundCell/ model additional cells and UE traffic generators, especially for NR/LTE background traffic experiments. The *_bgTraffic scenario folders and their trafficGeneratorConfigs/ inputs show that background load is a first-class input to network performance studies.
Mobility is partly externalized. src/mobility/trafficLightMobility/ supports vehicular/traffic-light mobility patterns, and the simulation trees under simulations/LTE/cars/ and simulations/NR/cars/ integrate with SUMO-style road network artifacts. This means vehicle movement is usually configured as an experiment input rather than hardcoded in the radio stack.
The repository’s executable content is almost entirely scenario-driven. simulations/ contains the testbeds for LTE and NR features such as standalone, dual connectivity, carrier aggregation, D2D, X2, handover, MEC, and video streaming. Each scenario bundles NED topology files, .ini configs, demo XML, and sometimes external trace files or generator configs, so a diagram should show scenarios as composition layers over the reusable library.
emulation/ mirrors some simulation features but integrates real external processes. The presence of run.sh, setup.sh, and teardown.sh in emulation examples indicates that these scenarios coordinate Simu5G with external clients/servers and host networking. This is an important boundary if you want to distinguish pure simulation from real-time emulation.
tests/fingerprint/ provides regression protection for model behavior. The CSV fingerprint baselines and fingerprinttest.py show that the project validates simulation output statistically rather than through unit tests alone. In an architecture diagram, this is best represented as a verification layer around the scenario library, not part of the runtime network path.
Build and documentation are standard but materially relevant. The project uses a top-level Makefile, OMNeT++ project metadata, and Sphinx documentation under doc/, with CI workflows for fingerprint tests and doc deployment. The repo therefore has three practical layers: reusable simulation library in src/, scenario/evidence assets in simulations/ and emulation/, and validation/documentation in tests/ and doc/.
Main entry points: nodes RAN nodes · NR NR sims · LTE LTE sims · packetFlowManager Flow map
Components 21
Reusable stack
Core protocol stack and reusable node models under src/
- Apps · VoIP, CBR, VoD, alerting, burst, and MEC user apps
src/apps - Flow map · Packet flow management and IP-to-NIC mapping
src/stack/packetFlowManager - PDCP/RRC · Connection state and PDCP/RRC entities for LTE and NR
src/stack/pdcp_rrc - RLC · AM/UM/TM entities, queues, and RLC PDUs
src/stack/rlc - MAC · HARQ buffers, AMC, schedulers, allocators, and conflict logic
src/stack/mac - PHY · PHY layers, feedback, and channel models
src/stack/phy - Radio world · Channel control and simulated wireless environment
src/world/radio - RAN nodes · LTE/NR node and NIC compound modules
src/nodes - X2 · X2 client/server roles and serializers for base-station coordination
src/x2 - Coordination · Handover, dual connectivity, and CoMP managers
src/stack/handoverManager - Core net · GTP user plane and traffic flow filtering
src/corenetwork - Background load · Background traffic generators and background cells
src/stack/backgroundTrafficGenerator - Mobility · Traffic-light mobility support
src/mobility/trafficLightMobility
MEC platform
MEC host, orchestrator, platform, and MEC apps
Scenarios
Simulation and showcase configurations built from the reusable library
Emulation
External-process integration examples
- Emulation · Real-process integration scenarios for ext client/server and MEC apps
emulation
Validation
Regression tests and documentation
- Fingerprints · Scenario output baselines and fingerprint test runner
tests/fingerprint - Docs · Sphinx documentation and guides
doc/src
Connections 33
- Apps → Flow map: injects traffic · Applications hand packets into the stack
- Flow map → PDCP/RRC: maps bearers · Flow and bearer mapping into radio bearers
- PDCP/RRC → RLC: hands down · PDCP/RRC data continues into RLC
- RLC → MAC: segments · RLC feeds MAC scheduling and transport
- MAC → PHY: schedules · MAC controls transmission over PHY
- PHY → Radio world: transmits · PHY uses the shared radio world and channel control
- RAN nodes → Apps: hosts · UE and base-station nodes embed application endpoints
- RAN nodes → Flow map: contains · Node NICs include packet-flow integration
- RAN nodes → PDCP/RRC: contains · Node NICs include PDCP/RRC layers
- RAN nodes → RLC: contains · Node NICs include RLC entities
- RAN nodes → MAC: contains · Node NICs include MAC layers
- RAN nodes → PHY: contains · Node NICs include PHY layers
- Radio world → PHY: feeds channel · Medium and channel control serve the PHY models
- X2 → Coordination: supports · X2 signaling carries inter-cell coordination
- Coordination → RAN nodes: coordinates · Handover, dual connectivity, and CoMP operate between base stations
- Core net → Flow map: terminates user plane · Core-network user-plane handling connects to bearer mapping
- Background load → NR sims: loads · Background traffic is configured by NR scenarios
- Background load → LTE sims: loads · Background traffic is also used by LTE experiments
- Mobility → LTE sims: drives · Vehicular mobility is configured by LTE car scenarios
- Mobility → NR sims: drives · Vehicular mobility is configured by NR car scenarios
- MEC host → MEC apps: hosts · MEC platform hosts and serves MEC applications
- MEC apps → Core net: uses HTTP/socket · MEC applications communicate through user-plane style messaging
- LTE sims → RAN nodes: assembles · LTE scenarios compose reusable nodes and stack modules
- NR sims → RAN nodes: assembles · NR scenarios compose reusable nodes and stack modules
- NR sims → MEC host: assembles · NR MEC scenarios add MEC infrastructure and apps
- Showcases → NR sims: documents · Showcases provide curated NR example compositions
- Emulation → MEC apps: integrates · Emulation examples couple Simu5G with external MEC apps
- Emulation → Core net: integrates · Emulation examples couple Simu5G with external client/server processes
- Fingerprints → LTE sims: validates · Fingerprint baselines cover LTE scenarios
- Fingerprints → NR sims: validates · Fingerprint baselines cover NR scenarios
- Docs → LTE sims: describes · Documentation covers LTE scenarios and usage
- Docs → NR sims: describes · Documentation covers NR scenarios and usage
- Docs → MEC host: describes · Documentation covers MEC architecture and usage