Controlling devices

Warning: This section may be partially out-of-date!

The purpose of the device package is to provide a unified python interface in a form of a class for each experiment-related device in the lab. This interface is used to create a GUI for the device and register it to the server (see device_client). This interface can be also used directly from a python interpreter for example when testing and developing code for a new device. Please relate to API for a list of existing device classes.

Quickstart

Assuming that the device is physically connected and turned on, basic usage can be summed up into three steps:

  1. Instantiate your device class.

  2. Call method connect().

  3. Call methods to control your device (see API).

When done using the device you can call method disconnect() to safely disconnect and clean up.

Example:
>>> from device import Mockup
>>> dev = Mockup()
>>> dev.connect()
>>> dev.initiate_discharge(20)
...
>>> dev.disconnect()

Common interface

Each hardware class offers a small set of common methods that establish and control the communication with the device:

  • connect() - Establish connection.

  • disconnect() - Close connection and clean-up.

  • is_connected() - Returns True if in connected state.

  • is_ready() - Returns True if connection is ok and device is ready to operate.

  • stop() - Terminate current command.

First four methods are self-explanatory. Note that the behavior of is_ready() in disconnected state is that it automatically tries to establish a connection. The last one, stop(), can be used in a multithreaded application (including our GUI) to terminate command that is being executed (see next section to learn more about commands).

There are three additional common methods that are called automatically in certain situations but they may be called manually as well:

  • to_safestate - Bring device to safe state. (See key features of commands in next section for more details.)

  • to_defaultstate - Init device settings to some predefined default state.

  • clear_defaultstate - Clean up default state settings (e.g. turn off key-lock).

These methods have an optional implementation, which means that depending on the device they may actually do nothing.

Interface of custom commands

The main functionality of the device class is to communicate with the hardware device and control it (start measurement, read data, etc.). To achieve this each class offers a selection methods that are referred to as commands. Note that not all methods in a class are necessarily commands, but those that communicate with the device most certainly are. You can recognize them by the @*_command decorators.

Here is a list of key features guaranteed for all command-type methods:

  • Command can be executed only in connected state.

  • Only one command is executed at any given time (thread-safety).

  • Command execution can be abruptly terminated when

    • user calls method stop()

    • command encounters error

    • device signalizes error

    • unexpected situation is encountered (unknown error)

  • Abrupt termination of command triggers a return to safe state. Usually that results in turning off anything dangerous that may have been turned on.

Goal of these features is to handle any trouble with device communication and ensure good user experience.

Writing a device class

TODO