Architecture Overview¶

FLoRaSat is built on top of OMNeT++ and the INET framework. It models LEO satellite IoT networks, where low-power terminals on the ground communicate with satellites that relay data to ground stations.

Project Structure¶

florasat/
├── src/                          # C++ implementation
│   ├── Global/                   # Shared framework modules
│   │   ├── Antenna/              # Custom antenna pattern loader
│   │   ├── Base/                 # Abstract base classes (MAC, routing)
│   │   ├── Channel/              # Link budget and propagation models
│   │   ├── Constellation_Creator/ # Satellite generation from Walker orbits
│   │   ├── Medium/               # Radio medium (CustomMedium)
│   │   ├── Messages/             # Message and tag definitions (.msg files)
│   │   ├── Mobility/             # NORAD interface (INorad)
│   │   ├── Statistics/           # Packet recording and statistics
│   │   ├── Topology_Control/     # ISL and ground-link management
│   │   ├── Transceiver/          # LoRa and custom Tx/Rx modules
│   │   └── Utilities/            # CSV reader, routing core, libnorad
│   └── Nodes/                    # Node implementations
│       ├── _10_Terminal/         # IoT terminal (4-layer stack)
│       ├── _20_Satellite/        # LEO satellite (4-layer stack + ISL/GSL/DSL)
│       ├── _30_Station/          # Ground station
│       └── _40_Server/           # Reserved, not in use
│
├── simulations/                  # Scenario definitions
│   ├── Custom_default/           # Default scenario template
│   └── Tutorials/                # Step-by-step tutorial scenarios
│       ├── 01-First_Exploration/
│       ├── 02-First_Constellation/
│       ├── 03-Blind_Optimization/
│       └── 04-Capacity/
│
└── simulation_analysis/          # Jupyter notebooks for result processing

Key File Types¶

Extension	Role
`.ned`	Defines module structure and connections (network topology)
`.ini`	Sets parameter values for a simulation run
`.cc` / `.h`	C++ implementation of each module
`.msg`	Message and packet type definitions (auto-generates `.cc`/`.h`)

Node Types¶

FLoRaSat has three active node types. Each uses the same four-layer OSI-inspired stack.

┌────────────────────────────┐
│  Application Layer (40)    │  Packet generation / data collection
├────────────────────────────┤
│  Network Layer (30)        │  Routing
├────────────────────────────┤
│  Data Link Layer (20)      │  MAC scheduling
├────────────────────────────┤
│  Physical Layer (10)       │  Radio, antenna, transceiver
└────────────────────────────┘

The number prefix in source paths (e.g., _10_Physical, _30_Network) reflects this ordering.

Terminal (`src/Nodes/_10_Terminal/`)¶

An IoT device on the ground. It generates uplink packets and transmits them to any satellite currently in view. The terminal has a single radio interface (phy) and uses the KiWan MAC protocol (dlk).

Parameter prefix: *.terminal[*].*

Satellite (`src/Nodes/_20_Satellite/`)¶

A LEO satellite acting as a relay. It has three separate radio interfaces:

Interface	Module path	Purpose
DSL	`.satellite[].phyDSL`	Device-to-Satellite Link — receives from terminals
GSL	`.satellite[].phyGSL`	Ground Station Link — connects to ground stations
ISL	`.satellite[].phyISL`	Inter-Satellite Link — connects to neighboring satellites

Each satellite carries a NORAD module (NoradModule) that computes its orbital position from TLE parameters using the SGP4/SDP4 propagator.

The network layer can run one of two routing strategies:

StoreAndForward — stores packets when isolated, forwards them as soon as a ground station link is established
DDRARouting — Dijkstra-based multi-hop routing across ISLs, with congestion feedback

Station (`src/Nodes/_30_Station/`)¶

A fixed ground station. It collects end-to-end statistics (delivery ratio, latency) for packets relayed through satellites. It does not generate traffic.

Global Modules¶

These modules run once per simulation and coordinate the entire network.

ConstellationCreator (`src/Global/Constellation_Creator/`)¶

Generates the satellite constellation at simulation startup from Walker orbit parameters: number of planes, satellites per plane, inclination, altitude, inter-plane spacing (F), and RAAN spread. It supports both Walker Star (180° RAAN spread) and Walker Delta (360° RAAN spread) configurations.

When using real TLE data instead of a generated constellation, orbital parameters are set directly on each satellite's NoradModule via the .ini file.

Sat_Mob_Orchestrator (`src/Nodes/_20_Satellite/_60_Mobility/`)¶

A centralized module that triggers position updates for all satellites at each time step. Without it, each satellite would schedule its own self-message, which does not scale well for large constellations.

Sat_Mob_SatelliteMobility + INorad (`src/Nodes/_20_Satellite/_60_Mobility/`, `src/Global/Mobility/`)¶

INorad is the interface to the orbital propagator. Sat_Mob_NoradA implements it using the SGP4/SDP4 algorithm (via libnorad) to compute latitude, longitude, and altitude from RAAN, mean anomaly, inclination, eccentricity, and altitude. Sat_Mob_SatelliteMobility translates these geodetic coordinates into an INET Coord position used by the radio medium.

ConstellationTopologyControl (`src/Global/Topology_Control/`)¶

Runs on a configurable updateInterval and manages all dynamic links:

Intra-plane ISLs — links between satellites in the same orbital plane
Inter-plane ISLs — links between satellites in adjacent planes (disabled near the poles by default)
Satellite-to-ground-station links — established when a satellite's elevation above a ground station exceeds minimumElevation
Satellite-to-terminal visibility — updates which terminals are in view of which satellites (used by the MAC layer)

It also computes the cost matrix used by DDRARouting.

CustomMedium / CustomPHYAnalogModel (`src/Global/Medium/`, `src/Global/Channel/`)¶

CustomMedium extends INET's radio medium to support the elevation-based visibility filter: a terminal-to-satellite link is only possible if the satellite is above minimumElevationTermSat degrees.

CustomPHYAnalogModel computes the received signal power using a configurable link budget model:

Free-space path loss with adjustable exponent
Transmit antenna pattern gain
Receive antenna gain (polynomial in elevation: a·elev² + b·elev + c)
Obstruction loss, Doppler effects (optional)

CustomPHYPathLoss adds margin terms on top: polarization loss, fading sigma, receiver system loss, implementation loss, and noise figure enhancement.

CustomReceiver / CustomTransmitter (`src/Global/Transceiver/`)¶

CustomReceiver determines whether a received frame is successfully decoded. It evaluates C/N₀ against a configurable threshold or a CSV-based lookup table (C/N₀ vs. packet error rate under load). It can also model inter-frequency collisions using a normalized-load model.

CustomTransmitter generates transmissions with configurable center frequency, bandwidth, and preamble duration.

The LoRa-specific equivalents (LoRaReceiver, LoRaTransmitter, LoRaAnalogModel) implement the LoRa spreading-factor orthogonality matrix and sensitivity curves for terrestrial LoRa scenarios.

KiWan MAC — `Ter_Dlk_KiWan` (`src/Nodes/_10_Terminal/_20_Data_Link/`)¶

The primary MAC protocol used by terminals. It divides a transmission time window (ttwDuration) into Ntx equal slots. For each packet, the terminal transmits once per slot at a random time within [ttxStart_min, ttxStart_max]. Multiple packets can be scheduled concurrently using numConcurrentTx independent servers.

Two transmission policies:

Blind mode — transmit regardless of satellite visibility. Simple, predictable energy consumption.

Satellite detection mode (enableSatDetect = true) — before transmitting in a slot, the terminal listens for a satellite beacon. If detected (with probability satelliteDetectionProbability), it transmits. Otherwise it skips the slot. A fallback mechanism can automatically switch between detection and blind mode based on recent success rate.

Simulation Scenario Layout¶

Each scenario folder follows the same structure:

simulations/MyScenario/
├── MyScenario.ini             # Top-level ini: includes sub-files, sets network
├── configurations/
│   ├── Scenarios.ini          # Concrete [Config ...] blocks (extend abstract ones)
│   ├── BlindTx.ini            # Abstract MAC configs for blind transmission
│   ├── SatDetect.ini          # Abstract MAC configs for satellite detection
│   ├── BandSelection.ini      # Frequency/bandwidth settings
│   ├── Constellations.ini     # Which constellation to use
│   ├── DevicePositionning.ini # Terminal deployment (lat/lon, radius)
│   ├── Services.ini           # Packet generation rates
│   ├── SimulationLength.ini   # sim-time-limit
│   └── StatisticRecording.ini # What vectors/scalars to record
├── constellations/            # Constellation-specific ini files (NORAD params)
├── devices/                   # Terminal deployment configurations
├── stations/                  # Ground station ini files
└── results/                   # Output directory (must exist)

Concrete scenarios are assembled by extends-ing multiple abstract configurations:

[Config MyRun]
extends = TenDevices, BlindKineis, ServiceEveryHour, UHF, ConstellationIridium

This compositional approach allows parameter sweeps across many independent dimensions without repetition.

Communication Flow¶

Terminal                 Satellite (DSL)          Station
   │                         │                       │
   │── uplink frame ────────►│                       │
   │   (KiWan MAC slot)      │── ground link ──────► │
   │                         │   (when GS in view)   │
   │                         │                       │
   │                         │◄──────────────────────│             
   │◄─────────────────────── │                       │

The terminal's application layer generates a packet at a configurable interval.
The KiWan MAC schedules transmission slots within the time window.
The CustomPHYAnalogModel computes received power; CustomPHYPathLoss applies margin terms.
CustomReceiver on the satellite decides if the packet is decoded successfully.
The satellite's network layer (StoreAndForward or DDRARouting) forwards the packet to a ground station when one is visible.
The station's network layer collects end-to-end statistics.

Architecture Overview¶

Project Structure¶

Key File Types¶

Node Types¶

Terminal (src/Nodes/_10_Terminal/)¶

Satellite (src/Nodes/_20_Satellite/)¶

Station (src/Nodes/_30_Station/)¶

Global Modules¶

ConstellationCreator (src/Global/Constellation_Creator/)¶

Sat_Mob_Orchestrator (src/Nodes/_20_Satellite/_60_Mobility/)¶

Sat_Mob_SatelliteMobility + INorad (src/Nodes/_20_Satellite/_60_Mobility/, src/Global/Mobility/)¶

ConstellationTopologyControl (src/Global/Topology_Control/)¶

CustomMedium / CustomPHYAnalogModel (src/Global/Medium/, src/Global/Channel/)¶

CustomReceiver / CustomTransmitter (src/Global/Transceiver/)¶

KiWan MAC — Ter_Dlk_KiWan (src/Nodes/_10_Terminal/_20_Data_Link/)¶