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:

# Base image to expand
FROM registry.gitlab.com/atomiq-project/herosdevices

# Copy the vendor library into the container
COPY pvcam /pvcam

# Install prerequisites
RUN apt-get update && apt-get install -y sudo git

# Install the vendor library itself
# We have to agree to some licenses here so we use the "yes" command.
# The EUID=1 is a little hack to trick the installer into thinking we're not root.
RUN yes | EUID=1 /bin/bash /pvcam/pvcam__install_helper-Ubuntu.sh

# Remove build files after installation to make image a bit smaller
RUN rm -rf /pvcam

# We need to point the python api to the correct library path
ENV PVCAM_SDK_PATH="/opt/pvcam/sdk"
# Install python API
RUN pip install --break-system-packages PyVCAM

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