User Devices for Artemis

Table of Contents

• Developer installation
• First configuration
• Adding a Custom Device to LabScript Suite
• Simulating the devices Serial port
• Troubleshooting

---

Installation

1. Install the Labscript Suite using the TU-APQ repository: labscript-install. if not already installed.

2. After successfully installing Labscript and all required drivers, clone this repository to: /labscript-suite/userlib/user_devices.

Configuring the labscript suite for first run

To run all applications, you first need to configure the labconfig/<your_name>.ini file generated after creating the LabScript profile. More details can be found in the LabScript Suite Configuration Guide.

Important: Update the user_devices path in your <your_name>.ini to point to the cloned user_devices directory.

1. Run Runmanager

• LabScript file: labscript-suite/userlib/labscript/example_apparatus/connection_table.py
• Default shot output folder: labscript_shared/Experiments/example_apparatus/connection_table/

Once you engage the system, .h5 output files will be generated in the specified shot output folder.

2. Synchronize with BLACS

In BLACS, ensure that you run the same connection_table.h5 file that was generated by Runmanager.

---

Adding a Custom Device to LabScript Suite

1. Navigate to the User Devices Folder:

cd labscript-suite/userlib/user_devices

2. Create a new folder for your custom device and navigate into it.

mkdir MyCustomDevice
cd MyCustomDevice

3. Create the following Python files and a markdown file:

touch __init__.py BLACS_tabs.py BLACS_workers.py labscript_devices.py register_classes.py MyCustomDevice.md

4. Implement your device:

• Describe the device in labscript_devices.py.
• Register the device in register_classes.py to integrate your device with the system.
• Optionally, add documentation in MyCustomDevice.md file.

5. Modify the connection_table.py file in userlib/labscriptlib/example_apparatus/ to include your new device.

Or also see docu

---

Simulating the devices Serial port

If you don't have access to the actual device, but want to test your code, you can simulate the device's serial port using provided script in each user_device folder.

1. Navigate to the device's folder:

cd path/to/user_devices/CustomDevice

2. Run serial port simulation:

python3 emulateSerPort.py

3. Interacting with the simulation: Once the script is running, it will provide the simulated serial port (e.g. /dev/pts/1), which you can use in your connection table.
4. Close the simulation when no longer needed (e.g. Ctrl+C): It will close the simulated serial port.

---

good-to-know

HDF files

The HDF file begins life containing only experiment parameters. As it is passed between components of the labscript suite, the file grows to contain the hardware instructions, acquired data, and analysis results. The GUI, runmanager, creates the HDF file for the experiment shot and stores the parameters within. If a parameter is a list of values, rather than a single value, runmanager creates an HDF file (a prospective shot) for each value.

Types of Devices

• Device: parent class for all devices (labscript.base)
• IntermediateDevice: base class for all devices that are to be clocked by a pseudoclock (labscript.core)

Troubleshooting

TypeError: Argument 'linger' has incorrect type

When closing the BLACS app, you may encounter an error from the pyzmq library: TypeError: Argument 'linger' has incorrect type (expected int, got bool)

This means the sock.close() method was given a bool instead of an int.

To fix it, modify the following lines in clientserver.py, under e.g. /home/<your_name>/labscript-suite/venv/lib/python3.12/site-packages/zprocess/clientserver.py:

Original:

        # line 242-243
        sock.close(linger=True) 
        self.sock.close(linger=False)

Fixed

        sock.close(linger=1)
        self.sock.close(linger=0)

ModuleNotFoundError: No module named 'labscript_devices.CustomDevice'

This can happen if there’s a mismatch between your user_devices folder you using and the one defined in .ini file. Go back to the Initial Configuration section and verify that your .ini file correctly points to the user_devices folder.