User interactions

The STM32Cube Software Examples are designed to illustrate the use of the STM32 in various application use-cases. STMicroelectronics does not provide ready-to-use product level applications, but a set of meaningful use-cases that can be used as a starting point for STM32 based applications. Each example is a minimalist implementation, yet functional. The objective is to provide the foundation to learn how to use the STM32 peripherals and software.

A user action is a specific task that the user performs to interact with the example. The examples are designed to offer the required user actions so that it is easy:

  • To trigger the required events, for instance by pressing a button.

  • To view the outcome of the scenario, for instance by observing the LEDs.

  • To follow the sequence of actions, for instance by observing the serial output.

  • To follow the execution flow of the example code, for instance by using a debugger.

  • To observe the signals on the pins of the STM32, for instance by using an oscilloscope.

Using the board parts

As the STM32Cube Software Examples are designed to operate across a number of STM32 boards, the user actions are implemented using the minimal set of board parts:

  • One user LED used as a status LED. It reports the execution status of the example.

  • One user button is used to trigger events.

User LED

By default, the user LED reports the execution status of the example. When a board offers multiple user LEDs, the example code uses:

  • Either the first one in the list.

  • Or gives preference to the green or blue LED over the red or orange LED.

The LED signals define the status of the board. The LED signals are defined in the following table.

LED behavior and system state

Example status

LED behavior and system state

Success

The LED remains turned on:

  • The example scenario is done

  • The device is alive, no more action needed

Error

The LED is flashing (50 ms on and 2 sec off):

  • The device is running an error handler code

  • The variables and STM32 states are not reset and can be read with a debugger

Fault

The LED is (tentatively) turned off:

  • The device is running a fault handler

  • The STM32 state is unknown as a system fault has been encountered

Note

The LED behavior can be different for some examples (for example hal_gpio_toggle). The specific LED behavior is documented in the README file of the example.

User button

The user button can be used with a short press or a long press, each of them triggering a different event.

The examples are written in a way that handles hardware rebounds properly. The possible cases are listed below:

  • The user button is debounced in hardware, by using a capacitor.

  • The user button is debounced in software, for example, by using a part driver.

  • The example code is not sensitive to rebounds, such as when the user button is used to trigger a one-shot event.

Using the pinout connections

When an example generates signals on pins, the pinout connections are used to show the signal. The exact pinout scheme is documented in the README file of the example.

The preference list for pins selection is by priority order:

  1. Arduino® UNO R3 connectors

  2. STM32 Zio connectors

  3. STM32 fanout connector

This means that the signals are evacuated on the Arduino® Uno V3 connectors whenever possible. An oscilloscope or a logical analyzer can be used to observe the signals on the pins of the STM32.

In addition, some examples output a clock signal on the MCO [1] pin. This pin can be connected to an oscilloscope or a logic analyzer to observe the system clock or a peripheral clock.

Using the console

Some examples generate application logs that are disabled by default. These logs can be enabled by setting the USE_TRACE compiler switch to 1.

Logs output

ST-LINK provides a virtual COM port interface allowing the host PC to communicate with the target STM32 through a UART. When enabled, logs are transmitted over the UART instance connected to the virtual COM port of the ST-LINK mounted on the STM32 board.

The management of this UART is done by the basic_stdio utility.

Terminal settings

A serial terminal emulator connected to the ST-LINK of the STM32 board is required to read the logs. We recommend using the Tera Term terminal emulator with these settings:

  • Set the serial terminal new-line transmit configuration to LineFeed (\n or LF) to allow copy-paste from UNIX® type text files.

  • The selection of the local echo option makes copy-paste results visible on the console.

  • Set the serial terminal new-line receive configuration to LineFeed (LF) or AUTO to ensure correct display of logs [2].

  • The serial port must be configured with the following settings:

    • COM port: COMx (where x is the number of the COM port assigned to the ST-LINK)

    • Baud rate: 115200

    • Data bits: 8

    • Parity: None

    • Stop bits: 1

    • Flow control: None

Using the debugger

The example IDE projects are designed for use with a debugger. The debug symbols are generated by default. The debugger can be used to:

  • Set breakpoints

  • Inspect variables

  • Step through the code.

Build profile

The example projects are delivered with an optimized profile by default:

  • The compiler optimizations are enabled.

  • The step-by-step debugging can be impeded by these optimizations in some situations.

To improve the step-by-step debugging experience, use a debug build profile. This build profile is not provided by default. Refer to Debug build profile for more information on how to create a debug build profile.

System variables

The variables declared in main.c are not required for the application use-case. All the examples provide the ExecStatus variable that reports the current execution status of the example. The volatile qualifier is set to this variable so that its content is always available in the debugger.