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 uninitialized 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, uint64_t armtime)

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

  • armtime: samples to wait in the untriggered state before allowing triggering. Help prevent accidental triggering on noisy edges

int ri_get_raw_data_triggered_repeat(ri_device *dev, uint64_t nsamples, uint16_t *buff, RI_TRIGGER_MODE_t mode, uint64_t armtime, 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 nsamples 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

  • armtime: samples to wait in the untriggered state before allowing triggering. Help prevent accidental triggering on noisy edges

  • 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:

enumerator RI_TRIG_AUTO

Trigger immediately.

Equivalent to no triggering like ri_get_raw_data()

enumerator RI_TRIG_S_RISING

Trigger when port S changes from Low to High

enumerator RI_TRIG_S_FALLING

Trigger when port S changes from High to Low

enumerator RI_TRIG_S_HIGH

Trigger when port S is High

enumerator RI_TRIG_S_LOW

Trigger when port S is Low

enumerator RI_TRIG_T_RISING

Trigger when port T changes from Low to High

enumerator RI_TRIG_T_FALLING

Trigger when port T changes from High to Low

enumerator RI_TRIG_T_HIGH

Trigger when port T is High

enumerator 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)

Retreive calibration stored in the detector memory.

Detectors are factory calibrated to give approximate linear conversions from votlages and adccodes to microwatts of power at the detectors peak responsivity wavelength.

Return

an RI_USB_SPEED_t value

Parameters

  • dev: an open *ri_device pointer

  • calibrationtype: A RI_CALIBRATIONTYPE_t enum value indicating which calibration to retreive

ri_calibration_t ri_get_rel_calibration(ri_device *dev, int calibrationtype, double wavelength)

Retreive calibration stored in the detector memory, and attempt to correct for wavelength responsivity.

Similar to ri_get_calibration, however also attempts to correct for photodiode responsivity across wavelengths.

Return

an RI_USB_SPEED_t value

Parameters

  • dev: an open *ri_device pointer

  • calibrationtype: A RI_CALIBRATIONTYPE_t enum value indicating which calibration to retreive

  • wavelength: Wavelength (in nanometers) to correct calibration to

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

Warning

doxygenfunction: Cannot find function “ri_read_p1_select” in doxygen xml output for project “libri” from directory: doxygen/xml/

Warning

doxygenfunction: Cannot find function “ri_read_p2_select” in doxygen xml output for project “libri” from directory: doxygen/xml/

Warning

doxygenfunction: Cannot find function “ri_set_p1_select” in doxygen xml output for project “libri” from directory: doxygen/xml/

Warning

doxygenfunction: Cannot find function “ri_set_p2_select” in doxygen xml output for project “libri” from directory: doxygen/xml/

Using the DPD80 ports

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

Note

For the DPD80 Balanced Photodetectors, the function of the S and T ports can be switched between analog outputs monitoring the individual photodiode signals (default behavior) and triggering/sync ports with the ri_set_p1_select() and ri_set_p2_select() functions.

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 product[32]

A null-terminated string describing the device.

char serial[16]

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

uint32_t samplerate

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

uint8_t bits

the number of ADC bits in the connected device

ri_version_t fw_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 major

major version

uint8_t minor

minor version

uint8_t release

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 m

Slope.

double b

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:

enumerator RI_SPEED_UNKNOWN
enumerator RI_SPEED_LOW
enumerator RI_SPEED_FULL
enumerator RI_SPEED_HIGH
enumerator RI_SPEED_SUPER
enumerator RI_SPEED_ERROR = -1
enum RI_VALUE_NAME_t

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

Values:

enumerator RI_VAL_SERIAL

char[16]

enumerator RI_VAL_PRODUCT

char[16]

enumerator RI_VAL_FWVERSION

uint8[3]

enumerator RI_VAL_SAMPLERATE

uint32

enumerator RI_VAL_ADCBITS

uint8

enumerator RI_VAL_PEAK_RESPONSIVITY

uint32

enumerator RI_VAL_USBVID = 0x20

uint16

enumerator RI_VAL_USBPID

uint16

enumerator RI_CAL_DIGITAL_HIGHGAIN = 0x30

float[2]

enumerator RI_CAL_DIGITAL_LOWGAIN

float[2]

enumerator RI_CAL_ANALOG_HIGHGAIN

float[2]

enumerator 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:

enumerator RI_SUCCESS = 0

Operation completed successfully.

enumerator RI_OK = 0
enumerator RI_ERROR = -1

Generic error occurred.

enumerator RI_ERROR_PARAMS = 0x30

Error occurred with function parameters.

enumerator RI_ERROR_MEMORY

Memory allocation error.

enumerator RI_ERROR_INVALID_DEVICE

Invalid ri_device.

enumerator RI_ERROR_BAD_CHECKSUM

Invalid checksum or signature computed for stored data.

enumerator RI_ERROR_DEVICE_SETTINGS

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

enumerator RI_ERROR_NOT_IMPLEMENTED

A needed feature is currently not implemented.

enumerator RI_ERROR_FIRMWARE

< Error occurred in firmware on the device.

enumerator RI_ERROR_USB = 0x20

Generic USB error.

enumerator RI_ERROR_USB_TIMEOUT

USB timeout error.

enumerator 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.