Getting Started¶

This package provides many drivers for different lab hardware. You can find them all in the list here Hardware.

Starting a device HERO¶

Important

All drivers also run without BOSS, however to use all features we strongly recommend starting them via BOSS!

The following examples assume the following device configuration in a json file in the working directory:

my_device.json¶

 {
     "_id": "my-vac-controller",
     "classname": "herosdevices.hardware.gamma_vacuum.EthernetSPC",
     "arguments": {
         "address": "192.0.2.1",
     }
 }

Tip

Check out the BOSS documentation to learn more about possible sources.

Install docker and create a docker-compose.yml file with the following content:

services:
  vacuum-controller:
    image: registry.gitlab.com/atomiq-project/herosdevices:latest
    restart: always
    network_mode: host
    command: python -m boss.starter -u file:///${PWD}/my_device.json

Then run it with

docker compose up

The device representations can also be installed locally via pip:

Hint

We recommend using uv to maintain an enclosed python environment.

uv pip install heros-boss herosdevices

Now you are ready to go! You can get an overview over the command line arguments of boss by running

uv run python -m boss.starter -u file:///${PWD}/my_device.json

Tip

Many of the device drivers have an atomiq-compatible interface so components can be exchanged seamlessly. Look out for inheritance from herosdevices.interfaces.atomiq.AtomiqInterface.

Adding vendor libraries¶

Due to the large variety of devices supported by herosdevices, it becomes intractable (and sometimes legally troublesome) to have all dependencies for every device installed in the the base image. It might thus be necessary to extend your installation by required third party libraries in one of the following ways:

While you can extend the docker image by the required packages, BOSS provides an easy way to install dependencies from the compose file during container creation. Both processes are described in the BOSS documentation.

Installing non-python third party drivers locally depends on what OS you are using, please refer to the official documentation of the driver. Additional python packages can be installed directly to the venv you run your BOSS in. For example:

uv pip install PyVCAM