device.base.base module

exception device.base.base.CommandError

Bases: DeviceError

Command execution resulted in error.

• Raise this in your command method to signalize an error.

• Raised automatically when a device signalizes error (via _readerror()).

exception device.base.base.CommandUserStop

Bases: DeviceError

Command has terminated because of stop() call.

• Raised automatically when stop() is called.

exception device.base.base.DeviceError

Bases: Exception

Universal exception: all other exceptions intherit from it.

Note: All DeviceError exceptions are internal in the sense, that they are all handled in _outside_call() wrapper and user does not come into contact with them directly. User gets to see only the messages in log.

class device.base.base.HardwareBase(debug_spam=False, log_callback=None, logger='main', ignore_log_conflict=False)

Bases: object

Base class for communication with devices. Thread-safe methods.

Any method that communicates with the device either directly or by calling other methods is refered to as command and MUST be decorated with one of the following: @base_command, @compound_command, @idle_command. Note: this does not apply to private abstract methods (e.g. _connect(), …).

@base_command - Base commands usually communicate with the device directly and implement elementary tasks (e.g. set output voltage). They cannot be terminated by user.

@compound_command - Compound commands implement more complex tasks using a set of base commands and other compound commands. They can be terminated by calling stop(). Tip: Any method decorated as a @compound_command can be instead decorated as a @base_command to forbid termination by user.

@idle_command - Idle commands implement low-priority tasks that are called periodically in background (e.g. read and plot current data from oscilloscope). They do not trigger error when they are blocked by the exectuion of another command. They ignore stop() calls.

If you reimplement __init__, make sure to call super().__init__ in it.

It is REQUIRED to implement following methods in a subclass, see their docstrings for more info. To implement these methods both commands and direct communication with the device can be used. However, do not decorate any of these with command decorators. Also none of these methods will be interupted by a stop() call:

def _connect(self):  # Must return True/False
def _disconnect(self):
def _is_ready(self):  # Must return True/False

It is OPTIONAL to implement these. Notes from above apply here as well:

def _safestate(self):
def _readerror(self):  # Must return str or None
def _defaultstate(self):
def _clear_defaultstate(self):

clear_defaultstate()

Release device from default state (e.g. turn off key-lock).

connect()

Connect to the device. Note: When already connected, connection validity is not checked - to do that call is_ready() instead.

disconnect()

Disconnect from the device.

is_connected()

Check if connected to a hardware device. Note: Connection validity is not checked - to do that call is_ready() instead.

is_ready()

Check if connection to device was opened and if it is responding. If not, try to open a new connection.

stop()

Signilize for current command (if any) to stop its execution as soon as possible. After command stops, device is brought to a safe state.

Note: Idle commands are not affected.

to_defaultstate()

Initialize device to default state.

to_safestate()

Return device to safe state (software kill-switch). This essentially means “turn off anything that can be turned off”.

exception device.base.base.TransmissionError

Bases: DeviceError

Communication related errors.

• Raise this in a communication check (if you implement any).

It is useful to implement comm. check in a universal command-sender method (like raw_scpi() in VisaHardwareBase). If you do not have this option then do not bother. It mainly just helps to make helpful log messages.

device.base.base.base_command(func)

Method decorator for BASE command. - User can terminate: no - Error if device busy: yes

Usage: @base_command

device.base.base.compound_command(func)

Method decorator for COMPOUND command. - User can terminate: yes (before & after any base command is called) - Error if device busy: yes

Usage: @compound_command

device.base.base.idle_command(func=None, *, busy_return=None)

Method decorator for IDLE command. - User can terminate: no - Error if device busy: no

Usage: @idle_command or @idle_command(busy_return=<your return value>)