# ripy Reference¶

Welcome to the ripy reference page. Here you will find a guide to all functions exposed through the ripy module. It is written to mirror the libri reference page, and functions organized into the same sections.

## Library initialization¶

Unlike libri, ripy is automatically initialized when required and deinitialized on program exit, so no explicit initialization has to be done.

## Opening a device¶

ripy wraps the libri ri_device type as a the Python class Device. To start communication with a connected device an instance of Device should be made.

class ripy.Device(open=True, serial=None)

Represents a Resolved Instruments DPD80 device.

Before any functions can be used, the device must be opened with open(). By default, this is automatically done whenever a new device is created, but this can be disabled by setting open to False.

Parameters: open (bool) – Immediatly try opening the device serial (str) – String to find in the device’s serial number to connect to. ripy.NoDeviceError – If no device is found.
Device.open(serial=None)

Opens communication with the device.

Must be called before before any communication can happen with the device. If serial is specified, open the first device in which the string serial is found in the devices serial number.

Parameters: serial (str) – Opens the first device where the string serial is a substring of the device’s serial number. ripy.NoDeviceError – If no device is found.
Device.close()

Closes the device. After called all commands communicating with the device will fail and raise a NoDeviceError.

Device.isopen()

Checks if the device is open.

Returns: If the device is open. bool

## High-speed data collection¶

Currently, the only method for high-speed data collection that is available is the blocking method analogous to ri_get_raw_data() which collects a predetermined number of samples. For streaming continuous data, libri and ri_start_continuous_transfer() must be used.

Device.get_raw_data(nsamples, mask=True)

Collects raw adc samples from the device.

Parameters: nsamples (int) – number of samples to collect mask (bool) – If true, zeros the highest 2 bits of the samples such that only the 14 bits sampled by the ADC are returned. trig_mode (str) – If triggering, combined with trig_port, determines when sample acquisition starts. Possible values are: "rising" triggered on a Low to High transition "falling" triggered on a High to Low transition "high" triggered when the port is High "low" triggered when the port is Low trig_port (str) – If triggering, determines which port the trigger signal is searched for on. Possible values are: "S" port S "T" port T samples_per_trigger (int) – If specified, on trigger, record only samples_per_trigger samples at a time. The function then waits for another trigger signal. This repeats until all nsamples samples are aquired. Requires trig_mode and trig_port to be specified. A numpy array of unsigned 16 bit ints containing the ADC samples measured. numpy array Error – An error occured.
Device.get_calibrated_data(self, nsamples, calibrationtype="auto")

Collect samples from the device, calibrated to units of uW. If wavelength is specified, use the internal photodiode response curve to calibrate the power at a given wavelength, otherwise calibrate to power at peak responsivity.

Parameters: nsamples (int) – Number of samples to Collect wavelength (int or None) – Wavelength (in nm) of input light used to calibrate power. **kwargs – Additional named arguments to pass to get_raw_data() internally. A numpy array of calibrated samples, with units uW. array

## Querying device parameters¶

Unlike libri which uses the ri_get_() series of functions to retrieve parameters, ripy implements the parameters as properties of Device.

For example, to read the serial number of a device, rather then using a get_serial() method, you would just read Device.serial.

Device.serial

The serial number of the device.

Device.product

The product name of the device.

Device.fwversion

Get the firmware version

Returns: The firmware version as a 3-tuple (tuple)

Device.samplerate

The sample rate of the device.

Device.adcbits

The number of ADC sampling bits of the device.

Device.usb_speed

The current usb connection speed as a string.

valid responses are:
• "unknown"
• "low"
• "full"
• "high"
• "super"

Device.peak_responsivity

The peak wavelength responsivity (in nm) of the photodiode in the device.

Device.get_rel_responsivity()

Get the relative responsivity from the peak responsivity for a given wavelength.

Parameters: wavelength (float) – Wavelength to calculate relative responsivity at (in nm) relative responsivity, between 0 and 1. float
Device.get_calibration(self, calibrationtype="auto")

Get a stored calibration. The calibrations are from native detector units (ADC code or Volts) to uW of power at the peak sensitivity of the photodiode.

Valid calibrationtypes are:

• "digital lowgain"
• "digital highgain"
• "analog lowgain"
• "analog highgain"
• "auto"

The calibration is returned as a two-item numpy array in the same format as numpy polynomials, such that, for instance, numpy.poly1d() can be used to convert the returned polynomial to a function.

The calibration can be used such that the calibrated value, Y, can be found from the uncalibrated value, X, with

Y = calibration[0]*X + calibration[1].
Parameters: calibrationtype – A valid calibration type the calibration array
Device.get_rel_calibration(self, wavelength, calibrationtype="auto")

Get a stored calibration, but adjusted to uW of power at a specific wavelength. The returned format is the same as get_calibration() .

Parameters: calibrationtype – A valid calibration type (see get_calibration()) wavelength (float) – wavelength (in nm) to calculate the calibration at
Device.highgain

Control the highgain feature of the DPD80

Controls wether the transimpedance amplifier is in highgain mode or lowgain mode. See ri_set_highgain().

Device.antialias

Control the antialias feature of the DPD80

Controls wether the antialiasign filter is enabled. See ri_set_antialias().

Device.powerdown

Control the powerdown feature of the DPD80

Controls wether the analog circuitry is powered down. See ri_set_powerdown().

Device.adcclock

Control the adcclock feature of the DPD80

Controls wether the ADC clock is enabled. See ri_set_adcclock().

## Using the DPD80 ports¶

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

The first argument of each of these methods is the port to control. This is specified by using one of the following strings:

• "A"
• "B"
• "S"
• "T"
Device.port_drive(self, port, value)

Drive a logic signal to a port.

Parameters: port – A valid port string value (bool) – Logic level to drive the port at
Device.port_read(self, port)

Read the logic level applied to the port.

Parameters: port – A valid port string The measured logic level bool
Device.port_pwm(self, port, threshold, period)

Drive a square wave on the port.

Parameters: port – A valid port string threshold (int) – The length of time during the cycle the port is High, in ~5 ns clock cycles. period (int) – The period of the square wave, in ~5 ns clock cycles.
Device.port_pulse(self, port, threshold)

Drive a single pulse on the port. This drives the port High for threshold clock cycles (~5 ns).

Parameters: port – A valid port string threshold (int) – The length of time to pulse the port High, in ~5 ns clock cycles.

## Miscellaneous functions¶

Device.reset()

Resets the attached device.

ripy.version()

Returns the version of libri used with ripy

## Error handling¶

Unlike libri which returns statuses indicating if an error occured which need to be checked, when using ripy assumes everything works, but raises an ripy.Error if an error occurs. The ripy.Error gives more information about the underlying libri error when converted to a string.

class ripy.Error

A class representing an libri error. This is raised whenever libri gives and error in it’s oporation.

It has two attributes, err and errstr which are the libri error code and error strings returned by ri_get_error() and ri_get_error_string() respectfully.