.. include:: /keyword.rst

==============================
Setup Tool Environment (Linux)
==============================

The flash programming process is performed over a USB connection between the target board and the host computer containing the image.

To do so, you need to install Genio tools. It is a set of tools to configure or interact with MediaTek Genio boards.

.. note::
   Genio tools also supports Windows. Please visit :ref:`this page <windows-tool-setup>` if you want to flash the board under Windows environment, however a Linux host is required for building.

.. contents:: Sections
    :local:
    :depth: 1

System Requirements
===================

To install Genio tools on a Linux host, you need:

* Internet connection
* Ubuntu 20.04 or later LTS version
* Administrator privilege
* Python 3.9 or later; Python 3.12 recommended
* pip3 20.3 or later
* Fastboot 34.0 or later

.. note::

    If your board is powered through a USB-C connector, e.g. i500-pumpkin, we recommend using high quality "fast charging" USB-C cables.


Python 3
========

If you don't have Python 3 and pip installed, run following commands to install them.

.. prompt:: bash

    sudo apt update
    sudo apt-get install python3
    sudo apt-get install python3-pip

You can check Python and pip versions by running the following commands:

.. prompt:: bash $ auto

    $ python3 --version
    Python 3.10.12
    $ pip3 --version
    pip 23.3.1 from /usr/bin/pip3 (python 3.10)

If your version of ``pip3`` is older than 20.3. Please upgrade it by running:

.. prompt:: bash $

	pip3 install --upgrade pip


Fastboot and ADB
================

Genio tools use `Fastboot <https://android.googlesource.com/platform/system/core/+/master/fastboot/#fastboot>`_ to flash images onto the device. Therefore, please ensure that the Fastboot device driver is properly installed before proceeding. After flashing the board with **rity-demo-image**, you can use the ADB tool to interact with the device, such as running commands and transferring files.

Both Fastboot and ADB tools are available as packages for Ubuntu. Please run following commands to install the tools:

.. prompt:: bash

    sudo apt update
    sudo apt-get install adb fastboot

.. note::
    Refer to `Android SDK Platform-Tools <https://developer.android.com/studio/releases/platform-tools>`_ to install Fastboot if you are using Linux distributions other than Ubuntu.


USB Device Rules
^^^^^^^^^^^^^^^^

To allow your host machine to communicate with the board via USB without requiring root privileges,
you need to create a `udev` rule that grants user access to the device:

.. prompt:: bash $ auto

    $ echo -n 'SUBSYSTEM=="usb", ATTR{idVendor}=="0e8d", ATTR{idProduct}=="201c", MODE="0660", TAG+="uaccess"
    SUBSYSTEM=="usb", ATTR{idVendor}=="0e8d", ATTR{idProduct}=="0003", MODE="0660", TAG+="uaccess"
    SUBSYSTEM=="usb", ATTR{idVendor}=="0403", MODE="0660", TAG+="uaccess"
    SUBSYSTEM=="gpio", MODE="0660", TAG+="uaccess"
    ' | sudo tee /etc/udev/rules.d/72-aiot.rules
    $ sudo udevadm control --reload-rules
    $ sudo udevadm trigger

.. note::
    `udev <https://en.wikipedia.org/wiki/Udev>`_ is a device manager for the Linux kernel.
    It can be used to grant an user or a group the permission to access a device.

Also, add new `udev` rule and add your user account to ``plugdev`` group if you plan to use `adb` to connect to the board:

.. prompt:: bash

    echo 'SUBSYSTEM=="usb", ATTR{idVendor}=="0e8d", ATTR{idProduct}=="201c", MODE="0660", GROUP="plugdev"' | sudo tee -a /etc/udev/rules.d/96-rity.rules
    sudo udevadm control --reload-rules
    sudo udevadm trigger
    sudo usermod -a -G plugdev $USER

After adding your user account to the group, you must logout and login again for the changes to take
effect. This setup only needs to be performed once.


UART Setup
==========

For Linux users, before you can connect to the device you must check if your user account is
a member of the ``dialout`` group:

.. prompt:: bash $ auto

    $ groups
    user dialout cdrom floppy sudo audio dip video plugdev netdev bluetooth

If not, you need to add your account to that group:

.. prompt:: bash $

    sudo usermod -a -G dialout $USER

This last command requires you to logout and login again with your account to make
it effective. You only have to do this once.


Install a Serial Terminal Emulator
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

A serial terminal emulator is required to communicate with the UART serial console provided by |IOT-YOCTO|.
There are a number of serial terminal emulators for Linux, including `picocom <https://github.com/npat-efault/picocom>`_ and `screen <https://savannah.gnu.org/projects/screen>`_.

To install picocom run:

.. prompt:: bash

    sudo apt update
    sudo apt-get install picocom

To install screen run:

.. prompt:: bash

    sudo apt update
    sudo apt-get install screen


Install Genio Tools
===================

Genio Tools contains the following utilities:

* ``genio-config`` checks if Linux or Windows host has proper setup.
* ``genio-flash`` provides flash writing functions.
* ``genio-board`` allows you to reset the board programmatically.

Only ``genio-flash`` and ``genio-config`` are used throughout operations mentioned in this guide. For usage of other utilities, please refer to :ref:`tools/genio-tools:Genio Tools`.

After finishing the installation of the required packages and necessary configuration, we are now ready to install Genio Tools:

.. prompt:: bash

    pip3 install -U genio-tools

.. important::

    Please logout and login again after installing `genio-tools`. 
    This makes sure the ``PATH`` environment variable is being properly updated.

After re-login, please check your installation with ``genio-config``:

.. prompt:: bash $ auto

    $ genio-config
    fastboot: OK
    udev rules: OK

In case your environment is not set up correctly, the tool provides you with instructions on how to correctly configure it.