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.
Raises:

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.
Raises: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.
Return type: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.

Returns:

A numpy array of unsigned 16 bit ints containing the ADC samples measured.

Return type:

numpy array

Raises:

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.
Returns:

A numpy array of calibrated samples, with units uW.

Return type:

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.

Read only.

Device.product

The product name of the device.

Read only.

Device.fwversion

Get the firmware version

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

Read only.

Device.samplerate

The sample rate of the device.

Read only.

Device.adcbits

The number of ADC sampling bits of the device.

Read only.

Device.usb_speed

The current usb connection speed as a string.

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

Read only.

Device.peak_responsivity

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

Read only.

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)
Returns:relative responsivity, between 0 and 1.
Return type: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
Returns:the calibration
Return type: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().

Readable and Writeable.

Device.antialias

Control the antialias feature of the DPD80

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

Readable and Writeable.

Device.powerdown

Control the powerdown feature of the DPD80

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

Readable and Writeable.

Device.adcclock

Control the adcclock feature of the DPD80

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

Readable and Writeable.

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
Returns:The measured logic level
Return type: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.