PyICe.lab_core

Channel and Threading Core Framework

changes to this file should be minimal!

Classes

channel(name[, read_function, write_function]) This is the basic channel object, it can be read and/or written.
channel_group([name])
channel_master([name]) Master channel collection.
delegator() base class for a read delegator, this is the lowest level class in the library.
instrument(name) Superclass for all lab instruments
integer_channel(name, size[, read_function, ...]) channel limited to writing integer values. Adds presets and formats but retains channel class’s read/write restrictions.
logger([channel_master_or_group, database, ...])
logger_backend([database, use_threads])
master([name])
register(name, size[, read_function, ...]) Register primitive superclass, inherits from integer_channel and channel.
remote_channel(proxy_channel, parent_delegator)
remote_channel_group_client([address, port, ...])
remote_channel_group_server(channel_group_object)
scpi_instrument(name) SCPI Instrument Base Class.

Exceptions

ChannelAccessException
ChannelAttributeError
ChannelException
ChannelNameException
ChannelValueException
RegisterFormatException
RemoteChannelGroupException
class PyICe.lab_core.channel(name, read_function=None, write_function=None)[source]

Bases: PyICe.lab_core.delegator

This is the basic channel object, it can be read and/or written. attributes can also be stored in it, for example channel number in a multi channel instrument

add_read_callback(read_callback)[source]

Adds a read callback. This is a function that will be called any time the channel is read. the callback function takes two arguments (channel_object, data)

add_write_callback(write_callback)[source]

Adds a write callback. This is a function that will be called any time the channel is written. the callback function takes two arguments (channel_object, data)

format_display(data)[source]

converts data to string according to string formatting rule set by self.set_display_format_str()

get_attribute(attribute_name)[source]

retrieve value previously set with set_attribute(attribute_name, value)

get_attributes()[source]

return dictionary of all channel attributes previously set with set_attribute(attribute_name, value)

get_category()[source]

returns category membership. should be a string.

get_description()[source]

return channel description string.

get_max_write_limit()[source]

return max writable channel value.

get_min_write_limit(formatted=False)[source]

return min writable channel value.

get_name()[source]

return channel name

get_write_delay()[source]

return automatic delay after channel write

is_readable()[source]

return register readability boolean

is_writeable()[source]

return register writability boolean

set_attribute(attribute_name, value)[source]

set attribute_name to value value can br retrived later with get_attribute(attribute_name)

set_category(category)[source]

each channel may be a member of a single category for sorting purposes. category argument is usually a string

set_description(description)[source]

sets the channel description. argument is string

set_display_format_function(function)[source]

abandon string formatting and pass data through custom user-supplied function

set_display_format_str(fmt_str='', prefix='', suffix='')[source]

format string to alter how data is displayed. example ‘3.2f’, ‘04X’, ‘#06X’, ‘#18b’, ‘.2%’ prefix will be displayed immediately before the channel data, example ‘0x’ suffix will be displayed immediately after the channel data, example ‘ A’ or ‘ V’

set_max_write_limit(max)[source]

set channel’s maximum writable value. None disables limit

set_min_write_limit(min)[source]

set channel’s minimum writable value. None disables limit

set_name(name)[source]

rename channel

set_read_access(readable=True)[source]

set or unset register read access

set_write_access(writeable=True)[source]

set or unset register write access

set_write_delay(delay)[source]

sets the automatic delay in seconds after channel write

write_unformatted(value)[source]

bypass unformatting stub. Only useful for integer and register channels. intended for use by GUI.

class PyICe.lab_core.channel_master(name=None)[source]

Bases: PyICe.lab_core.channel_group, PyICe.lab_core.delegator

Master channel collection. There is typically only one. It replaces the old lab_bench as the main point of interaction with channels. Channels and channel_groups (instruments) may be added to it. It also creates dummy and virtual channels and adds them to its collection. It also supports virtual_caching channels; these can use cached data if available during logging or other multiple channel read.

add_channel_counter(channel_name, **kwargs)[source]

Add a named timer channel. Returns zero the first time channel is read and increments by one each time thereafter.

add_channel_delta_timer(channel_name, reciprocal=False)[source]

Add a named timer channel. Returns the time elapsed since the prior channel read. Optionally, compute 1/time to return frequency instead.

add_channel_dummy(channel_name, integer_size=None)[source]

Add a named dummy channel. This can be used if a single physical instrument channel is externally multiplexed to multiple measurement nodes. The user can store the multiple measurement results from a single instrument into multiple dummy channels. Also it is useful for logging test conditions.

add_channel_total_timer(channel_name)[source]

Add a named timer channel. Returns the time elapsed since first channel read.

add_channel_virtual(channel_name, read_function=None, write_function=None, integer_size=None)[source]

Adds a channel named channel_name. Channel may have a read_function or a write_function but not both. If write_function is supplied, the write function is called with the value when written, and the last written value is returned when read. If read_function is supplied, this channel returns the return of read_function when read. If integer_size is not None, creates in integer_channel instead of a channel. integer_size should specify the number of data bits. Integer channels can add presets, formats.

add_channel_virtual_caching(channel_name, read_function=None, write_function=None)[source]

Adds a channel named channel_name. Channel may have a read_function or a write_function but not both. If write_function is supplied, the write function is called with the value when written, and the last written value is returned when read. If read_function is supplied, this channel returns the return of read_function when read. If the read_function calls the creating channel_master’s read_channel on another channel, a cached value may be used if part of a multi-channel channel read. This can improve logging speed in some cases.

add_read_callback(read_callback)[source]

Adds a read callback. This is a function that will be called any time a channel(s) is read. the callback function should accept one argument: the dictionary of results. If it is not important to group results by each batch read, consider adding a callback to an individual channel instead.

add_write_callback(write_callback)[source]

Adds a write callback. This is a function that will be called any time a channel is written. the callback function should accept one argument: the dictionary of results. In this case, the dictionary will only contain a key,value pair for the single channel that was written. For more flexibility, considering adding a callback to an individual channel instead.

get_flat_channel_group(name=None)

returns a channel_group directly containing all channels this one can resolve

merge_in_channel_group(channel_group_object)

merges in a channel group

read_all_channels(categories=None, exclusions=[])

read all readable channels in channel group and return orderd dictionary of results. Optionally filter by list of categories.

read_channels(item_list)

item list is a list of channel objects, names or channel_groups

resolve_channel_list(item_list)

takes a list of channels, channel_names, or channel_groups and produces a single channel group

write_channel(channel_name, value)[source]

Delegates channel write to the appropriate registered instrument.

write_html(file_name=None, verbose=True, sort_categories=False)

return html document string and optionally write to file_name if verbose, include tables of presets and attributes for each channel if sort_categories, group channel names first by category before alphabetical sort of channel name

class PyICe.lab_core.delegator[source]

Bases: object

base class for a read delegator, this is the lowest level class in the library. You will probably never use it directly.

class PyICe.lab_core.instrument(name)[source]

Bases: PyICe.lab_core.channel_group

Superclass for all lab instruments To add an instrument to a lab_bench object, it must inherit from instrument or one of its specialized subclasses

Rules for adding instruments:
  1. extend instrument class

  2. call the instrument classes __init__ from its __init__

  3. contain an add_channel (and/or add_channel_XXXXX) methods that:
    1. create a channel object with a:
      1. name
      2. EITHER a read_function or write_function
    2. call the _add_channel method with that channel as an argument

  4. has a name attribute which is a meaningful string about the instrument

add_channel(channel_name)[source]
Usage: Add channel name to instrument. For multi-channel instruments,
typically also takes a second argument representing the physical channel of the instrument. May also take channel configuration arguments specific to the instrument.

Operation: This method should create the channel object then call self._add_channel(channel) to add it to the internal channel group

Method must be overloaded by each instrument driver.
get_error()[source]

Return the first error from the instrument. Overload in scpi_instrument or the actual instrument class

get_errors()[source]

Return a list of all errors from the instrument. Overload in scpi_instrument or the actual instrument class

get_flat_channel_group(name=None)

returns a channel_group directly containing all channels this one can resolve

merge_in_channel_group(channel_group_object)

merges in a channel group

read_all_channels(categories=None, exclusions=[])

read all readable channels in channel group and return orderd dictionary of results. Optionally filter by list of categories.

read_channels(item_list)

item list is a list of channel objects, names or channel_groups

resolve_channel_list(item_list)

takes a list of channels, channel_names, or channel_groups and produces a single channel group

write_html(file_name=None, verbose=True, sort_categories=False)

return html document string and optionally write to file_name if verbose, include tables of presets and attributes for each channel if sort_categories, group channel names first by category before alphabetical sort of channel name

class PyICe.lab_core.integer_channel(name, size, read_function=None, write_function=None)[source]

Bases: PyICe.lab_core.channel

channel limited to writing integer values. Adds presets and formats but retains channel class’s read/write restrictions.

add_format(format_name, format_function, unformat_function, signed=False, units='')[source]

Add a format to this register. Formats convert a raw number into a more meaningful string and vice versa Formats can be generic hex, bin, etc, or can be more complicated. format_name is the name of the format format_function transforms from integer data to real unformat_function transforms from real data to integer format_function and unformat_function should be reversible signed treats integer data as two’s complement with self.size bit width units optionally appended to formatted (real) data when displayed by GUI

add_preset(preset_name, preset_value)[source]

Adds a preset named preset_name with value preset_value

add_read_callback(read_callback)

Adds a read callback. This is a function that will be called any time the channel is read. the callback function takes two arguments (channel_object, data)

add_write_callback(write_callback)

Adds a write callback. This is a function that will be called any time the channel is written. the callback function takes two arguments (channel_object, data)

format(data, format, use_presets)[source]

take in integer data, pass through specified formatting function, and return string/real representation.

format_display(data)

converts data to string according to string formatting rule set by self.set_display_format_str()

format_read(raw_data)[source]

transform from integer to real units according to using_presets_read() and active format

format_write(value)[source]

transform from real units to integer according to using_presets_write() and active format

get_attribute(attribute_name)

retrieve value previously set with set_attribute(attribute_name, value)

get_attributes()

return dictionary of all channel attributes previously set with set_attribute(attribute_name, value)

get_category()

returns category membership. should be a string.

get_description()

return channel description string.

get_format()[source]

return active format as set by set_format(format)

get_formats()[source]

Return a list of format_names associate with this register. The format_string elements of the returned list may be passed to the format or unformat methods

get_max_write_limit(formatted=False)[source]

return max writable channel value. If formatted, return max writeable value in transformed units accorting to set_format(format) active format.

get_min_write_limit(formatted=False)[source]

return min writable channel value. If formatted, return min writeable value in transformed units accorting to set_format(format) active format.

get_name()

return channel name

get_presets()[source]

Returns a list of preset names

get_presets_dict()[source]

Returns a dictionary of preset names and value

get_units(format)[source]

return real units string for specified format. ex ‘A’ or ‘V’

get_write_delay()

return automatic delay after channel write

is_readable()

return register readability boolean

is_writeable()

return register writability boolean

read_without_delegator()[source]

read intercept to apply formats/presets to channel (raw) read

remove_format(format_name)[source]

remove format_name from dictionary of available formats

set_attribute(attribute_name, value)

set attribute_name to value value can br retrived later with get_attribute(attribute_name)

set_category(category)

each channel may be a member of a single category for sorting purposes. category argument is usually a string

set_description(description)

sets the channel description. argument is string

set_display_format_function(function)

abandon string formatting and pass data through custom user-supplied function

set_display_format_str(fmt_str='', prefix='', suffix='')

format string to alter how data is displayed. example ‘3.2f’, ‘04X’, ‘#06X’, ‘#18b’, ‘.2%’ prefix will be displayed immediately before the channel data, example ‘0x’ suffix will be displayed immediately after the channel data, example ‘ A’ or ‘ V’

set_format(format)[source]

set active transformation format. reads and writes happen in transformed (real) units instead of native integer. Set to None to disable formatting.

set_max_write_limit(max)

set channel’s maximum writable value. None disables limit

set_min_write_limit(min)

set channel’s minimum writable value. None disables limit

set_name(name)

rename channel

set_read_access(readable=True)

set or unset register read access

set_write_access(writeable=True)

set or unset register write access

set_write_delay(delay)

sets the automatic delay in seconds after channel write

signedToTwosComplement(signed)[source]

transform signed integer to two’s complement formatted binary number. Requires register’s size attribute to be set in __init__

twosComplementToSigned(binary)[source]

transform two’s complement formatted binary number to signed integer. Requires register’s size attribute to be set in __init__

unformat(string, format, use_presets)[source]

take in formatted string / real, pass through specified unformatting function, and return integer representation.

use_presets_read(bool)[source]

enable replacement of integer value with named enum when reading channel

use_presets_write(bool)[source]

enable replacement of named enum with integer value when writing channel

using_presets_read()[source]

return boolean denoting last setting of use_presets_read()

using_presets_write()[source]

return boolean denoting last setting of use_presets_write()

write(value)[source]

write intercept to apply formats/presets before channel write. Coerce to integer and warn about rounding error. Also accepts None

write_unformatted(value)[source]

bypass unformatting. intended for use by GUI.

class PyICe.lab_core.register(name, size, read_function=None, write_function=None)[source]

Bases: PyICe.lab_core.integer_channel

Register primitive superclass, inherits from integer_channel and channel. Allows read and write access to integer data with presets and formats.

add_format(format_name, format_function, unformat_function, signed=False, units='')

Add a format to this register. Formats convert a raw number into a more meaningful string and vice versa Formats can be generic hex, bin, etc, or can be more complicated. format_name is the name of the format format_function transforms from integer data to real unformat_function transforms from real data to integer format_function and unformat_function should be reversible signed treats integer data as two’s complement with self.size bit width units optionally appended to formatted (real) data when displayed by GUI

add_preset(preset_name, preset_value)

Adds a preset named preset_name with value preset_value

add_read_callback(read_callback)

Adds a read callback. This is a function that will be called any time the channel is read. the callback function takes two arguments (channel_object, data)

add_write_callback(write_callback)

Adds a write callback. This is a function that will be called any time the channel is written. the callback function takes two arguments (channel_object, data)

format(data, format, use_presets)

take in integer data, pass through specified formatting function, and return string/real representation.

format_display(data)

converts data to string according to string formatting rule set by self.set_display_format_str()

format_read(raw_data)

transform from integer to real units according to using_presets_read() and active format

format_write(value)

transform from real units to integer according to using_presets_write() and active format

get_attribute(attribute_name)

retrieve value previously set with set_attribute(attribute_name, value)

get_attributes()

return dictionary of all channel attributes previously set with set_attribute(attribute_name, value)

get_category()

returns category membership. should be a string.

get_description()

return channel description string.

get_format()

return active format as set by set_format(format)

get_formats()

Return a list of format_names associate with this register. The format_string elements of the returned list may be passed to the format or unformat methods

get_max_write_limit(formatted=False)

return max writable channel value. If formatted, return max writeable value in transformed units accorting to set_format(format) active format.

get_min_write_limit(formatted=False)

return min writable channel value. If formatted, return min writeable value in transformed units accorting to set_format(format) active format.

get_name()

return channel name

get_presets()

Returns a list of preset names

get_presets_dict()

Returns a dictionary of preset names and value

get_units(format)

return real units string for specified format. ex ‘A’ or ‘V’

get_write_delay()

return automatic delay after channel write

is_readable()

return register readability boolean

is_writeable()

return register writability boolean

read_without_delegator()

read intercept to apply formats/presets to channel (raw) read

remove_format(format_name)

remove format_name from dictionary of available formats

set_attribute(attribute_name, value)

set attribute_name to value value can br retrived later with get_attribute(attribute_name)

set_category(category)

each channel may be a member of a single category for sorting purposes. category argument is usually a string

set_description(description)

sets the channel description. argument is string

set_display_format_function(function)

abandon string formatting and pass data through custom user-supplied function

set_display_format_str(fmt_str='', prefix='', suffix='')

format string to alter how data is displayed. example ‘3.2f’, ‘04X’, ‘#06X’, ‘#18b’, ‘.2%’ prefix will be displayed immediately before the channel data, example ‘0x’ suffix will be displayed immediately after the channel data, example ‘ A’ or ‘ V’

set_format(format)

set active transformation format. reads and writes happen in transformed (real) units instead of native integer. Set to None to disable formatting.

set_max_write_limit(max)

set channel’s maximum writable value. None disables limit

set_min_write_limit(min)

set channel’s minimum writable value. None disables limit

set_name(name)

rename channel

set_read_access(readable=True)

set or unset register read access

set_write_access(writeable=True)

set or unset register write access

set_write_delay(delay)

sets the automatic delay in seconds after channel write

signedToTwosComplement(signed)

transform signed integer to two’s complement formatted binary number. Requires register’s size attribute to be set in __init__

twosComplementToSigned(binary)

transform two’s complement formatted binary number to signed integer. Requires register’s size attribute to be set in __init__

unformat(string, format, use_presets)

take in formatted string / real, pass through specified unformatting function, and return integer representation.

use_presets_read(bool)

enable replacement of integer value with named enum when reading channel

use_presets_write(bool)

enable replacement of named enum with integer value when writing channel

using_presets_read()

return boolean denoting last setting of use_presets_read()

using_presets_write()

return boolean denoting last setting of use_presets_write()

write(value)

write intercept to apply formats/presets before channel write. Coerce to integer and warn about rounding error. Also accepts None

write_unformatted(value)

bypass unformatting. intended for use by GUI.

class PyICe.lab_core.scpi_instrument(name)[source]

Bases: PyICe.lab_core.instrument

SCPI Instrument Base Class. Implements methods common to all SCPI instruments Instruments which adhere to the SCPI specification should inherit from the scpi_instrument class rather than the instrument class.

add_channel(channel_name)
Usage: Add channel name to instrument. For multi-channel instruments,
typically also takes a second argument representing the physical channel of the instrument. May also take channel configuration arguments specific to the instrument.

Operation: This method should create the channel object then call self._add_channel(channel) to add it to the internal channel group

Method must be overloaded by each instrument driver.
beep()[source]

Send a beep command.

clear_status()[source]

Send the *CLS command.

display_clear()[source]

Clear the instrument display

display_off()[source]

Turn the instrument display off

display_on()[source]

Turn the instrument display on

display_text(text='')[source]

Display text on instrument front panel

enable_serial_polling()[source]

Enable the instrument to report operation complete via serial polling

error()[source]

Get error message.

fetch()[source]

Send FETCH? query.

get_error()[source]

Return the first error from the SCPI instrument. +0 is the errorcode for no error

get_errors()[source]

Return a list of all accumulated SCPI instrument errors.

get_flat_channel_group(name=None)

returns a channel_group directly containing all channels this one can resolve

identify()[source]

Send the *IDN? command.

init()[source]

Send INIT command.

initiate_measurement(enable_polling=False)[source]

Initiate a measurement

merge_in_channel_group(channel_group_object)

merges in a channel group

operation_complete()[source]

query if current operation is done blocks i/o until operation is complete or timeout this method retries query until a character is returned in cas of premature timeout EDIT - delet retry for now

read_all_channels(categories=None, exclusions=[])

read all readable channels in channel group and return orderd dictionary of results. Optionally filter by list of categories.

read_channels(item_list)

item list is a list of channel objects, names or channel_groups

read_measurement()[source]

Send FETCH? query.

reset()[source]

Send the *RST command.

resolve_channel_list(item_list)

takes a list of channels, channel_names, or channel_groups and produces a single channel group

trigger()[source]

Send the *TRG command.

write_html(file_name=None, verbose=True, sort_categories=False)

return html document string and optionally write to file_name if verbose, include tables of presets and attributes for each channel if sort_categories, group channel names first by category before alphabetical sort of channel name