uart.h File Reference

Header for uart module. More...

#include <stdbool.h>
#include "stm32_def.h"
#include "PinNames.h"

Classes
struct	serial_s
	Serial (U(S)ART) object. More...

Macros
#define	UART_IRQ_PRIO   1
	Default UART IRQ pre-emption priority.
#define	UART_IRQ_SUBPRIO   0
	Default UART IRQ sub-priority.
#define	TX_TIMEOUT   1000
	Transmission timeout in ms.
#define	RCC_USART1CLKSOURCE_HSI   RCC_USART1CLKSOURCE_HSIKER

Typedefs
typedef struct serial_s	serial_t

Functions
bool	uart_init (serial_t *obj, uint32_t baudrate, uint32_t databits, uint32_t parity, uint32_t stopbits, bool rx_invert, bool tx_invert, bool data_invert)
	Initialize the UART interface.
void	uart_deinit (serial_t *obj)
	Deinitialize the UART interface: reset the peripheral and disable its clock.
int	uart_getc (serial_t *obj, unsigned char *c)
	Configure the UART interface for low power operation: select HSI (LSE on STM32WB0x) as the source clock of the low power wakeup and enable the wakeup EXTI line when available.
void	uart_attach_rx_callback (serial_t *obj, void(*callback)(serial_t *))
	Begin an asynchronous RX transfer (enable interrupt for data collecting).
void	uart_attach_tx_callback (serial_t *obj, int(*callback)(serial_t *), size_t size)
	Begin an asynchronous TX transfer (enable interrupt for data sending).
uint8_t	serial_tx_active (serial_t *obj)
	Determine if the serial peripheral is already in use for TX.
uint8_t	serial_rx_active (serial_t *obj)
	Determine if the serial peripheral is already in use for RX.
void	uart_enable_tx (serial_t *obj)
	Enable the transmitter for half-duplex mode (when pin_rx is NC).
void	uart_enable_rx (serial_t *obj)
	Enable the receiver for half-duplex mode (when pin_rx is NC).
size_t	uart_debug_write (uint8_t *data, uint32_t size)
	Write data on the UART, used by printf for debug only (syscalls).

Detailed Description

Header for uart module.

Author

WI6LABS, fpistm

Attention

© COPYRIGHT(c) 2016 STMicroelectronics

Redistribution and use in source and binary forms, with or without modification, are permitted provided that the following conditions are met:

1. Redistributions of source code must retain the above copyright notice, this list of conditions and the following disclaimer.
2. Redistributions in binary form must reproduce the above copyright notice, this list of conditions and the following disclaimer in the documentation and/or other materials provided with the distribution.
3. Neither the name of STMicroelectronics nor the names of its contributors may be used to endorse or promote products derived from this software without specific prior written permission.

THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS" AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.

Function Documentation

serial_rx_active()

uint8_t serial_rx_active

(

serial_t *

obj

)

Determine if the serial peripheral is already in use for RX.

Parameters

obj	The serial object.

Returns

Non-zero if the RX transaction is ongoing, 0 otherwise.

serial_tx_active()

uint8_t serial_tx_active

(

serial_t *

obj

)

Determine if the serial peripheral is already in use for TX.

Parameters

obj	The serial object.

Returns

Non-zero if the TX transaction is ongoing, 0 otherwise.

uart_attach_rx_callback()

void uart_attach_rx_callback	(	serial_t *	obj,
		void(*)(serial_t *)	callback
	)

Begin an asynchronous RX transfer (enable interrupt for data collecting).

Does nothing if obj is NULL or a reception is already ongoing.

Parameters

obj	Pointer to serial_t structure.
callback	Function called at the end of reception.

uart_attach_tx_callback()

void uart_attach_tx_callback	(	serial_t *	obj,
		int(*)(serial_t *)	callback,
		size_t	size
	)

Begin an asynchronous TX transfer (enable interrupt for data sending).

Parameters

obj	Pointer to serial_t structure.
callback	Function called at the end of transmission.
size	Number of bytes to transmit, starting at the tx_tail index of the TX buffer.

uart_debug_write()

size_t uart_debug_write	(	uint8_t *	data,
		uint32_t	size
	)

Write data on the UART, used by printf for debug only (syscalls).

The debug UART (DEBUG_UART) is initialized on first use if no Serial instance already uses it.

Parameters

data	Bytes to write.
size	Number of bytes to write.

Returns

The number of bytes written, 0 on error or timeout (TX_TIMEOUT).

uart_deinit()

void uart_deinit

(

serial_t *

obj

)

Deinitialize the UART interface: reset the peripheral and disable its clock.

Parameters

obj	Pointer to serial_t structure.

uart_enable_rx()

void uart_enable_rx

(

serial_t *

obj

)

Enable the receiver for half-duplex mode (when pin_rx is NC).

No-op in full-duplex mode.

Parameters

obj	Pointer to serial_t structure.

uart_enable_tx()

void uart_enable_tx

(

serial_t *

obj

)

Enable the transmitter for half-duplex mode (when pin_rx is NC).

No-op in full-duplex mode.

Parameters

obj	Pointer to serial_t structure.

uart_getc()

int uart_getc	(	serial_t *	obj,
		unsigned char *	c
	)

Configure the UART interface for low power operation: select HSI (LSE on STM32WB0x) as the source clock of the low power wakeup and enable the wakeup EXTI line when available.

Parameters

obj	Pointer to serial_t structure.

Read the last received byte from the UART and restart the RX interrupt.

Parameters

obj	Pointer to serial_t structure.
c	Pointer where the received character is stored.

Returns

0 on success, -1 if obj is NULL or a reception is ongoing.

uart_init()

bool uart_init	(	serial_t *	obj,
		uint32_t	baudrate,
		uint32_t	databits,
		uint32_t	parity,
		uint32_t	stopbits,
		bool	rx_invert,
		bool	tx_invert,
		bool	data_invert
	)

Initialize the UART interface.

The U(S)ART peripheral is deduced from the pins set in obj (pin_tx, pin_rx, pin_rts, pin_cts). Swapped TX/RX pins are supported when the series allows it. If pin_rx is NC, the UART is configured in half-duplex mode.

Parameters

obj	Pointer to serial_t structure.
baudrate	Baud rate.
databits	Word length.
parity	Parity configuration.
stopbits	Number of stop bits.
rx_invert	Invert the RX line.
tx_invert	Invert the TX line.
data_invert	Invert the data bits.

Returns

true on success, false otherwise (obj is NULL, pins do not match the same U(S)ART peripheral or HAL initialization failed).