Getting Started
===============

This package provides many drivers for different lab hardware. You can find them all in the list here :ref:`hardware-index`.



Starting a device HERO
----------------------

.. important::

   All drivers also run without BOSS, however to use all features we strongly recommend starting them via `BOSS <https://boss-eb4966.gitlab.io/>`_!

The following examples assume a camera device configuration hosted in a CouchDB like:

.. code-block:: json

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

Check out the `BOSS documentation <https://boss-eb4966.gitlab.io/getting_started.html>`_ to learn more about possible sources.

.. tabs::

   .. tab:: Docker Container

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

      .. code-block:: yaml

          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

      .. code-block:: bash

          docker compose up


   .. tab:: Local Installation

      The device representations can also be installed locally via pip:

      .. hint::

         We recommend using `uv <https://docs.astral.sh/uv/>`_ to maintain an enclosed python environment.

      .. code-block::

         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

      .. code-block::

         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 <https://atomiq-atomiq-project-515d34b8ff1a5c74fcf04862421f6d74a00d9de1b.gitlab.io/heros.html#using-heros-in-the-atomiq-experiment>`_
   so components can be exchanged seamlessly. Look out for inheritance from :py:class:`herosdevices.interfaces.atomiq.AtomiqInterface`.

Adding vendor libraries
-----------------------

.. tabs::

   .. tab:: Docker Container

     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 :py:class:`herosdevices.hardware.teledyne.pvcam.PvcamCamera`:

     - Create a new a directory and download and unzip the `binary drivers <https://www.teledynevisionsolutions.com/products/pvcam-sdk-amp-driver/?model=PVCAM-SDK&vertical=tvs-princeton-instruments&segment=tvs>`_.
       There should now be two folders ``pvcam`` and ``pvcam-sdk`` among others.
     - Create ``Dockerfile`` with the following content:

       .. literalinclude :: ../../examples/expand_docker/Dockerfile
          :language: docker


       .. 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``.


   .. tab:: Local Installation

      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:

      .. code:: bash

        uv pip install PyVCAM