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, trig_mode=None, trig_port=None, arm_time=10, samples_per_trigger=None)

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

  • arm_time (int) – If triggering, determines how many samples to wait in the untriggered state before allowing triggering. This prevents undesired triggering on noisy edges.

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

Type

str

Device.product

The product name of the device.

Read only.

Type

str

Device.fwversion

Get the firmware version as a 3-tuple

Read only.

Type

tuple

Device.samplerate

The sample rate of the device.

Read only.

Type

int

Device.adcbits

The number of ADC sampling bits of the device.

Read only.

Type

int

Device.usb_speed

The current usb connection speed as a string.

valid responses are:

  • "unknown"

  • "low"

  • "full"

  • "high"

  • "super"

Read only.

Type

str

Device.peak_responsivity

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

Read only.

Type

int

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, type='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 types are:

  • "auto"

  • "digital lowgain" (non-balanced only)

  • "digital highgain" (non-balanced only)

  • "analog lowgain" (non-balanced only)

  • "analog highgain" (non-balanced only)

  • "bal digital" (balanced only)

  • "bal analog" (balanced only)

  • "i1 digital" (balanced only)

  • "i1 analog" (balanced only)

  • "i2 digital" (balanced only)

  • "i2 analog" (balanced only)

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, type='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

  • type – A valid calibration type (see get_calibration())

  • wavelength (float) – wavelength (in nm) to calculate the calibration at

Returns

the calibration

Return type

array

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.

Type

bool

Device.antialias

Control the antialias feature of the DPD80

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

Readable and Writeable.

Type

bool

Device.powerdown

Control the powerdown feature of the DPD80

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

Readable and Writeable.

Type

bool

Device.adcclock

Control the adcclock feature of the DPD80

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

Readable and Writeable.

Type

bool

Device.p1_select

Control the p1_select feature of the DPD80 Balanced photodetector. (DPD80 Balanced Photodetector only)

p1_select enables the analog power monitor output of the P1 photodiode to port “S” on the the DPD80 Balanced Photodetector.

When p1_select is True, an analog signal monitoring the output of the respective photodiode is output on port “S”.

When p1_select is False, port “S” acts as a high speed digital input that can be read with ripy.Device.get_raw_data() with mask=False which records port “S” as the 15th bit in each sample.

Readable and Writeable.

Type

bool

Device.p2_select

Control the p2_select feature of the DPD80 Balanced photodetector. (DPD80 Balanced Photodetector only)

p2_select enables the analog power monitor output of the P1 photodiode to port “T” on the the DPD80 Balanced Photodetector.

When p2_select is True, an analog signal monitoring the output of the respective photodiode is output on port “T”.

When p2_select is False, port “T” acts as a high speed digital input that can be read with ripy.Device.get_raw_data() with mask=False which records port “T” as the 16th bit in each sample.

Readable and Writeable.

Type

bool

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"

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 p1_select and p2_select properties.

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(msg=None)

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.