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


.. _download_aidk:

Download AIDK library
-------------------------

AIDK library can be downloaded to the workstation PC from any of the following sources: 

   * GitHub repository `[flexiv_aidk] <https://github.com/flexivrobotics/flexiv_aidk/>`_.


.. important::
   Before downloading, please refer to the release note to confirm the AIDK version that's compatible with the NoemaEdge App currently. If not compatible, some features may not be supported.


Setup and run C++ AIDK  
----------------------

.. note::
   If you will only be using Python AIDK, you can skip this section and jump to :ref:`setup_and_run_python_aidk`.

The C++ AIDK is packed into a unified modern CMake library named ``flexiv_aidk``, which can be configured via CMake on all supported OS.

.. _compile_and_install_for_linux:

Compile and install for Linux
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

.. note::
   For Ubuntu, the installed version of ``gcc`` and ``g++`` should be greater than 9.0.

1. In a new Terminal, install C++ compiler, Git, and CMake (with GUI) using the package manager::

        sudo apt install build-essential git cmake cmake-qt-gui -y

2. Choose a directory for installing ``flexiv_aidk`` library and all its dependencies. For example, a new folder named ``aidk_install`` under the home directory.
3. In a new Terminal, use CMake to configure ``flexiv_aidk``::

        cd flexiv_aidk
        mkdir build && cd build
        cmake .. -DCMAKE_INSTALL_PREFIX=~/aidk_install

  .. note::
    ``-D`` followed by ``CMAKE_INSTALL_PREFIX`` is a CMake parameter specifying the path of the chosen installation directory. Alternatively, this configuration step can also be done through CMake GUI.

4. Compile and install ``flexiv_aidk`` library::

        cd flexiv_aidk/build
        cmake --build . --target install --config Release

  .. note::
    The installation of ``flexiv_aidk`` library is complete now. The following steps show how to link to the installed library from a user project.

5. To find and link to the installed ``flexiv_aidk`` library from a user project, using the provided example project for instance::

        cd flexiv_aidk/example
        mkdir build && cd build
        cmake .. -DCMAKE_INSTALL_PREFIX=~/aidk_install
        cmake --build . --config Release -j 4

  .. note::
    ``-D`` followed by ``CMAKE_INSTALL_PREFIX`` tells user project's CMake where to find the installed ``flexiv_aidk`` library.


Run example C++ program
~~~~~~~~~~~~~~~~~~~~~~~~~

1. Make sure InferApp in NoemaEdge is already running and the connection between the workstation PC and the NoemaEdge App is successfully established according to the aforementioned instructions.
2. To run an compiled example program::
      
        ./test_aidk_compute [address] [config_path] [total_num] [enable_v1x]
        ./test_aidk_others [address] [config_path] [version]

   e.g. to communicate with NoemaEdge App (version v3.1.0) running in remote machine with ip 10.24.14.101::

        ./test_aidk_compute 10.24.14.101 ../../config/GRASPNET.json 1 false
        ./test_aidk_others 10.24.14.101 ../../config/GRASPNET.json v3.1.0

  .. note::
    ``sudo`` is not required unless prompted by the program saying "root privilege is required".
    

3. To close the running example program, simply press ``Ctrl+C``. 

.. _setup_and_run_python_aidk:

Setup and run Python AIDK  
------------------------

The Python AIDK provides a fast and compilation-free way to deploy AIDK programs.

Install supported version of Python
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Python **3.8** and **3.10** can be used to run Python AIDK on all supported ubuntu 18,20,22. To check the version of currently installed Python::

      python3 --version

If the version does not match neither of the supported Python version, you can install the supported version of Python using instructions below.

Linux
^^^^^^

On Linux, to install a specific version of Python alongside the existing Python, the easiest way is to use a PPA::

      sudo apt install software-properties-common
      sudo add-apt-repository ppa:deadsnakes/ppa

Press ``Enter`` to confirm adding the PPA, then install the desired Python version::

      sudo apt update
      sudo apt install python3.x

When done, this specific version of Python can be directly invoked from Terminal using ``python3.x``::

      python3.x --version

Some AIDK Python examples require packages installed from the ``pip`` Python package manager. To install ``pip`` 
for the PPA-installed Python 3.x::

      sudo apt install python3.x-distutils
      wget https://bootstrap.pypa.io/get-pip.py
      python3.x get-pip.py

Once it's finished, you can install a Python package discoverable by the PPA-installed Python 3.x via::

      python3.x -m pip install <package_name>

.. warning::
   The ordinary ``sudo apt install python3-pip`` method will only install ``pip`` for the system's native Python 3, 
   and Python packages installed from this ``pip`` is not discoverable by the PPA-installed Python 3.x.


Run example Python program
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

Similar to *Run example C++ program*, but without the need for any compilation, the execution command for example Python program is:: 

      cd flexiv_aidk/example_py
      python3 test_aidk_compute.py --ip [address] --config [config_path] --num [num] (--enable-v1x)

For example, to communicate with local running NoemaEdge:

      python3 test_aidk_compute.py --ip 127.0.0.1 --config ../config/GRASPNET.json --num 1

The NoemaEdge App will compute best grasp pose and gripper width from camera rgbd input, and send it to aidk client. The output log is:
         
      .. code-block:: c

            INFO:root:Namespace(config='../config/GRASPNET.json', enable_v1x=False, ip='127.0.0.1', num=1)
            INFO:root:Test config:
            {'project': 'GRASPNET', 'command': {'command': 'POSE6D', 'obj_name': 'GRASPNET_graspnet_0', 'coordinate_id': 0, 'camera_id': 'CAMID_0', 'instruction_id': -1, 'custom': 'test_0', 'camera_pose': [0.55, -0.034, 0.66, 0.0, -0.7071068, 0.7071068, 0.0]}, 'keys': ['obj_pose', 'double_value']}
            INFO:root:detect 0: 370.9 ms, 2.7 Hz, instruction -1
            INFO:root:state: True
            INFO:root:current detected object names: ['GRASPNET_graspnet_0'], current detected object nums: [1]
            INFO:root:key: obj_pose
            INFO:root:[0.5027717547217662, -0.003570836059272227, 0.25158332987576737, 0.08253609149323858, -0.3200245424326347, -0.943391842633212, -0.027998519512926395]
            INFO:root:key: double_value
            INFO:root:0.07259449357263434

.. note::
  Replace command ``python3`` with ``python3.x`` to explicitly invoke a specific version of Python.


Client-server reconnection  
---------------------------

When the AIDK user program is terminated or the connection is lost, the NoemaEdge App supports on-the-fly reconnection, so you can terminate a user program and start a new one without doing anything to the NoemaEdge App.

The next chapter will provide more details on the AIDK library, and you can also check out the other examples 
to get familiar with it.