.. _control-setup:

Setup Control module
====================

The control module currently uses an model predictiv control approach based on a solver by embotech. This solver needs
to be built first before it can be used. In theory and maybe in the future it is possible to built this solver
on one machine and share it with others. Currently we built the solver on the machine we want to use it.

To built a solver one needs an embotech engineering license.
This license is only valid for one specific host computer identified by some finterprint.

To use the solver one needs floating licenses (we don't have any, at the moment) or atleast an software or hardware testing license.
This license is also bind to a system finterprint. Since we want to use the solver inside a docker container,
we need to create and assign a new license every time we run a new container. Since one shouldn't recreate a container lightly.

Prerequisites
-------------

You have to:

#. Assign your docker container a software or hardware license

#. Setup a virtual python environment (venv / virtualenv)

#. Assign your host system an engineering license.

#. Download and install the forces pro client.


Open MyEmbotech Portal
``````````````````````
#. Log into the `MyEmbotech Portal`_.

#. Switch to the overview page for our `license group`_.


Assign the license for the docker container
```````````````````````````````````````````

#. Execute the fingerprint  tool inside the docker container:

   .. code-block:: bash

      docker exec -it as bash
      ./src/control/FORCES_PRO_Fingerprinter_docker_linux_x86_64

#. Copy the finterprint and assign a software or hardware license with ``Docker-Gnu-x86_64`` as platform.

Setup a virtual environment for assigning the license for the host system:
``````````````````````````````````````````````````````````````````````````

When you don't know, what an python virtual environment is, you can find an tutorial `here <https://www.geeksforgeeks.org/python-virtual-environment/>`_.
Either use Ubuntu for the following steps or execute them in the WSL.

1. First, you have to install the virtualenv library for python

   .. code-block:: bash

      python3 -m pip install virtualenv

2. Change into the directory of the clones repository and create the virtualenv. The virtualenv will be created under ``./venv``

   .. code-block:: bash

      python3 -m virtualenv venv

3. Activate the virtual environment.

   .. code-block:: bash

      source venv/bin/activate

4. Install all necessary requirements

   .. code-block:: bash

      pip install av
      pip install -r docker/additional_resources/requirements_base.txt
      pip install numpy==1.23.5

Assign the license for the host system
``````````````````````````````````````

#. Choose the ``Engineering Licenses`` tab on the overview page for our `license group`_.

#. Assign or transfer (preferably for a computer that doesn't need it anymore) an engineering license.

#. Download the fingerprint generator for your host os.

#. Make the generator executable and execute it.

   .. code-block:: bash
      :caption: Make the finterprint generator executable and execute it on Unix host system

      chmod +x FORCES_PRO_Fingerprinter_linux_x86_64 && ./FORCES_PRO_Fingerprinter_linux_x86_64

#. Copy the fingerprint and assign an engineering license.

#. Download the client for the newly assigned engineering license.

#. Unzip the downloaded client into ``./src/control/forces_pro_client``

   You have to redownload the forces pro client everytime you assigned a new software or hardware testing license which
   you want to use with a solver generated with the respective engineering license.

.. #. Create a python virtual Python environment on the host system and install all python dependencies.

..    a. Ensure that the python library ``virtualenv`` is installed: ``python3 -m pip install virtualenv``

..    b. Create a virtual Python environment: ``python3 -m virtualenv venv``

..    c. Activate the virtual python environment: ``source venv/bin/activate``

..    d. Install all base python requirements: ``pip install av && pip install -r docker/additional_resources/requirements_base.txt``

Generate solver
---------------

You always have to regenerate the mpc if you changed its configuration.

.. .. code-block:: bash
..    :caption: Unix

..    source venv/bin/activate

.. .. code-block:: bash
..    :caption: Windows

..    ./venv/bin/activate.bat

#. Ensure that you activated the virtual python environment.

#. Ensure that you specified a suitable configuration for the mpc in ``src/control/config/control.yaml``

#. Generate the solver:

   .. code-block:: bash

      cd src/control/scripts/ && python generate_solver.py

#. Go broom!

.. _MyEmbotech Portal: https://my.embotech.com

.. _license group: https://my.embotech.com/license_groups/7AC8ADE2-CAFE-4412-B54B-4BB5F69E059E