Internal API

Classes which regular users should not need to use directly are documented here.

Serial handler

Low-level communication for PSLab.

Example

>>> from pslab.serial_handler import SerialHandler
>>> device = SerialHandler()
>>> version = device.get_version()
>>> device.disconnect()

class pslab.serial_handler.ADCBufferMixin

Bases: object

Mixin for classes that need to read or write to the ADC buffer.

clear_buffer(samples: int, starting_position: int = 0)

Clear a section of the ADC buffer.

Parameters

• samples (int) – Number of samples to clear from the buffer.

• starting_position (int, optional) – Location in the ADC buffer to start from. By default samples will be cleared from the beginning of the buffer.

fetch_buffer(samples: int, starting_position: int = 0)

Fetch a section of the ADC buffer.

Parameters

• samples (int) – Number of samples to fetch.

• starting_position (int, optional) – Location in the ADC buffer to start from. By default samples will be fetched from the beginning of the buffer.

Returns

received – List of received samples.

Return type

list of int

fill_buffer(data: List[int], starting_position: int = 0)

Fill a section of the ADC buffer with data.

Parameters

• data (list of int) – Values to write to the ADC buffer.

• starting_position (int, optional) – Location in the ADC buffer to start from. By default writing will start at the beginning of the buffer.

class pslab.serial_handler.MockHandler(port: Optional[str] = None, baudrate: int = 1000000, timeout: float = 1.0)

Bases: pslab.serial_handler.SerialHandler

Mock implementation of SerialHandler for testing.

:param Same as SerialHandler.:

VERSION = 'PSLab vMOCK'

static check_serial_access_permission()

See SerialHandler.check_serial_access_permission().

connect(port: Optional[str] = None, baudrate: int = 1000000, timeout: float = 1.0)

See SerialHandler.connect().

disconnect()

See SerialHandler.disconnect().

get_version() → str

Return mock version.

read(number_of_bytes: int) → bytes

Mimic the behavior of the serial bus by returning recorded RX traffic.

The returned data depends on how write() was called prior to calling read().

See also SerialHandler.read().

reconnect(port: Optional[str] = None, baudrate: Optional[int] = None, timeout: Optional[float] = None)

See SerialHandler.reconnect().

wait_for_data(timeout: float = 0.2) → bool

Return True if there is data in buffer, or return False after timeout.

write(data: bytes)

Add recorded RX data to buffer if written data equals recorded TX data.

See also SerialHandler.write().

pslab.serial_handler.RECORDED_TRAFFIC = <list_iterator object>

An iterator returning (request, response) pairs.

The request is checked against data written to the dummy serial port, and if it matches the response can be read back. Both request and response should be bytes-like.

Intended to be monkey-patched by the calling test module.

class pslab.serial_handler.SerialHandler(port: Optional[str] = None, baudrate: int = 1000000, timeout: float = 1.0)

Bases: object

Provides methods for communicating with the PSLab hardware.

When instantiated, SerialHandler tries to connect to the PSLab. A port can optionally be specified; otherwise Handler will try to find the correct port automatically.

:param See connect().:

static check_serial_access_permission()

Check that we have permission to use the tty on Linux.

connect(port: Optional[str] = None, baudrate: int = 1000000, timeout: float = 1.0)

Connect to PSLab.

Parameters

• port (str, optional) – The name of the port to which the PSLab is connected as a string. On Posix this is a path, e.g. “/dev/ttyACM0”. On Windows, it’s a numbered COM port, e.g. “COM5”. Will be autodetected if not specified. If multiple PSLab devices are connected, port must be specified.

• baudrate (int, optional) – Symbol rate in bit/s. The default value is 1000000.

• timeout (float, optional) – Time in seconds to wait before cancelling a read or write command. The default value is 1.0.

Raises

• SerialException – If connection could not be established.

• RuntimeError – If ultiple devices are connected and no port was specified.

disconnect()

Disconnect from PSLab.

get_ack() → int

Get response code from PSLab.

Returns

Response code. Meanings:

0x01 ACK 0x10 I2C ACK 0x20 I2C bus collision 0x10 Radio max retransmits 0x20 Radio not present 0x40 Radio reply timout

Return type

int

get_version() → str

Query PSLab for its version and return it as a decoded string.

Returns

Version string.

Return type

str

read(number_of_bytes: int) → bytes

Log incoming bytes.

Wrapper for Serial.read().

Parameters

number_of_bytes (int) – Number of bytes to read from the serial port.

Returns

Bytes read from the serial port.

Return type

bytes

reconnect(port: Optional[str] = None, baudrate: Optional[int] = None, timeout: Optional[float] = None)

Reconnect to PSLab.

Will reuse previous settings (port, baudrate, timeout) unless new ones are provided.

:param See connect().:

wait_for_data(timeout: float = 0.2) → bool

Wait for :timeout: seconds or until there is data in the input buffer.

Parameters

timeout (float, optional) – Time in seconds to wait. The default is 0.2.

Returns

True iff the input buffer is not empty.

Return type

bool

write(data: bytes)

Log outgoing bytes.

Wrapper for Serial.write().

Parameters

data (int) – Bytes to write to the serial port.

pslab.serial_handler.detect()

Detect connected PSLab devices.

Returns

devices – Dictionary containing port name as keys and device version on that port as values.

Return type

dict of str: str

Analog channels

Objects related to the PSLab’s analog input channels.

This module contains several module level variables with details on the analog inputs’ capabilities, including possible gain values, voltage ranges, and firmware-interal enumeration.

This module also contains the AnalogInput class, an instance of which functions as a model of a particular analog input.

class pslab.instrument.analog.AnalogInput(name: str)

Bases: object

Model of the PSLab’s analog inputs, used to scale raw values to voltages.

Parameters

name ({'CH1', 'CH2', 'CH3', 'MIC', 'CAP', 'RES', 'VOL'}) – Name of the analog channel to model.

samples_in_buffer

Number of samples collected on this channel currently being held in the device’s ADC buffer.

Type

int

buffer_idx

Location in the device’s ADC buffer where the samples are stored. None if no samples captured by this channel are currently held in the buffer.

Type

int or None

chosa

Number used to refer to this channel in the firmware.

Type

int

property gain

Analog gain.

Setting a new gain level will automatically recalibrate the channel. On channels other than CH1 and CH2 gain is None.

Raises

• TypeError – If gain is set on a channel which does not support it.

• ValueError – If a gain value other than 1, 2, 4, 5, 8, 10, 16, 32 is set.

Type

int

property resolution

Resolution in bits.

Setting a new resolution will automatically recalibrate the channel.

Raises

ValueError – If a resolution other than 10 or 12 is set.

Type

int

scale(raw: Union[int, List[int]]) → float

Translate raw integer value from device to corresponding voltage.

Inverse of unscale().

Parameters

raw (int, List[int]) – An integer, or a list of integers, received from the device.

Returns

Voltage, translated from raw based on channel range, gain, and resolution.

Return type

float

unscale(voltage: float) → int

Translate a voltage to a raw integer value interpretable by the device.

Inverse of scale().

Parameters

voltage (float) – Voltage in volts.

Returns

Corresponding integer value, adjusted for resolution and gain and clipped to the channel’s range.

Return type

int

class pslab.instrument.analog.AnalogOutput(name)

Bases: object

Model of the PSLab’s analog outputs.

Parameters

name (str) – Name of the analog output pin represented by this instance.

frequency

Frequency of the waveform on this pin in Hz.

Type

float

wavetype

Type of waveform on this pin. ‘sine’ is a sine wave with amplitude 3.3 V, ‘tria’ is a triangle wave with amplitude 3.3 V, ‘custom’ is any other waveform set with load_function() or load_table().

Type

{‘sine’, ‘tria’, ‘custom’}

RANGE = (-3.3, 3.3)

property lowres_waveform_table

32-value waveform table loaded on this output.

Type

numpy.ndarray

property waveform_table

512-value waveform table loaded on this output.

Type

numpy.ndarray

Digital channels

Objects related to the PSLab’s digital input channels.

class pslab.instrument.digital.DigitalInput(name: str)

Bases: object

Model of the PSLab’s digital inputs.

Parameters

name ({"LA1", "LA2", "LA3", "LA4", "RES", "FRQ"}) – Name of the digital channel to model.

name

One of {“LA1”, “LA2”, “LA3”, “LA4”, “RES”, “FRQ”}.

Type

str

number

Number used to refer to this channel in the firmware.

Type

int

datatype

Either “int” or “long”, depending on if a 16 or 32-bit counter is used to capture timestamps for this channel.

Type

str

events_in_buffer

Number of logic events detected on this channel, the timestamps of which are currently being held in the device’s ADC buffer.

Type

int

buffer_idx

Location in the device’s ADC buffer where the events are stored. None if no events captured by this channel are currently held in the buffer.

Type

Union[int, None]

property logic_mode

Type of logic event which should be captured on this channel.

The options are:

any: Capture every edge. rising: Capture every rising edge. falling: Capture every falling edge. four rising: Capture every fourth rising edge. sixteen rising: Capture every fourth rising edge.

Type

str

class pslab.instrument.digital.DigitalOutput(name: str)

Bases: object

Model of the PSLab’s digital outputs.

Parameters

name ({'SQ1', 'SQ2', 'SQ3', 'SQ4'}) – Name of the digital output pin represented by the instance.

property duty_cycle

Duty cycle of the PWM signal on this pin.

Type

float

property name

Name of this pin.

Type

str

property reference_clock_map

Reference clock map value for this pin.

The reference clock map is used in the WAVEGEN->MAP_REFERENCE command to map a digital output pin directly to the interal oscillator. This can be used to achieve very high frequencies, with the caveat that the only frequencies available are quotients of 128 MHz and powers of 2 up to 15. For example, sending (2 | 4) followed by 3 outputs 128 / (1 << 3) = 16 MHz on SQ2 and SQ3.

Type

int

property state

State of the digital output. Can be ‘HIGH’, ‘LOW’, or ‘PWM’.

Type

str

property state_mask

State mask for this pin.

The state mask is used in the DOUT->SET_STATE command to set the digital output pins HIGH or LOW. For example:

0x10 | 1 << 0 | 0x40 | 0 << 2 | 0x80 | 1 << 3

would set SQ1 and SQ4 HIGH, SQ3 LOW, and leave SQ2 unchanged.

Type

int

Sources

class pslab.instrument.power_supply.Source(mcp4728: pslab.bus.i2c.I2CSlave, name: str)

Bases: object

Base class for voltage/current/power sources.

scale(raw: int) → float

Convert an integer value to a voltage value.

Parameters

raw (int) – Integer representation of a voltage value.

Returns

voltage – Voltage in Volt.

Return type

float

unscale(voltage: float) → int

Return integer representation of a voltage.

Parameters

voltage (float) – Voltage in Volt.

Returns

raw – Integer represention of the voltage.

Return type

int

class pslab.instrument.power_supply.VoltageSource(mcp4728: pslab.bus.i2c.I2CSlave, name: str)

Bases: pslab.instrument.power_supply.Source

Helper class for interfacing with PV1, PV2, and PV3.

property voltage

Most recent voltage set on PVx in Volt.

The voltage on PVx can be set by writing to this attribute.

Type

float

class pslab.instrument.power_supply.CurrentSource(mcp4728: pslab.bus.i2c.I2CSlave)

Bases: pslab.instrument.power_supply.Source

Helper class for interfacing with PCS.

property current

Most recent current value set on PCS in Ampere.

The current on PCS can be set by writing to this attribute.

Type

float