How to populate boards for Android

This article describes how to load AndroidTM distribution images, built for the STM32MPU, to defined Flash device partitions. It is intended for Distribution Package users.

1 Prerequisites[edit]

The recommended host PC setup is specified in the following article: PC prerequisites.

The environment must be installed using the Distribution Package adapted to the selected microprocessor device. See the list of AndroidTM Distribution Package.

It is assumed that:

2 Populate a board[edit]

The out/target/product/<BoardId> directory contains all images built for the selected board during the setup (lunch step).

The STM32CubeProgrammer tool is used to flash the first stages of the images to the board. Then fastboot is used to flash the remaining images.

The board shall be started in "Forced USB boot for flashing" mode (also named DFU), selecting it through boot switches as explained in the document <your board reference - hardware description>, chapter Boot related switches (for example, Boot switches on the STM32MP157x-EV1 board for the STM32MP157C-EV1 board).

Connect the board to the host PC through USB.

The board can be designed to support several flash devices, for example: microSD, eMMC and so on. This document uses the microSD card as the Flash device example for this article.

  • Go to the distribution root directory, and run flash-device:
PC $> flash-device
  • Select the flashlayout to be used (ex: FlashLayout_sd_optee.tsv to flash OP-TEE build for microSD card)
1) FlashLayout_emmc_optee.tsv	 3) FlashLayout_sd_optee.tsv
2) FlashLayout_sd_trusted.tsv	 4) FlashLayout_emmc_trusted.tsv
Which layout do you want to flash ?

Once the DFU flashing is completed, the boot switches must be configured so that the correct Flash device (e.g. microSD card) is selected as the boot source.

  • •Keep the reset button pressed until the board enters fastboot (refer to LEDs and buttons on STM32 MPU boards). The device provisioning continues until the required images have been loaded.
This operation takes several minutes.
  • When the download is finished, press the reset button in the board. The Android software then starts.

3 Populate a microSD card[edit]

Images can be flashed directly to a microSD card connected to the board.

Before starting, the microSD card settings need to match the configuration of the board. Refer to the Memory settings page.

3.1 Format the microSD card[edit]

The first time the microSD card is used or the partition layout changes, it needs to be formated. The goal is to prepare it with appropriate partition size to receive the images.

PC $> format-device <device_path>


  • <device_path>: the device identified in the system to access the microSD card (/dev/sdX for microSD card connected through USB dongle or /dev/mmcblkX for microSD card connected through reader, X is the instance associated to your Flash device).

This command will automatically use the partition configuration from device/stm/<STM32Series>/layout/android_layout.config.

For more information see the usage option:

Usage: format-device [Options] <device_path>

  This script allows the formatting of the memory device to create required partition before provisioning.

  -h/--help: print this message
  -v/--version: get script version
  -s/--size <disk-size>: set requested disk size [4GiB or 8GiB] (default: PART_MEMORY_SIZE value set in <path_to>/android_layout.config)
  -c/--config <config-file-path>: set used partition configuration file (default: <path_to>/android_layout.config)

<device_path>: /dev/sdX (sd connected through usb), /dev/mmcblkX (sd connected through reader)
Info.png The microSD card needs to be disconnect and reconnect the before going further

3.2 Provision the microSD card[edit]

To push the built images to the microSD card, the following instruction has to be executed:

PC $> provision-device <device_path>


  • <device_path>: the device identified in the system to access the microSD card (/dev/sdX for microSD card connected through USB dongle or /dev/mmcblkX for microSD card connected through reader, X is the instance associated to the Flash device).

Then all images are flashed on the Flash device.

The microSD card can be plugged to the board and rebooted.

4 Flash a dedicated image[edit]

If an Android distribution is already installed and booted on the board, it's possible to update partitions one by one depending on the need. For example, if the kernel is rebuilt, just flash the boot (kernel), the dt (device tree) and the vendor images (modules).

First the device has to be restarted in fastboot mode:

  • Keep the reset button pressed until the board enters fastboot (USER PA13 for Evaluation board, USER2 for Discovery kits).


  • Run the command
PC $> adb reboot-bootloader

Finally, execute the flashing command:

PC $> provision-device -i reboot
  • -i option means that a confirmation will be needed for flashing each partition at a time (select the partitions that need to be updated)
  • reboot option means that the device will reboot automatically at the end

5 Update an Android distribution[edit]

If the content of the partitions dedicated to AndroidTM needs to be updated (vendor,system or userdata) after a rebuild, use ADB tool.

The read-only partitions need to be changed to read-write:

PC $> adb root
PC $> adb remount

It is then possible to update the AndroidTM partitions.

PC $> adb sync

Finally, the device needs to be rebooted to take these changes into account

PC $> adb reboot