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}
- 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:
- 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 parameterbaud=
, as in the exampleserial://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:
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:
- Returns:
Object representing the connected instrument.
See also
Serial
for description ofport
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:
- Returns:
Object representing the connected instrument.
See also
Serial
for description ofport
, 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:
- Return type:
- Returns:
Object representing the connected instrument.
See also
connect
for description ofhost
andport
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
orNone
) – The stream of data coming from the instrumentstdout (
io.BytesIO
orNone
) – 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 usingopen_file
, provided that theusbtmc
kernel module is loaded. On Windows, some such devices can be opened using the VISA library and theopen_visa
method.- Parameters:
- Return type:
- 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, theopen_file
class method will work. On Windows, using theopen_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:
- 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:
- Returns:
Object representing the connected instrument.
- 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 theinstrument, 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.
- 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:
- 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.
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 property input_range¶
Gets/sets the input range setting for the electrometer. This is an abstract method.
- Type:
- abstract property mode¶
Gets/sets the measurement mode for the electrometer. This is an abstract method.
- Type:
- abstract property trigger_mode¶
Gets/sets the trigger mode for the electrometer. This is an abstract method.
- Type:
- abstract property unit¶
Gets/sets the measurement mode for the electrometer. This is an abstract method.
- Type:
- abstract property zero_check¶
Gets/sets the zero check status for the electrometer. This is an abstract method.
- Type:
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.
- 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 afloat
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 aQuantity
and aFunctionGenerator.VoltageMode
, or aQuantity
if no voltage mode applies.
- property frequency¶
Gets/sets the the output frequency of the function generator. This is an abstract property.
- Type:
- property function¶
Gets/sets the output function mode of the function generator. This is an abstract property.
- Type:
- property offset¶
Gets/sets the output offset voltage of the function generator. This is an abstract property.
- Type:
- 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:
- 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:
- property frequency¶
Gets/sets the the output frequency of the function generator. This is an abstract property.
- Type:
- property function¶
Gets/sets the output function mode of the function generator. This is an abstract property.
- Type:
- property offset¶
Gets/sets the output offset voltage of the function generator. This is an abstract property.
- Type:
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 property input_range¶
Gets/sets the current input range setting of the multimeter. This is an abstract method.
- abstract property mode¶
Gets/sets the measurement mode for the multimeter. This is an abstract method.
- Type:
- abstract property relative¶
Gets/sets the status of relative measuring mode for the multimeter. This is an abstract method.
- Type:
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.
- 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:
- 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:
- 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:
- abstract property bandwidth¶
Gets/sets the the bandwidth of the OSA. This is an abstract property.
- Type:
- 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:
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:
- abstract property mode¶
Gets/sets the output mode for the power supply channel. This is an abstract method.
- Type:
- abstract property output¶
Gets/sets the output status for the power supply channel. This is an abstract method.
- Type:
- 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:
- abstract property current¶
Gets/sets the output current for all channel on the power supply. This is an abstract method.
- Type:
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: