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. ThisChangeEvent
is a namedtuple withname
,old
, andnew
fields.name
is the facet’s name,old
is the old value, andnew
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. Ifforce
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 yourinstrumental.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 toquery()
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