.. 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.

Genio tools also supports Windows. Please visit :ref:`this page <windows-tool-setup>` if you want to flash the board under Windows environment.

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

Host System Requirement
=======================

To install **Genio Tools** on a Linux host, you need:

* Ubuntu 18.04 or later LTS version
* Administrator privilege
* Internet connection
* Git 1.8 or later
* Python 3.8 or later
* pip3 20.3 or later
* fastboot 28.0.2 or later

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`.

.. warning::

    ``genio-board`` is not supported under Windows environment. You can flash the image with ``genio-flash``, but can not power-cycle Genio 350-EVK with ``genio-board`` under Windows environment.

.. 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.


Setup Genio Tools on Linux
==========================

On Linux, follow these steps to setup required software, USB device rules and install Genio Tools.

Git
^^^

.. prompt:: bash

    add-apt-repository ppa:git-core/ppa
    apt update
    apt-get install git

Python3
^^^^^^^

If you don't have Python and pip installed on your Ubuntu, 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.9.2
	$ pip3 --version
	pip 21.2.4 from /usr/bin/pip3 (python 3.9)

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

.. prompt:: bash $

	pip3 install --upgrade pip

Fastboot
^^^^^^^^

Genio tools use `fastboot <https://android.googlesource.com/platform/system/core/+/master/fastboot/#fastboot>`_ to flash image, so you also need to install the fastboot executable. Run following commands to install packages:

.. prompt:: bash

    sudo apt update
    sudo apt-get install android-tools-adb android-tools-fastboot

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
^^^^^^^^^^^^^^^^

In order for your host machine to be able to talk to the board through USB without needing root privileges,
you need to create a udev rules that will grant user access to your 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

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


`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.
In this case, we added an udev rule to assign ``plugdev`` group to the newly created SoC USB device.
In order to access the SoC, your user account must be a member of the ``plugdev`` group.


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.

.. _uart-setup-linux:

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:

.. parsed-literal::

	$ groups | grep dialout
	**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.