Zpal-uart

Defines a platform abstraction layer for the Z-Wave UART. More...

Collaboration diagram for Zpal-uart:

Data Structures
struct	zpal_uart_config_t
	UART configuration. More...

Macros
#define	ZPAL_UART_CONFIG_FLAG_BLOCKING   (1 << 1)

Typedefs
typedef void *	zpal_uart_handle_t
	UART handle type.
typedef void(*	zpal_uart_receive_callback_t) (zpal_uart_handle_t handle, size_t length)
	Defines a type for the UART receive callback that is invoked whenever data is ready.
typedef void(*	zpal_uart_transmit_done_t) (zpal_uart_handle_t handle)
	Defines a type for the UART transmit done callback that is invoked when data has been transmitted.

Enumerations
enum	zpal_uart_id_t {   ZPAL_UART0 = 0 ,   ZPAL_UART1 ,   ZPAL_UART2 }
	IDs for each of the UARTs. More...
enum	zpal_uart_parity_bit_t {   ZPAL_UART_NO_PARITY ,   ZPAL_UART_EVEN_PARITY ,   ZPAL_UART_ODD_PARITY }
	IDs for each of the parity mode. More...
enum	zpal_uart_stop_bits_t {   ZPAL_UART_STOP_BITS_0P5 ,   ZPAL_UART_STOP_BITS_1 ,   ZPAL_UART_STOP_BITS_1P5 ,   ZPAL_UART_STOP_BITS_2 }
	IDs for each of the stop bits configuration. More...

Functions
zpal_status_t	zpal_uart_init (const zpal_uart_config_t *config, zpal_uart_handle_t *handle)
	Initializes a UART based on the given configuration.
zpal_status_t	zpal_uart_enable (zpal_uart_handle_t handle)
	Enables a given UART.
zpal_status_t	zpal_uart_disable (zpal_uart_handle_t handle)
	Disables a given UART.
zpal_status_t	zpal_uart_transmit (zpal_uart_handle_t handle, const uint8_t *data, size_t length, zpal_uart_transmit_done_t tx_cb)
	Transmits data using a given UART.
bool	zpal_uart_transmit_in_progress (zpal_uart_handle_t handle)
	Returns whether transmission is in progress.
size_t	zpal_uart_get_available (zpal_uart_handle_t handle)
	Get the number of bytes ready for reading.
size_t	zpal_uart_receive (zpal_uart_handle_t handle, uint8_t *data, size_t length)
	Receive available data into buffer using a given UART.

Detailed Description

Defines a platform abstraction layer for the Z-Wave UART.

How to use the UART API

The ZPAL UART API is used by only SerialAPI application, all functions are required.

The following outlines an example of use:

1. To initialize UART interface, invoke zpal_uart_init().
2. Enable UART by invoking zpal_uart_enable().
3. Invoke zpal_uart_transmit() to send data.
4. Use zpal_uart_transmit_in_progress() to check if transmission is in progress.
5. To get number of bytes available for reading, invoke zpal_uart_get_available().
6. Read received data with zpal_uart_receive().

Requirements:

• This interface must implement a non-blocking behavior.
• Transmit and receive buffers are provided by application.
• Transmit and receive buffers should be at least 200 bytes large.

Macro Definition Documentation

ZPAL_UART_CONFIG_FLAG_BLOCKING

#define ZPAL_UART_CONFIG_FLAG_BLOCKING   (1 << 1)

Set this flag in the configuration if the UART must be configured as a blocking UART.

Example of use:

zpal_uart_config_t config = {
  .flags = ZPAL_UART_CONFIG_FLAG_BLOCKING
}

Typedef Documentation

zpal_uart_handle_t

typedef void* zpal_uart_handle_t

UART handle type.

zpal_uart_receive_callback_t

typedef void(* zpal_uart_receive_callback_t) (zpal_uart_handle_t handle, size_t length)

Defines a type for the UART receive callback that is invoked whenever data is ready.

Parameters

[in]	handle	UART handle.
[in]	length	Length of available data in bytes.

zpal_uart_transmit_done_t

typedef void(* zpal_uart_transmit_done_t) (zpal_uart_handle_t handle)

Defines a type for the UART transmit done callback that is invoked when data has been transmitted.

Parameters

[in]

handle

UART handle.

Enumeration Type Documentation

zpal_uart_id_t

enum zpal_uart_id_t

IDs for each of the UARTs.

Enumerator
ZPAL_UART0	ID of UART 0.
ZPAL_UART1	ID of UART 1.
ZPAL_UART2	ID of UART 2.

zpal_uart_parity_bit_t

enum zpal_uart_parity_bit_t

IDs for each of the parity mode.

Enumerator
ZPAL_UART_NO_PARITY	No parity.
ZPAL_UART_EVEN_PARITY	Even parity.
ZPAL_UART_ODD_PARITY	Odd parity.

zpal_uart_stop_bits_t

enum zpal_uart_stop_bits_t

IDs for each of the stop bits configuration.

Enumerator
ZPAL_UART_STOP_BITS_0P5	0.5 stop bits.
ZPAL_UART_STOP_BITS_1	1 stop bits.
ZPAL_UART_STOP_BITS_1P5	1.5 stop bits.
ZPAL_UART_STOP_BITS_2	2 stop bits.

Function Documentation

zpal_uart_disable()

zpal_status_t zpal_uart_disable

(

zpal_uart_handle_t

handle

)

Disables a given UART.

Parameters

[in]

handle

UART handle.

Returns

ZPAL_STATUS_OK on success and ZPAL_STATUS_FAIL otherwise.

zpal_uart_enable()

zpal_status_t zpal_uart_enable

(

zpal_uart_handle_t

handle

)

Enables a given UART.

Parameters

[in]

handle

UART handle.

Returns

ZPAL_STATUS_OK on success and ZPAL_STATUS_FAIL otherwise.

zpal_uart_get_available()

size_t zpal_uart_get_available

(

zpal_uart_handle_t

handle

)

Get the number of bytes ready for reading.

Parameters

[in]

handle

UART handle.

Returns

Number of bytes in the receive buffer available for reading with zpal_uart_receive

zpal_uart_init()

zpal_status_t zpal_uart_init	(	const zpal_uart_config_t *	config,
		zpal_uart_handle_t *	handle )

Initializes a UART based on the given configuration.

Parameters

[in]	config	Pointer to UART configuration.
[out]	handle	Outputs a handle to a UART.

Returns

ZPAL_STATUS_OK on success and ZPAL_STATUS_FAIL otherwise.

zpal_uart_receive()

size_t zpal_uart_receive	(	zpal_uart_handle_t	handle,
		uint8_t *	data,
		size_t	length )

Receive available data into buffer using a given UART.

Parameters

[in]	handle	UART handle.
[out]	data	The data buffer to receive into
[in]	length	the maximum number of bytes we'd like to read

Returns

Number of bytes received into buffer

zpal_uart_transmit()

zpal_status_t zpal_uart_transmit	(	zpal_uart_handle_t	handle,
		const uint8_t *	data,
		size_t	length,
		zpal_uart_transmit_done_t	tx_cb )

Transmits data using a given UART.

Parameters

[in]	handle	UART handle.
[in]	data	Pointer to data.
[in]	length	Length of data.
[in]	tx_cb	Transmission done callback.

Returns

ZPAL_STATUS_OK if transmission has started, ZPAL_STATUS_FAIL otherwise.

Note

Expect tx_cb callback to be invoked in interrupt context.

This function will block if length of data exceeds internal transmit buffer.

zpal_uart_transmit_in_progress()

bool zpal_uart_transmit_in_progress

(

zpal_uart_handle_t

handle

)

Returns whether transmission is in progress.

Parameters

[in]

handle

UART handle.

Returns

True if transmission is in progress, false otherwise.