.. 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 Yoctoimage. The Windows tool environment can only be used for flashing the board
    and connecting to the board.

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

Windows System Requirement
==========================

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

Setup Git for Windows
=====================

Visit https://gitforwindows.org/ to download and install **git for Windows**.

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.

Install Fastboot and ADB Device USB Driver
==========================================

The Google USB Driver contains both device drivers for ``adb`` and ``fastboot`` on Windows.
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 these two drivers:

1. Download Google USB Driver from https://developer.android.com/studio/run/win-usb
2. Extract the downloaded zip file. The filename should be similar to ``usb_driver_r13-windows.zip``.
3. In the extracted directory, locate the file ``android_winusb.inf``
4. **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

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


Setup Python 3 on Windows
=========================

Follow these steps:

* 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

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

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

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

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

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


.. note::

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

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.

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

USB-to-Serial Driver Installation
=================================

For Windows users, you need to install the driver for the USB-to-UART chip on the development boards.

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/>`_
   "Oologic 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.