Driver Programming

Device Classes are small python based code snippets that act as drivers to tell SweepMe! how to interface with a certain instrument.

Basic idea

SweepMe! creates a Device object based on a selected Device Class. For this Device object, several semantic functions are called that are the identical across all modules and instruments. For example, these pre-defined functions are named "connect", "initialize", "configure", "start", "measure", "call", "unconfigure", "deinitialize", "disconnect". There are many more such functions and you only need to add those to your Device Class that you need. When these functions are called during the program run is described here: Sequencer procedure. As a Device Class programmer, you have to make sure that your instrument is doing right things at these functions, e.g. after "initialize" is called, your instrument should be initialized, but it remains your choice what is exactly done. Once, these semantic functions are perfectly adjusted, you can use your Device Class like a driver that can be used in combination with all other SweepMe! modules and drivers.

In SweepMe!'s devices classes you have no direct access to the main program or the modules, but rather SweepMe! calls the device class functions and sets a number of variables to control the program flow.

Conceptually, instruments are not implemented into SweepMe! as physical units with all their features, but rather instruments are implemented as functional units. Some instruments have multiple functions and for all these functions a device class can be created. For example, an instrument that can be used as signal generator and as oscilloscope can be implemented by a device class for Signal and by a device class for Scope. This way, functional units of the instrument can be controlled and accessed independently.

Minimal working example

A Device Class is a main.py file in which a python class-Object is inherited from a parent class called EmptyDeviceClass.

The following four lines of codes are always needed:

from EmptyDeviceClass import EmptyDevice  # Loading the EmptyDevice Class

class Device(EmptyDevice):            # Creating a new Device Class by inheriting from EmptyDevice
    def __init__(self):               # The python class object need to be initialized
       EmptyDevice.__init__(self)     # Finally, the initialization of EmptyDevice has to be done

Copying these four files into an empty main.py should result in a working Device Class that is basically doing nothing. You can then add further commands as needed.

Examples

All device classes that are available via the version manager are also examples. Download them and see the source code, e.g. using the "Open/Modify" button that each module has. Copy device classes to the public folder "CustomDevices" using the version manager and start using them as a template for your own device classes.

Programming style guide

All points are recommendation that might help you to create a device class, but feel free to do it your way. Also rudimentary device classes that do not support all features of an instrument or a certain programming style can be very helpful to other users to use get started.

• A device class should be as convenient as possible. If you can take a decision for the user by doing some extra checks or by getting the information from a config file try to include it.

• If a user could enter values that are not supported by the instrument, use the function connect to do an initial check and stop the measurement if a value is not supported. Inform the user what was wrong and which values are supported.

• Whenever you get a value e.g. "self.value" during apply or any parameter during "get_GUIparameter" transform them immediately into the type you need. The type of a parameter can change (e.g. from integer to string) at some point, when a value is handed over from a different module or if the user interface of a module is changed in future. By redefining the type of the parameter, you can ensure that your device class will not break.

• Sometimes the user interface of a module does not support all options of your instrument. In that case contact us to discuss how we can improve the module. Sometimes it is also possible to 'stretch' the user interface to your needs. For example: A module has the option "Input" (represented by drop-down menu), but your instrument has two inputs that can be selected/deselected, then you can add possible choices like "None", "1", "2", and "1 & 2". That way, you do not need a second user interface option like "Input 2" to support the second input.

• To make it easy to read a device class, we recommend to use a certain structure:

1. start with the import of modules
2. create the class 'Device' according to the minimal working example
3. add static variables such as "description"
4. add the function "__init__"
5. add the function "find_Ports" if your device class takes care about finding ports
6. add the function "set_GUIparameter" to set the default values of the modules user interface
7. add the function "get_GUIparameter" to retrieve the users selection
8. now add the standard functions such as connect, initialize, configure,
9. functions like connect/disconnect, initialize/deinitialize, configure/unconfigure, signin/signout can be added close together so that one can easily see what is done at the beginning and at the end.
10. then add standard functions that are called at each measurement points, such as start, apply, measure, call, ... Try to keep the sequence in which they are called.
11. After all standard overload functions are added that you need, you can add and create new functions that simplify the access to some properties of the instrument ("setter and getter function", e.g. "set_voltage", "get_voltage", "set_filter", "get_filter", etc. These functions can be used within the standard function, but they could also be used when device classes are used in independent python programs, e.g. using pysweepme.
12. At the bottom, you can add your own convenience functions that help you to do the programming, but which are no standard functions and that do not set/get any property directly.

Documentation

If a user of your device class needs further instruction, we recomment to upload the driver to our server and add a description on the webpage each driver gets on this webpage: [[1]]

If your device class is not publicly available, add a descriptive comment to the code of the main.py file. In case you develop a device class for the generic modules Logger and Switch, you can add a description to the device class by inserting a text for the static variable 'description'

In genereal, we recommend to rather add more comments than less. It will help other users to understand the code and to learn developing own drivers.

Instantiation & destruction

A instance of the Device class is instantiated and destroyed very often:

• for each measurement run
• whenever the Module needs to know the 'variables', 'units' or the shortname

Thus, the __init__ should be a light-weight function as it is called often. It also means that you cannot store parameters in a device class to use them later again. Every parameter of the device class instance exists only as long the device class lives and after a run, for example, the device class is destroyed. This further means that dll files or other files should not be loaded in the __init__ function, but rather during connect or initialize.

To handover parameters and objects to future device class instances, use the functions 'store_parameter' and 'restore_parameter' as explained here.

Importing python packages

All packages which come along with SweepMe! can be imported as usual at the beginning of the file. If you need to import packages that do not come with the SweepMe! installation, you can use the LibraryBuilder to ship an extra python package with your DeviceClass.

__init__

This function should be part of any device class, and according to the minimal working example the function "__init__" of the base class "EmptyDevice" must be called first. Then, you can define variables, units, plottype, and savetype as described above. Furthermore, you can set the variable self.shortname to a string that will be shown in the sequencer to help the user to quickly identify which instrument is used. Besides that, you can use the __init__ function to define important variables that are frequently needed in all other functions.

Defining return variables

Each Device Class can return an arbitrary number of variables that are subsequently available for plotting, displaying them in a monitor widget, or saving them to the measurement data file.

In the function "__init__" of your Device class you have to define following objects:

self.variables = ["Variable1", "Variable2", "Variable3"]
self.units = ["s", "m", ""]

In this example, three variables are defined, but you can also add more. Please make sure that you have the same number of units which are defined as seconds, meters, and no unit (empty string).

self.plottype = [True, True, False]
self.savetype = [True, False, False]

Additionally, you can define 'self.plottype' and 'self.savetype' which again need to have the same length as 'self.variables'. If you do not define them, they will be always True for each variable. If the plottype of a variable is True, you can select this variable in the plot. If the savetype of a variable is True, the data of this variable is saved to the measurement file.

In order to return your measured data to SweepMe! use the call function and return as many values as you have defined variables.

GUI interaction

The interaction with grahical user interface (GUI) is realized with the two function get_GUIparameter and set_GUIparameter. The function get_GUIparameter receives a dictionary with all parameters of the GUI. The function set_GUIparameter has to return a dictionary that tells SweepMe! which GUI elements should be enabled (active) and which options or default values should be displayed.

Getting GUI parameter

In order to figure out which parameters are selected by the user, the function 'get_GUIparameter' has to be used. It has one argument 'parameter' that is used to handover a dictionary that consists of keys that are related the GUI elements of the Module and the selected values. Overwrite this function in your device class to make use of it. For example:

def get_GUIparameter(self, parameter):
    print(parameter)

Here, the print command can be used to see the dictionary in the debug widget and learn which keys are accessible. These keys of the dictionary can vary between each Module, but there are some which are common for all, like "Label", "Device", "Port".

In order to load a single parameter, for example the Sweep mode or the selected port, use:

def get_GUIparameter(self, parameter):
    self.sweepmode = str(parameter["SweepMode"])
    self.port_string = str(parameter["Port"])

The variables 'self.sweepmode' and 'self.port_string' contain 'self.' which makes them an attribute of the entire device class so that you can use them in all other functions of your device class that have 'self' as first argument.

It is good practice to immediately change the data type to whatever you need for further processing. Should, the type of the data change, your code will not break.

Typical functions:

• int(): change to an integer number
• float(): change to a float number
• str(): change to a string

Setting GUI parameter

GUI elements of the Module for which you implement your Device Class must be activated. For that reason, put the following function into your DeviceClass

def set_GUIparameter(self):
    GUIparameter = {}
    return GUIparameter

Now, you can fill the dictionary GUIparameter with keys and values. Each key represents a certain GUI item of the Module.

GUIparameter = {
                "SweepMode" : ["Current in A", "Voltage in V"],  # define a list 
               }

Here, "SweepMode" represents the ComboBox of the Module that presents the possible modes to vary set values. To get all possible keys that can be used with set_GUIparameter, you can use the function get_GUIparameter.

For modules with a fixed user interface, you cannot change the type of the widget that is used for the given key. Accordingly, you have use a certain format to set the value for a key, for example:

GUIparameter = {
                "KeyInteger"    : 1,                       # use an integer for a field that requires an integer such as a SpinBox
                "KeyFloat"      : 1.23,                    # use a float for a field that requires an float such as DoubleSpinBox
                "KeyString "    : "SomeText",              # use a string for a field that requires a string such as a LineEdit
                "KeyComboBox"   : ["Choice1", "Choice2"],  # use a list of strings for a field that requires a selection such as a ComboBox
                "KeyCheckBox"   : True,                    # use a bool for a field that requires a check such as a CheckBox
               }

Creating individual parameters

The Modules Logger and Switch provide the possibility to generate GUI items dynamically. Just add your own keys to the dictionary and based on the type of the default value, the corresponding GUI element will be created for you.

GUIparameter = {
                "MyOwnKeyForInteger"   : 1,                       # define a GUI element to enter an integer
                "MyOwnKeyForFloat"     : 1.23,                    # define a GUI element to enter a float
                "MyOwnKeyForString"    : "SomeText",              # define a GUI element to enter a string
                "MyOwnKeyForSelection" : ["Choice1", "Choice2"],  # define a GUI element to select from a ComboBox
                "MyOwnKeyForBool"      : True,                    # define a GUI element to use CheckBox
                "MyOwnKeyForSeparator" : None,                    # define a GUI element that just displays the key with bold font
                ""                     : None,                    # an empty line
                "MyOwnKeyForFolder"    : pathlib.Path(<folder>),  # define a GUI element that displays a button to select a folder
                "MyOwnKeyForFile"      : pathlib.Path(<file>),    # define a GUI element that displays a button to select a file
                " "                    : None,                    # another empty line with a different key from the first empty line
               }

The keys you use will be returned then by get_GUIparameter with the selected values of the user. Please make sure that you do not use keys that are provided by the Module. See the description of get_GUIparameter to see which keys already exist.

Pre-defined GUI keys

There are some keys that should not be used to define your own GUI keys when creating device classes for Logger and Switch.

• "Label": The field where the user can change the label of the module
• "Device": The field where the user selects the device class
• "Port": the field where the user selects the port
• "Calibration": the field where the user selects the calibration
• "Channel": the field where the user selects the channel
• "Description": the field where the user can read an info about the device class
• "SweepMode": the field where the user selects the sweep mode
• "SweepValue": the field where the user selects the sweep value

Description

Device Classes that are programmed for the modules Logger or Switch can have a description that is displayed in the description box when the corresponding Device Class is selected.

To enable this feature, add a static variable 'description' to your class, e.g.

class Device(EmptyDevice):
    description = "here you describe how your Device Class should be used" # a static variable

    def __init__(self):
       ...

The string will be interpreted like html, so that headings, enumerations, etc. are possible.

Ports

If you use standardized communications interfaches like GPIB, COM, or USBTMC, you make use of SweepMe!'s port manager that manages everything and you can use write and read function to communicate with your instrument. Otherwise, you have to handle the creation and destruction of a port object yourself using the functions connect and disconnect.

Finding & selecting ports

If your Device Class makes use of the port manager, available ports will be automatically added to the field "Port". Otherwise you can add the function "find_Ports" and return a list of strings that identify possible ports. In both cases, you can retrieve the port selected by the user via the function "get_GUIparameter" using the key "Port".

Multichannel support

deprecated from 1.5.5: Use the key "Channel" with the functions "set_GUIparameter" and "get_GUIparameter" to list available ports in an extra ComboBox.

Some measurement equipment has two channels but only one communications port, e.g. some Source-Measuring-Units or Paramter Analyzers have multiple channels to independently source voltages or currents, but everything is controlled via one port.

Of course, one could implement a Device Class for each channel of the device but in case of changes multiple files have to be revised. In order to unify the device handling, you can define multiple channels in your Device Class by adding a static variable:

class Device(EmptyDevice):
    multichannel = ["CH1", "CH2", "CH3", "CH4"] # a static variable

    def __init__(self):
       ...

In that case, the user will see four Device Classes in the Device list of the Module with the string defined above at the end.

To figure out which channel is chosen by the user, use:

def get_GUIparameter(self, parameter):
    self.device = self.parameter["Device"]
    self.channel = int(self.device[-1])

The above example will first read out the name of the chosen Device Class. Assuming that the last character of the string is the number of the selected channel. Of course, you can modify the above example to your needs.

Stop a measurement

The measurement stops whenever a standard function such as 'connect', 'initialize', ... , return with False. So just add "return False" to your code whenever something goes wrong and you like to abort the measurement. The measurement also stops if the variable self.stopMeasurement is no empty string anymore. So you can use

self.stopMeasurement = "text-to-be-displayed-in-a-message-box-to-inform-user"

If SweepMe! detects a non-empty string it will stop the measurement after the current function returns. Use "return False" to let the current function return immediately.

Alternatively, you can use the following function

self.stop_Measurement("text-to-be-displayed-in-a-message-box-to-inform-user")

The error message will be displayed in a message box to the user.

Communication with the user

If you like to display a message in the info box of the "Measurement" tab, you can use:

self.message_Info("text-to-be-displayed-in-the-info-box")

If you like to inform the user with a message box, use

self.message_Box("text-to-be-displayed-in-the-message-box")

Please note that the message box is non-blocking and the measurement will continue, even if the the message is not confirmed by the user.

Log messages to a file

You can easily write messages to a file using

self.write_Log("message-to-be-saved")

The message will be saved in the file temp_logbook.txt within the temp-folder. When saving data the leading "temp" of the file will be automatically renamed by the given file name.

Exchange parameters between device class instances

(available from SweepMe! 1.5.5)

As device classes are often instantiated and destroyed, it might be necessary to forward parameters or infomation the next device class during a SweepMe! session. There are two possibilities:

• parameters are stored in a configuration file
• parameters and stored in a parameter store that is provided by SweepMe!

To store a parameter, use

self.store_parameter(key, value)

where 'key' is a string and 'value' can be any python object. The key-value pair is stored in dictionary that is available to all device classes and which exists during the entire SweepMe! session.

To restore a parameter, use

value = self.store_parameter(key)

where 'key' is a string that was previously used during 'store_parameter' and 'value' is the object that was stored. If the key is unknown, 'None' is returned.

Inter device class communication

Sometimes multiple instances of a device class are created for a measurement and they need to share some information, e.g. a certain object to handle the communication. For this purpose a dictionary called "self.device_communication" is available in all device classes that is exactly the same for all device classes. You can simply add a key-value pair and all other device classes can access the entries as well and vice versa. The dictionary is available starting with a measurement and can be accessed during all functions that are called during the measurement. To avoid interference, we recommend to use very unique key-strings that e.g. include the name of the device class. For example, a Device Class which opens a dll-file to communicate with a spectrometer will have exclusive access to that port. In order to allow multiple Spectrometer module and their device classes to access the same port object it must be made available to all.

def connect(self):
    
    if "my_spectrometer_port" in self.device_communication:           
        # it means that another instance of this device class already opened the port object
        self.port = self.device_communication["my_spectrometer_port"]   
    else:                                                             
        # the port object is not available yet, so we have to create it and make it available to other instances of the same device class
        self.port = create_some_port_object()
        self.device_communication["my_spectrometer_port"] = self.port

The same can be done, when disconnecting and closing the port object:

def disconnect(self):
    
    if "my_spectrometer_port" in self.device_communication:
        # if the key is still available, the first instance of the device class will close the port and remove the key
        self.port.close() # close your port or disconnect
        del self.device_communication["my_spectrometer_port"] # remove the key-value pair from the dictionary

The dictionary is emptied before each measurement so that values are not available during the next measurement.

Module specific functions

Several modules provide additional functionality, e.g. the latest version of the monochromator module has a button to tell the instrument to go to a home position. These module specific functions are described on the page of each Module.

Configuration file

Sometimes an instrument has setup-specific properties that are fixed but which must be once set for each instrument. These properties are typically not supported by the user interface of the module. Then, it would be more appropriate to save these configurations in a file that is stored in the public SweepMe! folder. This ensures that the configuration is not lost if a device class is updated.

There exist convenience functions to load such a configuration file that can be used within a device class. These functions expect to find a file in the folder "CustomFiles" of the public SweepMe! folder. The file must have the name of the device class and the extension ".ini". The formatting should be like in any INI file [[2]]

self.isConfigFile() # returns True if the file exists, else False

self.getConfigSections() # returns a list of strings that represent all found sections

self.getConfigOptions(section) # returns a dictionary of key-value pairs of the given section string

self.getConfig() # returns a dictionary with dictionaries of the options for all sections, i.e. the entire config file

A device class should come with a template configuration file. Starting from version 1.5.5, the user can copy the template configuration file to the "CustomFiles" using the version manager. Inform the user of your device class about the possibility to customize the handling via a configuration file by adding some documentation.

Find and get folders

Often you need to access some of the standard pre-defined folders. For that purpose you can use the function 'get_Folder' that each device class can use.

self.get_Folder("<KEY>") # returns an absolute path to the folder for a given <KEY>.

Often used keys

• "SELF": the folder of the device class script "main.py" (introduced with SweepMe! 1.5.5.)
• "TEMP": the temporary folder in which all measurement data is stored before the user saves it
• "CUSTOMFILES": the folder "CustomFiles" of the public SweepMe! folder in which setup-specific files might be stored
• "EXTLIBS": the folder "ExternalLibraries" of the public SweepMe! folder in which external dll files can be stored
• "CALIBRATIONS": the folder "Calibrations" of the public SweepMe! folder in which calibrations files can be stored
• "PUBLIC": the public SweepMe! folder