UART Interface

UART (A Universal Asynchronous Receiver/Transmitter) interface is supported only by DLN-4M and DLN-4S adapters.UART is a interface which is included in micro-controller, that translates data between parallel and serial forms. UART is commonly used in conjunction with communication standards such as EIA, RS-232, RS-422 or RS-485, so that it can “talk” to and exchange data with modems and other serial devices.

Rating:

Simple UART Module Example

This example shows how to setup and send data with UART module. You can find the complete example in the “..\Program Files\Diolan\DLN\examples\c_cpp\examples\simple” folder after DLN setup package installation.

C/C++

#include "..\..\..\common\dln_generic.h"
#include "..\..\..\common\dln_uart.h"
#pragma comment(lib, "..\\..\\..\\bin\\dln.lib")

int _tmain(int argc, _TCHAR* argv[])
{
	// Open device
	HDLN device;
	DlnOpenUsbDevice(&device);

	// Configure UART to 19200 8N1
	uint32_t baud;
	DlnUartSetBaudrate(device, 0, 19200, &baud);
	DlnUartSetCharacterLength(device, 0, DLN_UART_CHARACTER_LENGTH_8);
	DlnUartSetParity(device, 0, DLN_UART_PARITY_NONE);
	DlnUartSetStopbits(device, 0, DLN_UART_STOPBITS_1);
	// Enable UART
	uint16_t conflict;
	DlnUartEnable(device, 0, &conflict);

	// Write data
	uint8_t output[10] = "123456789";
	DlnUartWrite(device, 0, 10, output);
	
	// Read data
	uint8_t input[10];
	uint16_t total;
	DlnUartRead(device, 0, 10, &input, &total);
	// Print it
	for (int i = 0; i < total; i++) putchar(input[i]);

	// Disable UART
	DlnUartDisable(device, 0);

	// Close device
	DlnCloseHandle(device);
	return 0;
}

Line 1:#include "..\..\..\common\dln_generic.h"

The dln_generic..h header file declares functions and data structures for the generic interface. In current example this header is used to call DlnOpenUsbDevice() and DlnCloseHandle() functions.
Line 2:#include "..\..\..\common\dln_uart.h"

The dln_uart.h header file declares functions and data structure specific for UART interface. By including this header file you are able to call DlnUartSetBaudrate(), DlnUartSetCharacterLength(), DlnUartSetParity(), DlnUartSetStopbits(), DlnUartEnable(), DlnUartWrite(), DlnUartRead(), DlnUartDisable() and other UART interface functions.
Line 3:#pragma comment(lib, "..\\..\\..\\bin\\dln.lib")

Use dln.lib library while project linking.
Line 9:DlnOpenUsbDevice(&device);

The function establishes the connection with the DLN adapter. This application uses the USB connectivity of the adapter. For additional options, refer to the Device Opening & Identification section.
Line 13:DlnUartSetBaudrate(device, 0, 19200, &baud);

The function sets the baud rate value equal to 10200 bits.
Line 14:DlnUartSetCharacterLength(device, 0, DLN_UART_CHARACTER_LENGTH_8);

The function sets the character length equal to 8 bits.
Line 15:DlnUartSetParity(device, 0, DLN_UART_PARITY_NONE);

The function sets parity to none.
Line 16:DlnUartSetStopbits(device, 0, DLN_UART_STOPBITS_1);

The function sets the number of stop bits to be sent with each character.
line 19:DlnUartEnable(device, 0, &conflict);

The function enables the UART interface.
Line 22:uint8_t output[10] = "123456789";

Define the array of 10 8-bits unsigned integer values (10 bytes) and set it to “123456789”.
Line 23:DlnUartWrite(device, 0, 10, output);

The function sends 10 bytes data buffer via UART interface.
Line 28:DlnUartRead(device, 0, 10, &input, &total);

The function reads 10 bytes data buffer to input variable and returns the value of real read bytes to total variable.
Line 30: for (int i = 0; i < total; i++) putchar(input[i]);

Output input array values in loop.
Line 33:DlnUartDisable(device, 0);

Disable UART interface port 0.
Line 36:DlnCloseHandle(device);

The application closes handle to the DLN adapter.

Rating:

UART Functions

This section describes the UART functions. They are used to control UART interface and modify its settings.Actual control of the device is performed by use of commands and responses. Each function utilizes respective commands and responses. You can send such commands directly if necessary.

Rating:

DlnUartGetPortCount() Function

The DlnUartGetPortCount() function retrieves the total number of the UART ports available in your DLN-series adapter.

This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartGetPortCount(
    HDLN handle, 
    uint8_t *count
);

Parameters

handle: A handle to the DLN-series adapter.
count: A pointer to an unsigned 8-bit integer. This integer will be filled with the number of available ports after function execution.

Return Value

DLN_RES_SUCCESS: The UART port count has been successfully retrieved.

DlnUartEnable() Function

The DlnUartEnable() function enables UART port.This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartEnable(
    HDLN handle, 
    uint8_t port, 
    uint16_t *conflict
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the UART port to be enabled.
conflict: A pointer to an unsigned 16-bit integer. This integer can be filled with a number of the conflicted pin, if any.A conflict arises if a pin is already assigned to another module of the DLN-series adapter and cannot be used by the UART module. To fix this a user has to disconnect a pin from a module that it has been assigned to and call the DlnUartEnable() function once again. If there are any more conflicting pins, the next conflicted pin number will be returned.

Return Value

DLN_RES_SUCCESS: The operation completed successfully and UART port was enabled.

DlnUartDisable() Function

The DlnUartDisable() function deactivates corresponding UART port on your DLN-Series adapter.

This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartDisable(
    HDLN handle, 
    uint8_t port
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the SPI master port to be enabled.

Return Value

DLN_RES_SUCCESS: The operation completed successfully and UART port was disabled.

DlnUartIsEnabled() Function

The DlnUartIsEnabled() function retrieves information whether the specified SPI master port is activated. This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartIsEnabled(
    HDLN handle, 
    uint8_t port, 
    uint8_t *enabled
);

Parameters

handle

A handle to the DLN-series adapter.

port

A number of the UART port to retrieve the information from.

enabled

A pointer to an unsigned 8-bit integer. The integer will be filled with information whether the specified UART port is activated after the function execution. There are two possible values:

0 or DLN_UART_DISABLED - the port is not configured as UART.
1 or DLN_UART_ENABLED - the port is configured as UART.

Return Value

DLN_RES_SUCCESS: The operation completed successfully and UART port state was retrieved.

DlnUartSetBaudrate() Function

The DlnUartSetBaudrate() function sets the baud rate, which represents the number of bits that are actually being sent.This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartSetBaudrate(
    HDLN handle, 
    uint8_t port, 
    uint32_t baudrate, 
    uint32_t *actualBaudrate
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the UART port to be configured.
baudrate: The Baud rate value. The minimal baud rate value can be achieved by DlnUartGetMinBaudrate() function. The maximum baud rate value can be achieved by using DlnUartGetMaxBaudrate() function.
actualBaudrate: The pointer to uint32_t type value, which will be filled with actual Baud rate value to be set. This value is rounded value of baudrate parameter.

Return Value

DLN_RES_SUCCESS: The operation completed successfully and baud rate has been set.

DlnUartGetBaudrate() Function

The DlnUartGetBaudrate() function retrieves the baud rate value, which represents the number of bits that are actually being sent.This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartGetBaudrate(
    HDLN handle, 
    uint8_t port, 
    uint32_t *baudrate
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the UART port.
baudrate: The current baud rate value.

Return Value

DLN_RES_SUCCESS: The operation completed successfully and baud rate has been retrieved.

DlnUartSetCharacterLength() Function

The DlnUartSetCharacterLength() function selects the data character length of 5, 6, 7, 8 and 9 bits per character. This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartSetCharacterLength(
    HDLN handle, 
    uint8_t port, 
    uint8_t characterLength
);

Parameters

handle

A handle to the DLN-series adapter.

port

A number of the UART port to be configured.

characterLength

Set the data character length value of 5, 6, 7, 8 and 9 bits per character. You can use predefined constants to set required value.

5 or DLN_UART_CHARACTER_LENGTH_5
6 or DLN_UART_CHARACTER_LENGTH_6
7 or DLN_UART_CHARACTER_LENGTH_7
8 or DLN_UART_CHARACTER_LENGTH_8
9 or DLN_UART_CHARACTER_LENGTH_9

Return Value

DLN_RES_SUCCESS: The operation completed successfully and character length has been set.

DlnUartGetCharacterLength() Function

The DlnUartGetCharacterLength() function retrieves the current data character length.This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartGetCharacterLength(
    HDLN handle, 
    uint8_t port, 
    uint8_t *characterLength
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the UART port.
characterLength: The pointer to uint8_t type variable. Retrieve the current data character length value.

Return Value

DLN_RES_SUCCESS: The operation completed successfully and character length has been retrieved successfully.

DlnUartSetParity() Function

The DlnUartSetParity() function selects even, odd, mark (when the parity bit is always 1), space (the bit is always 0) or none parity.This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartSetParity(
    HDLN handle, 
    uint8_t port,
    uint8_t parity
);

Parameters

handle

A handle to the DLN-series adapter.

port

A number of the UART port to be configured.

parity

The parity value parameter. You can use predefined constants to set required value.

0 or DLN_UART_PARITY_EVEN
1 or DLN_UART_PARITY_ODD
2 or DLN_UART_PARITY_SPACE
3 or DLN_UART_PARITY_MARK
4 or NONE

Return Value

DLN_RES_SUCCESS: The operation completed successfully and parity has been set.

DlnUartGetParity() Function

The DlnUartGetParity() function retrieves the current parity bit value.This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartGetParity(
    HDLN handle, 
    uint8_t port, 
    uint8_t *parity
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the UART.
parity: The pointer to uint8_t type variable. Variable will be filled with current parity value after successful function execution.

Return Value

DLN_RES_SUCCESS: The operation completed successfully and parity value has been retrieved.

DlnUartSetStopbits() Function

The DlnUartSetStopbits() function selects the number of stop bits to be sent with each character.This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartSetStopbits(
    HDLN handle, 
    uint8_t port, 
    uint8_t stopbits
);

Parameters

handle

A handle to the DLN-series adapter.

port

A number of the UART port to be configured.

stopbits

The stop bit value parameter. You can use predefined constants to set required value.

0 or DLN_UART_STOPBITS_1
1 or DLN_UART_STOPBITS_1_5
2 or DLN_UART_STOPBITS_2

Return Value

DLN_RES_SUCCESS: The operation completed successfully and stop bit value has been set.

DlnUartGetStopbits() Function

The DlnUartGetStopbits() function retrieves the current number of stop bits to be sent with each character.This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartGetStopbits(
    HDLN handle, 
    uint8_t port, 
    uint8_t *stopbits
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the UART port to be configured.
stopbits: The pointer to uint8_t type variable. Variable will be filled with current stop bit value.

Return Value

DLN_RES_SUCCESS: The operation completed successfully and stop bit value has been retrieved.

DlnUartWrite() Function

The DlnUartWrite() function sends data via UART interface. This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartWrite(
    HDLN handle, 
    uint8_t port, 
    uint16_t size, 
    uint8_t *buffer
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the UART port.
size: The size of the message buffer. This parameter is specified in bytes. The maximum value is DLN_UART_MAX_TRANSFER_SIZE (256 bytes).
buffer: A pointer to an array of unsigned 8-bit integers. This array must be filled with data to be sent during the function execution.

Return Value

DLN_RES_SUCCESS: The operation completed successfully and data has been transmitted.

DlnUartRead() Function

The DlnUartRead() function receives data via UART interface.This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartRead(
    HDLN handle, 
    uint8_t port, 
    uint16_t size, 
    uint8_t *buffer, 
    uint16_t *actualSize
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the UART interface port.
size: The size of the message buffer. This parameter is specified in bytes. The maximum value is DLN_UART_MAX_TRANSFER_SIZE (256 bytes).
buffer: A pointer to an array of unsigned 8-bit integers. This array will be filled with received data during the function execution.
actualSize: A pointer to an array of unsigned 16-bit integers. This variable will be filled with actual data size value.

Return Value

DLN_RES_SUCCESS: The operation completed successfully and data has been read.

DlnUartEnableEvent() Function

The DlnUartEnableEvent() function enables UART event for specified UART port.This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartEnableEvent(
    HDLN handle, 
    uint8_t port
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the UART port.

Return Value

DLN_RES_SUCCESS: The operation completed successfully and events for UART port were enabled.

DlnUartDisableEvent() Function

The DlnUartDisableEvent() function disables UART events for specified UART port.This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartDisableEvent(
    HDLN handle, 
    uint8_t port
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the UART port.

Return Value

DLN_RES_SUCCESS: The operation completed successfully and events for UART port were disabled.

DlnUartIsEventEnabled() Function

The DlnUartIsEventEnabled() function informs whether the UART port is currently configured for monitoring events.This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartIsEventEnabled(
    HDLN handle, 
    uint8_t port, 
    uint8_t *enabled
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the UART port.
enabled: A pointer to an unsigned 8-bit integer. The integer will be filled with current port configuration after the function execution: 0 if events are disabled and 1 if events are enabled.

Return Value

DLN_RES_SUCCESS: The UART port information has been successfully retrieved.

DlnUartSetEventSize() Function

The DlnUartSetEventSize() function configures the event size.This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartSetEventSize(
    HDLN handle, 
    uint8_t port, 
    uint16_t size
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the UART port.
size: Event size value.

Return Value

DLN_RES_SUCCESS: The operation completed successfully and event size has been set.

DlnUartGetEventSize() Function

The DlnUartGetEventSize() function retrieves the current event size value.This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartGetEventSize(
    HDLN handle, 
    uint8_t port, 
    uint16_t *size
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the UART port.
size: The pointer to uint16_t type variable. Variable will be filled with the current event size value after function execution.

Return Value

DLN_RES_SUCCESS: The operation completed successfully and event size has been retrieved.

DlnUartSetEventPeriod() Function

The DlnUartSetEventPeriod() function configures the event period for specified UART port.This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartSetEventPeriod(
    HDLN handle, 
    uint8_t port, 
    uint32_t period
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the UART port to be configured.
period: Defines the event period for event in ms.

Return Value

DLN_RES_SUCCESS: The operation completed successfully and event period has been set.

DlnUartGetEventPeriod() Function

The DlnUartGetEventPeriod() function retrieves the current event period for specified UART port.This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartGetEventPeriod(
    HDLN handle, 
    uint8_t port, 
    uint32_t *period
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the UART port.
period: A pointer to an unsigned 32-bit integer. The integer will be filled with current event repeat interval after the function execution.

Return Value

DLN_RES_SUCCESS: The operation completed successfully and the current event period has been retrieved.

DlnUartGetMinBaudrate() Function

The DlnUartGetMinBaudrate() function retrieves the minimum possible baud rate value.This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartGetMinBaudrate(
    HDLN handle, 
    uint8_t port, 
    uint32_t *minBaudrate
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the UART port.
minBaudrate: The pointer to uint32_t type variable. Variable will contain minimum possible baud rate value after function execution.

Return Value

DLN_RES_SUCCESS: The operation completed successfully and minimum baud rate value has been retrieved.

DlnUartGetMaxBaudrate() Function

The DlnUartGetMaxBaudrate() function retrieves the maximum possible baud rate value.This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartGetMaxBaudrate(
    HDLN handle, 
    uint8_t port, 
    uint32_t *maxBaudrate
);

Parameters

handle: A handle to the DLN-series adapter.
port: A number of the UART port.
maxBaudrate: The pointer to uint32_t type variable. Variable will contain maximum possible baud rate value after function execution.

Return Value

DLN_RES_SUCCESS: The operation completed successfully and maximum baud rate value has been retrieved.

DlnUartGetSupportedCharacterLengths() Function

The DlnUartGetSupportedCharacterLengths() function returns all supported character length types. This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartGetSupportedCharacterLengths(
    HDLN handle, 
    uint8_t port, 
    DLN_UART_CHARACTER_LENGTHS *supportedLengths
);

Parameters

handle: A handle to the DLN-series adapter.
port: UART port number.
supportedLengths: The pointer to DLN_UART_CHARACTER_LENGTHS structure which will be filled by supported character length values.

Return Value

DLN_RES_SUCCESS: Function was successfully executed.

DlnUartGetSupportedParities() Function

The DlnUartGetSupportedParities() function returns all supported parities values. This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartGetSupportedParities(
    HDLN handle, 
    uint8_t port, 
    DLN_UART_PARITIES *supportedParities
);

Parameters

handle: A handle to the DLN-series adapter.
port: UART port number.
supportedParities: The pointer to DLN_UART_PARITIES structure which will be filled by supported parities values.

Return Value

DLN_RES_SUCCESS: Function was successfully executed.

DlnUartGetSupportedStopbits() Function

The DlnUartGetSupportedStopbits() function returns all supported stop bits values. This function is defined in the dln_uart.h file.

Syntax

C/C++

DLN_RESULT DlnUartGetSupportedStopbits(
    HDLN handle, 
    uint8_t port, 
    DLN_UART_STOPBITS *supportedStopbits
);

Parameters

handle: A handle to the DLN-series adapter.
port: UART port number.
supportedStopbits: The pointer to DLN_UART_STOPBITS structure which will be filled by supported stop bits values.

Return Value

DLN_RES_SUCCESS: Function was successfully executed.