Instrument Base Classes¶
Instrument
- Base class for instrument communication¶
-
class
instruments.
Instrument
(filelike)[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:
-
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 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: 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: 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.- port (str) – Name of the the port or device file to open a
connection on. For example,
-
classmethod
open_tcpip
(host, port)[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 instrument - stdout (
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
- stdin (
-
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: 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: Returns: The result of the query as returned by the connected instrument.
Return type:
-
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
-
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']¶
-
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
-
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
-
Multimeter
- Abstract class for multimeter instruments¶
-
class
instruments.abstract_instruments.
Multimeter
(filelike)[source]¶ Abstract base class for multimeter instruments.
All applicable concrete instruments should inherit from this ABC to provide a consistent interface to the user.
-
input_range
¶ Gets/sets the current input range setting of the multimeter. This is an abstract method.
Type: Quantity
orEnum
-
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.
-
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.
-
frequency
¶ Gets/sets the the output frequency of the function generator. This is an abstract property.
Type: Quantity
-
function
¶ Gets/sets the output function mode of the function generator. This is an abstract property.
Type: Enum
-
offset
¶ Gets/sets the output offset voltage of the function generator. This is an abstract property.
Type: Quantity
-
phase
¶ Gets/sets the output phase of the function generator. This is an abstract property.
Type: Quantity
-
-
class
Function
[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
[source]¶ Enum containing valid voltage modes for many function generators
-
dBm
= 'DBM'¶
-
peak_to_peak
= 'VPP'¶
-
rms
= 'VRMS'¶
-
-
amplitude
¶
-
channel
¶
-
frequency
¶ Gets/sets the the output frequency of the function generator. This is an abstract property.
Type: Quantity
-
function
¶ Gets/sets the output function mode of the function generator. This is an abstract property.
Type: Enum
-
offset
¶ Gets/sets the output offset voltage of the function generator. This is an abstract property.
Type: Quantity
-
phase
¶ Gets/sets the output phase of the function generator. This is an abstract property.
Type: Quantity
-
class
SignalGenerator
- Abstract class for Signal Generators¶
-
class
instruments.abstract_instruments.signal_generator.
SignalGenerator
(filelike)[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
-
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)[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
-
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.-
frequency
¶ Gets/sets the output frequency of the signal generator channel
Type: Quantity
-
phase
¶ Gets/sets the output phase of the signal generator channel
Type: Quantity
-
power
¶ Gets/sets the output power of the signal generator channel
Type: Quantity
-