.. include:: /keyword.rst

.. _windows-tool-setup:

================================
Setup Tool Environment (Windows)
================================

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.

.. warning::

    You must use a :doc:`Linux host computer <build-env-linux>` to build the IoT Yocto images.
    The Windows tool environment can be used for flashing pre-built images to the board and communicating with the board.

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

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

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

* Administrator privilege
* Internet connection
* Git 1.8 or later
* Python 3.8 or later
* pip3 20.3 or later
* Fastboot 34.0.4 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.


Git
===

Download and install `Git for Windows <https://gitforwindows.org/>`_.

After installation, open the **git bash** program and execute the following configuration commands:

.. prompt:: batch >

    git config --global http.sslBackend schannel
    git config --global credential.helper manager-core

This configures git to use Windows default credentials and secure connection channels.

Python 3
========

.. note::

        There are known issues reported for Python 3.10 on Windows platform when installing **genio-tools**.
        If you use Windows, we recommend you to **install Python 3.9**.

Follow these steps to install Python 3 and pip:

#. Download and install **Python 3.9** from https://www.python.org/downloads/release/python-3912/.
    * Make sure you've ticked the **Add Python to environment variables** or **Add Python to PATH** checkbox:

      .. figure:: /_asset/sw_yocto_get-started_env-setup_flash-env-windows_python-path.png
          :width: 614px

#. Make sure the version of ``pip3`` is greater than 20.3:

    * Launch a Command Prompt as administrator. To do so:
        * Press ``Windows+R`` to open the Run dialog
        * Type ``cmd`` into the box and then press ``Ctrl+Shift+Enter`` to run the command prompt as an administrator.
        * Run the following command:

        .. prompt:: batch > auto

            > pip3 --version
            pip 21.2.4 from c:\python39\lib\site-packages\pip (python 3.9)

.. note::

    If your windows console cannot locate ``pip3``, add the Python installation path and script path to your ``PATH`` environment variable, in some cases these paths are located in:
    
    * ``C:\Users\<your_username>\AppData\Local\Programs\Python\<python_version>``
    * ``C:\Users\<your_username>\AppData\Local\Programs\Python\<python_version>\Scripts``

.. note::
    If you are behind a corporate firewall, you might want to install additional packages to make sure Python can correctly process additional certificates:

    .. prompt:: batch >

        pip3 install python-certifi-win32 --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host files.pythonhosted.org --trusted-host gitlab.com

    After installation, add the following environment variable to your Windows system:

    .. prompt:: batch >

        setx REQUESTS_CA_BUNDLE %LOCALAPPDATA%\.certifi\cacert.pem
        set REQUESTS_CA_BUNDLE=%LOCALAPPDATA%\.certifi\cacert.pem

    **Please use DOS Prompt or Power Shell for this operation**, since Git, Bash or Cygwin would interpret ``\`` as escape characters instead of path separators.

    There are both ``set`` and ``setx`` here because ``setx`` only take effective on a new session, while ``set`` doesn't change the global environment variables.
    

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

Genio tools use `fastboot <https://android.googlesource.com/platform/system/core/+/master/fastboot/#fastboot>`_ to flash image.
The Google USB Driver contains device drivers for :command:`adb` and :command:`fastboot` on Windows.
The Genio tools require the Fastboot device driver to be properly installed.
ADB can be used to connect to the board once it has been flashed with **rity-demo-image**.

To install the drivers:

#. Download Google USB Driver from https://developer.android.com/studio/run/win-usb
#. Extract the downloaded zip file. The filename should be similar to ``usb_driver_r13-windows.zip``.
#. In the extracted directory, locate the file ``android_winusb.inf``
#. **Right-click** on the file ``android_winusb.inf`` and select **Install** from the context menu:
   
   .. figure:: /_asset/sw_yocto_get-started_env-setup_install-android-usb-driver.png

#. Confirm the pop-up dialog.

For details, please refer to https://developer.android.com/studio/run/oem-usb#InstallingDriver

The Fastboot device driver is categorized as **Android Device > Android Bootloader Interface** in Windows.

.. note::

    The Fastboot device driver may not be properly detected until you actually connect the board and enter download mode.
    You might have to manually assign the "Unknown Device" as an **Android Bootloader Device**.
    Please refer to :ref:`the troubleshooting page <missing-yocto-driver>` to do so.


Install Fastboot Tool on Windows
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^

The Fastboot program also requires separate installation. 

* Download `SDK Platform-Tools for Windows <https://developer.android.com/studio/releases/platform-tools>`_ and unzip the package
* Add the unzipped directory to ``PATH`` environment variable

Check if it is properly installed by following commands:

.. prompt:: batch > auto

    > fastboot --version
    fastboot version 34.0.4-10411341

The version should be greater than **34.0.4**.

.. warning::

    Fastboot 32.0 on Windows has an issue that may cause corrupted storage when flashing images larger than 4GiB.
    Please update to version 34.0.4 or later.


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

The Genio EVK boards has FTDI USB-to-UART chip on the board, though other development boards use other solutions.
For Windows users, you need to install the driver for the specific brand of USB-to-UART chip for it to work.

Here is a list of development boards and the corresponding USB-to-UART chip drivers you need to install:

.. csv-table:: USB-to-UART Driver List
   :header: "Board Name", "USB-to-UART Driver"
   :widths: 15, 15

   "Genio EVKs", `FTDI VCP <https://ftdichip.com/drivers/vcp-drivers/>`_
   "Ologic Pumpkin-i500", `FTDI VCP <https://ftdichip.com/drivers/vcp-drivers/>`_
   "Innocom SB52EVK", `CP210x VCP Driver <https://www.silabs.com/developers/usb-to-uart-bridge-vcp-drivers>`_

For other boards, please refer to the board user guide or datasheet.


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 Windows:

* `PuTTY <https://www.putty.org/>`_
* `Tera Term <https://teratermproject.github.io/index-en.html>`_
* `MobaXterm <https://mobaxterm.mobatek.net/>`_


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

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

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

Run the following command **as administrator** to install Genio Tools:

.. prompt:: batch >

    pip3 install -U genio-tools

.. note::

    **Missing Dependencies**

    If you encountered installation errors such as missing ``setuptools_scm``, you can install the packages first with following commands:

    .. prompt:: batch >

        pip3 install wheel setuptools_scm gpiod libusb1 packaging pyserial pyftdi pyusb pyyaml pyparsing enum34 oyaml windows-curses --trusted-host pypi.org --trusted-host pypi.python.org --trusted-host files.pythonhosted.org --trusted-host gitlab.com

    And then run ``pip3 install -U genio-tools``.

Check if it is properly installed with the following commands:

.. prompt:: batch >

    genio-flash --version

The version should be greater than 1.2.

Please check your installation with ``genio-config``:

.. prompt:: batch > auto

    > genio-config
    fastboot: OK

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