DVB-S2 Downlink ACI (`downlink_aci`)

Transmit IP network traffic over a DVB-S2 RF link using FPGA-based encoding.

Description

downlink_aci bridges a Linux TUN virtual network interface to a DVB-S2 RF transmitter. IP packets arriving on the TUN interface are encapsulated using Generic Stream Encapsulation (GSE, ETSI TS 102 606), packed into DVB-S2 Baseband (BB) frames, and streamed to the on-board FPGA DVB-S2 encoder via the OpenCPI Application Control Interface (ACI).

The application uses a two-thread architecture:

TUN reader thread — reads IP packets from the TUN device, fragments them into GSE packets sized to fit the BB frame data field, and pushes complete BB frames onto a bounded queue.
Main thread — blocks on getOutputBuffer until the FPGA encoder has a free DMA buffer, then dequeues and sends the next BB frame. If the queue is empty (no IP traffic), a pre-built GSE null-packet padding frame is sent instead to keep the encoder fed.

The FPGA application (downlink_aci.xml) connects:

The external bbframe_input port to the dvbs2_encoder worker input.
The dvbs2_encoder output to the Digital Radio Controller (DRC) TX port.

Default DVB-S2 parameters (compile-time constants in downlink_aci.cc):

Parameter	Value
Frame type	Long frame (FECFRAME = 64 800 bits)
Constellation	QPSK
Code rate	9/10
Pilots	Disabled
MATYPE1	`0x72` (GSE mode, roll-off 0.20)
BB frame size	7153 bytes (derived from DVB-S2 ETSI EN 302 307 tables)

DRC TX configuration (downlink_aci.xml):

Parameter	Value
Center frequency	400.0 MHz
Bandwidth	20 MHz
Sample rate	4.0 MSPS
Gain	−50 dB (manual)

Hardware Portability

This application is designed to run on the following platforms:

Hardware	RCC Platform	HDL Platform
ADALM-PLUTOSDR	`adi_plutosdr0_39`	`plutosdr`
LibreSDR	`xilinx24_1_aarch32`	`libresdr`
Xilinx ZC706	`xilinx24_1_aarch32`	`zc706`
Xilinx ZCU102	`xilinx24_1_aarch64`	`zcu102`

Execution

Prerequisites

Build the project for the PlutoSDR RCC and HDL platforms.
Deploy the bitstream and application artifacts to the target hardware.
Ensure the OpenCPI runtime is available on the target.
The application opens /dev/net/tun and requires either root privileges or CAP_NET_ADMIN on the target system.

Command(s)

Run the application on the target hardware:

./downlink_aci

The application prints the name of the TUN interface it allocates (e.g. tun0) and the commands needed to bring it up:

sudo ip link set tun0 up
sudo ip addr add 10.0.0.1/24 dev tun0

After running those commands, any IP traffic routed to the 10.0.0.1/24 subnet will be encapsulated and transmitted over the DVB-S2 RF link.

Verification

The application prints Running: FPGA encoder backpressure active via getOutputBuffer once the encoder is started.
Sending a ping from the host to 10.0.0.2 will produce GSE encapsulation debug output on stdout showing the fragment structure and CRC-32 of each GSE packet.
A spectrum analyzer or DVB-S2 receiver tuned to 400 MHz should detect the QPSK signal.

Troubleshooting

Cannot open /dev/net/tun — the process lacks CAP_NET_ADMIN; run as root or grant the capability.
Cannot ioctl TUNSETIFF — the tun kernel module is not loaded; run modprobe tun.
app failed: … — an OpenCPI runtime error occurred (bitstream not loaded, DRC initialization failure, etc.). Check that the correct bitstream is programmed and that the DRC worker is available for the target platform.
BB queue full, dropping oldest frame — the FPGA encoder cannot consume frames as fast as IP traffic arrives. Reduce traffic rate or verify that the encoder bitstream is running at the expected sample rate.

Worker Properties

The dvbs2_encoder worker (instance enc) exposes a regs array property used at startup to configure the QPSK constellation mapper:

Register offset	Value written	Description
`0x110 + 0`	`(+I, +Q)`	QPSK symbol (+1, +1)
`0x110 + 4`	`(+I, −Q)`	QPSK symbol (+1, −1)
`0x110 + 8`	`(−I, +Q)`	QPSK symbol (−1, +1)
`0x110 + 12`	`(−I, −Q)`	QPSK symbol (−1, −1)

Each 32-bit register packs the I sample in the upper 16 bits and the Q sample in the lower 16 bits. The magnitude used is 32 000 (out of a signed 16-bit range of ±32 767).

DVB-S2 Downlink ACI (downlink_aci)