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:

  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.

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.T7KR5OZRo/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.T7KR5OZRo/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.T7KR5OZRo/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.T7KR5OZRo/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.T7KR5OZRo/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.T7KR5OZRo/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


Definition at line 135 of file /mnt/raid/workspaces/ws.T7KR5OZRo/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


Definition at line 143 of file /mnt/raid/workspaces/ws.T7KR5OZRo/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


Definition at line 151 of file /mnt/raid/workspaces/ws.T7KR5OZRo/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

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.T7KR5OZRo/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.T7KR5OZRo/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


Definition at line 184 of file /mnt/raid/workspaces/ws.T7KR5OZRo/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.T7KR5OZRo/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.T7KR5OZRo/overlay/gsdk/protocol/z-wave/PAL/inc/zpal_uart.h