Skip to content

# Using the hardware

This page shows you how to access different peripherals and features of the hardware in general. To find out details about the board configuration and peripherals on a specific board, navigate to the hardware description page of that board.

## Reserved OTP ressources

The following locations in OTP are reserved for special usage by Kontron. These locations may be already programmed with appropriate content and can't be used by customers for their needs!

OTP word | Intended usage
--- | ---
59 | serial number of SoM
60 | serial number of baseboard
61 | reserved
62 | reserved
63 | reserved
64 | reserved
65 | reserved
66 | reserved

With the help of mptool it is possible to read and write these values.

## SOC and board features

### Sleep modes

The system can be suspended to the suspend-to-ram sleep mode. Please note that the actual state of the board and the devices in sleep mode depends on the hardware and software configuration.

For more information about this topic see STMicroelectronics Wiki Power overwiew

Suspend to RAM

    > echo mem > /sys/power/state

In this state the CPU and if possible any peripheral devices and buses will be halted. Only the RAM remains powered to keep the state of the system for wakeup.

Wakeup
To wake up from standby, multiple wakeup sources can be defined. By default only the built in RTC is enabled as wakeup source.

To list all drivers that expose a wakeup property in sysfs, you can run:

    > find /sys -name wakeup
    [...]
    /sys/kernel/irq/65/wakeup
    /sys/kernel/irq/27/wakeup
    /sys/kernel/debug/tracing/events/ftrace/wakeup
    /sys/devices/platform/soc/5c004000.rtc/power/wakeup
    /sys/devices/platform/soc/49000000.usb-otg/usb1/power/wakeup
    /sys/devices/platform/soc/4000e000.serial/power/wakeup
    /sys/devices/platform/soc/4000e000.serial/tty/ttySTM1/power/wakeup
    /sys/devices/platform/soc/40013000.i2c/power/wakeup
    /sys/devices/platform/soc/5c002000.i2c/power/wakeup
    /sys/devices/platform/soc/5800d000.usbh-ehci/usb2/2-1/power/wakeup
    /sys/devices/platform/soc/5800d000.usbh-ehci/usb2/2-1/2-1.1/power/wakeup
    /sys/devices/platform/soc/5800d000.usbh-ehci/usb2/power/wakeup
    /sys/devices/platform/soc/5800a000.ethernet/power/wakeup
    /sys/devices/platform/soc/40010000.serial/power/wakeup
    /sys/devices/platform/soc/40010000.serial/tty/ttySTM0/power/wakeup
    /sys/devices/platform/soc/5800c000.usbh-ohci/usb3/power/wakeup
    /sys/devices/platform/soc/4c001000.mailbox/power/wakeup

Example:
To wake up the system after 20 seconds using the internal RTC:

    > echo +20 > /sys/class/rtc/rtc0/wakealarm; echo mem > /sys/power/state

### Thermal management

The STM32MP1 contains a temperature sensor to measure the CPU temperature.

Measure the CPU temperature in millis of °C:

    > cat /sys/class/thermal/thermal_zone0/temp
    59000

If the device reaches the trip point the system shuts down (halt)!

### CPU core management

Some devices out of the STM32MP1 series of SOC have more than one A7 CPU core where linux runs on. It is possible to disable and enable CPU cores while linux is running. Normally all CPU cores are activated.

Disable the second CPU core:

    echo 0 > /sys/devices/system/cpu/cpu1/online

## Serial Interfaces

The following section provides general information on the serial interfaces found on Kontron hardware. For specific information on a certain board, please see the according hardware description.

### Debug

There's usually one UART, that is used as a debug and control interface to connect with terminal application on a PC via a Micro-USB header.

Depending on the hardware, the board contains an FTDI-USB-Chip or requires an external USB-Adapter to translate the UART-Signals to USB. To connect with the debug interface you can use terminal applications like TeraTerm (Windows), GtkTerm (Linux with GUI), screen (Linux shell) or the like. Set your terminal to 115200 baud 8N1.

UART4 is fixed for debug console usage!

### RS232

Some hardware also feature one or more RS232 interfaces.
Please note, that there might be no handshake lines available on the RS232 connector.

Normally linux treats the RS232 (and RS485) interfaces as tty devices. For historical reasons in linux tty devices are complex devices with e.g. line editing and character translation features (you can find a good overview on this on https://www.linusakesson.net/programming/tty).

There is the `stty` command line tool to control these features. To set the serial interface to a transparent mode which doesn't modify and interpret the data stream, you have to set particular options on the serial interface.

Set the serial device ttySTM2 into transparent mode at 115200 baud:

    > stty -F /dev/ttySTM2 raw -echo -echoe -echok 115200

After this you can realize a simple input and output mirroring on this serial interface:

    > cat < /dev/ttySTM2 > /dev/ttySTM2

### RS485

If your hardware features a RS485 port, it is usually initialized by the driver and can be used in your application right away, just the same as you would use any other serial interface. The DE-Signal for the RS485-Transceiver is handled by the driver.

Important

RS485 is a bus and supports mostly only half duplex data transfer. This means only one parcitipant on the bus can send data at the same time! So when the master sends data on the bus the slave device must wait until all data from the slave is sent. Only then the slave is allowed to send its response.

### USB

#### USB host

The USB host ports can be used to attach common USB devices like thumbdrives, keyboards, etc. Please note, that some device drivers might need to be enabled in the kernel config first, before those devices work correctly. Using USB storage devices is also possible in the bootloader.

#### USB OTG

A USB OTG port can be used as an additional host interface, or as USB device. If the hardware supports it, it can be switched to OTG mode to provide host or device functionality depending on the connected device.
The mode for the OTG port is defined in the devicetree.

## Network interfaces

### Ethernet

All STM32MP1 SOCs have an internal ethernet controller. On most SoMs this port is connected to an external PHY which is located on the SoM. SoMs without integrated PHY provide a RMII interface. See your hardware description for details. The SOC internal interface is available on eth0 by default and it can also be used in the bootloader (e.g. for network booting). Thruput measurements can be done with the `iperf3` tool.

On the server side (e.g. PC)

    > iperf3 -s

On the device side e.g.

    > iperf3 -c 10.255.255.1

### CAN bus

If your hardware features a CAN port and it is correctly setup in the devicetree, you can use it in Linux by installing the packages and `can-utils`.
If the Packages are installed you can set up the interface by using the command:

    > ip link set can0 up type can bitrate 1000000 berr-reporting on

This configuration shows a can interface with 1MBit/s speed. The device can also use CAN-FD. For this the configuration of the interface changes a little bit (using 4MBit/s in fd mode):

    > ip link set can0 up type can bitrate 1000000 dbitrate 4000000 fd on

Afterwars you'll see the interface `can0`listed when calling `ifconfig` without parameter.

Important

The communication parameters for a CAN bus interface are not limited to the appropriate baudrate! For reliable communication, especially in bigger CAN networks or different CAN participants, some more parameters besides the baudrate should be set for your configuration! Use the `ip` tool to set and get these parameters.

Hint

For example CiA (CAN In Automation) provides proposals how to set up these parameters for a common interopatibility of different CAN nodes. See https://www.can-cia.org/groups/specifications for further information.

To get the currently used parameters and statistics of the can interface use

    > ip -det -stat link show can0
    2: can0: <NOARP,ECHO> mtu 16 qdisc noop state DOWN mode DEFAULT group default qlen 10
        link/can  promiscuity 0 minmtu 0 maxmtu 0
        can state STOPPED (berr-counter tx 0 rx 0) restart-ms 0
              m_can: tseg1 2..256 tseg2 2..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 24000000
              re-started bus-errors arbit-lost error-warn error-pass bus-off
                0          0          0          0          0          0         numtxqueues 1 numrxqueues 1 gso_max_size 65536 gso_max_segs 65535
        RX: bytes  packets  errors  dropped overrun mcast
        0          0        0       0       0       0
        TX: bytes  packets  errors  dropped carrier collsns
        0          0        0       0       0       0

Sending and receiving from the interface can be done with the commands `cansend` and `candump`.

To send a CAN 2.0 telegram on the previously configured bus use this:

    cansend can0 010#00.10.20.30.40.50.60.70

To send a CAN-FD frame use:

    cansend can0 010##0.00.11.22.33.44.55.66.77.88.99.AA.BB.CC.DD.EE.FF

When you want to use the CAN-FD baudrate switch, the flags field must be set to '1' (or a combination with other flags):

    cansend can0 010##1.00.11.22.33.44.55.66.77.88.99.AA.BB.CC.DD.EE.FF

To receive from the can interface:

    candump can0

Hint

There are two packages of can tools available: `canutils` and `can-utils`. The commands above are for the package `can-utils`. The syntax for tools from `canutils` package may vary. Because `can-utils` seems to be the more modern package, it is the default in newer BSP releases.

## Display interfaces

In general there are two possible interfaces to connect a display to a Kontron STM32MP1 SOMs: RGB and DSI. Only one interface can be used once a time.

Depending on the kernel and bootloader settings, the display interfaces are mapped to framebuffer devices (`/dev/fb0`)

To test the display without running an application you can first enable it:

    > echo 0 > /sys/class/graphics/fb0/blank

and then write some random data to the display to get colored pixels:

    > dd if=/dev/urandom of=/dev/fb0

The display interfaces are configured in the devicetree for linux.

### Backlight brightness

To change the screen backlight the backlight file in sysfs has to be modified. Dependend on your hardware this could be `/sys/class/backlight/backlight/brightness`. Values from zero (maximal brightness) to seven (dark) are valid.
In the following example the backlight will be first set to dark and afterwards changed to maximal brightness.

    > echo 7 > /sys/class/backlight/backlight/brightness
    # dark
    > echo 0 > /sys/class/backlight/backlight/brightness
    # maximal brightness

It should be mentioned, that the settings need to be saved as ASCII string into the file. If the file will not be closed after writing the values, the separate strings of the set brightness have to end with a newline (`\n`).

## Touch devices

Kontron offers different display solutions with different touch panels. Depending on the setup, there's usually a touch controller connected to the SOC via I²C or USB.

The `evtest` program can be used to test wheter the touch device works. When you touch on your device `evtest` will print out the event information.

## Storage

### NAND flash

The NAND flash chip usually contains the filesystems including devicetrees and kernel image. Dependent on your configuration the filesystems 'bootfs', 'rootfs' and 'userfs' are available.

### NOR flash

The NOR flash chip usually contains the tf-a loader (fsbl) U-Boot bootloader(ssbl) and the U-Boot environment.

### SD card

Most Kontron boards feature an onboard micro SD card slot. The SD card can be used as boot device, or as general file storage. Please note, that depending on what card you use, there are limitations on the write cycles and general durability of the card. For a longer lifespan, especially in applications with heavy SD card usage, we recommend to not use commercial grade, but industrial grade cards.

### eMMC

Some Kontron boards have an onboard eMMC chip instead of or additional to the NAND flash. eMMC can be used the same way as a normal SD card.

## GPIOs

For gpios there are two interfaces in the linux kernel:

- the deprecated sysfs interface or
- the newer libgpiod interface

### Sysfs interface

Warning

Sysfs interface for GPIOs is deprecated! It will be removed in a future Linux kernel version! Use the 'libgpiod' interface instead!

Before using the GPIOs with sysfs they have to be exported. See your hardware description which GPIO number you have to use.

To export GPIO507, wich is the digital out dout1 on STM32MP157 Demo-Kit:

    > echo 507 > /sys/class/gpio/export

The configuration as input or output or both takes place in the devicetree.
To read an input you can do:

    echo in > /sys/class/gpio/gpio507/direction
    cat /sys/class/gpio/gpio507/value

To set an output you can do:

    echo out > /sys/class/gpio/gpio507/direction
    echo 1 > /sys/class/gpio/gpio507/value
    0

### libgpiod interface

With libgpiod and its tools it is also possible to set and read gpio lines. Only gpios which aren't already claimed by drivers can be used. This is also true for gpios exported via sysfs interface.

The following example shows the usage of GPIO507 (gpiochip8.3), wich is the digital out dout1 on STM32MP157 eval kit:

How to show the configuration of a gpio:

    > gpioinfo gpiochip8
    gpiochip8 - 8 lines:
            line   0:      unnamed       unused   input  active-high
            line   1:      unnamed       unused   input  active-high
            line   2:      unnamed       unused   input  active-high
            line   3:      unnamed       unused   input  active-high
            line   4:      unnamed       unused   input  active-high
            line   5:      unnamed       unused   input  active-high
            line   6:      unnamed       "LED3"  output   active-low [used]
            line   7:      unnamed      "reset"   input  active-high [used]

Read as input:

    > gpioget gpiochip8 3
    0

and set as output:

    > gpioset gpiochip8 3=1

Hint

Reading back digital output pin gpiochip8.3 on the STM32MP1 Demo-Kit always reads 0 due to the hardware design, regardless whether it was previously set to a different value. The reason for this is that this gpio is configured as input and reads back the real value on the pin.

For more information see libgpiod git repository

## RTC

The STM32MP1 has an internal RTC for timekeeping. Due to the chip technology this RTC is more power consuming as dedicated RTC chips.

For optimal power consumption an external RTC should be used.

### Using the rtc

The RTC can be accessed via the hwclock command (see Linux documentation for further information).

To perform synchronisations of system time and RTC manually, you can use `hwclock`:

RTC to system time:

    > hwclock --hctosys

system time to RTC:

    > hwclock --systohc

## Audio

To list all soundcards you can use the following command:

    > cat /proc/asound/cards
     0 [WM8510         ]: WM8510 - WM8510
                          WM8510

To test your soundcard you can use the command `speaker-test`:

    speaker-test -t sine -f 1000

### PWM beeper

The STM32MP157 Demo-Kit features a PWM controlled beeper. It is registered in evdev and can be controlled via the userspace tool `beep`, by sending a `BEL` character to the console (`echo -e "\a" > /dev/tty0`), or by using `ioctl("/dev/input/eventX",KIOCSOUND,<tone>)`