libri Reference

Welcome to the libri reference page. Here you will find descriptions of all the functions exposed by libri. The exposed functions are organized into sections based on what they do.

Library initialization

To use libri, the library must be initialized before use, and deinitialized at program exit.

int ri_init(void)

Initializes libri.

ri_init() should be called before any other libri functions are called. At exit, ri_exit() should be called.

Return
zero on success, an RI_ERROR_t on failure
See
ri_exit()

void ri_exit(void)

Deinitialize libri.

Should be called before program exit for proper shutdown of libri.

See
ri_init()

Opening a device

In order to communicate with a device, the device must be opened and a pointer to an ri_device found. This pointer is then passed as the first argument to any function that talks with a device to specify which device to communicate with.

ri_device *ri_open_device(void)

Opens the first available device.

If ri_open_device() returns zero, no devices were able to be found. If it returns a non-zero pointer, a device has been opened which should eventually be closed with ri_close_device().

Return
an ri_device pointer
See
ri_device(), ri_close_device()

ri_device *ri_open_from_serial(const char *serial)

Open a device based on serial number.

Opens the first device which the string serial is found in the device’s serial number. Since it searches for a substring match, the entire serial does not have to be provided, just enough to provide a unique match versus other connected devices.

Return
ri_device pointer of found device. Zero if no device found or an error occurred.
Parameters
  • serial: string in the serial to search for

ri_device *ri_close_device(ri_device *dev)

Closes an open ri_device.

After ri_close_device() is called the ri_device is invalid and the pointer should be set to zero. For convenience, this function returns zero for the pointer to be set to.

Return
a null *ri_device pointer
See
ri_device, ri_open_device()
Parameters

ri_device_info_t *ri_list_devices(int *ndevices)

List connected devices.

Returns an array of ri_device_info_t of all devices found connected to the computer. The pointer ndevices is set to the number of devices found and the size of the returned array.

This does not open any devices, the serial number of the desired device can be found and the device can be opened with ri_open_from_serial().

If no devices are found, or an error occurred, zero is returned.

If successfull, the ri_device_info_t* array must be deallocated with a call to ri_free_device_list().

Return
c array of ri_device_info_t with size ndevices
See
ri_free_device_list()
Parameters
  • ndevices: stores number of devices found

void ri_free_device_list(ri_device_info_t *devices)

Frees the array of ri_device_info_t returned by ri_list_devices().

Parameters
  • devices: pointer to the device list to free

High-speed data collection

int ri_get_raw_data(ri_device *dev, uint64_t nsamples, uint16_t *buff)

Collect raw ADC samples from the device.

ri_get_raw_data() is the simplest method to get samples from the DPD80. The function blocks and returns once the requested number of samples is collected and written to the supplied buffer buff.

Return
zero on success, an RI_ERROR_t on failure
Parameters
  • dev: an open *ri_device pointer
  • nsamples: number of samples to collect
  • *buff: pointer to a location in memory to store the collected samples

int ri_get_raw_data_triggered(ri_device *dev, uint64_t nsamples, uint16_t *buff, RI_TRIGGER_MODE_t mode)

Collect raw ADC samples after a trigger signal is received.

Wait for a trigger signal applied on the DPD80 port S or port T before collecting nsamples of raw ADC samples.

See RI_TRIGGER_MODE_t for a list of triggering modes. Once a triggering condition is reached, the entire nsamples of uint16_t samples are collected.

Return
zero on success, an RI_ERROR_t on failure
Parameters
  • dev: an open *ri_device pointer
  • nsamples: number of samples to collect
  • *buff: pointer to a location in memory to store the collected samples
  • mode: the trigger mode, described by a RI_TRIGGER_MODE_t value

int ri_get_raw_data_triggered_repeat(ri_device *dev, uint64_t nsamples, uint16_t *buff, RI_TRIGGER_MODE_t mode, uint64_t samples_per_trigger)

Collect raw ADC samples after a trigger signal is received.

Behaves like ri_get_raw_data_triggered, however on each trigger signal collect only samples_per_trigger samples, and repeat until the entire are collected.

See RI_TRIGGER_MODE_t for a list of triggering modes. Once a triggering condition is reached, samples_per_trigger of uint16_t samples are collected. The function then waits again for a trigger condition, until the entire nsamples are collected.

Return
zero on success, an RI_ERROR_t on failure
Parameters
  • dev: an open *ri_device pointer
  • nsamples: total number of samples to collect
  • *buff: pointer to a location in memory to store the collected samples
  • mode: the trigger mode, described by a RI_TRIGGER_MODE_t value
  • samples_per_trigger: the number of samples to collect every time the trigger signal is received.

enum RI_TRIGGER_MODE_t

Enum to set the triggering mode when collecting data.

See
ri_get_raw_data_triggered()

Values:

RI_TRIG_AUTO

Trigger immediately.

Equivalent to no triggering like ri_get_raw_data()

RI_TRIG_S_RISING

Trigger when port S changes from Low to High

RI_TRIG_S_FALLING

Trigger when port S changes from High to Low

RI_TRIG_S_HIGH

Trigger when port S is High

RI_TRIG_S_LOW

Trigger when port S is Low

RI_TRIG_T_RISING

Trigger when port T changes from Low to High

RI_TRIG_T_FALLING

Trigger when port T changes from High to Low

RI_TRIG_T_HIGH

Trigger when port T is High

RI_TRIG_T_LOW

Trigger when port T is Low

typedef int (*ri_transfer_callback)(uint16_t *data, int ndata, int dataloss, void *userdata)

Callback function type for use with ri_start_continuous_transfer().

Called after a set samples are collected, typically around 5120 - 10240, however the exact amount is undefined. The number of samples sent to this function is not guaranteed to be fixed. This function is called repeatedly until it returns false, which cancels the continuous transfer operation.

This function should return as quick as possible to prevent possible data loss.

Return
boolean value indicating if data collection should continue
Parameters
  • data: buffer containing the collected samples. The contents should be copied out of this buffer as the buffer may be deleted or reused once this function returns.
  • ndata: number of 16 bit samples in data
  • dataloss: boolean value indicating if data loss was detected since the last callback.
  • the: userdata void pointer passed to ri_start_continuous_transfer()

int ri_start_continuous_transfer(ri_device *dev, ri_transfer_callback callback, void *userdata)

Start continuous data collection using a callback function.

ri_start_continuous_transfer() allows data to be transferred for a potentially unlimited period of time. A callback function with the same type as ri_transfer_callback should be supplied which is called repeatedly whenever new data is available.

this function will block, and data transfer will continue until the callback function returns false.

See
The example example_data_streaming for an example on how to use this function.
Return
zero on success, an RI_ERROR_t on failure
Parameters
  • dev: an open *ri_device pointer
  • callback: a function pointer to a ri_transfer_callback callback function
  • userdata: a void pointer that will be passed to the callback function unchanged

Querying and setting device parameters

const char *ri_get_serial(ri_device *dev)

Gets the device’s serial number.

If an error occurred, a null pointer is returned. Use ri_get_error() to find further information on the error.

Return
null-terminated string
Parameters

const char *ri_get_product(ri_device *dev)

Gets the device’s product string.

If an error occurred, a null pointer is returned. Use ri_get_error() to find further information on the error.

Return
null-terminated string
Parameters

ri_version_t ri_get_fwversion(ri_device *dev)

Gets the device’s firmware version.

If an error occurs, returns RI_BAD_VERSION.

Return
an ri_version_t containing the firmware version information.
Parameters

int ri_get_fwversion_int(ri_device *dev)

Gets an intified version of the device’s firmware version.

Equivalent to calling ri_version_intify on the firmware’s version.

If an error occurs, returns -1.

Return
the intified firmware version number.
Parameters

uint32_t ri_get_samplerate(ri_device *dev)

Gets the device’s sample rate.

If an error occurs, returns RI_BAD_UINT32.

Return
the sample rate of the device, in samples per second.
Parameters

uint8_t ri_get_adcbits(ri_device *dev)

Gets the number of bits of the device’s ADC.

Return
The number of bits of the device’s Analog to Digital converter.
Parameters

RI_USB_SPEED_t ri_get_usb_speed(ri_device *dev)

Returns the USB speed of the open ri_device.

Data transfer operations are only supported when the device is RI_SPEED_SUPER i.e. when in USB 3 mode.

Return
an RI_USB_SPEED_t value
Parameters

int ri_get_peak_responsivity(ri_device *dev)

Returns the peak wavelength responsibility (in nm) of the model of photodiode on the device as an integer.

This is the typical peak sensitivity of the photodiode, not a per device calibrated sensitivity.

If an error occurred, return -1.

Return
peak wavelength reponsivity in nm
Parameters

double ri_get_rel_responsivity(ri_device *dev, double wavelength)

Returns the relative responsivity of the photodiode at a particular wavelength from the peak responsivity.

The rel_responsivity at the peak sensitivity is 1. This is estimated from the datasheet curve and due to polynomial representation internally may return a value slightly greater then 1 at values near the peak wavelength.

If the requested wavelength is out of range, zero is returned.

Parameters
  • dev: an open *ri_device pointer
  • wavelength: the wavelength (in nm) to calculate the relative responsivity at.

ri_calibration_t ri_get_calibration(ri_device *dev, int calibrationtype)
ri_calibration_t ri_get_rel_calibration(ri_device *dev, int calibrationtype, double wavelength)
int ri_get_value(ri_device *dev, RI_VALUE_NAME_t name, void *value)

ri_get_value() is an API to get various values from the attached device.

available values to query are listed in the RI_VALUE_NAME_t enum, and the data types they are copied as.

since the type of *value is not declared, care must be taken *value points to enough memory to write the requested value.

Due to type safety, the individual ri_get_ functions are recommended over ri_get_value().

Return
zero on success, an RI_ERROR_t on failure
Parameters
  • dev: an open *ri_device pointer
  • name: one of RI_VALUE_NAME_t values
  • value: a pointer to the place to write the value to

int ri_set_highgain(ri_device *dev, int enable)

Sets the highgain feature of the DPD80.

Controls whether the transimpedance amplifier is in highgain mode (1) or lowgain mode (0). highgain mode increases amplification by a factor of 4, but reduces the available dynamic range.

Default is highgain mode.

Resets to default when the device is powered on.

Return
zero on success, an RI_ERROR_t on failure
Parameters
  • dev: an open *ri_device pointer
  • enable: if the feature should be enabled.

int ri_read_highgain(ri_device *dev)

Reads the state of the highgain feature.

If an error occurred, returns -1.

Return
0 or 1 on success, -1 on failure.
See
ri_set_highgain()
Parameters

int ri_set_antialias(ri_device *dev, int enable)

Sets the antialias feature of the DPD80.

Controls whether the 35 MHz antialiasing filter is enabled. Only effects the digitally collected data, not the analog RF output.

Default is antialias mode on.

Resets to default when the device is powered on.

Return
zero on success, an RI_ERROR_t on failure
Parameters
  • dev: an open *ri_device pointer
  • enable: if the feature should be enabled.

int ri_read_antialias(ri_device *dev)

Reads the state of the antialias feature.

If an error occurred, returns -1.

Return
0 or 1 on success, -1 on failure.
See
ri_set_antialias()
Parameters

int ri_set_powerdown(ri_device *dev, int enable)

Sets the powerdown feature of the DPD80.

Controls whether the DPD80 is powered down. When powerdown is enabled all the analog circuitry is powered off.

Default is powerdown mode off.

Resets to default when the device is powered on.

Return
zero on success, an RI_ERROR_t on failure
Parameters
  • dev: an open *ri_device pointer
  • enable: if the feature should be enabled.

int ri_read_powerdown(ri_device *dev)

Reads the state of the powerdown feature.

If an error occurred, returns -1.

Return
0 or 1 on success, -1 on failure.
See
ri_set_powerdown()
Parameters

int ri_set_adcclock(ri_device *dev, int enable)

Sets the adcclock feature of the DPD80.

Controls whether the 80 MHz ADC clock is enabled. When disabled digital data collection will not work, however it will eliminate the pickup of the 80 MHz clock in the analog RF output signal.

Default is adcclock mode on.

Resets to default when the device is powered on.

Return
zero on success, an RI_ERROR_t on failure
Parameters
  • dev: an open *ri_device pointer
  • enable: if the feature should be enabled.

int ri_read_adcclock(ri_device *dev)

Reads the state of the adcclock feature.

If an error occurred, returns -1.

Return
0 or 1 on success, -1 on failure.
See
ri_set_adcclock()
Parameters

int ri_read_p1_select(ri_device *dev)

Reads if P1 Select is enabled.

(DPD80 Balanced Photodetector)

P1 Select enables the analog power monitor output of the P1 photodiode to port “S” on the the DPD80 Balanced Photodetector. See the calibration document supplied with the detector for voltage to optical power conversion factors.

When P1 Select is enabled, the normal port functions of the port “S” are disconnected and will not operate.

Return
1 if the monitor signal is output on port “S”, 0 otherwise.
Parameters

int ri_read_p2_select(ri_device *dev)
int ri_set_p1_select(ri_device *dev, int enable)

Sets P1 Select.

(DPD80 Balanced Photodetector)

P1 Select enables the analog power monitor output of the P1 photodiode to port “S” on the the DPD80 Balanced Photodetector. See the calibration document supplied with the detector for voltage to optical power conversion factors.

When P1 Select is enabled, the normal port functions of the port “S” are disconnected and will not operate.

Return
1 if the monitor signal is output on port “S”, 0 otherwise.
Parameters
  • dev: an open *ri_device pointer
  • enable: true enables P1 Select

int ri_set_p2_select(ri_device *dev, int enable)

Using the DPD80 ports

These methods control the MMCX ports on the back of the DPD80. See dpd80-ports for more information.

int ri_port_drive(ri_device *dev, RI_PORT_t port, int value)

Drive a 3.3 V logic signal on the specified port.

Return
zero on success, an RI_ERROR_t on failure
Parameters
  • dev: an open *ri_device pointer
  • port: the RI_PORT_t port to control
  • value: boolean value indicating the output: 3.3 V (true) or 0 V (false)

int ri_port_read(ri_device *dev, RI_PORT_t port)

Read a 3.3 V logic signal on the specified port.

Return
the logic signal applied to the port. -1 if and error occurred.
Parameters
  • dev: an open *ri_device pointer
  • port: the RI_PORT_t port to control

int ri_port_pwm(ri_device *dev, RI_PORT_t port, uint32_t threshold, uint32_t period)

Drive a square wave with a given duty cycle on the port.

threshold and period are specified in clock cycles, which correspond to approximately 5 ns.

Return
zero on success, an RI_ERROR_t on failure
Parameters
  • dev: an open *ri_device pointer
  • port: the RI_PORT_t port to control
  • threshold: the on-time of the square wave (in clock cycles)
  • period: the period of the square wave (in clock cycles)

int ri_port_pulse(ri_device *dev, RI_PORT_t port, uint32_t threshold)

Drive a single square wave pulse on the specified port.

threshold is specified in clock cycles, which correspond to approximately 5 ns.

Return
zero on success, an RI_ERROR_t on failure
Parameters
  • dev: an open *ri_device pointer
  • port: the RI_PORT_t port to control
  • threshold: the length of the pulse (in clock cycles)

Miscellaneous functions

int ri_reset_device(ri_device *dev)

Resets the device.

Return
zero on success, an RI_ERROR_t on failure
Parameters

ri_version_t ri_version()

Returns the version of libri being linked, as a ri_version_t containing the major, minor, and revision versions.

This may differ from the variable LIBRI_VERSION, if, for instance, a different version of libri.dll is being used compared with the version of ri.h when the program was compiled.

int ri_version_intify(ri_version_t version)

Turn a ri_version_t into an integer so that version numbers can be compared using standard operators.

Return
an int corresponding to the version number
Parameters

Structs and enums

struct ri_device

The device in use is stored as an opaque pointer with the type ri_device*.

When ri_device* is zero, no device exists and it’s considered unopened.

When a ri_device* is not equal to zero, it is assumed to be an opened device. Therefore, always initialize the device pointer to zero when declaring a variable, and after closing explicitly set the pointer to zero.

See
ri_open_device(), ri_close_device()

struct ri_device_info_t

A structure containing basic information about an device.

See
ri_list_devices()

Public Members

char ri_device_info_tproduct[32]

A null-terminated string describing the device.

char ri_device_info_tserial[16]

A null-terminated string containing the device’s serial number.

uint32_t ri_device_info_tsamplerate

the ADC samplerate of the connected device, in samples per second

uint8_t ri_device_info_tbits

the number of ADC bits in the connected device

ri_version_t ri_device_info_tfw_version

the firmware version of the connected device

struct ri_version_t

A structure containing versioning information.

This is represented in text as major.minor.release

Public Members

uint8_t ri_version_tmajor

major version

uint8_t ri_version_tminor

minor version

uint8_t ri_version_trelease

release number

struct ri_calibration_t

Struct representing a linear calibration.

Contains slope and y-offset to linearly convert one measurement to different units using the formula \( Y = m X + b \).

Public Members

double ri_calibration_tm

Slope.

double ri_calibration_tb

Offset.

enum RI_USB_SPEED_t

Enum containing the various USB connection speeds that a device can operate in.

See
ri_get_usb_speed()

Values:

RI_SPEED_UNKNOWN
RI_SPEED_LOW
RI_SPEED_FULL
RI_SPEED_HIGH
RI_SPEED_SUPER
RI_SPEED_ERROR = -1
enum RI_VALUE_NAME_t

A list of possible values that can be queried from a connected device.

Values:

RI_VAL_SERIAL

char[16]

RI_VAL_PRODUCT

char[16]

RI_VAL_FWVERSION

uint8[3]

RI_VAL_SAMPLERATE

uint32

RI_VAL_ADCBITS

uint8

RI_VAL_PEAK_RESPONSIVITY

uint32

RI_VAL_USBVID = 0x20

uint16

RI_VAL_USBPID

uint16

RI_CAL_DIGITAL_HIGHGAIN = 0x30

float[2]

RI_CAL_DIGITAL_LOWGAIN

float[2]

RI_CAL_ANALOG_HIGHGAIN

float[2]

RI_CAL_ANALOG_LOWGAIN

float[2]

Error handling

The majority of functions in libri return an integer indicating the error status of that function. On success the return status is 0, and a non-zero value indicates an error occurred. The #RI_ERROR_t enum describes the possible errors that can be reported.

enum RI_ERROR_t

Enum containing various error codes used by libri.

Often a function returning non-zero signals an error and value returned can give an indication where the error occurred.

Values:

RI_SUCCESS = 0

Operation completed successfully.

RI_OK = 0
RI_ERROR = -1

Generic error occurred.

RI_ERROR_PARAMS = 0x30

Error occurred with function parameters.

RI_ERROR_MEMORY

Memory allocation error.

RI_ERROR_INVALID_DEVICE

Invalid ri_device.

RI_ERROR_BAD_CHECKSUM

Invalid checksum or signature computed for stored data.

RI_ERROR_DEVICE_SETTINGS

The factory settings stored on the device are not configured correctly.

RI_ERROR_NOT_IMPLEMENTED

A needed feature is currently not implemented.

RI_ERROR_FIRMWARE

< Error occurred in firmware on the device.

RI_ERROR_USB = 0x20

Generic USB error.

RI_ERROR_USB_TIMEOUT

USB timeout error.

RI_ERROR_USB_SPEED

For convenience, some functions, such as ri_get_samplerate() and similar functions, return a value directly. In this case, a specific return value indicates an error. For pointers, this is zero. For other types it is given by these RI_BAD_TYPE types.

const uint8_t RI_BAD_UINT8 = 0xFFU

A uint8_t value indicating an error occurred.

const uint16_t RI_BAD_UINT16 = 0xFFFFU

A uint16_t value indicating an error occurred.

const uint32_t RI_BAD_UINT32 = 0xFFFFFFFFU

A uint32_t value indicating an error occurred.

const ri_version_t RI_BAD_VERSION = {0xFF, 0xFF, 0xFF}

A ri_version_t value indicating an error occurred.

Whenever an error occurs, the error code is stored in a global variable retrievable with the ri_get_error() function. Additionally, ri_get_error_string() can be used to get a string description of the error.

int ri_get_error()

Get the last error code that occurred.

Error codes are one of RI_ERROR_t values.

Return
an RI_ERROR_t value describing the last error

const char *ri_get_error_string()

Get a string describing the last error that occurred.

Return
a null terminated string describing the previous error

void ri_clear_errors()

Clear the last error and set it to RI_SUCCESS.

Useful if you need to check if an error occurred in a function without using it’s error status.