Skip to content

ntn-fapi

ntn-fapi is the ns3-ntn-toolkit module that puts a Small Cell Forum FAPI MAC-PHY interface on a running NR non-terrestrial cell, so the L1 and L2 message flow a real base station uses can be studied under an orbital round trip.

Why it matters. FAPI is the boundary real hardware is split along, and it is where a functional-split decision for a satellite payload actually bites: whether the MAC sits on the spacecraft or on the ground changes which of these messages has to cross a slant link. Modeling the interface in simulation makes that a measurable question rather than an architectural preference.

What it simulates

  • A decorated live SAP. The bridge wraps the NR MAC-PHY service access point rather than running beside it, so SLOT.indication fires at the radio's own cadence and every DL_TTI.request comes from a real downlink allocation with the radio's own SFN and slot number.
  • The P7 slot-timing message set. DL_TTI.request, TX_DATA.request, RX_DATA.indication, CRC.indication and SLOT.indication, with the CRC outcome drawn from the measured transport block error rate rather than a configured constant.
  • Per-UE HARQ state. Keyed by frame, subframe, slot and RNTI, because keying by slot alone lets two terminals scheduled in the same slot overwrite each other's process state.
  • A latency figure with its qualification attached. The measured request-to-indication interval is a slot-pipeline turnaround, not an NR-NTN turnaround, because the backend the bridge decorates carries no propagation delay model. The bridge reports that qualification with the number, and the gate asserts the mean stays below the geometric floor of the configured link while propagation is absent, so the figure cannot silently acquire a delay its label does not admit.

Standards and references

  • Small Cell Forum FAPI 222.10.02 - the P5 configuration and P7 slot-timing message sets and their field semantics.
  • 3GPP TS 38.211 section 4.1 - frame and slot timing the messages carry.
  • 3GPP TS 38.213 - K_offset and timing advance, which are what an NTN split has to absorb.
  • 3GPP TR 38.821 - the NTN delay budget the latency gate is anchored to.

Use cases

  • Functional-split studies for satellite payloads. Which FAPI messages tolerate a slant link and which do not.
  • Slot-pipeline characterization. How the MAC-to-PHY turnaround behaves under NTN-stretched HARQ and relaxed timers.
  • Interface conformance. Exercising the SCF-222 ABI against a live scheduler rather than against a hand-assembled message stream.

Examples

Example What it shows
ntn-fapi-real-stack The bridge on a live mmWave NR NTN cell, with the measured SAP latency and its provenance
ntn-fapi-dl-data-slotloop Per-slot TX_DATA.request to CRC.indication with HARQ retransmission under a descending elevation
ntn-fapi-leo-pass-slotloop The same over a real SGP4 LEO pass from a two-line element

The cross-check that these are driven rather than free-running is in the output: TX_DATA.request equals the health record's phy_rx_tb exactly, which a self-scheduled loop could not do.

Getting it

ntn-fapi ships only inside the toolkit tree, because it decorates the NR SAP that ntn-traffic builds.

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

See the getting started guide for a source build.