RIStream Reference

RIStream is a C++ header that builds on top of libri to provide a more advanced signal processing layer beyond the basic callbacks provided by libri.

Welcome to the RIStream reference page. Here you will find descriptions of the classes and functions defined in the ri_stream.hpp header file included with libri.

class RIGenericStream

RIGenericStream is the parent class the sample-type specific streams derive from.

This class defines all datatype-neutral functions that control the properties of an RIStream. The more specific RIStream<float> and RIStream<double> contain the datatype-specific methods for acquiring floating point samples from an RI device.

Since RIGenericStream is an purely-abstract class, streams cannot be created by constructing a new RIGenericStream. Instead, a pointer to a new RIStream can be created by calling ri_open_stream.

Subclassed by RIStream< dtype >

Public Functions

ri_device *device() = 0

Get the ri_device associated with this stream.

Return

the ri_device pointer associated with this stream.

double samplerate() = 0

Get the sampling rate of data returned by this stream.

This includes reductions to the samplerate caused when downsampling is enabled.

Return

the samplerate of data returned by this stream

int samplesize() = 0

Get the size (in bytes) of the floating point samples returned by this stream.

Valid sizes are 4 (float) and 8 (double).

Return

Size of individual samples in bytes

std::string calibration_mode() = 0

Return the calibration mode of the stream.

Valid calibration modes are:

• “none”: values are uncalibrated ADC code values

• ”auto” (default): Use the onboard calibration to convert from ADC samples to uW.

• ”custom”: Use a custom calibration set with set_custom_calibration

Return

The current calibration mode encoded as a std::string

int set_calibration_mode(const std::string mode) = 0

Set the calibration mode.

See calibration_mode for valid modes.

Return

zero on success, an RI_ERROR_t on failure

int set_calibration_mode(const char *mode) = 0

Set the calibration mode.

See calibration_mode for valid modes.

Return

zero on success, an RI_ERROR_t on failure

int update_auto_calibration() = 0

Forces the “auto” calibration mode to update the calibration while the stream is collecting data.

This is only required if some calibration effecting setting (eg. highgain mode) is changed while the stream is collecting data.

Return

zero on success, an RI_ERROR_t on failure

ri_calibration_t calibration() = 0

Gets the current calibration setting as an ri_calibration_t.

Return

the current ADC

int set_custom_calibration(const ri_calibration_t calibration) = 0

Set a custom calibration to multiply raw ADC samples by.

The calibrated samples will be computed by:

\[ \mathsf{calibrated} = \mathsf{raw} \times m + b \]

Setting a custom calibration automaticall sets the calibration_mode to “custom”.

Return

zero on success, an RI_ERROR_t on failure

double calibration_wavelength() = 0

Return the wavelength that is used to calculate incident power when the calibration mode is set to “auto”.

This defaults to the peak responsivity wavelength of the photodetector.

Return

the wavelength used to calculate measured power.

int set_calibration_wavelength(const double wavelength) = 0

Sets the calibration wavelength used when the calibration fan is set to “auto”.

Setting this value changes calibration mode to “auto”.

Return

zero on success, an RI_ERROR_t on failure

int calibration_units() = 0

Gets the power of ten units for power that are used when the calibration_mode is set to “auto”.

By default calibration_units will return -6 and the power will be calibrated in micro Watts.

Return

the power of ten the calibrated power is multiplied by.

int set_calibration_units(const int power_of_ten) = 0

Sets the power of ten units for power that are used when the calibration_mode is set to “auto”.

For example, setting this to -6 results in units of uW. -3 results in units of mW, and 0 results in units of Watts.

Return

zero on success, an RI_ERROR_t on failure

std::string filter() = 0

Gets the name of the filter applied to incoming data.

Valid filter modes are:

• ”none” (default): No filter is applied

• ”butterworth2”: A two-pole butterworth low-pass filter

• ”butterworth4”: A four-pole butterworth low-pass filter

• ”butterworth6”: A six-pole butterworth low-pass filter

• ”fir”: A simple square window finite-impulse response low-pass filter.

To adjust the filter cutoff paramater, use set_cutoff.

Return

a std::string with the filter mode in use.

int set_filter(const std::string filter) = 0

Sets the filter to apply to incoming samples.

See filter for valid filter types.

Return

zero on success, an RI_ERROR_t on failure

double cutoff() = 0

Gets the cutoff frequency of the filter.

This has no effect if filter is set to “none”.

Return

The -3dB cutoff frequency in Hz.

int set_cutoff(const double cutoff) = 0

Sets the cutoff frequency of the selected filter.

Return

zero on success, an RI_ERROR_t on failure

int downsampling() = 0

Gets The downsampling factor being applied to incoming data.

This reduced the samplerate by the downsampling factor. For example, when downsampling is disabled, this is set to 1. When the sample rate is reduced by half, it will be set to 2, and so on.

Return

The downsampling factor.

int set_downsampling(const int downsampling) = 0

Sets the downsampling factor for the stream.

See

downsampling

int set_decimation(const int decimation) = 0

Sets the decimation factor.

This automatically applies a filter, cutoff frequency, and downsampling rate that corresponds to the requested decimation factor.

Return

zero on success, an RI_ERROR_t on failure

uint64_t settling() = 0

Gets the number of samples the stream processs before saving data.

After a stream is started, the stream will acquire at least settling samples before it starts saving samples to the out buffer. This allows filters to settle to steady state conditions reducing artifacts from the unknown initial conditions of the filters.

int set_settling(const uint64_t nsamples) = 0

Sets the number of samples the stream processes before starting to saving data.

This is the number of samples received from the device before any downsampling by RIStream occurs.

Return

zero on success, an RI_ERROR_t on failure