.. _hardware-external:

Drivers from other Libraries
============================

Some drivers from other Python libraries require extra treatment for compatibility with HEROS. BOSS supports auto wrapping of these drivers to make them compatible for some libraries.

.. note::

   To use the external Libraries, you do not need to install the ``herosdevices`` library. They can be directly started with `BOSS <https://boss-eb4966.gitlab.io/index.html>`_.

.. warning::

   As we do not have any influence of the code in the external libraries, no
   warranty can be given for their functionality. We can not guarantee that they will be open source, available or up to date for all time.
   Please refer to the documentation of the external libraries for further information and report bugs in the drivers to the corresponding developers.

Devices which are available from other libraries that are supported by BOSS are also listed in :ref:`our hardware list <hardware-index>` and marked accordingly.

.. tip::

    BOSS also provides mechanisms to :ref:`adjust and configure
    <boss-json-datasource>` the device classes through JSON, for easier use
    with observables and data acquisition. You can also learn more about this
    in :ref:`this tutorial <tutorial_observables>`.


.. _qcodes:

QCoDeS
------

`QCoDeS <https://microsoft.github.io/Qcodes/>`_ is a Python-based data acquisition framework developed by Microsoft. Besides
a comprehensive suite of tools for controlling instruments and managing experimental data, it also provides a rich set of drivers for various instruments.
QCoDeS instrument driver classes can be directly used with HEROS through `BOSS <https://boss-eb4966.gitlab.io/index.html>`_, enabling seamless integration with the HEROS ecosystem.


Using QCoDeS with HEROS
^^^^^^^^^^^^^^^^^^^^^^^^

QCoDeS is built around the concept of Parameters, which are similar in principle to
HEROS's :py:class:`herosdevices.core.DeviceCommandQuantity` class. These Parameters represent controllable aspects
of instruments and can be read from or written to.

The available parameters for a QCoDeS device are documented in the corresponding
QCoDeS class documentation. When initializing a QCoDeS device in HEROS, you specify
the parameters you want to use through the ``parameters`` list argument. All other arguments
are passed directly to the constructor of the underlying QCoDeS device.

Parameters of QCoDeS submodules are specified by a dot notation. For example to specify the ``source``
`parameter <https://microsoft.github.io/Qcodes/drivers_api/Keysight.html#qcodes.instrument_drivers.Keysight.Keysight344xxATrigger.source>`_
of the ``trigger`` `submodule <https://microsoft.github.io/Qcodes/drivers_api/Keysight.html#qcodes.instrument_drivers.Keysight.Keysight344xxA.trigger>`_,
add the parameter ``trigger.source`` to the ``parameters`` list.


Example Configuration
^^^^^^^^^^^^^^^^^^^^^^

Below is an example JSON configuration for a `Keysight 34410A <https://microsoft.github.io/Qcodes/drivers_api/Keysight.html#qcodes.instrument_drivers.Keysight.Keysight34410A>`_
QCoDeS device which exposes the parameters ``volt`` and ``source`` of the ``trigger`` submodule:

.. code-block:: json

    {
      "_id": "my_qcodes_device",
      "classname": "qcodes.instrument_drivers.Keysight.Keysight34410A",
      "arguments": {
        "address": "TCPIP::172.16.111.169::INSTR",
        "parameters": [
          "volt",
          "trigger.source"
        ]
      }
    }

.. _pylablib:

PyLabLib
--------

`PyLabLib <https://github.com/AlexShkarin/pyLabLib>`_ is a Python-based instrument control and automation framework.
PyLabLib instrument driver classes can be directly used with HEROS through `BOSS <https://boss-eb4966.gitlab.io/index.html>`_, enabling seamless integration with the HEROS ecosystem.

Using PyLabLib with HEROS
^^^^^^^^^^^^^^^^^^^^^^^^^

PyLabLib uses similar paradigms in their device drivers like us or use ``set`` and ``get`` methods to manipulate the device, which makes their drivers work well with HEROS without needing extensive wrapper classes.
This means, that you can use the drivers like in their documentation without adjustment.

Example Configuration
^^^^^^^^^^^^^^^^^^^^^^

Below is an example JSON configuration for a `Thorlabs Kinesis Cube <https://pylablib.readthedocs.io/en/stable/devices/Thorlabs_kinesis.html>`_:

.. code-block:: json

    {
      "_id": "kinesis-cube",
      "classname": "pylablib.devices.Thorlabs.kinesis.KinesisPiezoMotor",
      "arguments": {
        "conn": "/dev/ttyUSB0"
      }
    }