This article describes how to obtain and use the Distribution Package for Android of the STM32MPU Embedded Software for any STM32MP1 family (STM32MP15 boards) development platform, in order to modify or add pieces of software, and to create the right Android distribution for the targeted product.
It lists some prerequisites in terms of knowledge and development environment, and gives step-by-step instructions to download and install the STM32MPU Embedded Software packages for this Package.
1. Distribution Package content[edit source]
If you are not familiar with the STM32MPU Embedded Software for Android distribution and its Packages, please read the following articles:
- Which STM32MPU Embedded Software Package for Android better suits your needs (and especially the Distribution Package chapter)
- STM32MPU Embedded Software distribution for Android
In summary, this Distribution Package provides:
- an Android build framework (aka distribution builder)
- for the STM32MPU distribution for Android (development on Arm Cortex-A processor):
- the BSP (Linux kernel, U-Boot, TF-A, optionally OP-TEE) pieces in binary (prebuilt). Several scripts are provided to load source code and re-build them.
- the application frameworks (including hardware abstraction code) pieces in source code.
- for the STM32Cube MPU Package (development on Arm Cortex-M processor), all pieces of software in source code: BSP, HAL, middlewares and applications
- a toolset to tune the system for your needs, and to handle the built image (for example STM32CubeProgrammer to install the built image on the board)
2. Checking the prerequisites[edit source]
2.1. Knowledges[edit source]
The STM32MP1 Distribution Package aims at creating an Android distribution for the targeted product: solid knowledge of Linux and Android are recommended to make the most of this Package.
The STM32MPU distribution for Android is an Android distribution based on the Android build framework: a short introduction about Android is available in AOSP[1].
Reading the STM32MPU Embedded Software for Android architecture overview is also highly recommended.
2.2. Development setup[edit source]
The recommended setup for the development PC (host) is specified in the following article: PC prerequisites.
Whatever the development platform (board) and development PC (host) used, the range of possible development setups is illustrated by the picture below.
The following components are mandatory:
- Host PC for cross-compilation and cross-debugging, installed as specified above
- Board assembled and configured as specified in the associated Starter Package article
- Mass storage device (for example, microSD card) to load and update the software images (binaries)
The following components are optional, but recommended:
- A serial link between the host PC (through Terminal program) and the board for traces (even early boot traces), and access to the board from the remote PC (command lines)
- An Ethernet link between the host PC and the board for cross-development and cross-debugging through a local network. This is an alternative or a complement to the serial (or USB) link
- A display connected to the board, depending on the technologies available on the board: DSI LCD display, HDMI monitor (or TV) and so on
- A mouse and a keyboard connected through USB ports
Additional optional components can be added by means of the connectivity capabilities of the board: cameras, displays, JTAG, sensors, actuators, and much more.
3. Installing the STM32MPU distribution for Android[edit source]
|
Delivery for Android coming soon (Q4 2019) |
In order to install the STM32MPU distribution for Android you need to have access to the ST git.
First you need to install the repo tool[2].
mkdir ~/bin PATH=~/bin:$PATH curl https://storage.googleapis.com/git-repo-downloads/repo > ~/bin/repo chmod a+x ~/bin/repo
This tool looks like a git but it is able to manage multiple git at the same time, more information available in the repo documentation[3].
Initialize your local reposirtory. To do so create a folder:
mkdir myDistribution cd myDistribution
Then launch repo:
repo init -u <git_url>
This will automaticaly download the default.xml file located in the git project given by the option -u.
This file is the manifest containing all projects reference.
Now you need to download all sources attach to each projects:
repo sync
This may take several hours.
3.1. Use local mirror[edit source]
For further loads, it can be interesting to create a local mirror of the different repositories used.
A helper script cachesetup is available for that purpose which will create / update the mirrors based on the configuration file device/stm/<STM32Series>/scripts/cache/android_cache.config.
Update cache configuration file (android_cache.config) depending on your needs. Two possible kind of cache:
- REPO mirror: mirror of list of modules in repositories based on provided manifest (ex: Android AOSP)
- GIT mirror: mirror of one module (ex: Linux kernel)
Be careful: if you change environment variable name, you’ll have to adapt associated scripts load_xxxx available in device/stm/<STM32Series>-xxxx/source directory.
Create the mirrors executing the following commands:
source build/envsetup.sh cachesetup --new
From this stage, it's possible to regularly update your mirror executing
cachesetup
For more information on how to use the command look at the cachesetup usage:
Usage: cachesetup [Options] <cache option>
Setup (create or update) Git cache based on configuration file android_cache.config
Options:
-h/--help: get current help
-v/--version: get script version
or
-u/--update: update cache (default)
or
-f/--force: create cache (force)
-n/--new: create cache (only create non-existing cache)
<cache option>:
all (default)
or select list of required cache within the following options:
aosp
android
kernel
tf-a
u-boot
From this stage, you can use the local mirror instead of the remote repository adding --reference=$CACHE_DIR) to the repo init commands (CACHE_DIR environment variable name is set in android_cache.config file):
repo init --reference=$CACHE_DIR -u <repo_url> -b <version>
This will copy all necessary files define by the manifest from the mirror instead of downloading it.
3.2. Use packages[edit source]
If you have been provided with an archive, for example stm32mpuDistribution.tar.gz you need to follow those steps:
- Download the official AOSP version compatible with the archive (with or without mirror):
mdkir myDistribution cd myDistribution repo init -u https://android.googlesource.com/platform/manifest -b android-<version> repo sync
For more info on available version please have a look in the official page[4].
- Extract the archive inside
myDistribution:
tar -xzf stm32mpuDistribution.tar.gz
This will put all custom ST files at the right location.
4. Building the STM32MPU distribution for Android[edit source]
When the installation is completed, please refer to the How to build STM32MPU distribution for Android page to learn how to build it.
5. Flashing the built image[edit source]
The ${ANDROID_PRODUCT_OUT}> directory receives complete file system images built for board selected un lunch step.
${ANDROID_PRODUCT_OUT}
├── boot.img Binary for boofs partition
├── dt.img Linux kernel device tree image for bootfs partition
├── fsbl-optee.img TF-A binary for FSBL partition (OP-TEE)
├── fsbl-programmer.img TF-A binary for FSBL partition (trusted boot chain for programmer)
├── fsbl-trusted.img TF-A binary for FSBL partition (trusted boot chain)
├── misc.img Binary for misc partition
├── ramdisk.img Binary for ramdisk partition
├── ramdisk-recovery.img Binary for ramdisk recovery partition
├── splash.img Binary for splashscreen
├── ssbl-optee-fbsd.img U-Boot binary for SSBL partition (OP-TEE)
├── ssbl-programmer.img U-Boot binary for SSBL partition (trusted boot chain for programmer)
├── ssbl-trusted-fbsd.img U-Boot binary for SSBL partition (trusted boot chain)
├── system.img Binary for system partition
├── teed.img Binary for OP-TEE OS paged data
├── teeh.img Binary for OP-TEE OS header image
├── teex.img Binary for OP-TEE OS resident core
├── userdata.img Binary for userdata partition
├── vendor.img Binary for vendor partition
└── [...]
The STM32CubeProgrammer tool is used to flash the 1st stages of images to the STM32MP15 board. It is assumed that this tool has been installed through the Starter Package associated with your board. The fastboot is also used to flash Android images.
Depending on the board, several Flash devices (microSD, eMMC and so on) might be available. The microSD card is considered as the Flash device in the rest of this article.
- Go to the Distribution Package directory, and run flash-device:
flash-device
- Select the flashlayout you want to use (ex:FlashLayout_sd_optee.tsv to flash optee 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 terminated, the boot switches must be configured so that the Flash device (e.g. microSD card) on which the image has been flashed, is selected as the boot source:
- Boot switches on the STM32MP157x-EV1 Evaluation board
- Boot switches on the STM32MP157x-DKx Discovery kit
The figures below show the boot-switch configurations for a boot from microSD card on different boards:
| Boot from microSD card on STM32MP157x-EV1 Evaluation board | Boot from microSD card on STM32MP157x-DKx Discovery kit |
- Press the reset button, and a long press on the button associated with fastboot (USER2 for Disco board and PA13 for Eval board). This causes the image download to continue.
- This operation takes several minutes.
- When the download is finished, press the reset button to reset the board. The Android software then starts.
5.1. Populate a SD card[edit source]
You can flash images directly to a SD card connected to your machine.
Before starting, you need to be sure that SD card settings match yours. Please refer to the Memory settings page.
5.1.1. Format the SD card[edit source]
The first time you use your SD card or if the partition layout changes, you need to format it. The goal is to prepare it with appropriate partition size to accept images.
format-device <device_path>
With:
- <device_path>: the device identify in your system to access your SD card. For example
/dev/sdbfor an USB connected SD card reader.
This command will automatically use the partition configuration from device/stm/<STM32Series>/layout/android_layout.config.
For more information please see the usage option:
Usage: format-device [Options] <device_path> This script allows formatting memory device to create required partition before provisioning Options: -h/--help: print this message -v/--version: get script version -s/--size <disk-size>: set requested disk size [4GiB or 8GiB] (default: 4GiB) -c/--config <config-file-path>: set used partition configuration file (default: ) <device_path>: /dev/sdX (sd connected through usb), /dev/mmcblkX (sd connected through reader)
5.1.2. Provision the SD card[edit source]
To push the built images, you need to execute:
provision-device <device_path>
With:
- <device_path>: the device identify in your system to access your SD card. For example
/dev/sdbfor an USB connected SD card reader.
This will push all images to the SD card.
From this stage, you can plug your SD card on your board and reboot it.
5.2. Flash a dedicated image[edit source]
If you already have an Android distribution installed and started, it's possible to update only one partition depending on your needs. For example, if you rebuild the kernel you can just flash the boot (kernel), the dt (device tree) and the vendor images (modules).
First you need to restart your device in fastboot mode:
- Press the reset button, and a long press on the button associated with fastboot (USER PA13 button for Evaluation board, USER2 button for Discover kits).
or
- Run the command
adb reboot-bootloader
Then execute the flashing command:
provision-device -i reboot
- -i option means that you will have to confirm the flash partition per partition (select the partitions you want to update)
- reboot option means that the device will reboot automatically at the end
5.3. Switch read only to write[edit source]
During developpment you can be forced to change or add files in the system or vendor partition. However those partitions are readonly.
You can temporary switch the partition from readonly to read and write mode.
First switch adb in root mode.
adb root adb shell
Then run the following commands:
mount -o remount,rw <mount point>
With <mount point> an existing mount point visible in the command
mount
Make the change you need and then reboot.
adb reboot
6. References[edit source]
Arm® is a registered trademark of Arm Limited (or its subsidiaries) in the US and/or elsewhere. 