EO3000I_API  2.6.1.0
 All Data Structures Functions Variables Enumerations Enumerator Groups Pages
UART functions
Collaboration diagram for UART functions:

Functions

void uart_init (uint8 *pu8Param, uint8 u8ParamToSet)
RETURN_TYPE uart_getByte (uint8 *pu8Byte)
RETURN_TYPE uart_sendByte (uint8 u8Byte)
RETURN_TYPE uart_getBuffer (uint8 *pu8Buffer, uint8 u8NumBytes)
RETURN_TYPE uart_sendBuffer (uint8 *pu8Buffer, uint8 u8NumBytes)
RETURN_TYPE uart_getTelegram (TEL_SERIAL_TYPE *pu8Tel)
RETURN_TYPE uart_sendTelegram (TEL_SERIAL_TYPE *pu8Tel)
void uart_getTxStatus (uint8 *pu8TxBytesToSend)
void uart_getRxStatus (uint8 *pu8RxBytesReceived)
RETURN_TYPE uart_getPacket (PACKET_SERIAL_TYPE *pPacket, uint16 u16MaxLength)
RETURN_TYPE uart_sendPacket (PACKET_SERIAL_TYPE *pPacket)

Detailed Description

The UART module is used for RS232 communication between the DOLPHIN IC and a HOST. It provides the following features:

Several baudrates are supported.

Note:
The serial character format is 8 databits, no parity, 1 stopbit.
The UART works exclusively in CPU mode. If using UART before the application enters to a sleep mode make sure that all pending UART bytes has been transmitted. You can make sure by calling uart_getRxStatus function.


Function Documentation

void uart_init ( uint8 *  pu8Param,
uint8  u8ParamToSet 
)

Sets the RS232 parameters

Parameters:
[in]*pu8ParamPointer to the list of parameters to configure the UART. See #uart_param[]
[in]u8ParamToSetIt has to be SET_ALL_PARAM to configure all UART parameters
Returns:
-
See also:
uart_setConfig, uart_PARAM_IDX
RETURN_TYPE uart_getByte ( uint8 *  pu8Byte)

Reads a byte from the UART rx buffer interface. The interface is configured with the uart_init function.

Parameters:
[out]*pu8BytePointer where the received byte is stored.
Returns:
OK Byte in RX buffer
NO_RX_BYTE No byte in RX buffer
Note:
The pointer to the byte or buffer has to reside in XDATA
See also:
uart_sendByte
RETURN_TYPE uart_sendByte ( uint8  u8Byte)

Sends a byte to UART tx buffer interface. The interface is configured with the uart_init function.

Parameters:
[in]pu8ByteByte to send.
Returns:
OK Byte sucessfully send.
BUFF_FULL No space left in UART tx buffer.
See also:
uart_getByte
RETURN_TYPE uart_getBuffer ( uint8 *  pu8Buffer,
uint8  u8NumBytes 
)

Receive several bytes through the UART interface. If the number of bytes to be received is bigger than bytes available in Rx buffer the function returns with NO_RX_BYTE.

Parameters:
[out]*pu8BufferPointer to receive buffer
[in]u8NumBytesNumber of bytes to receive
Returns:
OK Bytes receive through UART stored in pu8Buffer.
NO_RX_BYTE There are no/not enought bytes in the intern receive buffer.
Note:
The pointer to the byte or buffer has to reside in XDATA
See also:
uart_sendBuffer
RETURN_TYPE uart_sendBuffer ( uint8 *  pu8Buffer,
uint8  u8NumBytes 
)

Sends several bytes through the UART interface. If the number of bytes to be sent is bigger than the available space in Tx buffer the function returns with BUFF_FULL.

Parameters:
[in]*pu8BufferPointer to the first byte to send
[in]u8NumBytesNumber of bytes to transmit
Returns:
OK Bytes to send through UART/SPI stored in the tx buffer.
BUFF_FULL No space found in the uart tx buffer. Bytes not sent.
Note:
The pointer to the byte or buffer has to reside in XDATA
Minimum execution time: 13.875 micro seconds Maximum execution time: 609 micro seconds
See also:
uart_getBuffer
RETURN_TYPE uart_getTelegram ( TEL_SERIAL_TYPE pu8Tel)

Gets a telegram using the EnOcean Serial protocol2 (ESP2.0 - EnOcean Serial Protocol 2 (ESP2)).

Parameters:
[out]*pTelPointer to the telegram structure where to store the telegram
Returns:
OK New telegram
NO_RX_TEL No new telegram.
NOT_VALID_CHKSUM Received ESP2 serial telegram has an invalid checksum
Note:
The receiving of the telegram is executed paralel to the application. It is possible that the function returns NO_RX_TEL but it already receives and modifies few bytes in the pTel variable. Therefore if a blocking receiving is required use the function in a while statement. See blocking and non blocking example for more details.
The pointer to pTel has to reside in XDATA
This function adds the 0xA5 and 0x5A synch bytes to the telegram structure sent i.e the tel->cmd.u8Synch1; tel->cmd.u8Synch2;

Example 1:
Blocking receiving of telegram. The application has to wait until a telegram is received

while (uart_getTelegram(pTel) != OK);
//... process pTel ...

Example 2:
Nonblocking receiving of telegram. The application can do other processing during the serial telegram is receiving

if (uart_getTelegram(pTel) == OK)
{
//... process telegram ...
}
//... do some other code processing but be sure not to use pTel ....
Note:
Minimum execution time: 9 micro seconds Maximum execution time: 1722.375 micro seconds
See also:
uart_sendTelegram, misc_serialToRadio, misc_radioToSerial
RETURN_TYPE uart_sendTelegram ( TEL_SERIAL_TYPE pu8Tel)

Sends a UART telegram using the EnOcean Serial protocol2 (ESP2.0 - EnOcean Serial Protocol 2 (ESP2)).

Parameters:
[in]*pu8TelPointer to the telegram to send
Returns:
OK Telegram sent
BUFF_FULL No space found in the uart tx buffer. Telegram not sent.
Note:
The pointer to pTel has to reside in XDATA

Example 1:
Sending an RCT telegram with 2 data bytes

mainInit();
sTel.cmd.u3Hseq = RCT;
sTel.cmd.u8Org = (ORG_TYPE)OK_SYS_WR;
//fill uart telegram with data
for (i=0; i<DATA_SIZE; i++)
sTel.cmd.u8Bytes[i]=i;
//add 2 because of org and checksum
sTel.cmd.u5Length = DATA_SIZE + 2;
for (i=0; i<14;i++)
while (uart_sendTelegram(&sTel) != OK);
while(1);

Example 2:
Converting a radio telegram to a serial telegram

// Telegram types
mainInit();
while (1)
{
// Handle radio to uart traffic
if (radio_getTelegram(&rTel, NULL) == OK)
{
io_togDigital(ADIO_0);
misc_radioToSerial(&rTel,&sTel);
}
}
Note:
Minimum execution time: 273.375 micro seconds Maximum execution time: 1535.25 micro seconds
See also:
uart_getTelegram, misc_serialToRadio, misc_radioToSerial
void uart_getTxStatus ( uint8 *  pu8TxBytesToSend)

Retrieve the status of UART TX buffer.

Parameters:
[out]pu8TxBytesToSendPointer to status byte
Returns:
-
Note:
This function is allowed to be used in an interrupt callback function ONLY if it is ensured that it is not used at the same time from the main program!
See also:
uart_init, uart_getBuffer, uart_sendBuffer
void uart_getRxStatus ( uint8 *  pu8RxBytesReceived)

Retrieves the status of UART RX buffer.

Parameters:
[out]pu8RxBytesReceivedPointer to status byte
Returns:
-
Note:
This function is allowed to be used in an interrupt callback function ONLY if it is ensured that it is not used at the same time from the main program!
See also:
uart_init, uart_getBuffer, uart_sendBuffer
RETURN_TYPE uart_getPacket ( PACKET_SERIAL_TYPE pPacket,
uint16  u16MaxLength 
)

Retrieves a packet with the EnOcean serial protocol3 (ESP3) from the UART.

Parameters:
[out]pPacketAddress of the received packet
[in]u16MaxLengthMaximal number of data + optional bytes allowed to be received : protocol sync byte, length fields, type, CRC8D, CRC8H are excluede from the count.
Returns:
OK Correct packet received
TIME_OUT The time between two bytes exceeded 100ms
NOT_VALID_CHKSUM Not valid data checksum
NO_RX_TEL No complete packet received
NEW_RX_BYTE Transmission in progress. The pPacket.u8DataBuffer is being updated
OUT_OF_RANGE The telegram data + optianal length is either 0 or bigger then the allocated packet buffer.
Note:
Since the EO3000I RAM is 2kB, this is the maximum value of the pPacket buffer, where you store the incoming bytes. Therefore, the maximum value that you should set to u16MaxLength is 2kB.
The OK code is received only once when the whole packet has been received. If the data transmission is in progress the function returns NEW_RX_BYTE. In this state the pPacket.u8DataBuffer can not be modified by application. Changing the pPacket.u8DataBuffer during transmission would cause corrupt data.
The function starts to measure the time between bytes from the moment that it detects a sysnchronizing 0x55 code. If the time between bytes exceeds 100ms, the functions will return an error code TIME_OUT. It is important that you read this function more often than every 100ms. Otherwise the function returns a time-out although bytes have been received
Since the function makes use of time resources, in particular the time_setCounter() and time_getTimeOut() functions, enable the system time control in the init macro INIT_EO3000I. There, the functions pwr_enableXTAL() and pwr_selectXTAL() must be called, to start the 16MHz external crystal The isr_timer0Init() function must also be called to configure and start the system time interrupts.
In case that the Header CRC8 is false the function returns NO_RX_TEL.
If the data length of the received packet is bigger than u16MaxLength, only the first u16MaxLength bytes are loaded to the packet. The next byte is considered the CRC8D of the telegram

Example 1:
Blocking receiving of telegram. The application has to wait until a telegram is received

while (uart_getPacket(pPacket) != OK);
//... process pPacket ...

Example 2:
Non-blocking receiving of packet. The application can do other processing during the serial packet is receiving

if (uart_getTelegram(pPacket) == OK)
{
//... process packet ...
}
//... do some other code processing but be sure not to use pPacket ....
Note:
Minimum execution time: 30.75 micro seconds Maximum execution time: 923.625 micro seconds
See also:
uart_init, uart_getBuffer, uart_getBuffer, uart_sendPacket, pwr_enableXTAL, pwr_selectXTAL, isr_timer0Init
RETURN_TYPE uart_sendPacket ( PACKET_SERIAL_TYPE pPacket)

Sends a serial packet with the EnOcean serial protocol3 (ESP3) through the UART.

Parameters:
[in]pPacketAddress of the received packet
Returns:
OK Correct packet received
OUT_OF_RANGE The length fields are both 0
Note:
The function waits for available space in the UART tx FIFO buffer, if the buffer happens to be full. Once there is available place it copies there the next byte to send. It repeats the process of waiting and copying until all bytes in pPacket have been copied to the UART tx FIFO buffer.
The function is returned when the last byte has been copied to the UART tx buffer. At this moment, the last byte has not been sent completely through the serial port.
See also:
uart_init, uart_getBuffer, uart_getBuffer, uart_getPacket