Skip to content

ntn-traffic

ntn-traffic is the spine of the ns3-ntn-toolkit: NtnRealStackHelper assembles a genuine 5G NR non-terrestrial cell, mmWave FR2 or 5G-LENA nr at FR1, under satellite mobility, so that every other module's decisions are taken against a radio that actually carries packets.

Why it matters. Most satellite network studies compute their key performance indicators from a closed form: slant range over the speed of light for latency, a Shannon bound for throughput, a threshold for loss. That is fast, and it makes the mechanism under study unfalsifiable, because the KPI cannot disagree with the model that produced it. ntn-traffic exists so it can disagree. Delay and jitter come from an in-band header carrying a sequence number and a transmit timestamp through the GTP tunnel; throughput comes from bytes that survived an LDPC decoder; loss comes from sequence gaps. If the physics is wrong, the numbers move.

What it simulates

  • A real NR cell under orbit. SpectrumPhy, LDPC error model, AMC with real MCS and rank selection, HARQ with an NTN-stretched process pool and the Release 17 n32 cap, RLC UM and AM, PDCP, RRC, and an EPC with GTP tunnelling, all under SGP4 or Walker satellite mobility.
  • Two interchangeable backends. The mmWave FR2 stack and the 5G-LENA nr FR1 stack, selectable per scenario, with the same helper API over both so a result can be checked against a different radio implementation.
  • TR 38.811 NTN physics. Excess path loss with the scenario shadow-fading sigma tables, elevation-interpolated, plus the satellite beam pattern, per-bandwidth-part loss chaining and power split, and a spectrum seam that composes with the base channel rather than replacing it.
  • Geometry that is not sampled once. Service-link delay, the one-way delay floor, K_offset and the X2 delay are taken over the worst case across every gNB and UE pair, not from index zero.
  • An honest link budget. Satellite EIRP is set either as a conducted power or as a TR 38.821 Set-1 density, never as a total EIRP fed into a conducted setter with array gain added on top, and a health gate fails in the negative direction if it drifts.
  • Provenance on every row. sim_health.csv labels each KPI measured, modeled or configured, so a reader can tell which numbers came off the wire.

Standards and references

  • 3GPP TR 38.811 - NTN channel model: shadow-fading sigma tables per scenario, Rician K-factor, aperture and beam geometry.
  • 3GPP TR 38.821 - Set-1 LEO-600 and GEO reference parameters, the link budget the calibration example is graded against.
  • 3GPP TS 38.101-5 - NTN FR1 bands n255 and n256 and their permitted channel bandwidths.
  • 3GPP TS 38.213 - K_offset and timing advance, applied as scheduler delay.
  • 3GPP TS 38.214 - CQI and MCS tables used by the AMC.
  • 3GPP TS 38.423 - Xn, whose delay is derived from inter-satellite geometry.
  • 3GPP TS 28.552 - the measurement names the exported KPI series use.

Use cases

  • Any experiment that needs a defensible KPI. If a paper claims a measured throughput or a measured one-way delay over a satellite link, this is the layer that makes the word "measured" mean something.
  • Backend cross-checks. Running the same scenario on the mmWave and nr spines and comparing, which catches results that depend on one PHY implementation's quirks.
  • Link-budget calibration. ntn-tr38821-calibration compares the assembled cell against the TR 38.821 Set-1 reference and reports the offset and the elevation slope separately, because a constant offset can be calibrated away and a wrong slope cannot.
  • Traffic modeling over NTN. Per-5QI flows with dedicated bearers and TFT filters, so QoS differentiation is visible in the radio rather than only in the labels.

Examples

Example What it shows
ntn-real-stack-smoke The minimal working cell: satellite mobility, one gNB, traffic, measured SINR and throughput
ntn-tr38821-calibration TR 38.821 Set-1 LEO-600 link-budget calibration with offset and slope gates
ntn-tr38821-array-gain-calibration The two-regime beam-pattern calibration, body-fixed against tracking
ntn-oran-qos-flows Four 5QI flows plus a control channel on one NR NTN cell

Getting it

ntn-traffic ships only inside the toolkit tree, because it is the spine the other modules build on rather than a separable capability.

docker run --rm -it uzairdocker69/ns3-ntn-toolkit:latest bash
./ns3 run ntn-real-stack-smoke

See the getting started guide for a source build.