Skip to content

# Tools and demos

## STMicroelectronics Tools

STMicroelectronics provides some tools to ease development for their STM32MP products. The Kontron BSP is built to work with these tools.

- STM32MPCubeProgrammer
  is the tool to flash images on virgin devices.
- STM32CubeMX
  for doing the pin multiplexing and for generating the linux and bootloader device tree files and M4 IDE project with HAL libraries.
- SystemWorkbench for STM32 with STM32-CoPro-MPU plugin
  as IDE for M4 development and debugging.

These tools are already installed in the Kontron VmWare image for a quick start of development.

## Kontron Tools and Demos

The Kontron BSPs include or provide several demo applications and tools, which can be helpful to get started and to configure your hardware.

### Prebuild BSP releases

You can find prebuild BSP releases for your board in https://files.kontron-electronics.de/stm32mp. There you can find images, sdk, open source sourcecode and license texts for your board. Check this location for new pre-built software for your Demo-Kit.

### Kontron VMware Image

Kontron provides a VMware Image with preinstalled tools and access to the sources located on the Kontron GitLab server. You can access the newest version of this VMware image under
https://files.kontron-electronics.de/stm32mp. The image is based on a current Ubuntu LTS release.

For using the VMware image you should have

- installed VMware Player Version 10 or higher,
- at least 12GB of RAM on your PC
- at least 80GB free space on hard disk

This VMware provides all tools required for developing software with STM32MP1:

- Yocto build environment for linux image
  Yocto is the environment to build your customized linux image for your board. The VMware contains the Kontron Yocto environment for STM32MP1 devices.
- STM32 CubeMX
  for clock tree setup and pin multiplexing. This is required if you need your own pin multiplexing or want to tweak clock settings of your board. It creates the basic device tree files for the bootloader and linux. It also can generate a code skeleton for M4 development.
- STM32 CubeProgrammer
  to equip a totally blank device with software or to burn OTP fuses in the device.
- QtCreator
  Development environment for Qt5 programming.
- SW4STM32 IDE
  Development environment for programming M4.

#### Issues with VMware STM32MP 1.3.1 r1

- On this VMware image the tftp and nfs directories do not exist. See Setup tftp and nfs on the host for how to set it up.

### Tools

#### create-sd-card.sh

Kontron provides the 'create-sd-card.sh' script to generate bootable sd card images for your board from your built images. For instructions how to create a bootable sd card see documentation here.

To create the sd card you have to provide:

- the images to burn (normally located in your images directory)
- a layout configuration file which descirbes your partitions, contents and sizes

The sdcard image file is located alongside your image contents in your images directory and called like your layout file with the ending of '.sdcard'.

This script requires root rights to generate the sdcard image for mounting and populating the images with the correct access rights. So use sudo to run this script.

Layout configuration files for the Kontron EvalKits can be found in the /script-mp directory after an image was built. Additionally a file called 'sd-card.layout' is placed there with all available settings and comments how to use. Other preconfigured layout files exist for different configurations of machine, distro and image in the `meta-ktn-stm32mp/recipes-ktn/production-tool/mptool/common` directory. These configurations are a good starting point when you want to create a layout for your board.

Example for the layout file of EVK STM32MP157:

    # image directory set by recipe
    FW_DIR="./.."

    TFA_IMG="tf-a-stm32mp-t1000-s-trusted.stm32"
    UBOOT_IMG="u-boot-stm32mp-t1000-s-sdcard.stm32"
    UBOOT_IMG_PROD="u-boot-stm32mp-t1000-s-trusted.stm32"

    # borootfs (boot + rootfs)
    BOROOTFS_IMG="image-ktn-qt-stm32mp-t1000-s-multi.tar.gz"
    BOROOTFS_SIZE="500"

    # userfs
    USERFS_IMG="image-ktn-qt-userfs-stm32mp-t1000-s-multi-thud.tar.gz"
    USERFS_SIZE="50"

The script supports the partitions borootfs, userfs and optionally rescuefs. In normal configuration it also places the tar.gz archives of these filesystems and the bootloader on the sd card. This way you can use this sd card to flash your internal storage with your firmware and mptool.

The most important command line options are:

Option | Config file setting | Description
--- | --- | ---
-p y|n | PROD_IMG | Expand userfs and copy tar files to it (default y)
-c | - | Use alternate config file (default ist /etc/mptool.config)
-u | FW_DIR | Set base directory for update files (default is FW_DIR)

Command line options always have precedence of config file settings

Hint

If you want to create a bootable SD card to update the internal flashes with `mptool` and new software, don't forget the `-p y` option on the command line or the `PROD_IMG=y` option in the config file. With this all firmware image files are stored in the SD card image under `/usr/local` so that mptool can use them directly.

#### mptool

mptool is a set of scripts used to execute tasks for production purposes, such as flashing firmware to memory, setting the mac address, programming OTP locations or running tests for usage on the device.

To view a list of available tasks, run:

    mptool -h

To run a specific task:

    mptool <task_name>

Settings for partition sizes, image names and flash memory (NAND / EMMC) can be configured in the mptool.config. This config file can be found either in the `meta-ktn-stm32mp` layer in the directory `recipes-ktn/production-tool/mptool/<MACHINE>` or on the running linux image in the `/etc` directory.

The images used to flash or update the memory needs to be in the `/usr/local` directory. For the bootfs, rootfs and userfs the image needs to be in `tar.gz` format while for the tf-a and u-boot image a `.stm32` image is needed.

To partition the memory device defined in the config file and afterwards flash the respective images:

    mptool flash-full-fs

All partitions can be seperately updated with e.g `update-rootfs`. Furthermore, with the option `-f=imagename` it is possible to use a different image than the one specified in the config file.

The MAC address can be written into the respective OTP register with 'set-lan-mac'.

#### System service autostart-eglfs

The system service `autostart-eglfs` is used to start an Qt application on bootup with all desired environment variables set.

This service has a configuration file `/etc/default/autostart-eglfs`. The configuration is done by setting appropriate environment variables:

- APPLICATION
  absolute path to Qt application
- APPLICATION_OPTIONS
  command line parameters for application
- QT_QPA_PLATFORM linuxfb|eglfs
  configuration settings wheter hardware acceleration(eglfs) or software rendering (linuxfb) shall be used.
- DISPLAY_PHYS_WIDTH, DISPLAY_PHYS_HEIGHT
  display dimensions in milimeters

Further informations can be achieved by examining the companion file `/usr/bin/autostart-eglfs.sh`.

### Demo applications

#### C-app-demo

A simple Hello-World application in C. Only available in the VMware image.

#### kontron-demo (QML)

A QML-based demo application, featuring a simple touch UI. It contains demos for Qt widgets, multitouch controls, slideshow and QtWebEngine webbrowser. This application is started when the Demo-Kit is powered on.

#### imagegestures and animatedtiles (Qt Widgets)

Two modified Qt examples to show performance of Qt-Widgets-based applications (also usable without GPU).

#### Web viewer with virtual keyboard

The package `webengine-vk` contains a simple web browser with integrated onscreen touch keyboard. You can load a specific website or rotate the screen by running the application by launching the application manually.

When using `autostart-eglfs` set your parameters in `/etc/default/autostart-eglfs`

    ## Simple webbrowser based on Qt
    APPLICATION=/opt/webengine-vk/webengine-vk
    APPLICATION_OPTIONS=rot 180 http://www.kontron-electronics.de

and start the application by typing:

    /etc/init.d/autostart-eglfs-initscript.sh start

Hint

- Please note that the web viewer is only capable to display a single page at the same time. No tab browsing is possible.
- This application is not included in the standard image for Kontron Demo-Kits. It has to be compiled with Yocto.

## Linux tools

### screen

Screen is a terminal multiplexer which is also very handy to open serial terminals. To use screen for a serial connecton on `/dev/ttyUSB0` with 115200 baud call it with following parameters:

    screen /dev/ttyUSB0 115200

To exit this screen type `Ctrl-a k`. To scroll back Type `Ctrl-a ESC` and use your cursor keys to scroll back. Stop the scrollback mode with pressing `ESC` again.

There are various cheat sheet for screen, for example https://catonmat.net/ftp/screen.cheat.sheet.pdf