Data Structures
struct	IotUARTConfig_t
	Configuration parameters for the UART. More...

Macros
#define	IOT_UART_BAUD_RATE_DEFAULT ( 115200 )
	The default baud rate for a given UART port.

#define	IOT_UART_SUCCESS ( 0 )
	Error codes returned by every function module in UART HAL. More...

#define	IOT_UART_INVALID_VALUE ( 1 )

#define	IOT_UART_WRITE_FAILED ( 2 )

#define	IOT_UART_READ_FAILED ( 3 )

#define	IOT_UART_BUSY ( 4 )

#define	IOT_UART_NOTHING_TO_CANCEL ( 5 )

#define	IOT_UART_FUNCTION_NOT_SUPPORTED ( 6 )

Typedefs
typedef void(*	IotUARTCallback_t) (IotUARTOperationStatus_t xStatus, void *pvUserContext)
	The callback function for completion of UART operation. More...

typedef struct IotUARTDescriptor_t *	IotUARTHandle_t
	IotUARTHandle_t is the handle type returned by calling iot_uart_open(). This is initialized in open and returned to caller. The caller must pass this pointer to the rest of APIs.

Enumerations
enum	IotUARTOperationStatus_t { eUartCompleted = IOT_UART_SUCCESS, eUartLastWriteFailed = IOT_UART_WRITE_FAILED, eUartLastReadFailed = IOT_UART_READ_FAILED }
	UART read/write operation status values. More...

enum	IotUARTParity_t { eUartParityNone, eUartParityOdd, eUartParityEven }
	UART parity mode. More...

enum	IotUARTStopBits_t { eUartStopBitsOne, eUartStopBitsTwo }
	UART stop bits. More...

enum	IotUARTIoctlRequest_t { eUartSetConfig, eUartGetConfig, eGetTxNoOfbytes, eGetRxNoOfbytes }
	Ioctl requests for UART HAL. More...

Functions
IotUARTHandle_t	iot_uart_open (int32_t lUartInstance)
	Initializes the UART peripheral of the board. More...

void	iot_uart_set_callback (IotUARTHandle_t const pxUartPeripheral, IotUARTCallback_t xCallback, void *pvUserContext)
	Sets the application callback to be called on completion of an operation. More...

int32_t	iot_uart_read_sync (IotUARTHandle_t const pxUartPeripheral, uint8_t *const pvBuffer, size_t xBytes)
	Starts receiving the data from UART synchronously. More...

int32_t	iot_uart_write_sync (IotUARTHandle_t const pxUartPeripheral, uint8_t *const pvBuffer, size_t xBytes)
	Starts the transmission of data from UART synchronously. More...

int32_t	iot_uart_read_async (IotUARTHandle_t const pxUartPeripheral, uint8_t *const pvBuffer, size_t xBytes)
	Starts receiving the data from UART asynchronously. More...

int32_t	iot_uart_write_async (IotUARTHandle_t const pxUartPeripheral, uint8_t *const pvBuffer, size_t xBytes)
	Starts the transmission of data from UART asynchronously. More...

int32_t	iot_uart_ioctl (IotUARTHandle_t const pxUartPeripheral, IotUARTIoctlRequest_t xUartRequest, void *const pvBuffer)
	Configures the UART port with user configuration. More...

int32_t	iot_uart_cancel (IotUARTHandle_t const pxUartPeripheral)
	Aborts the operation on the UART port if any underlying driver allows cancellation of the operation. More...

int32_t	iot_uart_close (IotUARTHandle_t const pxUartPeripheral)
	Stops the operation and de-initializes the UART peripheral. More...

Detailed Description

Macro Definition Documentation

◆ IOT_UART_SUCCESS

#define IOT_UART_SUCCESS ( 0 )

Error codes returned by every function module in UART HAL.

UART operation completed successfully.

◆ IOT_UART_INVALID_VALUE

#define IOT_UART_INVALID_VALUE ( 1 )

At least one parameter is invalid.

◆ IOT_UART_WRITE_FAILED

#define IOT_UART_WRITE_FAILED ( 2 )

UART driver returns error when performing write operation.

◆ IOT_UART_READ_FAILED

#define IOT_UART_READ_FAILED ( 3 )

UART driver returns error when performing read operation.

◆ IOT_UART_BUSY

#define IOT_UART_BUSY ( 4 )

UART bus is busy at current time.

◆ IOT_UART_NOTHING_TO_CANCEL

#define IOT_UART_NOTHING_TO_CANCEL ( 5 )

No ongoing operation when cancel is performed.

◆ IOT_UART_FUNCTION_NOT_SUPPORTED

#define IOT_UART_FUNCTION_NOT_SUPPORTED ( 6 )

UART operation is not supported.

Typedef Documentation

◆ IotUARTCallback_t

typedef void( * IotUARTCallback_t) (IotUARTOperationStatus_t xStatus, void *pvUserContext)

The callback function for completion of UART operation.

Parameters

[out]	xStatus	UART asynchronous operation status.
[in]	pvUserContext	User Context passed when setting the callback. This is not used or modified by the driver. The context is provided by the caller when setting the callback, and is passed back to the caller in the callback.

Enumeration Type Documentation

◆ IotUARTOperationStatus_t

enum IotUARTOperationStatus_t

UART read/write operation status values.

Enumerator
eUartCompleted	UART operation completed successfully.
eUartLastWriteFailed	UART driver returns error when performing write operation.
eUartLastReadFailed	UART driver returns error when performing read operation.

◆ IotUARTParity_t

enum IotUARTParity_t

UART parity mode.

Enumerator
eUartParityNone	UART parity as none.
eUartParityOdd	UART parity as odd.
eUartParityEven	UART parity as even.

◆ IotUARTStopBits_t

enum IotUARTStopBits_t

UART stop bits.

Enumerator
eUartStopBitsOne	UART stop bits is 1.
eUartStopBitsTwo	UART stop bits is 2.

◆ IotUARTIoctlRequest_t

enum IotUARTIoctlRequest_t

Ioctl requests for UART HAL.

Enumerator
eUartGetConfig	Sets the UART configuration according to .
eGetTxNoOfbytes	Gets the UART configuration according to .
eGetRxNoOfbytes	Get the number of bytes sent in write operation. Get the number of bytes received in read operation.

Function Documentation

◆ iot_uart_open()

IotUARTHandle_t iot_uart_open ( int32_t lUartInstance )

Initializes the UART peripheral of the board.

The application should call this function to initialize the desired UART port.

Warning: Once opened, the same UART instance must be closed before calling open again.

Parameters

[in] lUartInstance The instance of the UART port to initialize.

Returns

'the handle to the UART port (not NULL)', on success.
'NULL', if
- invalid instance number
- open same instance more than once before closing it

Example

   // These two buffers can contain 32 bytes for reading and writing.
   uint8_t cpBuffer[ 32 ] = { 0 };
   uint8_t cpBufferRead[ 32 ] = { 0 };
 
   IotUARTHandle_t xOpen;
   int32_t lRead, lWrite, lClose;
   BaseType_t xCallbackReturn;
   uint8_t ucPort = 1; /* Each UART peripheral will be assigned an integer.
 
*  xOpen = iot_uart_open( ucPort );
*  if( xOpen != NULL )
*  {
*      iot_uart_set_callback( xOpen, prvReadWriteCallback, NULL );
 
*      lWrite = iot_uart_write_async( xOpen, cpBuffer, testIotUART_READ_BUFFER_LENGTH );
*      // assert(IOT_UART_SUCCESS, lWrite)
*      // Wait for asynchronous write to complete
*      xCallbackReturn = xSemaphoreTake( ( SemaphoreHandle_t ) &xUartSemaphore, IotUART_DEFAULT_SEMPAHORE_DELAY );
*      // assert(xCallbackReturn, pdTrue)
 
*      lRead = iot_uart_read_async( xOpen, cpBufferRead, testIotUART_READ_BUFFER_LENGTH );
*      // assert(IOT_UART_SUCCESS, lRead)
 
*      // Wait for asynchronous read to complete
*      xCallbackReturn = xSemaphoreTake( ( SemaphoreHandle_t ) &xUartSemaphore, IotUART_DEFAULT_SEMPAHORE_DELAY );
*      // assert(xCallbackReturn, pdTrue)
*  }
 
*  lClose = iot_uart_close( xOpen );
*  // assert(IOT_UART_SUCCESS, lClose)
*  

◆ iot_uart_set_callback()

void iot_uart_set_callback	(	IotUARTHandle_t const	pxUartPeripheral,
		IotUARTCallback_t	xCallback,
		void *	pvUserContext
	)

Sets the application callback to be called on completion of an operation.

The callback is guaranteed to be invoked when the current asynchronous operation completes, either successful or failed. This simply provides a notification mechanism to user's application. It has no impact if the callback is not set.

Note: This callback will not be invoked when synchronous operation completes.; This callback is per handle. Each instance has its own callback.; Single callback is used for both read_async and write_async. Newly set callback overrides the one previously set.

Warning: If the input handle is invalid, this function silently takes no action.

Parameters

[in]	pxUartPeripheral	The peripheral handle returned in the open() call.
[in]	xCallback	The callback function to be called on completion of transaction (This can be NULL).
[in]	pvUserContext	The user context to be passed back when callback is called (This can be NULL).

◆ iot_uart_read_sync()

int32_t iot_uart_read_sync	(	IotUARTHandle_t const	pxUartPeripheral,
		uint8_t *const	pvBuffer,
		size_t	xBytes
	)

Starts receiving the data from UART synchronously.

This function attempts to read certain number of bytes from transmitter device to a pre-allocated buffer, in synchronous way. Partial read might happen, e.g. no more data is available. And the number of bytes that have been actually read can be obtained by calling iot_uart_ioctl.

Note: If the number of bytes is not known, it is recommended that the application reads one byte at a time.

Warning: None of other read or write functions shall be called during this function.

Parameters

[in]	pxUartPeripheral	The peripheral handle returned in the open() call.
[out]	pvBuffer	The buffer to store the received data.
[in]	xBytes	The number of bytes to read.

Returns

IOT_UART_SUCCESS on successful completion of synchronous read, else one of the IOT_UART_INVALID_VALUE, IOT_UART_BUSY, IOT_UART_READ_FAILED on error.

IOT_UART_SUCCESS, on success (all the requested bytes have been read)
IOT_UART_INVALID_VALUE, if
- pxUartPeripheral is NULL
- pxUartPeripheral is not opened yet
- pucBuffer is NULL
- xBytes is 0
IOT_UART_READ_FAILED, if there is unknown driver error
IOT_UART_BUSY, if the bus is busy which means there is an ongoing operation.

◆ iot_uart_write_sync()

int32_t iot_uart_write_sync	(	IotUARTHandle_t const	pxUartPeripheral,
		uint8_t *const	pvBuffer,
		size_t	xBytes
	)

Starts the transmission of data from UART synchronously.

This function attempts to write certain number of bytes from a pre-allocated buffer to a receiver device, in synchronous way. Partial write might happen, e.g. receiver device unable to receive more data. And the number of bytes that have been actually written can be obtained by calling iot_uart_ioctl.

Warning: None of other read or write functions shall be called during this function.

Parameters

[in]	pxUartPeripheral	The peripheral handle returned in the open() call.
[in]	pvBuffer	The buffer with data to transmit.
[in]	xBytes	The number of bytes to send.

Returns

IOT_UART_SUCCESS, on success (all the requested bytes have been write)
IOT_UART_INVALID_VALUE, if
- pxUartPeripheral is NULL
- pxUartPeripheral is not opened yet
- pucBuffer is NULL
- xBytes is 0
IOT_UART_WRITE_FAILED, if there is unknown driver error
IOT_UART_BUSY, if the bus is busy which means there is an ongoing operation.

◆ iot_uart_read_async()

int32_t iot_uart_read_async	(	IotUARTHandle_t const	pxUartPeripheral,
		uint8_t *const	pvBuffer,
		size_t	xBytes
	)

Starts receiving the data from UART asynchronously.

This function attempts to read certain number of bytes from a pre-allocated buffer, in asynchronous way. It returns immediately when the operation is started and the status can be check by calling iot_uart_ioctl. Once the operation completes, successful or not, the user callback will be invoked.

Partial read might happen. And the number of bytes that have been actually read can be obtained by calling iot_uart_ioctl.

Note: In order to get notification when the asynchronous call is completed, iot_uart_set_callback must be called prior to this.

Warning: pucBuffer must be valid before callback is invoked.; None of other read or write functions shall be called during this function or before user callback.

Parameters

[in]	pxUartPeripheral	The peripheral handle returned in the open() call.
[out]	pvBuffer	The buffer to store the received data.
[in]	xBytes	The number of bytes to read.

Returns

IOT_UART_SUCCESS, on success
IOT_UART_INVALID_VALUE, if
- pxUartPeripheral is NULL
- pxUartPeripheral is not opened yet
- pucBuffer is NULL
- xBytes is 0
IOT_UART_READ_FAILED, if there is unknown driver error

◆ iot_uart_write_async()

int32_t iot_uart_write_async	(	IotUARTHandle_t const	pxUartPeripheral,
		uint8_t *const	pvBuffer,
		size_t	xBytes
	)

Starts the transmission of data from UART asynchronously.

This function attempts to write certain number of bytes from a pre-allocated buffer to a receiver device, in asynchronous way. It returns immediately when the operation is started and the status can be check by calling iot_uart_ioctl. Once the operation completes, successful or not, the user callback will be invoked.

Partial write might happen. And the number of bytes that have been actually written can be obtained by calling iot_uart_ioctl.

Note: In order to get notification when the asynchronous call is completed, iot_uart_set_callback must be called prior to this.

Warning: None of other read or write functions shall be called during this function.

Parameters

[in]	pxUartPeripheral	The peripheral handle returned in the open() call.
[in]	pvBuffer	The buffer with data to transmit.
[in]	xBytes	The number of bytes to send.

Returns

IOT_UART_SUCCESS, on success
IOT_UART_INVALID_VALUE, if
- pxUartPeripheral is NULL
- pxUartPeripheral is not opened yet
- pucBuffer is NULL
- xBytes is 0
IOT_UART_WRITE_FAILED, if there is unknown driver error

◆ iot_uart_ioctl()

int32_t iot_uart_ioctl	(	IotUARTHandle_t const	pxUartPeripheral,
		IotUARTIoctlRequest_t	xUartRequest,
		void *const	pvBuffer
	)

Configures the UART port with user configuration.

Note: eUartSetConfig sets the UART configuration. This request expects the buffer with size of IotUARTConfig_t.; eUartGetConfig gets the current UART configuration. This request expects the buffer with size of IotUARTConfig_t.; eGetTxNoOfbytes returns the number of written bytes in last operation. This is supposed to be called in the caller task or application callback, right after last operation completes. This request expects 2 bytes buffer (uint16_t).

If the last operation was write, this returns the actual number of written bytes which might be smaller than the requested number (partial write).
If the last operation was read, this returns 0.

Note: eGetRxNoOfbytes returns the number of read bytes in last operation. This is supposed to be called in the caller task or application callback, right after last operation completes. This request expects 2 bytes buffer (uint16_t).

If the last operation was read, this returns the actual number of read bytes which might be smaller than the requested number (partial read).
If the last operation was write, this returns 0.

Parameters

[in]	pxUartPeripheral	The peripheral handle returned in the open() call.
[in]	xUartRequest	The configuration request. Should be one of the values from IotUARTIoctlRequest_t.
[in,out]	pvBuffer	The configuration values for the UART port.

Returns

IOT_UART_SUCCESS on successful configuartion of UART port, else one of the IOT_UART_INVALID_VALUE, IOT_UART_BUSY, IOT_UART_FUNCTION_NOT_SUPPORTED on error.

IOT_UART_SUCCESS, on success
IOT_UART_INVALID_VALUE, if
- pxUartPeripheral is NULL
- pxUartPeripheral is not opened yet
- pucBuffer is NULL with requests which needs buffer
IOT_UART_FUNCTION_NOT_SUPPORTED, if this board doesn't support this feature.
- eUartSetConfig: specific configuration is not supported

◆ iot_uart_cancel()

int32_t iot_uart_cancel ( IotUARTHandle_t const pxUartPeripheral )

Aborts the operation on the UART port if any underlying driver allows cancellation of the operation.

The application should call this function to stop the ongoing operation.

Parameters

[in] pxUartPeripheral The peripheral handle returned in the open() call.

Returns

IOT_UART_SUCCESS, on success
IOT_UART_INVALID_VALUE, if
- pxUartPeripheral is NULL
- pxUartPeripheral is not opened yet
IOT_UART_NOTHING_TO_CANCEL, if there is no on-going transaction.
IOT_UART_FUNCTION_NOT_SUPPORTED, if this board doesn't support this operation.

◆ iot_uart_close()

int32_t iot_uart_close ( IotUARTHandle_t const pxUartPeripheral )

Stops the operation and de-initializes the UART peripheral.

Parameters

[in] pxUartPeripheral The peripheral handle returned in the open() call.

Returns

IOT_UART_SUCCESS, on success
IOT_UART_INVALID_VALUE, if
- pxUartPeripheral is NULL
- pxUartPeripheral is not opened yet

Data Structures

Macros

Typedefs

Enumerations

Functions

Detailed Description

Macro Definition Documentation

◆ IOT_UART_SUCCESS

◆ IOT_UART_INVALID_VALUE

◆ IOT_UART_WRITE_FAILED

◆ IOT_UART_READ_FAILED

◆ IOT_UART_BUSY

◆ IOT_UART_NOTHING_TO_CANCEL

◆ IOT_UART_FUNCTION_NOT_SUPPORTED

Typedef Documentation

◆ IotUARTCallback_t

Enumeration Type Documentation

◆ IotUARTOperationStatus_t

◆ IotUARTParity_t

◆ IotUARTStopBits_t

◆ IotUARTIoctlRequest_t

Function Documentation

◆ iot_uart_open()

◆ iot_uart_set_callback()

◆ iot_uart_read_sync()

◆ iot_uart_write_sync()

◆ iot_uart_read_async()

◆ iot_uart_write_async()

◆ iot_uart_ioctl()

◆ iot_uart_cancel()

◆ iot_uart_close()