Zpal-uart#

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:

To initialize UART interface, invoke zpal_uart_init().
Enable UART by invoking zpal_uart_enable().
Invoke zpal_uart_transmit() to send data.
Use zpal_uart_transmit_in_progress() to check if transmission is in progress.
To get number of bytes available for reading, invoke zpal_uart_get_available().
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.

Modules#

zpal_uart_config_t

Enumerations#

enum

zpal_uart_id_t {

ZPAL_UART0

ZPAL_UART1

}

IDs for each of the UARTs.

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.

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.

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.

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.

Macros#

#define

ZPAL_UART_CONFIG_FLAG_BLOCKING (1 << 1)

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

Enumeration Documentation#

zpal_uart_id_t#

zpal_uart_id_t

IDs for each of the UARTs.

Enumerator
ZPAL_UART0
ZPAL_UART1

Definition at line 63 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_uart.h

zpal_uart_parity_bit_t#

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.

Definition at line 72 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_uart.h

zpal_uart_stop_bits_t#

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.

Definition at line 82 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_uart.h

Typedef Documentation#

zpal_uart_handle_t#

typedef void* zpal_uart_handle_t

UART handle type.

Definition at line 93 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_uart.h

zpal_uart_receive_callback_t#

typedef void(* zpal_uart_receive_callback_t) (zpal_uart_handle_t handle, size_t length) )(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.

Definition at line 101 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_uart.h

zpal_uart_transmit_done_t#

typedef void(* zpal_uart_transmit_done_t) (zpal_uart_handle_t handle) )(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.

Definition at line 108 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_uart.h

Function Documentation#

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.

Definition at line 135 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_uart.h

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.

Definition at line 143 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_uart.h

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.

Definition at line 151 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_uart.h

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.

Definition at line 166 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_uart.h

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.

Definition at line 175 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_uart.h

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

Definition at line 184 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_uart.h

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

Definition at line 194 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_uart.h

Macro Definition Documentation#

ZPAL_UART_CONFIG_FLAG_BLOCKING#

#define ZPAL_UART_CONFIG_FLAG_BLOCKING

Value:

(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
}

Definition at line 58 of file /mnt/raid/workspaces/ws.Mh9rMZz8x/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_uart.h