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 a camera device configuration hosted in a CouchDB like:

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

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 http://<user>:<pw>@<couchdb_host>:5984/my-boss/my-vac-controller

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 http://<user>:<pw>@<couchdb_host>:5984/my-boss/my-vac-controller

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¶

To install third party drivers to a docker container, you have to extend the docker image. The following example shows this process at the example of herosdevices.hardware.teledyne.pvcam.PvcamCamera:

Create a new a directory and download and unzip the binary drivers. There should now be two folders pvcam and pvcam-sdk among others.
Create Dockerfile with the following content:

Tip

The docker container runs a debian system. Vendor libraries for ubuntu are therefore mostly compatible.
Run sudo docker buildx build --tag herosdevices:pvcam .

Tip

The :pvcam is the tag name of the image. You should choose something to make it descriptive of what you put in the image.
In your docker compose files, replace the registry.gitlab.com/atomiq-project/herosdevices:latest by herosdevices:pvcam.

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