STM32duino III. – How to use Serial (USART)
STM32duino Wiki
Welcome to the stm32duino wiki!
API HardwareSerial
PlatformIO
How to use stm32duino build_opt.h in PlatformIO?
How to use stm32duino (official STM32 core) build_opt.h in PlatformIO
Include header files using command line option?
build_flags =
-DENABLE_HWSERIAL3
-DPIN_SERIAL3_RX=PB11
-DPIN_SERIAL3_TX=PB10
or
build_flags =
-include build_opt.h
Variant
ldscript.ld PeripheralPins.c PinNamesVar.h variant.cpp variant.h
#define PC5 0 #define PC4 1 #define PA10 2 [...]
HAL_ADC_MODULE_ENABLED HAL_DAC_MODULE_ENABLED HAL_I2C_MODULE_ENABLED HAL_TIM_MODULE_ENABLED HAL_UART_MODULE_ENABLED HAL_SPI_MODULE_ENABLED
WEAK const PinMap PinMap_UART_TX[] = {
[...]
{PA_5, USART3, STM_PIN_DATA(STM_MODE_AF_PP, GPIO_PULLUP, GPIO_AF4_USART3)},
{PB_2, USART3, STM_PIN_DATA(STM_MODE_AF_PP, GPIO_PULLUP, GPIO_AF4_USART3)},
[...]
^ ^
| |
STM_MODE_INPUT GPIO_NOPULL
STM_MODE_OUTPUT_PP GPIO_PULLUP
STM_MODE_OUTPUT_OD GPIO_PULLDOWN
STM_MODE_ANALOG
STM_MODE_AF_OD => Alternate Function, Open-Drain
STM_MODE_AF_PP => Alternate Function, Push-Pull
#define STM_PIN_DATA(FUNC_OD, PUPD, AFNUM) \
STM_PIN_DEFINE(FUNC_OD, PUPD, AFNUM)
#define STM_PIN_DATA_EXT(FUNC_OD, PUPD, AFNUM, CHANNEL, INVERTED) \
STM_PIN_DEFINE_EXT(FUNC_OD, PUPD, AFNUM, CHANNEL, INVERTED)
Digital
Arduino_Core_STM32—pinMode() implementation analysis
void pinMode(uint32_t ulPin, uint32_t ulMode)
{
PinName p = digitalPinToPinName(ulPin);
if (p != NC) {
[...]
switch (ulMode) {
case INPUT: /* INPUT_FLOATING */
pin_function(p, STM_PIN_DATA(STM_MODE_INPUT, GPIO_NOPULL, 0));
break;
case INPUT_PULLUP:
pin_function(p, STM_PIN_DATA(STM_MODE_INPUT, GPIO_PULLUP, 0));
break;
case INPUT_PULLDOWN:
pin_function(p, STM_PIN_DATA(STM_MODE_INPUT, GPIO_PULLDOWN, 0));
break;
[...]
}
}
}
PinMap_UART_TX
typedef struct {
PinName pin;
void *peripheral;
int function;
} PinMap;
typedef enum {
// Not connected
NC = (int)0xFFFFFFFF,
// Pin name definition
PA_0 = (PortA << 4) + 0x00,
[...]
// Specific pin name define in the variant
#include "PinNamesVar.h"
P_END = NC
} PinName;
extern GPIO_TypeDef *GPIOPort[];
typedef enum {
FirstPort = 0x00,
PortA = FirstPort,
PortB,
#if defined GPIOC_BASE
PortC,
#endif
[...]
PortEND,
LastPort = PortEND - 1
} PortName;
#define MAX_NB_PORT (LastPort-FirstPort+1)
extern const PinName digitalPin[];
extern const uint32_t analogInputPin[];
[...]
#define digitalPinToPinName(p) (((uint32_t)p < NUM_DIGITAL_PINS) ? digitalPin[p] : \
((uint32_t)p >= NUM_ANALOG_FIRST) && ((uint32_t)p <= NUM_ANALOG_LAST) ? \
digitalPin[analogInputPin[p-NUM_ANALOG_FIRST]] : NC)
STM_PIN_DATA()STM_PIN_DATA_EXT()pin_in_pinmap()bool pin_in_pinmap(PinName pin, const PinMap *map)
Looppinmap_peripheral()void *pinmap_peripheral(PinName pin, const PinMap *map)pinmap_pinout()void pinmap_pinout(PinName pin, const PinMap *map)pinmap_pin()PinName pinmap_pin(void *peripheral, const PinMap *map)
./cores/arduino/pins_arduino.h: pin_in_pinmap(digitalPinToPinName(p), PinMap_UART_TX)) ./cores/arduino/stm32/PeripheralPins.h: extern const PinMap PinMap_UART_TX[]; ./libraries/SrcWrapper/src/stm32/uart.c: #define DEBUG_UART pinmap_peripheral(digitalPinToPinName(PIN_SERIAL_TX), PinMap_UART_TX) ./libraries/SrcWrapper/src/stm32/uart.c: USART_TypeDef *uart_tx = pinmap_peripheral(obj->pin_tx, PinMap_UART_TX); ./libraries/SrcWrapper/src/stm32/uart.c: pinmap_pinout(obj->pin_tx, PinMap_UART_TX); ./libraries/SrcWrapper/src/stm32/uart.c: serial_debug.pin_tx = pinmap_pin(DEBUG_UART, PinMap_UART_TX);
Serial3
HAVE_HWSERIAL3ENABLE_HWSERIAL3SERIAL_UART_INSTANCE
[...] extern HardwareSerial Serial3; extern HardwareSerial Serial4; [...]
[...]
#if defined(HAVE_HWSERIAL3)
HardwareSerial Serial3(USART3);
void serialEvent3() __attribute__((weak));
#endif
#if defined(HAVE_HWSERIAL4)
#if defined(USART4)
HardwareSerial Serial4(USART4);
#else
HardwareSerial Serial4(UART4);
#endif
void serialEvent4() __attribute__((weak));
#endif
[...]
// Constructors ////////////////////////////////////////////////////////////////
/* ex. PA0 from #define in variant.h */
HardwareSerial::HardwareSerial(uint32_t _rx, uint32_t _tx)
{
init(digitalPinToPinName(_rx), digitalPinToPinName(_tx));
}
/* ex. PA_0 from enum PinName in PinNames.h*/
HardwareSerial::HardwareSerial(PinName _rx, PinName _tx)
{
init(_rx, _tx);
}
[...]
void HardwareSerial::init(PinName _rx, PinName _tx)
{
[...]
}
[...]
#if defined(ENABLE_HWSERIAL3)
#if defined(USART3_BASE)
#define HAVE_HWSERIAL3
#endif
#endif
#if defined(ENABLE_HWSERIAL4)
#if defined(USART4_BASE) || defined(UART4_BASE)
#define HAVE_HWSERIAL4
#endif
#endif
[...]
WEAK void serialEventRun(void)
{
[...]
#if defined(HAVE_HWSERIAL3)
if (serialEvent3 && Serial3.available()) {
serialEvent3();
}
#endif
#if defined(HAVE_HWSERIAL4)
if (serialEvent4 && Serial4.available()) {
serialEvent4();
}
#endif
[...]
}
Callstack
size_t HardwareSerial::write(uint8_t c)
{
[...]
if (!serial_tx_active(&_serial)) {
uart_attach_tx_callback(&_serial, _tx_complete_irq);
}
[...]
}
int HardwareSerial::_tx_complete_irq(serial_t *obj)
{
// If interrupts are enabled, there must be more data in the output
// buffer. Send the next byte
obj->tx_tail = (obj->tx_tail + 1) % SERIAL_TX_BUFFER_SIZE;
if (obj->tx_head == obj->tx_tail) {
return -1;
}
return 0;
}
typedef struct serial_s serial_t;
struct serial_s {
/* The 1st 2 members USART_TypeDef *uart
* and UART_HandleTypeDef handle should
* be kept as the first members of this struct
* to have get_serial_obj() function work as expected
*/
USART_TypeDef *uart;
UART_HandleTypeDef handle;
void (*rx_callback)(serial_t *);
int (*tx_callback)(serial_t *);
PinName pin_tx;
PinName pin_rx;
IRQn_Type irq;
uint8_t index;
uint8_t recv;
uint8_t *rx_buff;
uint8_t *tx_buff;
uint16_t rx_tail;
uint16_t tx_head;
volatile uint16_t rx_head;
volatile uint16_t tx_tail;
};
/**
* Begin asynchronous TX transfer.
*
* @param obj : pointer to serial_t structure
* @param callback : function call at the end of transmission
* @retval none
*/
void uart_attach_tx_callback(serial_t *obj, int (*callback)(serial_t *))
{
if (obj == NULL) {
return;
}
obj->tx_callback = callback;
/* Must disable interrupt to prevent handle lock contention */
HAL_NVIC_DisableIRQ(obj->irq);
/* The following function will enable UART_IT_TXE and error interrupts */
HAL_UART_Transmit_IT(uart_handlers[obj->index], &obj->tx_buff[obj->tx_tail], 1);
/* Enable interrupt */
HAL_NVIC_SetPriority(obj->irq, UART_IRQ_PRIO, UART_IRQ_SUBPRIO);
HAL_NVIC_EnableIRQ(obj->irq);
}
/**
* @brief Tx Transfer completed callback
* @param UartHandle pointer on the uart reference
* @retval None
*/
void HAL_UART_TxCpltCallback(UART_HandleTypeDef *huart)
{
serial_t *obj = get_serial_obj(huart);
if (obj && obj->tx_callback(obj) != -1) {
if (HAL_UART_Transmit_IT(huart, &obj->tx_buff[obj->tx_tail], 1) != HAL_OK) {
return;
}
}
}