Introduction

This Quickstart guide describes the tools and provides the know-how to install and work with the Linux Board Support Package (BSP) for the phyCORE-STM32MP1Alpha 2 Kit. This guide shows you how to do everything including installing the appropriate tools and sources, building custom kernels, and deploying the OS in order to operate the software and hardware.

The phyCORE-STM32MP1 Alpha 2 Kit contains the following hardware versions:

• phyCORE-STM32MP1 PL1534.0  (or  PL1534.1) equipped with stm32mp157 @650Mhz MPU, 3D GPU, 1GiB RAM, 8GiB eMMC, 16MB QSPI NOR
• phyBOARD-Sargas PL1517.2

This kit is currently in Alpha Status. There are several topics to keep in mind while working with this kit and guide:

• The phyCORE-STM32MP1 will go through several functional changes during the Alpha Stage of development. Due to this, this Quickstart guide may change without any prior notice.
• The phyCORE-STM32MP1 has some functionality that is not currently operational. Please be aware of this when working with the Alpha Kit.
• This Quickstart guide is only for booting and starting the basic functionality of the phyCORE-STM32MP1. This guide does not qualify as a Hardware manual for the phyCORE-STM32MP1.
• For more information or details regarding the phyCORE-STM32MP1, please contact the PHYTEC Sales department.

PHYTEC Documentation

PHYTEC will provide a variety of hardware and software documentation for all of our products. This includes any or all of the following:

• QS Guide: A short guide on how to set up and boot a phyCORE board along with brief information on building a BSP, the device tree, and accessing peripherals.
• Hardware Manual:  A detailed description of the System on Module and accompanying carrier board. 
• Yocto Guide:  A comprehensive guide for the Yocto version the phyCORE uses. This guide contains an overview of Yocto; introducing, installing, and customizing the PHYTEC BSP; how to work with programs like Poky and Bitbake; and much more.
• BSP Manual:  A manual specific to the BSP version of the phyCORE. Information such as how to build the BSP, booting, updating software, device tree, and accessing peripherals can be found here.
• Development Environment Guide:  This guide shows how to work with the Virtual Machine (VM) Host PHYTEC has developed and prepared to run various Development Environments. There are detailed step-by-step instructions for Eclipse and Qt Creator, which are included in the VM. There are instructions for running demo projects for these programs on a phyCORE product as well. Information on how to build a Linux host PC yourself is also a part of this guide.
• Pin Muxing Table:  phyCORE SOMs have an accompanying pin table (in Excel format). This table will show the complete default signal path, from processor to carrier board. The default device tree muxing option will also be included. This gives a developer all the information needed in one location to make muxing changes and design options when developing a specialized carrier board or adapting a PHYTEC phyCORE SOM to an application. 

On top of these standard manuals and guides, PHYTEC will also provide Product Change Notifications, Application Notes, and Technical Notes. These will be done on a case by case basis. Most of the documentation can be found in the applicable download page of our products.

phyCORE-STM32MP1 Development KIT Architecture

Requirements

The following components and system requirements are necessary to successfully complete this Quickstart. Deviations from these requirements are possible but may require workarounds.

Hardware and Equipment

Equipment preinstalled with the phyCORE-STM32MP1 Alpha Kit

• phyCORE-STM32MP1 (PCM-068) plugged onto phyBOARD-Sargas (PCM-939)
• uSD Card inserted into X14 carrier board connector
• 2x5 header to DB-sub 9 male inserted on X36 carrier board connector (CAN)
• 2x5 header to DB-sub 9 male on X35 carrier board connector (RS232/RS485)

Additional equipment not included in the Kit

• Additional Serial null modem cable (RS-232)
• Display HDMI interface Add-on Kit (PEB-AV-01)
• Display Parallel Add-on Kit (PEB-AV-02 with 7''capacitive screen)

Connecting the phyBOARD-Sargas

There are a few manual connections that you will need to make before using the phyBOARD-Sargas.

phyBOARD-Sargas - Connectors

phyBOARD-Sargas - Buttons, LED, and Jumpers

Connecting the USB Debug

For the following steps, a console connection via USB is required. You can use the included USB cable.

Connect your PC's USB port with the micro USB connector of the carrier board (X13). Two COM-Ports will show up.

1. UART4 is the default debug UART (Cortex-A7)
2. USART3 is an additional debug UART (can be used for Cortex-M4 debug purpose)

When the Debug USB cable is not plugged in, UART4 and USART3 are available on the Expansion Connector (X33). USART3 can be forced to be exclusively available on X33 by putting a jumper on JP16.

Connecting to the Ethernet (optional)

Connect the Ethernet cable to the Ethernet port on the carrier board (X47). Connect the other end to a suitable Ethernet source, as the development host will need to communicate with the phyCORE-STM32MP15x.

Connecting the RS-232 or RS-485 (optional)

RS-232 or RS-485 interfaces are available on the connector X35 (with 2x5 header to DB-sub 9 male cable plugged on it). Both interfaces are connected to the USART1 of the CPU. RS232 is the default interface, but RS-485 can be used instead by changing the jumpers JP4 and JP5 to position 2+3.

Connecting the CAN-FD (optional)

The CAN-FD (CAN with Flexible Data-Rate) interface is available at connector X36 (with 2x5 header to DB-sub 9 male cable plugged on it). CAN devices can be directly connected to this connector. This interface is connected to the FDCAN2 of the CPU.

Powering the Board

There are 3 different ways of powering the board:

• Connect the delivered 24 V power adapter to the green Power-In connector (X9):

phyBOARD-Sargas Power Schematic

• Use a 9V-24V power adapter equipped with a DC-10 power socket and connect it to the black DC power socket (DCIN1)
• Use a USB-C cable (5V) and connect it to the USB-C socket (X5VIN)

Software

• A modern Linux operating host system either natively or via a virtual machine.
• Ubuntu 16.04 LTS (64-bit recommended). Other distributions will likely work but note that some setup information, as well as OS-specific commands and paths, may differ.
• VMWare Workstation, VMWare Player, and VirtualBox are possible solutions if you want to use a virtual machine.
• Root access to your Linux host PC. Some commands in this guide will not work if you do not have sudo access (e.g. package installation, formatting an SD card).
• At least 8GB of RAM (16GB or more is recommended).
• At least 100 GB of free space on the build partition of the host PC.
• An SD card reader operational under Linux.
• An active internet connection.

For more details concerning Linux PC configuration, please refer to: https://wiki.st.com/stm32mpu/wiki/PC_prerequisites

Getting Started with the Included SD Card

This section is designed to get the board up and running with the SD Card included in the kit, which has been prepared with pre-built images.

Booting from the SD Card

This section describes how to boot the KIT with the pre-built images on the included SD card.

• Insert the micro SD card into the SD card slot of the board.
• Check that the S7 DIP switch is in the default position (boot from SD): POS1=> OFF, POS2 => ON, POS3 => OFF
• Plug the USB cable into the USB debug on the board (X13) and your host PC. You should see two new devices appear: /dev/ttyUSB0 and /devttyUSB1. A Linux terminal will be accessible on /dev/ttyUSB0. 
• Start your favorite terminal software (e.g. Minicom or Tera Term) on your host PC and configure it for 115200 baud, 8 data bits, no parity, and 1 stop bit (8n1) with no handshake.
• Example to launch minicom on /dev/ttyUSB0:

host:~$sudo minicom -D /dev/ttyUSB0 

• Connect the power supply to the power connector (please note the polarity shown in the picture phyBOARD-Sargas Power Schematic).

The RGB LED (D11) will begin blinking BLUE as the board begins booting into Linux. The console output can be viewed in your terminal window. If everything was done correctly, the login prompt will be shown at the end of the booting process:

ST OpenSTLinux - Weston - (A Yocto Project Based Distro) 2.6-snapshot phycore-stm32mp1-1 ttySTM0
phycore-stm32mp1-1 login: root (automatic login)
root@phycore-stm32mp1-1:~#

Log in is done automatically as root (no password is required).

Building the BSP

This section will guide you through the general build process of the STM32MP1 BSP using the repo tool.

Our BSP is based on OpenSTLinux Distribution: https://wiki.st.com/stm32mpu/wiki/STM32MP15_OpenSTLinux_release_note

To adapt the OpenSTLinux distribution to our board, we added our own yocto layer, "meta-phytec". You can find our specific meta-phytec layer for stm32mp in:

https://git.phytec.de/meta-phytec/tree/dynamic-layers/stm-st-stm32mp

In this meta-phytec yocto layer, we have added some extra features and patches to U-boot and Linux Kernel.

Get the BSP

• Create a fresh project directory:

host:~$ mkdir ~/PHYTEC_STM32MP1_BSP

• Initialize repo in the current directory:

host:~$ cd ~/PHYTEC_STM32MP1_BSP
host:~/PHYTEC_STM32MP1_BSPx$ repo init -u git://git.phytec.de/phy2octo -b stm32mp1 -m PD-BSP-Yocto-OpenSTLinux-STM32MP1-ALPHA2.xml --reference=/home/share/repo_reference

• Synchronize the local project directories with the remote repositories specified in the manifest:

host:~/PHYTEC_STM32MP1_BSP$ repo sync

Basic Set-Up

There are a few important steps that have to be done before the main build process.

• Setting up the host:  refer to OpenSTLinux documentation: https://wiki.st.com/stm32mpu/wiki/PC_prerequisites

Finding the Right Software Platform

The STM32MP1 BSP is planned as a unified BSP, which means in the future it will support a set of different PHYTEC carrier boards (CB) with different Systems on Module (SOMs). However, this ALPHA BSP supports only one PHYTEC machine: <MACHINE>=phycore-stm32mp1-1

OpenEmbedded Environment Setup

• Select the correct MACHINE and DISTRIBUTION and initialize the OpenEmbedded build environment:

host:~/PHYTEC_STM32MP1_BSP$ DISTRO=openstlinux-weston MACHINE=phycore-stm32mp1-1 BSP_DEPENDENCY=layers/meta-phytec source layers/meta-phytec/scripts/envsetup.sh

Available Distributions (DISTRO): please refer to https://wiki.st.com/stm32mpu/index.php/OpenSTLinux_distribution#Distros
By default, our BSP image (loaded in the uSD-card that we include in the kit) is based on "openstlinux-weston" distribution.

Available Hardware configuration (MACHINE): "phycore-stm32mp1-1" (this hardware configuration is the only one available in Alpha KIT)
The BSP for STM32MP1 depends on packages and firmware which are covered by a software license agreement (SLA). You will be asked to read and to accept this EULA:

• After accepting the EULA, you should now be in a sub-folder named '~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>'

host:~/PHYTEC_STM32MP1_BSP$ source layers/meta-phytec/scripts/envsetup.sh

Build Process

Now you should be in a sub-folder named '~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>' and you can start the first build process:

host:~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp1-1$ bitbake st-image-weston

"st-image-westion" is the default image that we deliver with our BSP. This image supports the Weston Display server protocol with basic Wayland support. It comes with a graphical application demo that will show up on a Screen (if one display is connected to the carrier board: see Displays section).

To check all other available images, please refer to: https://wiki.st.com/stm32mpu/index.php/OpenSTLinux_distribution#Images

BSP Images

All images generated by Bitbake are deployed to ~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>/tmp-glibc/deploy/images/<MACHINE>. The following list shows the generated files used for flashing the phycore-stm32mp1-1 machine:

System Booting

The phyCORE STM32MP15x can boot from the following devices:

• eMMC
• NOR
• NAND (when populated instead of eMMC)
• UART 
• USB
• SD-Card

For the Alpha release, the only available boot sources are SD-card and NOR-eMMC¹ 

The boot source is chosen by setting the S7 DIP switch:

• Boot from SPI NOR: POS1=> OFF,  POS2 => ON,  POS3 => ON 
• Boot from SD Card:  POS1=> OFF,  POS2 => ON,  POS3 => OFF 

_{1:  Booting from NOR and then Linux will run on eMMC (NOR and eMMC have to be flashed first: see  How to flash BSP with STM32CubeProgrammer tool)}

Booting from SD Card

Booting from the SD Card is useful in several situations (for example when bootloader in Flash memory has crashed).

To boot from SD card, set the S7 DIP switch as follow: POS1=> OFF,  POS2=> ON,  POS3 => OFF 

There are two ways to create a bootable SD card. You can either use:

• use a single prebuilt SD card image (see section Create an SD card image (with PC Host SD card reader))
• use STM32MPCubeprogrammer to flash the SD card from target (see How to flash BSP with STM32CubeProgrammer tool)

Create an SD card image (with PC Host SD card reader)

To boot from SD, the first possibility is to create an SD Card image that contains all BSP binary files in correctly preformatted partitions. This image can be copied to the SD card easily using the single Linux command dd. Use the script create_sdcard_from_flashlayout.sh with the <FlashLayout file> = FlashLayout_sdcard_phycore-stm32mp1-1-trusted.tsv:

host:~$ cd build-<DISTRO>-<MACHINE>/tmp-glibc/deploy/images/<MACHINE>/scripts
host:~$ ./create_sdcard_from_flashlayout.sh ../flashlayout_<built-image>/<FlashLayout file>

Example:

host:~$ cd build-openstlinuxweston-phycore-stm32mp1-1/tmp-glibc/deploy/images/phycore-stm32mp1-1/scripts
host:~$ ./create_sdcard_from_flashlayout.sh ../flashlayout_st-image-weston/FlashLayout_sdcard_phycore-stm32mp1-1-trusted.tsv 

The script will generate the following SD Card image (raw file): ../flashlayout_st-image-weston/../flashlayout_st-image-weston_FlashLayout_sdcard_phycore-stm32mp1-1-trusted.raw

Use this raw file to populate the SD Card with dd command:

• Insert the uSD Card in the PC Host
• Umount all the partitions associated with uSD Card
• Populate microSD card with dd command:

host:~$ cd build-openstlinuxweston-phycore-stm32mp1-1/tmp-glibc/deploy/images/phycore-stm32mp1-1
host:~$ sudo dd if=flashlayout_st-image-weston_FlashLayout_sdcard_phycore-stm32mp1-1-trusted.raw of=/dev/mmcblk0 bs=8MB conv=fdatasync

More details can be found here: https://wiki.st.com/stm32mpu/wiki/How_to_populate_the_SD_card_with_dd_command

Booting from NOR Flash

• First, you have to follow the procedure to flash the eMMC and NAND: How to flash BSP with STM32CubeProgrammer tool
• After flashing, power off the board. Then set the S7 DIP switch to the correct positions: POS1=> OFF, POS2 => ON,  POS3 => ON
• When powering the board again, the system will boot from NOR.

How to flash BSP with STM32CubeProgrammer tool

In this section, we explain how to use the STM32MPCubeProgrammer tool that can be used to flash the NOR, eMMC, NAND, or SD Card.

Install STM32CubeProgrammer tool

Refer to: https://wiki.st.com/stm32mpu/wiki/STM32CubeProgrammer

Connecting the Board via USB DFU Link

To be able to download the BSP via DFU link, change the BOOT mode to UART/USB boot mode

• Switch OFF the board
• Change the S7 DIP switch to UART/USB boot mode : POS1=> ON, POS2 => ON,  POS3 => ON
• Switch ON the board => The RED LED on the SOM must start blinking RED.
• Connect a USB micro-AB (OTG) to X12 and to the host PC that contains the downloaded image. => The RED led should stop blinking.

How to use STM32CubeProgrammer

• Go to the directory that contains the binaries and the flash layout files: 

host:~$ cd ~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-stm32mp1/tmp-glibc/deploy/images/phycore-stm32mp1-1

• Get the device port location for the USB link:

$ STM32_Programmer_CLI -l usb
      -------------------------------------------------------------------
                        STM32CubeProgrammer <tool version>                  
      -------------------------------------------------------------------

=====  DFU Interface   =====

Total number of available STM32 device in DFU mode: 1

  Device Index           : USB1
  USB Bus Number         : 001
  USB Address Number     : 001
  Product ID             : DFU in HS Mode @Device ID /0x500, @Revision ID /0x0000
  Serial number          : 003C00283338510C34383330
  Firmware version       : 0x0110
  Device ID              : 0x0500

• Use the flashing command:

$ STM32_Programmer_CLI -c port=<DEVICE_PORT_LOCATION> -w [<file.tsv>]
where 
 w:
     Write
 <file.tsv>:PathToFlashlayout/flashlayout.tsv file
         if Flashlayout and binaries are not in the same directory, then the path to the Flashlayout files must be precised.
 <DEVICE_PORT_LOCATION>:
         e.g. usb1 (case sensitive)

How to Flash SD Card

To flash the SD Card with STM32CubeProgrammer:

• If not already done, insert an SD Card in the SD Card (X14).
• Use the flashing command with the following Flashlayout file: /flashlayout_st-image-weston/FlashLayout_sdcard_phycore-stm32mp1-1-trusted.tsv

$ STM32_Programmer_CLI -c port=usb1 -w flashlayout_st-image-weston/FlashLayout_sdcard_phycore-stm32mp1-1-trusted.tsv

This operation takes several minutes (mainly depending on the rootfs size). A successful flashing outputs the following message: "Flashing service completed successfully"

How to Flash NOR and eMMC (boot from NOR)

To flash the NOR and eMMC:

• Use the flashing command with the following Flashlayout file: /flashlayout_st-image-weston/FlashLayout_nor-emmc_phycore-stm32mp1-1-trusted.tsv

$ STM32_Programmer_CLI -c port=usb1 -w flashlayout_st-image-weston/FlashLayout_nor-emmc_phycore-stm32mp1-1-trusted.tsv

This operation takes several minutes (mainly depending on the rootfs size). A successful flashing outputs the following message: "Flashing service completed successfully"

Using Peripherals (in Linux user space)

UARTs (tty)

The STM32MP15x SoC provides up to 4 x UART and 4 x USART. phyCORE-STM32MP15x and carrier board is configured by default with 4 UARTs:

Below are some Linux userspace commands to test the UART on target:

• Command to send a message on USART3:

target$ echo "test" > /dev/ttySTM1

• Command to receive a message on USART3:

target$ cat /dev/ttySTM1

• Be sure that the baud rate is set correctly on the host and target. In order to get the currently configured baud rate, you can use the command stty on the target.

Command to get tty help:

target$ tty --help

FD CAN bus

For an overview of the Linux Controller Area Network (CAN) framework, please refer to https://wiki.st.com/stm32mpu/wiki/CAN_overview.

Below are some examples on how to send or receive data on a SocketCAN interface using the can-utils package with the cansend and candump command:

Prerequisite: At least two nodes are required to communicate on a CAN network.

• Initialize CAN0 Link with 1Mbit/s:

target$ ip link set can0 up type can bitrate 1000000

• The command below allows you to get details on the created link:

target$ ip -details link show can0
2: can0: <NOARP,UP,LOWER_UP,ECHO> mtu 16 qdisc fq_codel state UNKNOWN mode DEFAULT group default qlen 10
    link/can  promiscuity 0 
    can state ERROR-ACTIVE (berr-counter tx 0 rx 0) restart-ms 0 
          bitrate 992063 sample-point 0.761
          tq 48 prop-seg 7 phase-seg1 8 phase-seg2 5 sjw 1
          m_can: tseg1 2..256 tseg2 1..128 sjw 1..128 brp 1..512 brp-inc 1
          m_can: dtseg1 1..32 dtseg2 1..16 dsjw 1..16 dbrp 1..32 dbrp-inc 1
          clock 62500000numtxqueues 1 numrxqueues 1 gso_max_size 65536 gso_max_segs 65535

• To send a single frame, use the cansend utility (cansend <device> <can_frame>):

target$ cansend can0 123#1122334455667788                                                                                                                                                   

• To receive CAN message, use the candump utility:

target$ candump can0                                                                                                                                                     
  can0  123   [8]  00 11 22 33 44 55 66 77
  can0  123   [8]  00 11 22 33 44 55 66 77

• To print help on candump utility, use: "candump -h"

Network

A gigabit Ethernet is provided by our module and board. The interfaces offer a standard Linux network port that can be programmed using theBSD socket interface. The BSP contains different Network tools that allow for the configuration and testing of the Ethernet connection.

For information about these different tools and how to use it, please refer to: https://wiki.st.com/stm32mpu/wiki/Network_tools

Example on how to assign a given IP address to an Ethernet ETH0 interface:

ifconfig eth0 10.48.1.324

SD-Card

The STM32MP1 ALPHA release kit supports a slot for Secure Digital Cards to be used as general-purpose block devices. These devices can be used in the same way as any other block device.

After inserting an SD/MMC card, the kernel will generate new device nodes in /dev. The full device can be reached via its /dev/mmcblk0 device node. SD/MMC card partitions will show up in the following way:

/dev/mmcblk0p<Y>

<Y> counts as the partition number starting from 1 to the max count of partitions on this device. The partitions can be formatted with any kind of file system and also handled in a standard manner, e.g. the mount and umount command work as expected.

GPIOs

The phyBOARD-Sargas carrier board has a set of pins specifically dedicated as user I/Os. Those pins are connected directly to STM32MP15x balls and are muxed as GPIOs. Accessing GPIOs from userspace can be done using the libgpiod.

To see how to access the GPIOs, please refer to: https://wiki.st.com/stm32mpu/wiki/How_to_control_a_GPIO_in_userspace 

Keys

With gpio-keys driver, the Linux kernel can interpret GPIO signals as virtual keyboard events. The carrier board has 2 buttons (S4 and S5), which can be used with the gpio-keys driver. 

To display the key events in ASCII format, use evtest.

• To show the available input devices, run:

target$ evtest

• You will get, for example:

No device specified, trying to scan all of /dev/input/event*
Available devices:
/dev/input/event0:      pmic_onkey
/dev/input/event1:      gpio-keys
Select the device event number [0-1]:

• Select input device event number 1 for gpio-keys:

Select the device event number [0-1]: 1
Input driver version is 1.0.1
Input device ID: bus 0x19 vendor 0x1 product 0x1 version 0x100
Input device name: "gpio-keys"
Supported events:
  Event type 0 (EV_SYN)
  Event type 1 (EV_KEY)
    Event code 28 (KEY_ENTER)
    Event code 102 (KEY_HOME)
Properties:
Testing ... (interrupt to exit)

• Now you will see every hit on push buttons S4 (KEY_HOME) or S5 (KEY_ENTER):

Event: time 1570639195.409061, type 1 (EV_KEY), code 102 (KEY_HOME), value 1
Event: time 1570639195.409061, -------------- SYN_REPORT ------------
Event: time 1570639195.569047, type 1 (EV_KEY), code 102 (KEY_HOME), value 0
Event: time 1570639195.569047, -------------- SYN_REPORT ------------
Event: time 1570639196.809052, type 1 (EV_KEY), code 28 (KEY_ENTER), value 1
Event: time 1570639196.809052, -------------- SYN_REPORT ------------
Event: time 1570639197.009031, type 1 (EV_KEY), code 28 (KEY_ENTER), value 0
Event: time 1570639197.009031, -------------- SYN_REPORT ------------

• You can exit evtest with Ctrl+C
• Listening to the device with cat will print the raw output:

target$ cat /dev/input/event1
root@phycore-stm32mp1-1:/sys/class# cat /dev/input/event1 
F
�]��fF
�]��F
�]BfF
�]B

LEDs

If any LEDs are connected to GPIOs, you have the possibility to access them by a special LED driver interface instead of the general GPIO interface (section GPIOs). You will then access them using /sys/class/leds/ instead of /sys/class/gpio/. The maximum brightness of the LEDs can be read from the max_brightness file. The brightness file will set the brightness of the LED (taking a value from 0 up to max_brightness). Most LEDs do not have hardware brightness support and therefore, will just be turned on by all non-zero brightness settings.

Here is a simple example:

• To get all LEDs available, type:

target$ ls /sys/class/leds
blue-power  pca:green:power  pca:red:power

Here the LEDs are the three possible color from RGB lED driven by a LED dimmer present on carrier board. By default, the RGB LED blinks blue (it is the "Linux Heartbeat" that shows that the Linux Kernel is running). But this RGB LED can also be used as a "user LED".

• Example to toggle the RGB LED Blue color OFF:

target$ echo 0 >  blue-power/brightness

• Example to toggle RGB LED Blue color ON with a brightness=10:

target$ echo 10 >  blue-power/brightness

• Example to toggle RGB LED Green color ON with a brightness=20:

target$ echo 20 >  pca\:green\:power/brightness

I²C Bus

The STM32MP15x SoC provides up to 6 I²C FM (Fast-Mode). The phyCORE-STM32MP15x is configured to features two Fast-Mode I²C modules called I2C4 and I2C1.

• I²C4 is reserved for the I²C devices on the Module (PMIC, RTC, EEPROM).
• I²C1 is reserved for the carrier board which provides plenty of different I²C devices connected I²C1 bus of the STM32MP15x. This chapter will describe the basic device usage.

EEPROM

It is possible to read and write directly to the device:

/sys/class/i2c-dev/i2c-1/device/1-0050/eeprom

• To read and print the first 1024 bytes of the EEPROM as hex number, execute:

target$ dd if=/sys/class/i2c-dev/i2c-1/device/1-0050/eeprom bs=1 count=1024  | od -x

• To fill the whole EEPROM with zeros, use:

target$ dd if=/dev/zero of=/sys/class/i2c-dev/i2c-1/device/1-0050/eeprom bs=4096 count=1

This operation takes some time because the EEPROM is relatively slow.

RTC

RTCs can be accessed via /dev/rtc*. 

• Check the available RTC:

target$ ls /sys/class/rtc
target$ rtc0  rtc1

• To find the name of the RTC devices, you can read its sysfs entry with:

target$ cat /sys/class/rtc/rtc*/name
rtc-rv3028 1-0052
stm32_rtc 5c004000.rtc

As the time is set according to the value of rtc0 during system boot, rtc0 should always be the RTC that is being backed up. 

• Date and time can be manipulated with the date command and the hwclock tool. Example to set the date on /dev/RTC0:

target$ date 1010123119
Thu Oct 10 12:31:00 UTC 2019
target$ hwclock -w

SPI Bus

The STM32MP1 SoC provides up to 6 SPI interfaces. The phyCORE-STM32MP1 is configured to feature 1 SPI called SPI16 (configured as SPI1 or SPI6).

By default, the linux spi driver used in the BSP is spidev

USB HOST and OTG

To know about the Linux USB framework and how to use it, please refer to the USB framework: https://wiki.st.com/stm32mpu/wiki/USB_overview

Both OTG and Host use the same framework. 

For more software details about the OTG internal peripheral, please refer to: https://wiki.st.com/stm32mpu/wiki/OTG_internal_peripheral

For more software details about the USBH internal peripheral, please refer to: https://wiki.st.com/stm32mpu/wiki/USBH_internal_peripheral

Create an SSH connection with USB OTG

When the target is running on Linux, you can create an SSH connection with Ethernet or USB OTG.

To create a SSH connection over USB OTG, proceed as follows: 

• On the PC host, use "ifconfig" on a terminal
• Plug a USB-A male to USB Micro B between the carrier board (X12) and the PC Host.
• On the PC host, use "ifconfig" on a terminal, and check that there is a new network interface 
• Check the IP address of the USB OTG device:

target$ ifconfig 
eth0      Link encap:Ethernet  HWaddr 8E:C5:2C:68:CF:75  
          inet6 addr: fe80::8cc5:2cff:fe68:cf75/64 Scope:Link
          UP BROADCAST RUNNING MULTICAST  MTU:1500  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:35 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000 
          RX bytes:0 (0.0 B)  TX bytes:7597 (7.4 KiB)
          Interrupt:61 Base address:0x2000 

lo        Link encap:Local Loopback  
          inet addr:127.0.0.1  Mask:255.0.0.0
          inet6 addr: ::1/128 Scope:Host
          UP LOOPBACK RUNNING  MTU:65536  Metric:1
          RX packets:264 errors:0 dropped:0 overruns:0 frame:0
          TX packets:264 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000 
          RX bytes:16800 (16.4 KiB)  TX bytes:16800 (16.4 KiB)

usb0      Link encap:Ethernet  HWaddr BA:15:19:D5:BC:01  
          inet addr:192.168.7.2  Bcast:192.168.7.255  Mask:255.255.255.0
          UP BROADCAST MULTICAST  MTU:1500  Metric:1
          RX packets:0 errors:0 dropped:0 overruns:0 frame:0
          TX packets:0 errors:0 dropped:0 overruns:0 carrier:0
          collisions:0 txqueuelen:1000 
          RX bytes:0 (0.0 B)  TX bytes:0 (0.0 B)

• On the PC host, use "ifconfig" to set the new Network interface IP that matches with the usb0 target interface. Example:

host:~$ sudo ifconfig enp0s20f0u2u3 192.168.7.1

• Connect to the target:

host:~$ ssh root@192.168.7.2

The same procedure can be applied with an Ethernet connection.

Audio

On the phyCORE-STM32MP1, we use the TI TLV320AIC3007 audio codec. Audio support is done via the SAI2 interface and controlled via I²C.

• To check if your sound card driver is loaded correctly and to check which audio output device is available:

target$ aplay -L

• You will get output similar toː

null
      Discard all samples (playback) or generate zero samples (capture)
pulse
      PulseAudio Sound Server
default
      Default ALSA Output (currently PulseAudio Sound Server)
sysdefault:CARD=STM32MP1PHYCORE
      STM32MP1-PHYCORE, 
       Default Audio Device

• To test Audio Playback:

target$ aplay -D plughw:CARD=STM32MP1PHYCORE /usr/share/sounds/alsa/Front_Center.wav

• To list audio capture devices:

target$ arecord -l
**** List of CAPTURE Hardware Devices ****card 0: STM32MP1PHYCORE [STM32MP1-PHYCORE], device 1: 4400b004.audio-controller-tlv320aic3x-hifi tlv320aic3x-hifi-1 [] 
Subdevices: 1/1 Subdevice #0: subdevice #0

• Run speaker-test to identify channel numbers (Left, Right...). Example to check right and left channel (2 channels):

target$ speaker-test -c 2 -t wav

• You may have to select the audio device:

target$ speaker-test -c 2 -t wav -D plughw:CARD=STM32MP1PHYCORE

• To inspect your sound cards capabilities, call:

target$ alsamixer -c STM32MP1PHYCORE

You should see a lot of options as the audio-ICs has many features you can play with. It might be better to open alsamixer via ssh (see Create an SSH connection with USB OTG) instead of the serial console, as the console graphical effects are better.

Audio Sources and Sinks

The phyBOARD-Sargas carrier board has three jacks: headphone (X28), line in (X27), line out (X26); and one Mono speaker output connector (X5). Enabling and disabling input and output channels can be done with the alsamixer program.

With the Tabulator key, you can switch between the following screens:   Screen Playback; Screen Capture. To enable or disable switchable controls, press m (mute)

With the cursor keys left and right, you can step through the different channels. 

You can leave alsamixer by pressing the ESC key. The settings are saved automatically on shutdown and restored on boot by the systemd service alsa-restore. If you want to save the mixer settings manually, you can execute alsactl store. The settings are saved in /var/lib/alsa/asound.state.

Playback

To playback simple audio streams, you can use aplay. For example:

target$ aplay /usr/share/sounds/alsa/Front_Center.wav
#OR you may have to select the audio device:
target$ aplay -D plughw:CARD=STM32MP1PHYCORE /usr/share/sounds/alsa/Front_Center.wav

Capture

arecord is a command-line tool for capturing audio streams which uses Line In as the default input source. 

The following example captures the current stereo input source with a sample rate of 48000 Hz and creates an audio file in WAV format (signed 16 bit per channel, 32 bit per sample):

target$ arecord -t wav -c 2 -r 48000 -f S16_LE test.wav
#OR :
target$ arecord -t wav -c 2 -f dat test.wav
#OR you may have to select the audio device:
target$ arecord -t wav -c 2 -f dat test.wav -D hw:0,1

Capturing can be stopped using CTRL-C. You can also specify the capture duration with the -d option.

To play the recorded file: 

target$ aplay test.wav

Texas Instruments TLV320AIC3007

The TI chip has a lot of mixing features as you will notice when opening alsamixer. To get an idea of the possibilities, refer to the datasheet from TI. One important feature is the analog mixing capability. You can route input channels to output channels, either active or passive, without transferring data back and forth to the SoC. This is usually known as zero-latency monitoring in terms of PC Audio cards. To control this feature, open alsamixer and go to Playback section (F3). There will be one group of selectors for each output channel, e.g. Right Line Mixer. For most of the input paths, you can select between "passive through" or you can activate a programmable gain signal path. To route the line input to the line output, activate both "Right Line Mixer PGAR Bypass" and "Left Line Mixer PGAL Bypass". You should now hear the input signal at the line-out.

As an example application, we can route the audio stream through the whole system. First, we deactivate the direct loop from line-in to line-out in alsamixer and activate the ADC for the analog input mixer and the DAC for the analog output mixer. We can now close the signal path in the user space by using a pipe and the ALSA tools:

target$ arecord -c 2 -r 48000 -f S16_LE | aplay
#OR
target$ arecord -c 2 -r 48000 -f S16_LE -D hw:0,1 | aplay -D plughw:CARD=STM32MP1PHYCORE

We created the following audio routing path:

analog in -> ADC -> STM32MP1 -> kernel -> (userspace -> kernel -> )* DAC -> analog out

* actually twice for the pipe

You should now hear the input signal at the line output again. But this time, the routing through the entire system added a latency of 750 ms to the signal. The line mixer on the other side will only add about 4 μs delay.

This pipe routing is a crude example of how to use audio. If you need good audio performance, you should use an audio server. There are two prominent choices available, pulseaudio and jack.

As a third option, you can route the audio from line-in to the internal ADC. But instead of taking the signal path through the complete system, you can use the internal digital mixer of the TLV to directly route the signal back to the DAC and then to the output analog mixer and line-out. This signal path is record only. You do not have the option of full-duplex playback in this mode. You can, however, use all the available DSP features of the TLV, the automatic gain, the high-pass filter, EQ, and de-emphasis filters for the record path. To activate this mode, you have to use the TI Windows tool to look up the specific I²C commands. The software can be found on the TI webpage and is called TLV320AIC3107EVM-K - GUI software. The 3107 is register compatible with all available features to the 3007. The software is used for both chips.

Displays

Three different kinds of displays are currently supported:

• HDMI monitor => with PEB-AV-01 PHYTEC addon connected on Audio/Video connectors X24/X25
• AC158 7" EDT capacitive LCD screen => with PEB-AV-02 PHYTEC addon connected on Audio/Video connectors X24/X25
• MB1407 MIPI DSI screen (from STMicroelectronics : https://wiki.st.com/stm32mpu/wiki/MB1407) => connected on MIPI DSI connector X41

By default, the PHYTEC BSP is configured for the AC158 display.

To switch between the 3 different configurations, the device tree has to be rebuilt.

How to change the BSP Display configuration

Prerequisite: Building the BSP must have been done.

Build a new image enabling/disabling the following device tree files :

• phycore-stm32mp1-dsi-lcd-mb1407.dtsi
• phycore-stm32mp1-peb-av01-hdmi.dtsi
• phycore-stm32mp1-peb-av02-lcd.dtsi

By default, only phycore-stm32mp1xx-peb-av02-lcd.dtsi is enabled (for AC158 parallel display screen configuration)

To enable/disable those extensions, comment (line begin with #) or uncomment the corresponding line in the phycore-stm32mp1-x.dtsi kernel device tree file (at the end of file). 

To modify the device tree, please refer to chapter BSP customization

Special connectors pinout configuration

By special connectors, we mean the Raspberry PI HAT, the Arduino Shields, and the Motor Control connectors.

Those special connectors pinout can be configured in the device tree with the following dts files:

• phycore-stm32mp1-pi-hat-extension.dtsi
• phycore-stm32mp1-uno-r3-extension.dtsi
• phycore-stm32mp1-motor-control.dtsi

By default, only phycore-stm32mp1-pi-hat-extension.dtsi is enabled.

To enable/disable those device tree file, comment (line begin with #) or uncomment the corresponding line in the phycore-stm32mp1-1.dtsi device tree file (at the end of file). Commented lines begin with #

To modify the device tree, please refer to chapter BSP customization

Prerequisite: Building the BSP must have been done.

Rapsberry PI HAT connector (X7)

This connector is compatible with the pinout of standard Raspberry Pi HAT connector (https://pinout.xyz/)

The pinout can be configured by pin muxing in the following device tree file: phycore-stm32mp1-pi-hat-extension.dtsi

Arduino Shields connector (X3)

This connector is compatible with the standard Arduino pinout connector (https://www.arduino.cc/en/reference/board)

Socket 1 x 8

Socket 1 x 10

Socket 1 x 6 (analog)

Socket 1 x 8 (power)

Motor Control connector (X38)

This connector is compatible with the pinout of STM32 standard motor control power boards. It is also possible to connect X-NUCLEO-IHMx STM32 motor control expansions using X-NUCLEO-IHM09M1 adaptor: https://www.st.com/en/ecosystems/x-nucleo-ihm09m1.html

BSP Customization

STM32MP1 BSP Device Tree Concept

All Device tree documentation can be found under:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>/tmp-glibc/work/<MACHINE>-<DISTRO>-linux-gnueabi/linux-stm32mp/4.19.9-phy1-r0/linux-4.19.9-phy1/Documentation/devicetree/bindings

An introduction of the Device Tree usage can be found in the Linux kernel: linux/Documentation/devicetree/usage-model.txt

STM32MP documentation about the STM32MP1Device Tree can be found at:

• https://wiki.st.com/stm32mpu/wiki/Device_tree
• https://wiki.st.com/stm32mpu/wiki/STM32MP15_device_tree

Note that in this ST documentation, the device tree files name concerning the boards do not correspond to our PHYTEC boards but the concept is exactly the same. The device tree files for our boards start with "phycore".

STM32MP1 Pin Muxing

The STM32MP1 SoC contains many peripheral interfaces. In order to reduce package size and lower overall system cost while maintaining maximum functionality, many of the STM32MP1 terminals can multiplex up to 16 signal functions. The STM32MP1 BSP is based on the pin controller Linux kernel framework (pinctrl) with specific pinctrl-stm32 driver. The configuration is performed in the device tree (dts).

Please refer to ST documentations to learn about pinctrl and how to configure it in the device tree:

• https://wiki.st.com/stm32mpu/wiki/Pinctrl_overview
• https://wiki.st.com/stm32mpu/wiki/Pinctrl_device_tree_configuration

Below are the location of the PHYTEC device tree source files under each source directory:

Patch Kernel, Bootloader, or Trusted Firmware

Modify the sources with devtool

Apart from using the standard PHYTEC versions of kernel, bootloader, or trusted firmware which are provided in the Yocto recipes, you can modify the source code or use our own repositories to build your customized BSP.

For example, it is necessary when you have to modify the pin muxing (configured in device tree files).

Devtool is a set of helper scripts to enhance the user workflow of Yocto. It is available as soon as you set up your shell environment. Devtool can be used to:

• modify existing sources
• integrate software projects into your build setup
• build software and deploy software modifications to your target

Devtool command to modify an existing recipe:

devtool modify -x <recipename> <directory> 

The corresponding recipe names for kernel, bootloader, or trusted firmware are: 

Example for modifying the kernel:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ devtool modify -x linux-stm32mp sources/linux-stm32mp

Devtool will create a new yocto layer in /build-openstlinuxweston-phycore-stm32mp1-1/workspace where you can see all modifications done by devtool. It will extract the sources corresponding to the recipe to the specified directory. In this example kernel sources will be extracted on the following local git directory: /build-openstlinuxweston-phycore-stm32mp1-1/sources/linux-stm32mp

A bbappend file will be created in the workspace directing the SRC_URI to this directory. Building an image with Bitbake will now use the sources in this directory. Now you can do your kernel, u-boot, or trusted-firmware modifications.

Example for modifying a device tree file and rebuilding the kernel only:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ vim sources/linux-stm32mp/arch/arm/boot/dts/phycore-stm32mp1-1.dtsi

Make a change in the dts file. Then rebuild the kernel:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp

A new device tree blob will be generated in the deploy directory:

~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>/tmp-glibc/deploy/images/phycore-stm32mp1-1/phycore-stm32mp1-1.dtb

If you want to include your new kernel device tree in your final image, you have to rebuild the bootfs partition:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake st-image-bootfs

Note that this last operation is not necessary when modifying trusted firmware or u-boot. If you want to store your changes permanently, it is advisable to create a patch from the changes, then store and backup only the patch. You can go into the linux-stm32mp directory and create a patch with the method described in the next section.

Create patches

You have to create the patch from the local git directory containing the modified source code (directory created by devtool).

Example to create a kernel patch :

Enter to the <local git directory>:

host:~/PHYTEC_STM32MP1_BSP/build-openstlinuxweston-phycore-stm32mp1-1$ cd sources/linux-stm32mp 

host:<local git directory>$ cd sources/linux-stm32mp
host:<local git directory>$ git status                        # Show changes files
host:<local git directory>$ git diff                          # Show all the changes made compared to the previous commit
host:<local git directory>$ git add .                         # Add all modified file to the staging area
host:<local git directory>$ git commit -m "DTS modification"  # Creates a commit with a not so useful commit message
host:<local git directory>$ git format-patch -1 -o ~/         # Creates a patch of the last commit and saves it in you home directory
/home/<user>/0001-DTS-modification.patch

The created patch is the home directory: host:~/0001-DTS-modification.patch

Apply Patches

The created patches can be used once you have validated your device tree modifications (using devtool for example) and you want to customize the BSP adding a custom yocto layer (how to create a yocto layer is described in the next section Create Custom yocto Layer).

After you have created the kernel patch, you must create a .bbappend file in your custom layer. The locations for the append recipes are:

The following example is for the linux-stm32mp recipe. You have to adjust the paths. First, create the folders and move the patch into it. Then create the bbappend file:

host:~/PHYTEC_STM32MP1_BSP/$ mkdir -p layers/meta-custom/recipes-kernel/linux/features                          # create the directories
host:~/PHYTEC_STM32MP1_BSP/$ cp ~/0001-DTS-modification.patch layers/meta-custom/recipes-kernel/linux/features  # copy patch in the features directory
host:~/PHYTEC_STM32MP1_BSP/$ touch layers/meta-custom/recipes-kernel/linux/linux-stm32mp_%.bbappend             # create a bbappend file

Pay attention to your current work directory. You have to execute the commands in the BSP top-level directory. Not in the build directory!

After that, use your favorite editor to add the following snipped into the bbappend file (here layers/meta-custom/recipes-kernel/linux/linux-stm32mp_%.bbappend):

# contents of the file linux-stm32mp_%.bbappend
FILESEXTRAPATHS_prepend := "${THISDIR}/features:"
SRC_URI_append = " \
file://0001-DTS-modification.patch \
"

Save the file, go back to the build directory and rebuild the kernel recipe with:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp-c clean
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake linux-stm32mp

If the build is successful, you can then rebuild the st-image-bootfs partition (containing the kernel) or the entire image (st-image-weston for example)

Create Custom Yocto Layer

Creating your layer should be one of the first tasks when customizing the BSP.

In the following chapter, we have an embedded project called "racer" which we will implement using the OpenSTLinux distribution. First, we need to create a new layer.

Yocto provides a script for that. If you set up the BSP and the shell is ready, type:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake-layers create-layer meta-racer

Default options are fine for now. Move the layer to the source directory:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ mv meta-racer ../layers/

Create a Git repository in this layer to track your changes:

host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ cd ../layers/meta-racer
host:~/PHYTEC_STM32MP1_BSP/layers/meta-racer$ git init && git add . && git commit -s -m "create meta-racer"

Now you can add the layer directly to your build-<DISTRO>-<MACHINE>/conf/bblayers.conf:

BBLAYERS += "${BSPDIR}/sources/meta-racer"

or with a script provided by Yocto:

host:~/PHYTEC_STM32MP1_BSP/layers/meta-racer$ cd ../../build-<DISTRO>-<MACHINE>
host:~/PHYTEC_STM32MP1_BSP/build-<DISTRO>-<MACHINE>$ bitbake-layers add-layer ../layers/meta-racer

Revision History