Streaming API Reference

Complete API documentation for the Red Pitaya streaming client library. This library enables high-performance data streaming between Red Pitaya and your computer.

Note

The streaming client library runs on your computer (not on Red Pitaya). It communicates with the streaming server running on Red Pitaya over TCP/IP.

Overview 

The streaming API provides two main client classes for bidirectional data streaming:

ADCStreamClient - Stream data from Red Pitaya ADC inputs to your computer
DACStreamClient - Stream waveforms from your computer to Red Pitaya DAC outputs

Both classes use a callback-based architecture for efficient, non-blocking data transfer.

Architecture:

Computer                          Red Pitaya
+------------------+             +-----------------+
|  Your Program    |             | Streaming Server|
|                  |   TCP/IP    |                 |
|  ADCStreamClient |------------>|  FPGA -> ADC    |
|  DACStreamClient |<------------|  DAC <- FPGA    |
|                  |             |                 |
|  Callback Class  |             |  Deep Memory    |
+------------------+             +-----------------+

Installation 

Python:

The rp_stream Python library is included with the Streaming command line client. Download the command line client from the Data Stream control application on your Red Pitaya.

C++:

The C++ streaming library is included with the Streaming command line client. Download the command line client from the Data Stream control application on your Red Pitaya.

Class Reference 

class ADCStreamClient: Main client class for ADC streaming operations.

class ADCCallback: Base callback class for ADC streaming events.

class ADCPack: Data packet structure containing ADC channel samples.

class DACStreamClient: Main client class for DAC streaming operations.

class DACCallback: Base callback class for DAC streaming events.

ADC Streaming API 

ADCStreamClient Class 

Main class for streaming data from Red Pitaya ADC channels to your computer.

Basic Usage:

import rp_stream as streaming

# Create client
client = streaming.ADCStreamClient()

# Set callback handler
callback = MyADCCallback()
client.setReceiveDataCallback(callback.__disown__())

# Connect (auto-discovery)
client.connect()

# Configure streaming
client.sendConfig('adc_decimation', '256')
client.sendConfig('channel_state_1', 'ON')
client.sendConfig('channel_state_2', 'ON')

# Start streaming
client.startStreaming()
client.wait()

#include "adc_streaming.h"
#include "callbacks.h"

// Create callback handler
class MyCallback : public ADCCallback {
    void receivePack(ADCStreamClient* client, ADCPack& pack) override {
        // Process incoming data
    }
};

// Create client
ADCStreamClient client;
MyCallback callback;
client.setReceiveDataCallback(&callback);

// Connect (auto-discovery)
client.connect();

// Configure streaming
client.sendConfig("adc_decimation", "256");
client.sendConfig("channel_state_1", "ON");
client.sendConfig("channel_state_2", "ON");

// Start streaming
client.startStreaming();
client.wait();

Connection Methods

connect() → bool

Connect to a single Red Pitaya using auto-discovery. Automatically searches the network for available Red Pitaya boards and connects to the first one found.

Returns:: True if connection successful, False otherwise
Return type:: bool

Example:

if not client.connect():
    print("Connection failed")

Note

Currently connects to a single host only. For multi-board acquisition, use connect(hosts) method.

connect(hosts: list[str]) → bool

Connect to multiple Red Pitaya boards for synchronized multi-board acquisition (master/slave configuration). The first board in the list acts as the master.

Parameters:: hosts (list[str]) – List of hostnames or IP addresses (first is master, rest are slaves)
Returns:: True if all connections successful
Return type:: bool

Example:

# Master board first, then slaves
boards = ["200.0.0.7", "200.0.0.8"]
client.connect(boards)

# Configure master board
client.sendConfig(boards[0], 'adc_decimation', '64')
client.sendConfig(boards[0], 'channel_state_1', 'ON')

# Copy config to slave
config = client.getFileConfig(boards[0])
client.sendFileConfig(boards[1], config)

Configuration Methods

sendConfig(key: str, value: str) → bool

Send a configuration parameter to the streaming server.

Parameters:

key (str) – Configuration parameter name
value (str) – Parameter value as string

Returns:

True if configuration accepted

Return type:

bool

Common parameters:

Key	Description	Values
`adc_decimation`	Sample rate divisor (1-65536)	“1” - “65536”
`adc_pass_mode`	Destination mode	“NET”, “FILE”
`channel_state_1`	Enable/disable channel 1	“ON”, “OFF”
`channel_state_2`	Enable/disable channel 2	“ON”, “OFF”
`channel_state_3`	Enable/disable channel 3 (250-12)	“ON”, “OFF”
`channel_state_4`	Enable/disable channel 4 (250-12)	“ON”, “OFF”
`block_size`	Network packet size (bytes)	“2048” - “2097152”
`adc_size`	FPGA buffer size (bytes)	“1048576” - “104857600”

Example:

client.sendConfig('adc_decimation', '256')
client.sendConfig('channel_state_1', 'ON')
client.sendConfig('block_size', '131072')

sendConfig(host: str, key: str, value: str) → bool

Send configuration to a specific board in multi-board setup.

Parameters:

host (str) – Target Red Pitaya hostname
key (str) – Configuration parameter name
value (str) – Parameter value

Returns:

True if configuration accepted

Return type:

bool

getConfig(key: str) → str

Retrieve current configuration value from the server.

Parameters:: key (str) – Configuration parameter name
Returns:: Current value as string
Return type:: str

Example:

decimation = client.getConfig('adc_decimation')
print(f"Current decimation: {decimation}")

getConfig(host: str, key: str) → str

Retrieve configuration from specific board in multi-board setup.

Parameters:

host (str) – Target Red Pitaya hostname
key (str) – Configuration parameter name

Return type:

str

Streaming Control Methods

startStreaming() → bool

Start the data streaming process.

Returns:: True if streaming started successfully
Return type:: bool

Example:

if not client.startStreaming():
    print("Failed to start streaming")

stopStreaming()

Stop the streaming process on all connected boards.

Return type:: None

Example:

client.stopStreaming()

wait()

Block until streaming completes or is stopped. Call this after startStreaming().

Return type:: None

Example:

client.startStreaming()
client.wait()  # Blocks here until streaming stops

notifyStop()

Signal the streaming process to stop (for use in callbacks or other threads).

Return type:: None

Example:

# In callback after collecting enough data:
if self.sample_count >= self.target_samples:
    client.notifyStop()

notifyStop(host)

Stop streaming on a specific board in multi-board setup.

Parameters:: host (str) – Target Red Pitaya hostname
Return type:: None

Configuration File Methods

sendFileConfig(config)

Send a complete configuration as JSON string.

Parameters:: config (str) – JSON configuration string
Returns:: True if configuration accepted
Return type:: bool

getFileConfig()

Retrieve complete configuration as JSON string.

Returns:: JSON configuration string
Return type:: str

Utility Methods

setVerbose(enable)

Enable or disable detailed logging output.

Parameters:: enable (bool) – True for verbose logging
Return type:: None

Example:

client.setVerbose(True)  # Show connection and transfer details

setReceiveDataCallback(callback)

Register a callback object to receive streaming data and events.

Parameters:: callback (ADCCallback) – ADCCallback instance (use __disown__() in Python)
Return type:: None

Example:

callback = MyADCCallback()
client.setReceiveDataCallback(callback.__disown__())

removeReceiveDataCallback()

Unregister the callback handler.

Return type:: None

ADCCallback Class 

Base class for handling ADC streaming events. Override methods to process incoming data.

Minimal Implementation:

class MyCallback(streaming.ADCCallback):
    def __init__(self):
        super().__init__()
        self.data = []

    def receivePack(self, client, pack):
        """Called when data arrives"""
        if pack.channel1.samples > 0:
            self.data.extend(pack.channel1.raw)

#include "adc_streaming.h"
#include "callbacks.h"

class MyCallback : public ADCCallback {
public:
    std::vector<int16_t> data;

    void receivePack(ADCStreamClient* client, ADCPack& pack) override {
        // Process channel 1 data
        if (pack.channel1.samples > 0) {
            data.insert(data.end(),
                        pack.channel1.raw,
                        pack.channel1.raw + pack.channel1.samples);
        }
    }
};

Data Callback Method

receivePack(client, pack)

Primary callback - Called when a new data packet arrives from the streaming server.

Parameters:

client (ADCStreamClient) – The ADCStreamClient instance
pack (ADCPack) – ADCPack object containing channel data

Return type:

None

ADCPack Structure:

pack.host              # str: Source Red Pitaya hostname
pack.channel1.raw      # list[int16]: Raw ADC samples
pack.channel1.samples  # int: Number of samples in packet
pack.channel1.fpgaLost # int: Samples lost by FPGA buffer overflow
pack.channel1.packId   # int: Packet sequence number
# channel2, channel3, channel4 same structure

Example:

def receivePack(self, client, pack):
    # Store data
    self.ch1_data.extend(pack.channel1.raw)
    self.ch2_data.extend(pack.channel2.raw)

    # Monitor for data loss
    if pack.channel1.fpgaLost > 0:
        print(f"WARNING: Lost {pack.channel1.fpgaLost} samples")

    # Stop after collecting enough data
    if len(self.ch1_data) >= self.target_samples:
        client.notifyStop()

Connection Event Callbacks

Note

All callback methods receive a host parameter that identifies which Red Pitaya board triggered the event. This is essential for tracking events in multi-board master/slave configurations.

connected(client, host)

Called when successfully connected to a Red Pitaya.

Parameters:

client (ADCStreamClient) – The ADCStreamClient instance
host (str) – Hostname or IP of the Red Pitaya that connected

Return type:

None

disconnected(client, host)

Called when connection to a Red Pitaya is lost.

Parameters:

client (ADCStreamClient) – The ADCStreamClient instance
host (str) – Hostname or IP of the Red Pitaya that disconnected

Return type:

None

error(client, host, code)

Called when a connection or streaming error occurs.

Parameters:

client (ADCStreamClient) – The ADCStreamClient instance
host (str) – Hostname or IP of the Red Pitaya reporting the error
code (int) – Error code (system-specific)

Return type:

None

Server State Callbacks

stopped(client, host)

Called when streaming stops normally.

Parameters:

client (ADCStreamClient) – The ADCStreamClient instance
host (str) – Hostname or IP of the Red Pitaya that stopped

Return type:

None

stoppedNoActiveChannels(client, host)

Called when streaming stops because no channels are enabled.

Parameters:

client (ADCStreamClient) – The ADCStreamClient instance
host (str) – Hostname or IP of the Red Pitaya that stopped

Return type:

None

stoppedMemError(client, host)

Called when streaming stops due to memory allocation error.

Parameters:

client (ADCStreamClient) – The ADCStreamClient instance
host (str) – Hostname or IP of the Red Pitaya that stopped

Return type:

None

stoppedMemModify(client, host)

Called when streaming stops due to memory configuration change during streaming.

Parameters:

client (ADCStreamClient) – The ADCStreamClient instance
host (str) – Hostname or IP of the Red Pitaya that stopped

Return type:

None

stoppedSDFull(client, host)

Called when streaming to SD card stops because the card is full.

Parameters:

client (ADCStreamClient) – The ADCStreamClient instance
host (str) – Hostname or IP of the Red Pitaya that stopped

Return type:

None

stoppedSDDone(client, host)

Called when streaming to SD card completes successfully.

Parameters:

client (ADCStreamClient) – The ADCStreamClient instance
host (str) – Hostname or IP of the Red Pitaya that completed

Return type:

None

Configuration Connection Callbacks

configConnected(client, host)

Called when configuration connection is established.

Parameters:

client (ADCStreamClient) – The ADCStreamClient instance
host (str) – Hostname or IP of the Red Pitaya that connected

Return type:

None

configError(client, host, code)

Called when configuration connection encounters an error.

Parameters:

client (ADCStreamClient) – The ADCStreamClient instance
host (str) – Hostname or IP of the Red Pitaya reporting the error
code (int) – Error code

Return type:

None

configErrorTimeout(client, host)

Called when configuration connection times out.

Parameters:

client (ADCStreamClient) – The ADCStreamClient instance
host (str) – Hostname or IP of the Red Pitaya that timed out

Return type:

None

DAC Streaming API 

DACStreamClient Class 

Main class for streaming waveforms from your computer to Red Pitaya DAC outputs.

Basic Usage:

import rp_stream as streaming

# Create client
client = streaming.DACStreamClient()

# Set callback handler (optional)
callback = MyDACCallback()
client.setCallback(callback.__disown__())

# Connect and configure
client.connect()
client.sendConfig('dac_rate', '125000000')
client.sendConfig('dac_pass_mode', 'NET')

# Stream from WAV file
client.startStreaming('./waveform.wav')
client.wait()

#include "dac_streaming.h"
#include "callbacks.h"

// Create callback handler
class MyCallback : public DACCallback {
    void sentPack(DACStreamClient* client, uint32_t ch1, uint32_t ch2) override {
        // Handle sent packet notification
    }
};

// Create client
DACStreamClient client;
MyCallback callback;
client.setCallback(&callback);

// Connect and configure
client.connect();
client.sendConfig("dac_rate", "125000000");
client.sendConfig("dac_pass_mode", "NET");

// Stream from WAV file
client.startStreaming("./waveform.wav");
client.wait();

Connection Methods

connect() → bool

Connect to Red Pitaya using auto-discovery.

Returns:: True if connection successful
Return type:: bool

connect(host: str) → bool

Connect to specific Red Pitaya.

Parameters:: host (str) – Hostname or IP address
Returns:: True if connection successful
Return type:: bool

Example:

if not client.connect("rp-f0a235.local"):
    print("Connection failed")

Configuration Methods

sendConfig(key: str, value: str) → bool

Send configuration parameter to streaming server.

Parameters:

key (str) – Configuration parameter name
value (str) – Parameter value

Return type:

bool

Common DAC parameters:

Key	Description	Values
`dac_rate`	DAC output rate (Hz)	“1” - “125000000”
`dac_pass_mode`	Source mode	“NET”, “FILE”
`block_size`	Network packet size (bytes)	“2048” - “2097152”
`adc_size`	FPGA buffer size (bytes)	“1048576” - “104857600”

Example:

client.sendConfig('dac_rate', '125000000')  # 125 MS/s
client.sendConfig('block_size', '16384')

getConfig(key: str) → str

Retrieve current configuration value.

Parameters:: key (str) – Configuration parameter name
Return type:: str

Example:

rate = client.getConfig('dac_rate')

Playback Control Methods

setRepeatCount(count)

Set number of times to repeat the waveform.

Parameters:: count (int) – Number of repetitions
Return type:: None

Example:

client.setRepeatCount(10)  # Play 10 times

setRepeatInf(enable)

Enable or disable infinite repeat mode.

Parameters:: enable (bool) – True for continuous playback
Return type:: None

Example:

client.setRepeatInf(True)  # Loop forever

Streaming Methods

startStreamingWAV(fileName)

Stream a WAV audio file to DAC outputs.

Parameters:: fileName (str) – Path to WAV file (relative or absolute)
Returns:: True if streaming started
Return type:: bool

Supported formats:

Mono (1 channel) - outputs on DAC 1
Stereo (2 channels) - outputs on DAC 1 and DAC 2
8-bit or 16-bit PCM

Example:

if not client.startStreamingWAV('./my_waveform.wav'):
    print("Failed to start")

startStreamingTDMS(fileName)

Stream a TDMS file to DAC outputs.

Parameters:: fileName (str) – Path to TDMS file
Returns:: True if streaming started
Return type:: bool

startStreamingFromMemory()

Stream waveforms previously loaded to memory with setMemory16Bit().

Returns:: True if streaming started
Return type:: bool

Example:

# Load waveform data
waveform = [100, 200, 300, ...]  # int16 values
client.setMemory16Bit(1, waveform)
client.setMemory16Bit(2, waveform)

# Stream from memory
client.startStreamingFromMemory()

stopStreaming()

Stop the streaming process.

Return type:: None

wait()

Block until streaming completes or is stopped.

Return type:: None

notifyStop()

Signal streaming to stop (for use in callbacks or other threads).

Return type:: None

Memory Loading Methods

setMemory8Bit(channel, buffer)

Load 8-bit waveform data into FPGA memory for a channel.

Parameters:

channel (int) – Channel number (1 or 2)
buffer (list[int]) – List of 8-bit signed integers

Returns:

True if data loaded successfully

Return type:

bool

Example:

data = [127, 0, -128, 0, ...]  # 8-bit values
client.setMemory8Bit(1, data)

setMemory16Bit(channel, buffer)

Load 16-bit waveform data into FPGA memory for a channel.

Parameters:

channel (int) – Channel number (1 or 2)
buffer (list[int]) – List of 16-bit signed integers

Returns:

True if data loaded successfully

Return type:

bool

Example:

import numpy as np

# Generate waveform
t = np.linspace(0, 1, 1024)
waveform = (32767 * np.sin(2 * np.pi * t)).astype(np.int16)

# Load to both channels
client.setMemory16Bit(1, waveform.tolist())
client.setMemory16Bit(2, waveform.tolist())

Utility Methods

setVerbose(enable)

Enable or disable detailed logging.

Parameters:: enable (bool) – True for verbose logging
Return type:: None

setCallbackFunction(callback)

Register callback to receive streaming events.

Parameters:: callback (DACCallback) – DACCallback instance
Return type:: None

Example:

callback = MyDACCallback()
client.setCallbackFunction(callback.__disown__())

removeCallbackFunction()

Unregister the callback handler.

Return type:: None

DACCallback Class 

Base class for handling DAC streaming events. Override methods to monitor streaming progress.

Minimal Implementation:

class MyCallback(streaming.DACCallback):
    def __init__(self):
        super().__init__()
        self.packets_sent = 0

    def sentPack(self, client, ch1_size, ch2_size):
        """Called after each packet is sent"""
        self.packets_sent += 1
        print(f"Sent CH1: {ch1_size} bytes, CH2: {ch2_size} bytes")

#include "dac_streaming.h"
#include "callbacks.h"

class MyCallback : public DACCallback {
public:
    int packets_sent = 0;

    void sentPack(DACStreamClient* client, uint32_t ch1_size, uint32_t ch2_size) override {
        packets_sent++;
        std::cout << "Sent CH1: " << ch1_size
                    << " bytes, CH2: " << ch2_size << " bytes" << std::endl;
    }
};

Data Callback Method

sentPack(client, ch1_size, ch2_size)

Primary callback - Called after a data packet is successfully sent to the DAC.

Parameters:

client (DACStreamClient) – The DACStreamClient instance
ch1_size (int) – Number of samples sent to channel 1
ch2_size (int) – Number of samples sent to channel 2

Return type:

None

Example:

def sentPack(self, client, ch1_size, ch2_size):
    self.total_samples += ch1_size + ch2_size
    print(f"Sent {self.total_samples:,} samples")

Connection Event Callbacks

connected(client, host)

Called when successfully connected.

Parameters:

client (DACStreamClient) – The DACStreamClient instance
host (str) – Hostname or IP

Return type:

None

disconnected(client, host)

Called when connection is lost.

Parameters:

client (DACStreamClient) – The DACStreamClient instance
host (str) – Hostname or IP

Return type:

None

error(client, host, code)

Called when a connection error occurs.

Parameters:

client (DACStreamClient) – The DACStreamClient instance
host (str) – Hostname or IP
code (int) – Error code

Return type:

None

Server State Callbacks

stopped(client, host)

Called when streaming stops normally.

Parameters:

client (DACStreamClient) – The DACStreamClient instance
host (str) – Hostname or IP

Return type:

None

stoppedFileEnd(client, host)

Called when streaming stops because the file ended.

Parameters:

client (DACStreamClient) – The DACStreamClient instance
host (str) – Hostname or IP

Return type:

None

stoppedFileBroken(client, host)

Called when streaming stops due to corrupted file.

Parameters:

client (DACStreamClient) – The DACStreamClient instance
host (str) – Hostname or IP

Return type:

None

stoppedEmpty(client, host)

Called when streaming stops because no data is available.

Parameters:

client (DACStreamClient) – The DACStreamClient instance
host (str) – Hostname or IP

Return type:

None

stoppedMissingFile(client, host)

Called when streaming stops because the file is not found.

Parameters:

client (DACStreamClient) – The DACStreamClient instance
host (str) – Hostname or IP

Return type:

None

stoppedMemError(client, host)

Called when streaming stops due to memory error.

Parameters:

client (DACStreamClient) – The DACStreamClient instance
host (str) – Hostname or IP

Return type:

None

stoppedMemModify(client, host)

Called when streaming stops due to memory modification during streaming.

Parameters:

client (DACStreamClient) – The DACStreamClient instance
host (str) – Hostname or IP

Return type:

None

Configuration Connection Callbacks

configConnected(client, host)

Called when configuration connection is established.

Parameters:

client (DACStreamClient) – The DACStreamClient instance
host (str) – Hostname or IP

Return type:

None

configError(client, host, code)

Called when configuration connection error occurs.

Parameters:

client (DACStreamClient) – The DACStreamClient instance
host (str) – Hostname or IP
code (int) – Error code

Return type:

None

configErrorTimeout(client, host)

Called when configuration connection times out.

Parameters:

client (DACStreamClient) – The DACStreamClient instance
host (str) – Hostname or IP

Return type:

None

Data Structures 

ADCPack Structure 

Contains data from a single streaming packet with information for all channels.

class ADCPack:
    host: str                # Source Red Pitaya hostname
    channel1: ADCChannel     # Channel 1 data
    channel2: ADCChannel     # Channel 2 data
    channel3: ADCChannel     # Channel 3 data (4-Input only)
    channel4: ADCChannel     # Channel 4 data (4-Input only)

ADCChannel Structure 

Contains data and metadata for a single ADC channel.

class ADCChannel:
    samples: int             # Number of samples in this packet
    bitsBySample: int        # ADC resolution (12, 14, or 16 bits)
    fpgaLost: int            # Cumulative samples lost due to buffer overflow
    attenuator_1_20: bool    # True if 1:20 attenuator is active
    baseRate: int            # Base ADC sampling rate (Hz)
    adcBaseBits: int         # Native ADC bit depth
    packId: int              # Packet sequence number
    raw: list[int16]         # Raw ADC sample data

Example Usage:

def receivePack(self, client, pack):
    ch1 = pack.channel1

    # Access samples
    samples = ch1.raw

    # Check for data loss
    if ch1.fpgaLost > 0:
        print(f"Lost {ch1.fpgaLost} samples")

    # Check attenuation
    if ch1.attenuator_1_20:
        print("1:20 attenuator is active")

Complete Examples 

For complete, production-ready examples with error handling and best practices, see Streaming Examples.