.. _setting_up_et:

#######################################
Setting Up and Running Exploration Tool
#######################################

This page will help you

* Install and run Exploration Tool
* Connect your EVK to Exploration Tool
* Start retrieving Radar Data using Exploration Tool


.. _installation-and-setup:

*****************************
Exploration Tool Installation
*****************************

Depending on what you wish to accomplish with Exploration Tool or the :doc:`Python API </exploration_tool/api/index>`,
you can install in different ways.

If you are unsure, pick the *Quick Start* for your operating system.

Refer to the :ref:`capability table <install-options-capability-table>` if you want to learn the difference between the different options.

.. tab-set::

   .. tab-item:: :fab:`windows;fa-xl` Quick Start

      If you have a Windows PC and you're only interested in running Exploration Tool to see visualizations,
      experiment with configurations or use the :doc:`/resource_calc`, the Portable Windows
      package is a great choice.

      Get started with the following steps:

      #. :octicon:`download` `Download the zip <portable_et_download_>`_
      #. Extract the ``.zip`` file in a suitable place
      #. Double-click the ``update`` script
      #. Double-click the ``run_app`` script to start the Exploration Tool Application


      It's also possible to install & run Exploration Tool with ``uv``
      (terminal-based package manager, read more `here <https://docs.astral.sh/uv/>`_):

      .. code-block::
         :caption: Command to install ``uv`` in Windows (using ``cmd`` or PowerShell)

         winget install --id=astral-sh.uv  -e

      .. code-block::
         :caption: Running Exploration Tool Application with ``uvx`` (part of ``uv``)

         uvx acconeer-exptool[app]

   .. tab-item:: :fab:`ubuntu;fa-xl` Quick Start

      If you are familiar with the Python echo system, you might have heard of ``uv``.
      Regardless, you are (at a maximum) 2 terminal command away from running the
      Exploration Tool Application:

      .. code-block:: bash
         :caption: Linux command to install ``uv``

         $ curl -LsSf https://astral.sh/uv/install.sh | sh

      .. code-block::
         :caption: Running Exploration Tool Application with ``uvx`` (part of ``uv``)

         uvx acconeer-exptool[app]

   .. tab-item:: :fab:`python;fa-xl` Python Package

      If you have a PC with Windows or Ubuntu, want to use Python,
      want to run the Exploration Tool Application,
      and interested in scripting using the :doc:`Python API </exploration_tool/api/index>`,
      you can install the `Exploration Tool Python package <et_pypi_>`_.
      Information on example scripts can be found in :ref:`python_api_example_scripts`.

      Python is needed to install the package. If you don't have Python installed, see below for instructions,
      otherwise go to next step.

      .. tab-set::

         .. tab-item:: :fab:`windows;fa-xl` Windows

            #. Go to `python.org <https://www.python.org/downloads/>`_ and download the latest version
            #. Start the installer
            #. Select 'Add python to PATH'
            #. Click 'Install Now'
            #. Disable path length limit
            #. Click 'Close'

         .. tab-item:: :fab:`ubuntu;fa-xl` Ubuntu

            Go to `how-to-install-python <https://phoenixnap.com/kb/how-to-install-python-3-ubuntu>`_ for example how to install.

      Install the Exploration Tool package:

      .. code-block::

         python -m pip install --upgrade acconeer-exptool[app]

      .. note::
         Depending on your environment, you might have to replace ``python`` with ``python3`` or ``py``.

      .. dropdown:: Python API in non-graphical environments

         If you only want to use the :doc:`Python API </exploration_tool/api/index>` and not use the
         Exploration Tool Application, for example on a platform that might not support graphical programs
         (like Raspberry Pi), skip installing the graphical dependencies by
         only installing the ``algo`` *extra*:

         .. code-block::

            python -m pip install --upgrade acconeer-exptool[algo]

      If you run into any issues during installation, try installing Exploration Tool
      in a virtual environment (`Guide <venv_guide_>`_)

      Finally, run

      .. code-block::

         python -m acconeer.exptool.app

      to start the Exploration Tool Application.

      .. tip::
         Running the command ``python -m acconeer.exptool.app.new``
         will start the new Exploration Tool directly

   .. tab-item:: :fab:`github;fa-xl` GitHub

      If you have a PC with Windows or Ubuntu and want a more flexible install than what's offered
      in the **Python Package** install, Exploration Tool is open source on `GitHub <et_github_>`_.

      This allows you to edit the source code (which should not be done in the other installation options),
      create `Forks <gh_docs_forks_>`_ and much more.

      To install the latest version from source; download or clone the repository from `GitHub <et_github_>`_.
      Run the following command in the newly created directory:

      .. code-block::

         python -m pip install --upgrade .[app]

      .. note::
         Any edit to the source code requires reinstalling ``acconeer-exptool`` unless you are using an editable install:

         .. code-block::

            python -m pip install -e .[app]

         You can read more about editable installs `here <pip_docs_editable_>`_.

      If you run into any issues during installation, try installing Exploration Tool
      in a virtual environment (`Guide <venv_guide_>`_)

      Finally, run

      .. code-block::

         python -m acconeer.exptool.app

      to start the Exploration Tool Application.

      .. tip::
         Exploration Tool is managed with ``hatch`` (`Install guide <hatch_install_>`_), which automates
         virtual environments and the editable install for you.

         After cloning or downloading the repo from GitHub and installing ``hatch``,
         start the Exploration Tool Application by running the command

         .. code-block::

            hatch run app:launcher

         To skip the launcher, you can go to the *new* Exploration Tool directly with

         .. code-block::

            hatch run app:new

.. dropdown:: Install Options Capability Table
   :name: install-options-capability-table

   ================================ ====================== ==================== ============== =======
   Capability                       Quick Start (Portable) Quick Start (``uv``) Python Package GitHub
   ================================ ====================== ==================== ============== =======
   Run Exploration Tool Application **Yes**                **Yes**              **Yes**        **Yes**
   Run |example_scripts|            No                     No                   **Yes**        **Yes**
   Add your |own_plugin|            No                     **Yes**              **Yes**        **Yes**
   Modify ET's source code          No                     No                   No             **Yes**
   ================================ ====================== ==================== ============== =======

   .. |example_scripts| replace:: :doc:`example scripts </exploration_tool/example_scripts/index>`
   .. |own_plugin| replace:: :doc:`own plugin </exploration_tool/adding_your_own_plugin>`

****************
Additional Setup
****************

.. tab-set::

   .. tab-item:: :fab:`windows;fa-xl`

      If you encounter any connection issues while following along :ref:`installation-and-setup` you *might* be missing
      drivers that allow proper function of Acconeer's modules.

      See :doc:`evk_setup/index` for your specific module for more information.

   .. tab-item:: :fab:`ubuntu;fa-xl`

      After installing the ``acconeer-exptool`` package, you can run:

      .. code-block::

         python -m acconeer.exptool.setup

      which lets you interactively configure your machine and download needed dependencies.
      This is done in order for your machine to work at its best with Exploration Tool.
      ``acconeer.exptool.setup`` performs the same steps that are described in the **Details** below.

      .. dropdown:: Details

         Serial port permissions
            If you are running Linux together with an XM112, XM122, or XM132 module through UART,
            you probably need permission to access the serial port. Access is obtained by adding
            yourself to the ``dialout`` group:

            .. code-block::

               sudo usermod -a -G dialout $USER

            Reboot for the changes to take effect.

            .. note::
               If you have ``ModemManager`` installed and running it might try to connect to the module,
               which has proven to cause problems. If you are having issues, try disabling the ``ModemManager`` service.

         USB permissions
            If you are using Linux together with an XC120, the USB communication is preferred over
            serial port communication. To be able to access the USB device.
            Either run the scripts with ``sudo`` or create an ``udev`` rule as follows. Create and edit:

            .. code-block::

               sudo nano /etc/udev/rules.d/50-xc120.rules

            with the following content:

            .. code-block::

               SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="a41d", MODE:="0666"
               SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="a42c", MODE:="0666"
               SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="a42d", MODE:="0666"
               SUBSYSTEM=="usb", ATTRS{idVendor}=="0483", ATTRS{idProduct}=="a449", MODE:="0666"

            This method is confirmed to work for **Ubuntu 22.04**.

         SPI permissions
            If you are using Linux together with an XM112, you probably need permission to access the SPI bridge USB device.
            Either run the scripts with ``sudo`` or create an `udev` rule as follows. Create and edit:

            .. code-block::

               sudo nano /etc/udev/rules.d/50-ft4222.rules

            with the following content:

            .. code-block::

               SUBSYSTEM=="usb", ATTRS{idVendor}=="0403", ATTRS{idProduct}=="601c", MODE:="0666"

            This method is confirmed to work for ***Ubuntu 22.04**.

         Ubuntu 22.04
            To run the application on Ubuntu 22.04, ``libxcb-xinerama0-dev``, ``libusb-1.0-0`` and
            ``libxcb-cursor0`` needs to be installed:

            .. code-block::

               sudo apt update
               sudo apt install -y libxcb-xinerama0-dev libusb-1.0-0 libxcb-cursor0

            Udev needs to be informed that rules have changed if changes have been made in ``/etc/udev/rules/``:

            .. code-block::

               sudo udevadm control --reload-rules
               sudo udevadm trigger

            An USB device have to be disconnected and reconnected before the udev permissions are updated.


.. _connecting-your-evk:

*******************
Connecting Your EVK
*******************

The next step is to connect Exploration Tool to your EVK. See :doc:`evk_setup/index` for instructions.

When that is done, depending on how you installed in :ref:`installation-and-setup`, start Exploration Tool by either

* Double-clicking the ``run_app`` script,
* Running the command ``python -m acconeer.exptool.app`` in your terminal.

To connect, click on the **Stream tab** and then the **Connect** button. Use the same port as when flashing the device in :doc:`evk_setup/index`.


.. _getting-radar-data:

******************
Getting Radar Data
******************

After that, have a look at the functional overview below for an introduction of Exploration Tool:

.. youtube:: NXmYK40akvU
   :width: 100%

Running Example Scripts
=======================

See :ref:`python_api_example_scripts` section on how to get started with Example Scripts and the :doc:`Python API </exploration_tool/api/index>`.


.. _other-media:

***********
Other Media
***********

For Getting Started videos, see:

* *Getting started with the XM126 EVK*: `YouTube <yt_xm126_getting_started_>`_
* *Getting started with the XE125 EVK*: `YouTube <yt_xe125_getting_started_>`_
* *Getting started with the A121 EVK*: `YouTube <yt_xe121_getting_started_>`_

If information is different in the videos compared to this site, use the information on this site.


.. _et_github: https://github.com/acconeer/acconeer-python-exploration
.. _et_pypi: https://pypi.org/project/acconeer-exptool
.. _gh_docs_forks: https://docs.github.com/en/pull-requests/collaborating-with-pull-requests/working-with-forks/fork-a-repo
.. _hatch_install: https://hatch.pypa.io/latest/install/
.. _pip_docs_editable: https://pip.pypa.io/en/stable/topics/local-project-installs/#editable-installs
.. _portable_et_download: https://developer.acconeer.com/download/portable_exploration_tool
.. _venv_guide: https://packaging.python.org/en/latest/guides/installing-using-pip-and-virtual-environments/
.. _yt_xe121_getting_started: https://www.youtube.com/watch?v=5fCZnHZYJhA&list=PLBXaD001iDmsY03T91ltIomJjMNzmk0aY
.. _yt_xe125_getting_started: https://www.youtube.com/watch?v=Z8lQgxaJFOY&list=PLBXaD001iDmsY03T91ltIomJjMNzmk0aY
.. _yt_xm126_getting_started: https://www.youtube.com/watch?v=MxdJxe9-ipw&list=PLBXaD001iDmsY03T91ltIomJjMNzmk0aY