.. include:: /keyword.rst

=========================
Troubleshooting (Windows)
=========================

.. warning::

   This section applies to Windows only.

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

Missing Image or Binary
=======================

This issue might happen to compressed image archive in *.zip* or *.tar.gz* format.
You might encounter the following error on Windows after executing ``genio-flash``:

.. code:: text

    Traceback (most recent call last):
    ...
    with open(f"{path}/{name}-{machine}.testdata.json", 'r') as fp:
    FileNotFoundError: [Errno 2] No such file or directory: './rity-demo-image-genio-350-evk.testdata.json'

This is usually caused by incompletely extracted file archives. In this case, try the following:

1. Rename the image archive to a short name, such as ``image.tar.gz``.
2. Extract the images to root directory, such as ``D:\\`` on Windows.


.. _missing-yocto-driver:

Missing "Yocto" Device Driver
=============================

If you are connecting the board and switching it to Download Mode for the first time, you might find that

1. There is an unrecognized ``Yocto`` device, and 
2. ``genio-flash`` keeps waiting for the device after ``Jumping to bootstrap``:

.. prompt:: batch > auto
    
    > genio-flash
    Genio Tools: v1.4
    Yocto Image:
            name:     Rity Demo Image (rity-demo-image)
            distro:   Rity Demo Layer 25.0-dev (rity-demo)
            codename: scarthgap
            machine:  genio-1200-evk
            overlays: ['video.dtbo', 'gpu-mali.dtbo']

    Looking for MediaTek SoC matching USB device 0e8d:0003
    Opening COM14 using baudate=115200
    Connected to MediaTek MT8168 SoC
    Sending bootstrap to address: 0x201000
    Jumping to bootstrap at address 0x201000 in AArch64 mode
    erasing mmc0
    < waiting for any device >

This is likely caused by an unrecognized device driver. To confirm if this is exactly the issue:

1. Press ``Windows+R`` and type ``devmgmt.msc`` then press ``ENTER``.
2. Check the Device Manager dialog and see if it has a **Other devices > Yocto** device that is not recognized:
   
   .. figure:: /_asset/sw_rity_get-started_flash_unrecog_dev.png
    :align: center
    :width: 640

    Unrecognized "Yocto" device in Windows Device Manager

To install driver for the unrecognized device, please follow steps below:

1. Right-click on the **Yocto** device, and select **Update Driver Software**.
2. Click **Browse my computer for driver software**.
3. Click **Let me pick from a list of device drivers on my computer**.
4. Choose **Android Device**.
5. Choose **Android Bootloader Interface**.
6. Click **Yes** if a "Update Driver Warning" dialog pops.

.. figure:: /_asset/sw_yocto_get-started_flash_update-yocto-device-driver-on-windows.gif
    :align: center
    :width: 55%


After updating the Android Bootloader Interface driver, ``genio-flash`` should be able to detect the device and start the flashing procedure.


Windows Device Drivers
======================

Different ports on Genio EVK require different Windows drivers when connected to your windows host PC. Here is a list of the drivers and the corresponding location in the Windows Device Manager:


* UART-to-USB-Serial

   .. figure:: /_asset/sw_yocto_get-started_flash_flash-troubleshoot-windows_UART-to-USB-Serial.jpg
    :align: center
    :width: 640
    
* FastBoot (for `genio-flash`)

   .. figure:: /_asset/sw_yocto_get-started_flash_flash-troubleshoot-windows_FastBoot-for-genio-flash.jpg
    :align: center
    :width: 640

* RNDIS (After boot into Yocto and connected to Windows via USB port)

   .. figure:: /_asset/sw_yocto_get-started_flash_flash-troubleshoot-windows_RNDIS.jpg
    :align: center
    :width: 640

* ADB (After boot into Yocto and connected to Windows via USB port)
    
   .. figure:: /_asset/sw_yocto_get-started_flash_flash-troubleshoot-windows_ADB.jpg
    :align: center
    :width: 640


Flash Process Paused
====================

You might find that the flashing process is "paused" during writing operation:

.. figure:: /_asset/sw_yocto_get-started_flash_windows_pause.png
    :width: 55%


And the flash process can be resumed by pressing **ENTER** in the console window.

To remedy this problem, please follow these steps:

* Click the console icon in the upper-left corner of the console window, and select **Defaults**

  .. figure:: /_asset/sw_yocto_get-started_flash_windows_open_console_setting.png
      :width: 35%

* In the Console Window Properties window:
  
  1. Click **Options** tab.
  2. Uncheck **QuickEdit** Mode in Edit Options
  3. Click **OK**

  .. figure:: /_asset/sw_yocto_get-started_flash_windows_disable-quick-edit.png
      :width: 35%

This should prevent the flashing process being paused in the future console sessions.


Genio Tools Crash When Programming FTDI
=======================================

Depending on your EVK board and FTDI driver version, the ``program-ftdi``
command of the ``genio-board`` tool may crash on Windows.

For example, the command:

.. prompt:: batch > auto

    > genio-board -s B001I4X2 program-ftdi --set-serial DUT0001

may crash in the FTDI driver DLL with the following error:

.. code-block:: text

    ERROR:aiot:exception: access violation reading 0x0000027CC3E24079

You can remedy this issue by reprogramming the FTDI chip of the UART0 port using
the official `FTDI FTProg tool <https://ftdichip.com/utilities/>`__.

To do so, follow these steps:

1. Visit https://ftdichip.com/ to download the **FT_PROG** tool, and
   install it on your host PC.
2. Connect the EVK's UART0 port to the host PC.
3. Terminate any terminal applications connected to the UART0 port of
   the EVK.
4. In the FT_Prog application, click the **EEPROM** tab.
5. Select the **DEVICES** menu and then select the **Scan and Parse** item.
6. The **Device Tree** window should now be populated with the chip information.
7. Select **USB String Descriptors**.
8. Uncheck **Auto Generate Serial** and update the **Serial Number**
   to the value you need. For example, in the command above, we want it to be
   ``DUT0001``:

   .. figure:: /_asset/sw_yocto_get-started_flash_flash-troubleshoot-ft_prog-set-serial.png

9. Select **Hardware Specific** and then **IO Controls**.
10. Make sure properties **C0**, **C1**, and **C2** are set to **I/O MODE**:

    .. figure:: /_asset/sw_yocto_get-started_flash_flash-troubleshoot-ft_prog-set-gpio.png

11. Select the **DEVICE** menu and then click **Program**.
12. In the popup dialog, click **Program**.

Finally, close the **FTProg** application. You may now run ``genio-board program-ftdi``
again and check if the crash issue has been resolved.