How to Add a Device¶
Adding a labscript-device involves implementing interfaces for your hardware to different protions of the labscript-suite. Namely, you must provide
A
labscript_device
that takes labscript high-level commands and turns them into instructions that are saved to the shot h5 file.A
BLACS_worker
that handles communication with the hardware, in particular interpreting the instructions from the shot h5 file into the necessary hardware commands to configure the device.A
BLACS_tab
which provides a graphical interface to control the instrument via BLACS
Though not strictly required, you should also consider providing a runviewer_parser
, which can read the h5 instructions and produce the appropriate shot timings that would occur. This interface is only used in runviewer.
General Strategy¶
As a general rule, it is best to model new hardware implementations off of a currently implemented device that has similar functionality. If the functionality is similar enough, it may even be possible to simply sub-class the currently implemented device, which is likely preferrable.
Barring the above simple solution, one must work from scratch.
It is best to begin by determining the labscript device class to inherit from: Psuedoclock
, Device
, IntermediateDevice
.
The first is for implementing Psuedoclock devices, the second is for generic devices that are not hardware timed by a pseudoclock, and the last is for hardware timed device that are connected to another device controlled via labscript.
The labscript_device
implements general configuration parameters, many of which are passed to the BLACS_worker
.
It also implements the generate_code
method which converts labscript high-level instructions and saves them to the h5 file.
The BLACS_tab
defines the GUI widgets that control the device.
This typically takes the form of using standard widgets provided by labscript for controlling labscript output primitives (ie AnalogOut
, DigitalOut
,`DDS`, etc).
This configuration is done in the initialiseGUI
method.
This also links directly to the appropriate BLACS workers.
The BLACS_worker
handles communication with the hardware itself and often represents the bulk of the work required to implement a new labscript device.
In general, it should provide five different methods:
init
: This method initialised communications with the device. Not to be confused with the standard python class__init__
method.program_manual
: This method allows for user control of the device via theBLACS_tab
, setting outputs to the values set in theBLACS_tab
widgets.check_remote_values
: This method reads the current settings of the device, updating theBLACS_tab
widgets to reflect these values.transition_to_buffered
: This method transitions the device to buffered shot mode, reading the shot h5 file and taking the saved instructions fromlabscript_device.generate_code
and sending the appropriate commands to the hardware.transition_to_manual
: This method transitions the device from buffered to manual mode. It does any necessary configuration to take the device out of buffered mode and is used to read an measurements and save them to the shot h5 file as results.
The runviewer_parser
takes shot h5 files, reads the saved instructions, and allows you to view them in runviewer in order to visualise experiment timing.
Code Organization¶
There are currently two supported file organization styles for a labscript-device.
The old style has the labscript_device
, BLACS_tab
, BLACS_worker
, and runviewer_parser
all in the same file, which typically has the same name as the labscript_device
class name.
The new style allows for arbitrary code organization, but typically has a folder named after the labscript_device
with each device component in a different file (ie labscript_devices.py
, BLACS_workers.py
, etc).
With this style, the folder requires an __init__.py
file (which can be empty) as well as a register_classes.py
file.
This file imports <labscript-utils:labscript_utils.device_registry>
via
from labscript_devices import register_classes
This function informs labscript where to find the necessary classes during import. An example for the NI_DAQmx
device is
register_classes(
'NI_DAQmx',
BLACS_tab='labscript_devices.NI_DAQmx.blacs_tabs.NI_DAQmxTab',
runviewer_parser='labscript_devices.NI_DAQmx.runviewer_parsers.NI_DAQmxParser',
)
Contributions to labscript-devices¶
If you decide to implement a labscript-device for controlling new hardware, we highly encourage you to consider making a pull-request to the labscript-devices repository in order to add your work to the labscript-suite. Increasing the list of supported devices is an important way for the labscript-suite to continue to grow, allowing new users to more quickly get up and running with hardware they may already have.