Getting Started - Heros Devices 0.8.0 documentation

Skip to content
Back to top
View this page

# 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