Finding the name of the USART handle

[OIp.1]

Hi. I am going through the STM32 Step by Step instructions, as well as going through the "Description of STM32F7 HAL and low-layer drivers" manual. I am using the STM32756-EVAL board so I have made some appropriate changes based on the pins and ports used.

One of the functions from the instructions page is to transmit a message through UART.

HAL_UART_Transmit(&huart2,Test,sizeof(Test),10);

This function, based on my reading of the HAL manual, has the following inputs.

> UART_HandleTypeDef * huart, uint8_t * pTxData, uint16_t Size, uint32_t Timeout

In the example, we are provided with the input text for huartx to be called. But I am wondering where, in the HAL manual, can the input for huart be found, as I have not been able to find where, in the HAL manual or otherwise, it is given that the UART handle should be "huartx".

Please let me know if more information is required.

[LCE]

I don't really get the question.

A UART handle is a structure with all the relevant variables and pointers to work with the UART, usually the structure is defined in the corresponding HAL header file.

There should be a declaration of huart2 somewhere in the usart/uart.c file, it should look like this:

UART_HandleTypeDef huart2;

But you could also call it "Sam"...

[OIp.1]

Thank you for your time and patience. I am very fresh to STM32 so there are many concepts that still elude me.

So, the UART handle is not defined in the HAL Driver alongside the macros, but in the HAL header file? When you said "There should be a declaration of huart2 somewhere in the usart/uart.c file", is this file somewhere in the core files or is this part of the drivers? I'm assuming it's the former since the drivers have a distinct naming convention.

Also, what are some other official ST released manuals to learn about handles? I am trying to learn these concepts relying primarily on ST manuals since I'd like to locate the useful manuals as quickly as possible.

[Tesla DeLorean]

Think of it as an instance / object passed by address.

The structure is defined in the relevant HAL include file.

You create the instance in YOUR code, and you pass the pointer to the initialization, and assort HAL functions.

You create an instance for each UART you use as they function independently.

The use of these "handles" is not unique to ST / STM32

Win32 uses something very similar, but there it dynamically allocates the memory, ie CreateFile(), and passes you a "pointer", where as here you statically allocate them, typically, and use them throughout your application.

[OIp.1]

Thank you very much.

So, the handle (which can be imagined to be like an instance), is created in my code. Since I do not recall having to personally write the code (plus the answers of other commenters), I assume this element of the code was created by STM32CubeMX? If it is, is there any official documentation on how STM32CubeMX names these handles? If the code wasn't created by STM32CubeMX, how is the code written and is there any official documentation on how the handles are named?

Again, thank you very much for your time and patience and please let me know if more information is required.

[Pavel A.]

The microcontroller has several UARTs. Some of them are called UARTs, some - USARTs and some LPUARTs. Which one (or more) of them will you use depends on your design.

The Cube-generated code creates the "handle" structures for each enabled U(S)ART. All they are called "huartN" where N is the same number as of the U(S)ART. (note that the numbers are unique among them all, for example there cannot be UART1 and USART1).

So what should you use in your code?

Very simple. Define a pointer that points to the used instance, give it a meaningful name, for example "terminal_uart". Use that. Bingo.

UART_HandleTypeDef * const terminal_uart = &huart2;

or maybe use a define:

#define terminal_uart (&huart2)

[OIp.1]

Thank you very much. So, the cube generated code creates the handle structures; is there any official documentation on the naming convention? I have not yet found the manual which explains the naming convention; not only for UART but for many other features too such as ADC or general GPIOs.

Again, thank you very much for your time and patience and please let me know if more information is required.

[unsigned_char_array]

STM32CubeMX creates these handles for peripherals that use HAL(it won't if you select LL for that peripheral in advanced settings).

These are just structs with the instance pointer (pointer to the peripheral registers), some state variables(such as transmit buffer counters for USART) and optionally callback pointers.

If you want to use these handles in other files you need to declare them extern in a header file.

If you want to make some type of object (in C or C++) you can send a pointer to a handle to your object as a form of dependency injection so your object (such as a communication driver) is connected to a specific UART or other peripheral. In that case your code doesn't need to know the name of the handle. It only needs to be binded in one place, such as an init function.

[OIp.1]

So, handles can be seen as structs that CubeMX builds. Thank you very much.

Where in the code is this handle definition code usually found? And is there any official documentation on the naming convention? I have yet to find manuals which explains the naming convention for these features such as UART or ADC or general GPIOs.

Again, thanks for your answer, and please let me know if more info is required.

[unsigned_char_array]

In STM32CubeMX you can check under Project Manager/Code Generrator/Generated files: "Generate peripheral initialization as a pair of '.c/.h' files per peripheral". Then each peripheral will have a separate C file such as adc.c. In this C file you will see the handles declared as globals. The names start with "h", such as "hadc1" for the handle for ADC1. Unfortunately STM32CubeMX doesn't declare them as extern in the header files, but you can easily do that yourself in the user section of the header file.