Genio Tools

Overview

Genio tools are a set of tools to configure or interact with MediaTek Genio boards. MediaTek and community developers write the Genio tools in Python. Ensure you have Python 3.9 or later installed on your system. MediaTek tested Genio Tools v1.5 with Python 3.9.

Note

Some known issues affect Python 3.10 on the Windows platform. If you use Windows, we recommend you install Python 3.9.

The Genio tools consist of 4 tools:

  • genio-config: a tool to setup your host system in order to be able to communicate with MediaTek Genio boards

  • genio-flash: a tool to flash a board with a RITY image

  • genio-board: a tool to control the board (reset / power / download signals)

  • genio-multi-download-cli: a command line tool to monitor and running multiple downloads to boards with a RITY image

Genio Tools v1.3.3 still support legacy commands such as aiot-flash, but we plan to deprecate these aiot- commands in the future. We strongly encourage all users to migrate to the new genio-flash command.

Setup Tool Environment (Linux)

Please refer to Setup Tool Environment (Linux).

Setup Tool Environment (Windows)

Please refer to Setup Tool Environment (Windows).

Genio Tools Usage

This section will describe how to use each Genio tool.

genio-config

Note

The genio-config tool is supported on both Linux and Windows. The udev rules information is only supported on Linux environment.

Developers use this tool to check the configuration of the host environment.

Run the following command to check that your environment is correctly configured:

genio-config
fastboot: OK
udev rules: OK

In case your environment is not setup correctly, the tool will give you some instructions on how to correctly configure it.

Run the following commands or reboot the Linux system for the udev rules to take effect:

sudo udevadm control --reload-rules
sudo udevadm trigger

genio-flash

Note

The genio-flash tool is supported on both Linux and Windows.

This tool allows you to flash your board. genio-flash supports flashing Yocto images (RITY).

You can flash an image by running the following command:

genio-flash

The tool tries to find an image to flash in your current working directory. If you want to flash an image in a different path, use the –path parameter:

genio-flash --path /path/to/image

It is possible to flash individual partitions by using:

genio-flash <partition1> <partition2> <partitionX>

or

genio-flash <partition1>:/path/to/file1 <partition2>:/path/to/file2

Select an Image

A few options are specific to flashing Yocto images. If your build folder contains more than one image you can specify which image to flash by using the –image parameter.

genio-flash --image rity-demo-image

or

genio-flash -i rity-demo-image

Load a DTBO

When flashing, you can also choose the Device-Tree Blob Overlay (DTBO) you wish to load automatically at boot:

genio-flash --load-dtbo <dtbo_name> --load-dtbo <another_dtbo_name>
List Available DTBO

See which Device-Tree Blob Overlays (DTBOs) are available with your image by running the following command:

genio-flash --list-dtbo
Interactively Choose DTBO

Instead of specifying the DTBO to load, run genio-flash in interactive mode:

genio-flash --interactive

or

genio-flash -I

Bootstrap Configuration

In case your bootstrap has a configuration different from the default values, you can use the following parameter:

genio-flash --bootstrap lk.bin --bootstrap-addr 0x201000 \
             --bootstrap-mode aarch64

Board Control

Warning

Board control is supported on both Linux and Windows.

If your board supports genio-board, genio-flash will also be able to control the reset and download GPIOs. You can flash and control your board using the following command:

genio-flash --gpio-power <power_gpio> \
             --gpio-reset <reset_gpio> \
             --gpio-download <download_gpio>

genio-flash –daemon

The genio-flash tool supports a daemon mode which allows it to run as a background service, handling multiple flashing tasks concurrently. This section provides a detailed analysis of running genio-flash in daemon mode.

Warning

The daemon mode of genio-flash requires the Yocto 24.1 download agent (lk.bin) to function. Starting from Yocto v24.1, lk.bin supports virtual board identification using the USB serial number, which is derived from a virtual unique hash value of the chip.

Note

The genio-tools daemon is intended for advanced developers. If you are a developer looking to create your own UI or develop a multiple download tool, you should refer to the contents of this section. For end-users, it is recommended to skip directly to the genio-multi-download-cli section.

Important

A PC’s ordinary host USB port cannot supply enough current for multiple download devices. You need a USB hub with an external power supply to bridge the download connection between multiple devices and the PC host. The USB’s bandwidth is shared among the devices using a root USB controller. Design the download scenario properly for each USB root controller to meet the speed and safety requirements during mass production.

Installation

Only the preview installation package is available from Genio’s GitLab repository. Please install the specific 1.5 and later version to try this feature.

pip install genio-tools==1.5

Usage

Use the following shell command to start genio-flash in daemon mode with 4 workers, listening on port 5000:

genio-flash --daemon --worker 4 --port 5000

Warning

Due to the limitation caused by the transition from the virtual COM interface created by genio-bootrom to the fastboot interface created by the Download Agent, there are several states when a target is being flashed by a flash worker via fastboot. Users should only plug a new target into the PC host when the worker shows the Starting state; otherwise, multiple downloads might fail.

Parameters

  • --daemon: Enables daemon mode, allowing the tool to run as a background service.

  • --worker: Specifies the number of worker subprocesses for concurrent flashing. The default is 2.

    • At a time, the system activates only one Stopped (idle) worker. The worker must reach the Starting state before the user can connect a target for download.

    • After jumping to DA, the target enters flash (fastboot) mode, prompting the daemon to activate the next worker.

    • The user must wait for the next worker to reach the Starting state before connecting the next target for download.

  • --port: If a port is specified, the event logs are converted to JSON and then duplicated to the specified port.

    • By default, the system prints the status of each worker as event logs to STDOUT.

    • Manufacturers can write their own parsers and UIs to monitor each worker’s status.

Flashing States For A Worker

genio-flash daemon will analyze the state of each worker. It will record the state information in the action attributes for each worker. The following states are the possible action of a worker.

  • Stopped : All flash workers start in this Stopped state, indicating that they are not performing any operations.

  • Starting : The flash worker starts up, waits for the target to connect to the PC host, and then performs flash operations.

  • Opening : Opening the virtual COM port prepares for communication with the device.

  • Sending DA : Sending the Download Agent (DA) to the device. This agent handles subsequent data transfer and writing operations.

  • Jumping DA : Jumping to the bootstrap process allows the device to enter download mode.

  • Error: Jump DA failed : Abort the download process if a flash worker cannot find a valid fastboot device within 10 seconds after downloading the DA. This failure is usually due to Surface Mount Technology (SMT) or component issues, or a loose connector. Please unplug the device and check.

  • erasing : Erasing the existing data on the device.

  • sending then writing : Sending and then writing the new part of the sparse image to the device.

  • Rebooting : Rebooting the device after completing the writing process.

Note

The erasing, sending, and writing states simplify to the flashing… state in the simplified log display. Manufacturers can use the --verbose option to show the full event details.

An Example of Daemon Output

Let’s see what output is available if the daemon mode is ran without --port parameters.

genio-flash --daemon --worker 4

User can see that genio-flash --daemon have simplified the state transition events for each worker. Initially, Worker 0 transitions to the Starting state with the action attribute. If the genio-board control is not available, an error message will appear. However, this will not block the flashing process. Next, user will see a device connected to the PC host. genio-flash will attempt to bootstrap it with the DA. If the DA runs successfully, DA will set a fastboot_sn with the RANDOM_FIRMWARE_ID (supported by v24.1 Download Agent) as the USB serial number for the target’s fastboot device. The target will then enter the flashing state. When Worker 0 enters the flashing... state, the system spawns Worker 1 to begin its work.

Genio Tools: v1.5
Yocto Image:
        name:     Rity Bringup Image (rity-bringup-image)
        distro:   Rity Demo Layer 24.0-dev (rity-demo)
        codename: kirkstone
        machine:  genio-1200-evk
        overlays: []

Trying to kill legacy ['aiot-bootrom.exe', 'fastboot.exe']...
INFO:aiot:Worker 0, None, None, {action: Starting, error: "Board Ctrl: Unable to find and reset the board. You can check detail with normal single download."}
Looking for MediaTek SoC matching USB device 0e8d:0003
Opening COM15 using baudrate=115200
Connected to MediaTek SoC: hw_code[0x8195]
Sending bootstrap to address: 0x201000
Jumping to bootstrap at address 0x201000 in AArch64 mode

INFO:aiot:Worker 0, COM15, None, {action: Jumping DA, com_port: COM15, baudrate: 115200, hw_code: 0x8195, address: 0x201000, mode: AArch64}
INFO:aiot:Worker 0, COM15, CA95DINZ65CYCEGY, {fastboot_sn: CA95DINZ65CYCEGY}
INFO:aiot:Worker 0, COM15, CA95DINZ65CYCEGY, flashing...
INFO:aiot:Worker 1, None, None, {action: Starting, error: "Board Ctrl: Unable to find and reset the board. You can check detail with normal single download."}
INFO:aiot:Worker 0, COM15, CA95DINZ65CYCEGY, {action: rebooting, status: OKAY, duration: 0.002s, total_duration: 0.003s}

Note

When all the flashing tasks are complete, simply press Ctrl-C to quit the genio-flash daemon. Also, remember to remove all connected devices.

genio-board

Note

The genio-board tool is supported on both Linux and Windows.

Use this tool to control MediaTek boards. The FTDI chip provides the serial console to also control the reset/power/download GPIO lines.

Important

Board control is available to Genio 510/700-EVK and Genio 350-EVK. Genio 1200-EVK does not support board control due to the board design.

Configuration of the FTDI Chip

In order to be able to control the GPIO lines, the FTDI chip must be properly configured. Run the following command to configure the FTDI chip:

genio-board program-ftdi --ftdi-product-name <board_name> \
                         --gpio-power <power_gpio> \
                         --gpio-reset <reset_gpio> \
                         --gpio-download <download_gpio>

Please replace <board_name>, <power_gpio>, <reset_gpio>, and <download_gpio> with the values corresponding to your board. You can check your Development Boards to know the values to use.

Note

Connect only one board to the host when programming an FTDI chip. If there are multiple boards connected, use genio-board list to query serial numbers of each connected board. Use genio-board -s <serial> to specify which board to program. If the tool detects more than one FTDI chip and there are no -s option given, it will quit.

For example for the Genio 350-EVK board, the command would be:

genio-board program-ftdi --ftdi-product-name i350-evk \
                         --gpio-power 0 \
                         --gpio-reset 1 \
                         --gpio-download 2

Warning

Be careful, configuring bad values into your FTDI chip could potentially brick your board.

Configure the FTDI chip only once per board.

Reset the Board

To reset the board, run the following command:

genio-board reset --gpio-power <power_gpio> \
                  --gpio-reset <reset_gpio> \
                  --gpio-download <download_gpio>

Reset in Download Mode

To reset the board and boot it in download mode, run the following command:

genio-board download --gpio-power <power_gpio> \
                     --gpio-reset <reset_gpio> \
                     --gpio-download <download_gpio>

Power the Board

To simulate pressing the power button (for 1 second), run the following command:

genio-board power --gpio-power <power_gpio> \
                  --gpio-reset <reset_gpio> \
                  --gpio-download <download_gpio>

Default Values for the GPIOs

Developers do not need to set the –gpio-power, –gpio-reset, and –gpio-download parameters if they match the default values. Check the default values used by the tool below:

Parameter

Parameter alias

Default value

--gpio-power

-p

0

--gpio-reset

-r

1

--gpio-download

-d

2

genio-multi-download-cli

The purpose of this tool is to enable customers to flash multiple boards simultaneously during production. This feature depends on the genio-flash daemon mode. For more details, please refer to the genio-flash –daemon section for developers.

Warning

genio-multi-download-cli requires the Yocto 24.1 download agent (lk.bin) to function. Starting from Yocto v24.1, lk.bin supports virtual board identification using the USB serial number, which is derived from a virtual unique hash value of the chip.

Note

This tool demonstrates various capabilities. Manufacturers should customize their own multi-download text-based user interfaces (TUI) to suit their specific factory environments.

Installation

Only the preview installation package is available from Genio’s GitLab repository. Please install the specific 1.5 and later version to try this feature.

pip install genio-tools==1.5

Usage

The Multiple Download Demo tool genio-multi-download-cli is designed with a client-server architecture. It runs genio-tools in daemon mode. When genio-tools is running in daemon mode, it can launch multiple flash workers to flash the image to multiple targets. The daemon of genio-tools will continuously update the status of each flash worker and report the status summary repeatedly to genio-multi-download-cli. genio-multi-download-cli and genio-tools use network sockets to connect to each other for easy deployment and flexibility.

For example, to flash 16 boards with the same image in text-based user interfaces (TUI) mode, you would run:

genio-multi-download-cli --run-daemon --port 5000 --worker 16 --tui

Parameters

  • --run-daemon: Runs genio-tools in daemon mode on the same PC host as the genio-multi-download-cli tool.

  • --worker: Must be used with –run-daemon. In the example, it asks genio-tools to create 16 workers to flash 16 targets.

  • --port: Connects to the genio-tools daemon using port number 5000.

  • --tui: Runs genio-multi-download-cli in text-based user interfaces (TUI) mode, instead of printing out the status summary repeatedly.

An Example of TUI Output

Let’s see what output is available if the daemon mode is ran with --tui parameters.

genio-multi-download-cli --run-daemon --port 5000 --worker 5 --tui

The following output shows the status of multiple workers involved in a flashing process. The system displays each worker’s status, COM port, serial number (SN), progress, and duration. The TUI will collect the state in the action attribute of each worker, along with other attributes, instead of representing them as JavaScript Object Notation (JSON) events.

Warning

  • Insert a board only when the Worker status displays as Starting.

  • You can insert only one board at a time, and there will be one Worker in the Starting status at any given time.

  • When the status shows Rebooting, it indicates the board has finished flashing and is rebooting.

For more detailed information on the flashing status transitions, please refer to the Flashing States For A Worker section.

== Menu == [q]uit ==
Worker 0 status: rebooting (COM Port: COM15) (SN: CA95DINZ65CYCEGY) (Progress: 100.00%) (Duration: 56.52s)
Worker 1 status: sending (COM Port: COM14) (SN: NBD6PVCQMZEAL7SG) (Progress: 75.00%) (Duration: 45.52s)
Worker 2 status: sending (COM Port: COM16) (SN: CA94DINZABCYC3GY) (Progress: 25.00%) (Duration: 3.03s)
Worker 3 status: Starting
Worker 4 status: Stopped

Note

When all the flashing tasks are complete, simply press Ctrl-C or q to quit the genio-flash daemon. Press q and then press Enter key to leave the utility may required on Linux. Also, remember to remove all connected devices.