Instrument Base Classes

Instrument - Base class for instrument communication

class instruments.Instrument(filelike, *args, **kwargs)[source]

This is the base instrument class from which all others are derived from. It provides the basic implementation for all communication related tasks. In addition, it also contains several class methods for opening connections via the supported hardware channels.

binblockread(data_width, fmt=None)[source]

” Read a binary data block from attached instrument. This requires that the instrument respond in a particular manner as EOL terminators naturally can not be used in binary transfers.

The format is as follows: #{number of following digits:1-9}{num of bytes to be read}{data bytes}

Parameters:
  • data_width (int) – Specify the number of bytes wide each data point is. One of [1,2,4].

  • fmt (str) – Format string as specified by the struct module, or None to choose a format automatically based on the data width. Typically you can just specify data_width and leave this default.

classmethod open_file(filename)[source]

Given a file, treats that file as a character device file that can be read from and written to in order to communicate with the instrument. This may be the case, for instance, if the instrument is connected by the Linux usbtmc kernel driver.

Parameters:

filename (str) – Name of the character device to open.

Return type:

Instrument

Returns:

Object representing the connected instrument.

classmethod open_from_uri(uri)[source]

Given an instrument URI, opens the instrument named by that URI. Instrument URIs are formatted with a scheme, such as serial://, followed by a location that is interpreted differently for each scheme. The following examples URIs demonstrate the currently supported schemes and location formats:

serial://COM3
serial:///dev/ttyACM0
tcpip://192.168.0.10:4100
gpib+usb://COM3/15
gpib+serial://COM3/15
gpib+serial:///dev/ttyACM0/15 # Currently non-functional.
visa://USB::0x0699::0x0401::C0000001::0::INSTR
usbtmc://USB::0x0699::0x0401::C0000001::0::INSTR
test://

For the serial URI scheme, baud rates may be explicitly specified using the query parameter baud=, as in the example serial://COM9?baud=115200. If not specified, the baud rate is assumed to be 115200.

Parameters:

uri (str) – URI for the instrument to be loaded.

Return type:

Instrument

See also

PySerial documentation for serial port URI format

classmethod open_gpibethernet(host, port, gpib_address, model='pl')[source]

Opens an instrument, connecting via a Prologix GPIBETHERNET adapter.

Parameters:
  • host (str) – Name or IP address of the instrument.

  • port (int) – TCP port on which the insturment is listening.

  • gpib_address (int) – Address on the connected GPIB bus assigned to the instrument.

  • model (str) – The brand of adapter to be connected to. Currently supported is “gi” for Galvant Industries, and “pl” for Prologix LLC.

Warning

This function has been setup for use with the Prologix GPIBETHERNET adapter but has not been tested as confirmed working.

classmethod open_gpibusb(port, gpib_address, timeout=3, write_timeout=3, model='gi')[source]

Opens an instrument, connecting via a Galvant Industries GPIB-USB adapter.

Parameters:
  • port (str) – Name of the the port or device file to open a connection on. Note that because the GI GPIB-USB adapter identifies as a serial port to the operating system, this should be the name of a serial port.

  • gpib_address (int) – Address on the connected GPIB bus assigned to the instrument.

  • timeout (float) – Number of seconds to wait when reading from the instrument before timing out.

  • write_timeout (float) – Number of seconds to wait when writing to the instrument before timing out.

  • model (str) – The brand of adapter to be connected to. Currently supported is “gi” for Galvant Industries, and “pl” for Prologix LLC.

Return type:

Instrument

Returns:

Object representing the connected instrument.

See also

Serial for description of port and timeouts.

classmethod open_serial(port=None, baud=9600, vid=None, pid=None, serial_number=None, timeout=3, write_timeout=3)[source]

Opens an instrument, connecting via a physical or emulated serial port. Note that many instruments which connect via USB are exposed to the operating system as serial ports, so this method will very commonly be used for connecting instruments via USB.

This method can be called by either supplying a port as a string, or by specifying vendor and product IDs, and an optional serial number (used when more than one device with the same IDs is attached). If both the port and IDs are supplied, the port will default to the supplied port string, else it will search the available com ports for a port matching the defined IDs and serial number.

Parameters:
  • port (str) – Name of the the port or device file to open a connection on. For example, "COM10" on Windows or "/dev/ttyUSB0" on Linux.

  • baud (int) – The baud rate at which instrument communicates.

  • vid (int) – the USB port vendor id.

  • pid (int) – the USB port product id.

  • serial_number (str) – The USB port serial_number.

  • timeout (float) – Number of seconds to wait when reading from the instrument before timing out.

  • write_timeout (float) – Number of seconds to wait when writing to the instrument before timing out.

Return type:

Instrument

Returns:

Object representing the connected instrument.

See also

Serial for description of port, baud rates and timeouts.

classmethod open_tcpip(host, port, auth=None)[source]

Opens an instrument, connecting via TCP/IP to a given host and TCP port.

Parameters:
  • host (str) – Name or IP address of the instrument.

  • port (int) – TCP port on which the insturment is listening.

  • auth – Authentication credentials to establish connection. Type depends on instrument and authentication method used.

Return type:

Instrument

Returns:

Object representing the connected instrument.

See also

connect for description of host and port parameters in the TCP/IP address family.

classmethod open_test(stdin=None, stdout=None)[source]

Opens an instrument using a loopback communicator for a test connection. The primary use case of this is to instantiate a specific instrument class without requiring an actual physical connection of any kind. This is also very useful for creating unit tests through the parameters of this class method.

Parameters:
  • stdin (io.BytesIO or None) – The stream of data coming from the instrument

  • stdout (io.BytesIO or None) – Empty data stream that will hold data sent from the Python class to the loopback communicator. This can then be checked for the contents.

Returns:

Object representing the virtually-connected instrument

classmethod open_usb(vid, pid)[source]

Opens an instrument, connecting via a raw USB stream.

Note

Note that raw USB a very uncommon of connecting to instruments, even for those that are connected by USB. Most will identify as either serial ports (in which case, open_serial should be used), or as USB-TMC devices. On Linux, USB-TMC devices can be connected using open_file, provided that the usbtmc kernel module is loaded. On Windows, some such devices can be opened using the VISA library and the open_visa method.

Parameters:
  • vid (str) – Vendor ID of the USB device to open.

  • pid (str) – Product ID of the USB device to open.

Return type:

Instrument

Returns:

Object representing the connected instrument.

classmethod open_usbtmc(*args, **kwargs)[source]

Opens an instrument, connecting to a USB-TMC device using the Python usbtmc library.

Warning

The operational status of this is unknown. It is suggested that you connect via the other provided class methods. For Linux, if you have the usbtmc kernel module, the open_file class method will work. On Windows, using the open_visa class method along with having the VISA libraries installed will work.

Returns:

Object representing the connected instrument

classmethod open_visa(resource_name)[source]

Opens an instrument, connecting using the VISA library. Note that PyVISA and a VISA implementation must both be present and installed for this method to function.

Parameters:

resource_name (str) – Name of a VISA resource representing the given instrument.

Return type:

Instrument

Returns:

Object representing the connected instrument.

classmethod open_vxi11(*args, **kwargs)[source]

Opens a vxi11 enabled instrument, connecting using the python library python-vxi11. This package must be present and installed for this method to function.

Return type:

Instrument

Returns:

Object representing the connected instrument.

query(cmd, size=-1)[source]

Executes the given query.

Parameters:
  • cmd (str) – String containing the query to execute.

  • size (int) – Number of bytes to be read. Default is read until termination character is found.

Returns:

The result of the query as returned by the connected instrument.

Return type:

str

read(size=-1, encoding='utf-8')[source]

Read the last line.

Parameters:

size (int) – Number of bytes to be read. Default is read until termination character is found.

Returns:

The result of the read as returned by the connected instrument.

Return type:

str

read_raw(size=-1)[source]

Read the raw last line.

Parameters:

size (int) – Number of bytes to be read. Default is read until termination character is found.

Returns:

The result of the read as returned by the connected instrument.

Return type:

str

sendcmd(cmd)[source]

Sends a command without waiting for a response.

Parameters:

cmd (str) – String containing the command to be sent.

write(msg)[source]

Write data string to the connected instrument. This will call the write method for the attached filelike object. This will typically bypass attaching any termination characters or other communication channel related work.

See also

Instrument.sendcmd if you wish to send a string to the

instrument, while still having InstrumentKit handle termination characters and other communication channel related work.

Parameters:

msg (str) – String that will be written to the filelike object (Instrument._file) attached to this instrument.

URI_SCHEMES = ['serial', 'tcpip', 'gpib+usb', 'gpib+serial', 'visa', 'file', 'usbtmc', 'vxi11', 'test']
property address

Gets/sets the target communication of the instrument.

This is useful for situations when running straight from a Python shell and your instrument has enumerated with a different address. An example when this can happen is if you are using a USB to Serial adapter and you disconnect/reconnect it.

Type:

int for GPIB address, str for other

property prompt

Gets/sets the prompt used for communication.

The prompt refers to a character that is sent back from the instrument after it has finished processing your last command. Typically this is used to indicate to an end-user that the device is ready for input when connected to a serial-terminal interface.

In IK, the prompt is specified that that it (and its associated termination character) are read in. The value read in from the device is also checked against the stored prompt value to make sure that everything is still in sync.

Type:

str

property terminator

Gets/sets the terminator used for communication.

For communication options where this is applicable, the value corresponds to the ASCII character used for termination in decimal format. Example: 10 sets the character to NEWLINE.

Type:

int, or str for GPIB adapters.

property timeout

Gets/sets the communication timeout for this instrument. Note that setting this value after opening the connection is not supported for all connection types.

Type:

int

Electrometer - Abstract class for electrometer instruments

class instruments.abstract_instruments.Electrometer(filelike, *args, **kwargs)[source]

Abstract base class for electrometer instruments.

All applicable concrete instruments should inherit from this ABC to provide a consistent interface to the user.

abstract fetch()[source]

Request the latest post-processed readings using the current mode. (So does not issue a trigger)

abstract read_measurements()[source]

Trigger and acquire readings using the current mode.

abstract property input_range

Gets/sets the input range setting for the electrometer. This is an abstract method.

Type:

Enum

abstract property mode

Gets/sets the measurement mode for the electrometer. This is an abstract method.

Type:

Enum

abstract property trigger_mode

Gets/sets the trigger mode for the electrometer. This is an abstract method.

Type:

Enum

abstract property unit

Gets/sets the measurement mode for the electrometer. This is an abstract method.

Type:

Unit

abstract property zero_check

Gets/sets the zero check status for the electrometer. This is an abstract method.

Type:

bool

abstract property zero_correct

Gets/sets the zero correct status for the electrometer. This is an abstract method.

Type:

bool

FunctionGenerator - Abstract class for function generator instruments

class instruments.abstract_instruments.FunctionGenerator(filelike)[source]

Abstract base class for function generator instruments.

All applicable concrete instruments should inherit from this ABC to provide a consistent interface to the user.

class Channel(parent, name)[source]

Abstract base class for physical channels on a function generator.

All applicable concrete instruments should inherit from this ABC to provide a consistent interface to the user.

Function generators that only have a single channel do not need to define their own concrete implementation of this class. Ones with multiple channels need their own definition of this class, where this class contains the concrete implementations of the below abstract methods. Instruments with 1 channel have their concrete implementations at the parent instrument level.

query(cmd, size=-1)[source]
sendcmd(cmd)[source]
property amplitude

Gets/sets the output amplitude of the function generator.

If set with units of \(\text{dBm}\), then no voltage mode can be passed.

If set with units of \(\text{V}\) as a Quantity or a float without a voltage mode, then the voltage mode is assumed to be peak-to-peak.

Units:

As specified, or assumed to be \(\text{V}\) if not specified.

Type:

Either a tuple of a Quantity and a FunctionGenerator.VoltageMode, or a Quantity if no voltage mode applies.

property frequency

Gets/sets the the output frequency of the function generator. This is an abstract property.

Type:

Quantity

property function

Gets/sets the output function mode of the function generator. This is an abstract property.

Type:

Enum

property offset

Gets/sets the output offset voltage of the function generator. This is an abstract property.

Type:

Quantity

property phase

Gets/sets the output phase of the function generator. This is an abstract property.

Type:

Quantity

class Function(value)[source]

Enum containg valid output function modes for many function generators

arbitrary = 'ARB'
noise = 'NOIS'
ramp = 'RAMP'
sinusoid = 'SIN'
square = 'SQU'
triangle = 'TRI'
class VoltageMode(value)[source]

Enum containing valid voltage modes for many function generators

dBm = 'DBM'
peak_to_peak = 'VPP'
rms = 'VRMS'
property amplitude

Gets/sets the output amplitude of the first channel of the function generator

Type:

Quantity

property channel

Gets a channel object for the function generator. This should use ProxyList to achieve this.

The number of channels accessable depends on the value of FunctionGenerator._channel_count

Return type:

FunctionGenerator.Channel

property frequency

Gets/sets the the output frequency of the function generator. This is an abstract property.

Type:

Quantity

property function

Gets/sets the output function mode of the function generator. This is an abstract property.

Type:

Enum

property offset

Gets/sets the output offset voltage of the function generator. This is an abstract property.

Type:

Quantity

property phase

Gets/sets the output phase of the function generator. This is an abstract property.

Type:

Quantity

Multimeter - Abstract class for multimeter instruments

class instruments.abstract_instruments.Multimeter(filelike, *args, **kwargs)[source]

Abstract base class for multimeter instruments.

All applicable concrete instruments should inherit from this ABC to provide a consistent interface to the user.

abstract measure(mode)[source]

Perform a measurement as specified by mode parameter.

abstract property input_range

Gets/sets the current input range setting of the multimeter. This is an abstract method.

Type:

Quantity or Enum

abstract property mode

Gets/sets the measurement mode for the multimeter. This is an abstract method.

Type:

Enum

abstract property relative

Gets/sets the status of relative measuring mode for the multimeter. This is an abstract method.

Type:

bool

abstract property trigger_mode

Gets/sets the trigger mode for the multimeter. This is an abstract method.

Type:

Enum

Oscilloscope - Abstract class for oscilloscope instruments

class instruments.abstract_instruments.Oscilloscope(filelike, *args, **kwargs)[source]

Abstract base class for oscilloscope instruments.

All applicable concrete instruments should inherit from this ABC to provide a consistent interface to the user.

class Channel[source]

Abstract base class for physical channels on an oscilloscope.

All applicable concrete instruments should inherit from this ABC to provide a consistent interface to the user.

abstract property coupling

Gets/sets the coupling setting for the oscilloscope. This is an abstract method.

Type:

Enum

class DataSource(parent, name)[source]

Abstract base class for data sources (physical channels, math, ref) on an oscilloscope.

All applicable concrete instruments should inherit from this ABC to provide a consistent interface to the user.

abstract read_waveform(bin_format=True)[source]

Gets the waveform of the specified data source channel. This is an abstract property.

Parameters:

bin_format (bool) – If the waveform should be transfered in binary (True) or ASCII (False) formats.

Returns:

The waveform with both x and y components.

Return type:

numpy.ndarray

abstract property name

Gets the name of the channel. This is an abstract property.

Type:

str

abstract force_trigger()[source]

Forces a trigger event to occur on the attached oscilloscope.

abstract property channel

Gets an iterator or list for easy Pythonic access to the various channel objects on the oscilloscope instrument. Typically generated by the ProxyList helper.

abstract property math

Gets an iterator or list for easy Pythonic access to the various math data sources objects on the oscilloscope instrument. Typically generated by the ProxyList helper.

abstract property ref

Gets an iterator or list for easy Pythonic access to the various ref data sources objects on the oscilloscope instrument. Typically generated by the ProxyList helper.

OpticalSpectrumAnalyzer - Abstract class for optical spectrum analyzer instruments

class instruments.abstract_instruments.OpticalSpectrumAnalyzer(filelike, *args, **kwargs)[source]

Abstract base class for optical spectrum analyzer instruments.

All applicable concrete instruments should inherit from this ABC to provide a consistent interface to the user.

class Channel[source]

Abstract base class for physical channels on an optical spectrum analyzer.

All applicable concrete instruments should inherit from this ABC to provide a consistent interface to the user.

abstract data(bin_format=True)[source]

Gets the y-axis of the specified data source channel. This is an abstract property.

Parameters:

bin_format (bool) – If the waveform should be transfered in binary (True) or ASCII (False) formats.

Returns:

The y-component of the waveform.

Return type:

numpy.ndarray

abstract wavelength(bin_format=True)[source]

Gets the x-axis of the specified data source channel. This is an abstract property.

Parameters:

bin_format (bool) – If the waveform should be transfered in binary (True) or ASCII (False) formats.

Returns:

The wavelength component of the waveform.

Return type:

numpy.ndarray

abstract start_sweep()[source]

Forces a start sweep on the attached OSA.

abstract property bandwidth

Gets/sets the the bandwidth of the OSA. This is an abstract property.

Type:

Quantity

abstract property channel

Gets an iterator or list for easy Pythonic access to the various channel objects on the OSA instrument. Typically generated by the ProxyList helper.

abstract property start_wl

Gets/sets the the start wavelength of the OSA. This is an abstract property.

Type:

Quantity

abstract property stop_wl

Gets/sets the the stop wavelength of the OSA. This is an abstract property.

Type:

Quantity

PowerSupply - Abstract class for power supply instruments

class instruments.abstract_instruments.PowerSupply(filelike, *args, **kwargs)[source]

Abstract base class for power supply instruments.

All applicable concrete instruments should inherit from this ABC to provide a consistent interface to the user.

class Channel[source]

Abstract base class for power supply output channels.

All applicable concrete instruments should inherit from this ABC to provide a consistent interface to the user.

abstract property current

Gets/sets the output current for the power supply channel. This is an abstract method.

Type:

Quantity

abstract property mode

Gets/sets the output mode for the power supply channel. This is an abstract method.

Type:

Enum

abstract property output

Gets/sets the output status for the power supply channel. This is an abstract method.

Type:

bool

abstract property voltage

Gets/sets the output voltage for the power supply channel. This is an abstract method.

Type:

Quantity

abstract property channel

Gets a channel object for the power supply. This should use ProxyList to achieve this.

This is an abstract method.

Return type:

PowerSupply.Channel

abstract property current

Gets/sets the output current for all channel on the power supply. This is an abstract method.

Type:

Quantity

abstract property voltage

Gets/sets the output voltage for all channel on the power supply. This is an abstract method.

Type:

Quantity

SignalGenerator - Abstract class for Signal Generators

class instruments.abstract_instruments.signal_generator.SignalGenerator(filelike, *args, **kwargs)[source]

Python abstract base class for signal generators (eg microwave sources).

This ABC is not for function generators, which have their own separate ABC.

See also

FunctionGenerator

abstract property channel

Gets a specific channel object for the SignalGenerator.

Return type:

A class inherited from SGChannel

SingleChannelSG - Class for Signal Generators with a Single Channel

class instruments.abstract_instruments.signal_generator.SingleChannelSG(filelike, *args, **kwargs)[source]

Class for representing a Signal Generator that only has a single output channel. The sole property in this class allows for the user to use the API for SGs with multiple channels and a more compact form since it only has one output.

For example, both of the following calls would work the same:

>>> print sg.channel[0].freq # Multi-channel style
>>> print sg.freq # Compact style
property channel

Gets a specific channel object for the SignalGenerator.

Return type:

A class inherited from SGChannel

SGChannel - Abstract class for Signal Generator Channels

class instruments.abstract_instruments.signal_generator.SGChannel[source]

Python abstract base class representing a single channel for a signal generator.

Warning

This class should NOT be manually created by the user. It is designed to be initialized by the SignalGenerator class.

abstract property frequency

Gets/sets the output frequency of the signal generator channel

Type:

Quantity

abstract property output

Gets/sets the output status of the signal generator channel

Type:

bool

abstract property phase

Gets/sets the output phase of the signal generator channel

Type:

Quantity

abstract property power

Gets/sets the output power of the signal generator channel

Type:

Quantity