Driver Utils

class instrumental.drivers.Instrument(inst=None, **kwds)

Base class for all instruments.

_after_init()

Called just after _initialize

_before_init()

Called just before _initialize

classmethod _create(paramset, **other_attrs)

Factory method meant to be used by instrument()

_fill_out_paramset()
_initialize(**settings)
_load_state(state_path=None)

Load instrument state from a pickle file

_save_state(state_path=None)

Save instrument state to a pickle file

close()
get(facet_name, use_cache=False)
observe(name, callback)

Add a callback to observe changes in a facet’s value

The callback should be a callable accepting a ChangeEvent as its only argument. This ChangeEvent is a namedtuple with name, old, and new fields. name is the facet’s name, old is the old value, and new is the new value.

save_instrument(name, force=False)

Save an entry for this instrument in the config file.

Parameters
  • name (str) – The name to give the instrument, e.g. ‘myCam’

  • force (bool, optional) – Force overwrite of the old entry for instrument name. By default, Instrumental will raise an exception if you try to write to a name that’s already taken. If force is True, the old entry will be commented out (with a warning given) and a new entry will be written.

_abc_impl = <_abc_data object>
_all_instances = {}
_instances = <_weakrefset.WeakSet object>
_prop_funcs = {}
_props = []
property _state_path
instrumental.drivers.instrument(inst=None, **kwargs)

Create any Instrumental instrument object from an alias, parameters, or an existing instrument.

reopen_policystr of (‘strict’, ‘reuse’, ‘new’), optional

How to handle the reopening of an existing instrument. ‘strict’ - disallow reopening an instrument with an existing instance which hasn’t been cleaned up yet. ‘reuse’ - if an instrument is being reopened, return the existing instance ‘new’ - always create a new instance of the instrument class. Not recommended unless you know exactly what you’re doing. The instrument objects are not synchronized with one another. By default, follows the ‘reuse’ policy.

>>> inst1 = instrument('MYAFG')
>>> inst2 = instrument(visa_address='TCPIP::192.168.1.34::INSTR')
>>> inst3 = instrument({'visa_address': 'TCPIP:192.168.1.35::INSTR'})
>>> inst4 = instrument(inst1)
instrumental.drivers.list_instruments(server=None, module=None, blacklist=None)

Returns a list of info about available instruments.

May take a few seconds because it must poll hardware devices.

It actually returns a list of specialized dict objects that contain parameters needed to create an instance of the given instrument. You can then get the actual instrument by passing the dict to instrument().

>>> inst_list = get_instruments()
>>> print(inst_list)
[<NIDAQ 'Dev1'>, <TEKTRONIX 'TDS 3032'>, <TEKTRONIX 'AFG3021B'>]
>>> inst = instrument(inst_list[0])
Parameters
  • server (str, optional) – The remote Instrumental server to query. It can be an alias from your instrumental.conf file, or a str of the form (hostname|ip-address)[:port], e.g. ‘192.168.1.10:12345’. Is None by default, meaning search on the local machine.

  • blacklist (list or str, optional) – A str or list of strs indicating driver modules which should not be queried for instruments. Strings should be in the format 'subpackage.module', e.g. 'cameras.pco'. This is useful for very slow-loading drivers whose instruments no longer need to be listed (but may still be in use otherwise). This can be set permanently in your instrumental.conf.

  • module (str, optional) – A str to filter what driver modules are checked. A driver module gets checked only if it contains the substring module in its full name. The full name includes both the driver group and the module, e.g. 'cameras.pco'.

instrumental.drivers.list_visa_instruments()

Returns a list of info about available VISA instruments.

May take a few seconds because it must poll the network.

It actually returns a list of specialized dict objects that contain parameters needed to create an instance of the given instrument. You can then get the actual instrument by passing the dict to instrument().

>>> inst_list = get_visa_instruments()
>>> print(inst_list)
[<TEKTRONIX 'TDS 3032'>, <TEKTRONIX 'AFG3021B'>]
>>> inst = instrument(inst_list[0])
class instrumental.drivers.ParamSet(cls=None, **params)
__init__(cls=None, **params)
create(**settings)
get(key, default=None)
items()
keys()
lazyupdate(other)

Add values from other for keys that are missing

matches(other)

True iff all common keys have matching values

to_ini(name)
update(other)
values()
class instrumental.drivers.VisaMixin(inst=None, **kwds)
_end_transaction()
_flush_message_queue()

Write all queued messages at once

_start_transaction()
query(message, *args, **kwds)

Query the instrument’s VISA resource with message

Flushes the message queue if called within a transaction.

transaction()

Transaction context manager to auto-chain VISA messages

Queues individual messages written with the write() method and sends them all at once, joined by ‘;’. Messages are actually sent (1) when a call to query() is made and (2) upon the end of transaction.

This is especially useful when using higher-level functions that call write(), as it lets you combine multiple logical operations into a single message (if only using writes), which can be faster than sending lots of little messages.

Be cognizant that a visa resource’s write and query methods are not transaction-aware, only VisaMixin’s are. If you need to call one of these methods (e.g. write_raw), make sure you flush the message queue manually with _flush_message_queue().

As an example:

>>> with myinst.transaction():
...     myinst.write('A')
...     myinst.write('B')
...     myinst.query('C?')  # Query forces flush. Writes "A;B" and queries "C?"
...     myinst.write('D')
...     myinst.write('E')  # End of transaction block, writes "D;E"
write(message, *args, **kwds)

Write a string message to the instrument’s VISA resource

Calls format(*args, **kwds) to format the message. This allows for clean inclusion of parameters. For example:

>>> inst.write('source{}:value {}', channel, value)
_abc_impl = <_abc_data object>
property _in_transaction
_instances = <_weakrefset.WeakSet object>
_prop_funcs = {}
_props = []
property resource

VISA resource

instrumental.drivers._get_visa_instrument(params)

Returns the VISA instrument corresponding to ‘visa_address’. Uses caching to avoid multiple network accesses.

Helpful utilities for writing drivers.

instrumental.drivers.util.as_enum(enum_type, arg)

Check if arg is an instance or key of enum_type, and return that enum

instrumental.drivers.util.check_enums(**kw_args)

Decorator to type-check input arguments as enums.

Allows strings and anything that can be passed to as_enum.

@check_enums(mode=SampleMode)
def set_mode(mode):
    pass  # `mode` will be of type SampleMode
instrumental.drivers.util.check_units(*pos, **named)

Decorator to enforce the dimensionality of input args and return values.

Allows strings and anything that can be passed as a single arg to pint.Quantity.

@check_units(value='V')
def set_voltage(value):
    pass  # `value` will be a pint.Quantity with Volt-like units
instrumental.drivers.util.unit_mag(*pos, **named)

Decorator to extract the magnitudes of input args and return values.

Allows strings and anything that can be passed as a single arg to pint.Quantity.

@unit_mag(value='V')
def set_voltage(value):
    pass  # The input must be in Volt-like units and `value` will be a raw number
          # expressing the magnitude in Volts
instrumental.drivers.util.visa_timeout_context(resource, timeout)

Context manager for temporarily setting a visa resource’s timeout.

with visa_timeout_context(rsrc, 100):
     ...  # `rsrc` will have a timeout of 100 ms within this block