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.

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, **kwargs)[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.
kwargs – Additional keyword arguments that will be passed on to serial, e.g., parity.

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.

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-F}{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.

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.

abstractmethod fetch()[source]: Request the latest post-processed readings using the current mode. (So does not issue a trigger)

abstractmethod 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 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(*values)[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(*values)[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 accessible depends on the value of FunctionGenerator._channel_count

Return type:: FunctionGenerator.Channel

property frequency

Gets/sets 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.

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

abstractmethod 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

abstractmethod 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(*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(parent, name)[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.

Optical spectrum analyzers 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.

abstractmethod 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

abstractmethod 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

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

abstractmethod start_sweep()[source]: Forces a start sweep on the attached OSA.

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

property bandwidth

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

Type:: Quantity

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.

property start_wl

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

Type:: Quantity

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

Instrument Base Classes

Instrument - Base class for instrument communication

Electrometer - Abstract class for electrometer instruments

FunctionGenerator - Abstract class for function generator instruments

Multimeter - Abstract class for multimeter instruments

Oscilloscope - Abstract class for oscilloscope instruments

OpticalSpectrumAnalyzer - Abstract class for optical spectrum analyzer instruments

PowerSupply - Abstract class for power supply instruments

SignalGenerator - Abstract class for Signal Generators

SingleChannelSG - Class for Signal Generators with a Single Channel

SGChannel - Abstract class for Signal Generator Channels

`Instrument` - Base class for instrument communication

`Electrometer` - Abstract class for electrometer instruments

`FunctionGenerator` - Abstract class for function generator instruments

`Multimeter` - Abstract class for multimeter instruments

`Oscilloscope` - Abstract class for oscilloscope instruments

`OpticalSpectrumAnalyzer` - Abstract class for optical spectrum analyzer instruments

`PowerSupply` - Abstract class for power supply instruments

`SignalGenerator` - Abstract class for Signal Generators

`SingleChannelSG` - Class for Signal Generators with a Single Channel

`SGChannel` - Abstract class for Signal Generator Channels