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

Functions

void radio_init (uint8 u8NumBuffers, uint8 u8MaturityTime)
void radio_initDutyCycleLimit (uint8 u8NumSlots)
RETURN_TYPE radio_getTelegram (TEL_RADIO_TYPE *pu8RxRadioTelegram, TEL_PARAM_TYPE *pu8TelParam)
void radio_waitEndMaturity (bit1 bValue)
RETURN_TYPE radio_sendTelegram (TEL_RADIO_TYPE *pu8TxRadioTelegram, TEL_PARAM_TYPE *pu8TelParam)
RETURN_TYPE radio_ulpPrepareTelegram (TEL_RADIO_TYPE *pu8TxRadioTelegram, TEL_PARAM_TYPE *puTxParam)
void radio_ulpSend3SubTels ()
void radio_ulpSendTelegram ()
void radio_getNoRxBusyBuffs (uint8 *pu8No)
void radio_getNoTxBusyBuffs (uint8 *pu8No)
RETURN_TYPE radio_enableRx (bit1 bEnable)
void radio_readBaseId (uint32 *pu32BaseID)
RETURN_TYPE radio_setBaseId (uint32 u32BaseID)
void radio_getOngoingRxTx (uint8 *u8TxOn, uint8 *u8RxOn)
void radio_getRSSI (uint16 *pu16StRssi, uint16 *pu16LtRssi)
uint8 radio_rssiToDbm_asm (uint16 u16RssiLna)

Variables

code uint8 u8CRC8Table [256]

Detailed Description

Functions used for radio communication


Function Documentation

void radio_init ( uint8  u8NumBuffers,
uint8  u8MaturityTime 
)

Sets the radio parameters

Parameters:
[in]Numberof the used radio buffers.
[in]Usedmaturity time in system.
Returns:
Note:
The radio_init_asm files are dependent on the chip frequency. Use the apropriate for you module from the EO3000I_LIB directory.
This function can be used with the scheduller (line powered applications) and in ultra low power applications.
void radio_initDutyCycleLimit ( uint8  u8NumSlots)

Sets the number of duty cycle slots and initializes Duty Cycle limitation

Parameters:
[in]Numberof the duty cyle slots.
Returns:
Note:
The duty cycle limitation is a regulation which only applies in 868 MHz in Europe
This function can be used only with the scheduller (line powered applications). For ultra low power applications the user has to care to meet the duty cycle limit.
RETURN_TYPE radio_getTelegram ( TEL_RADIO_TYPE pu8RxRadioTelegram,
TEL_PARAM_TYPE pu8TelParam 
)

Gets a radio telegram stored in a radio rx buffer.

Parameters:
[out]*pu8RxRadioTelegramAddress where the received telegram is copied to.
[out]*pu8TelParamAddress where the telegram additional parameters are copied to.
Returns:
OK Radio telegram received and copied.
NO_RX_TEL No radio telegram received.
Note:
Note that the subtelegram number in u8TelParam shows the actual stand of the subtelegram counter. If the function is called too early - before the maturity time limit of the telegram is reached - it is possible that this parameter shows only 1 or 2 subtelegrams because only 1 or 2 subtelegram has arrived. It doesn't neceseraly mean that the rest of the subtelegrams are lost. See timing diagram below for explanation.
subtel_early.png
Fetching telegram before all subtelegrams has arrived
If you need the exact amount of all received sub telegrams use radio_waitEndMaturity to enable this feature. But then all telegrams are delayed till the end of the maturity time before they will returned by radio_getTelegram.
The dBm value in u8TelParam is the strongest value of all up to now received subtelegrams (30 is very strong, 96 is very weak signal). Note this value is an unasigned value, in reality it is a negative value. I.e. value 70dBm in reality is -70dBm
Different subtelegrams has different dBm level. The radio_getTelegram returns always the lowest dBm value, although it may happen that by the time the radio_getTelegram is called only the 1st subtelegram has been received. To make sure you get realy the lowest dBm among all subtelegrams set the radio_waitEndMaturity to on.
If telegram was encapsulated in ADT (Addressing Destination Telegram)than the Destination ID is in u8TelParam. If the destinationID is 0xFFFFFFFF that means either an ADT was received with a BROADCAST_ID or the telegram received was not ADT encapsulated (all not ADT encapsulated are considered to be broadcast).
Each received telegram will be stored in one of the available radio buffers. The amount of radio buffers is defined in EO3000i_cfg.h in RADIO_BUFF_NUM.
Only calling radio_getTelegram will release a busy buffer. It is important to call it periodically, because when all buffers are full, new received telegrams will be discarded. There is no possibility to determine the order of the received telegrams, because this depends on rx and tx traffic and the number of lost sub telegrams.
If a filter is defined, it is also impossible to call radio_getTelegram periodically, because the check, if the filter applies, is in radio_getTelegram. If it is not called, the radio buffers get full, even when no telegram is expected by filter rule.
This function can only be used with the scheduller (line powered applications).
Minimum execution time: 99.75 micro seconds Maximum execution time: 932.25 micro seconds
See also:
radio_sendTelegram, radio_waitEndMaturity
void radio_waitEndMaturity ( bit1  bValue)

Switchs radio_getTelegram function to return only telegrams where the maturity time is elapsed

Parameters:
[in]bValueFALSE (Default): Return telegrams in radio_getTelegram independent of the maturity time TRUE: Return in radio_getTelegram only telegrams where the maturity time is elapsed
Returns:
Note:
If it is necessary to get the correct amount of sub telegrams in TEL_PARAM_TYPE of the radio_getTelegram function, use radio_waitEndMaturity(TRUE) once to switch API in state to wait till end of maturity time before returning a telegram. So there is always the delay in length of the maturity time!
This function can only be used with the scheduller (line powered applications).
See also:
radio_getTelegram
RETURN_TYPE radio_sendTelegram ( TEL_RADIO_TYPE pu8TxRadioTelegram,
TEL_PARAM_TYPE pu8TelParam 
)

Sends a radio telegram with u8Subtel subtelegrams and optionally also encapsulated to ADT (Address Destination Telegram) with Destination ID. If Destination ID is set to 0 no ecapsulation is done. Encapsulation is made only if Destiantion ID has other value as 0.

If no other telegram is to send. Before transmitting the telegram be sure to set the u8Length parameter of the TEL_RADIO_TYPE structure. If there is no free Tx buffer the function returns imediately.

Parameters:
[in]*pu8TxRadioTelegramAddress of the first telegram byte.
[in]*pu8TelParamParam for sending. (Subtelegram number count and Destination ID) If value is NULL, than 3 subtelegram count is used by default and ADT encapsulation is not preformed.
Returns:
OK Telegram sent.
BUFF_FULL No free Tx buffer available for transmission
NOT_VALID_PARAM The telegram length in TEL_RADIO_TYPE was not set OR the u8Subtel number is 0 or more than 3 OR the encapsulated ADT telegram length is bigger > 16bytes
ID_OUT_OF_RANGE The ID given in TEL_RADIO_TYPE structure is out of allowed range
LOCK_SET Duty cycle limit reached
Note:
Notice that Rx and Tx use the same buffers. When buffers are full occupied by received telegram, sendTelegram will fail because no buffer for send is free. When send command is called in a infinite cyrcle until send is successful, deadlock will occure.
When you want to transmit more telegrams as there are available telegram buffers and you want to do it during one cycle of the maturity time the telegram sending sequence can't be ensured.
Example 1:
There are 3 available telegram buffers and we want to transmitt telegrams: rTel_a, rTel_b, rTel_c during 1 maturity time. We call the following code:
radio_sendTelegram(&rTel_a);
radio_sendTelegram(&rTel_b);
radio_sendTelegram(&rTel_c);
The result sequence in the air can be: rTel_a, rTel_c, rTel_b OR rTel_a, rTel_b, rTel_c. To avoid this problem be sure to leave enough time delay between telegram transmission.
Be sure to let enough time between calling the radio_sendTelegram. The receiver has to put each telegram in a different buffer and has to wait the maturity time long until freeing the buffer. When sending too much different telegrams in short time the receiver has to have enougth receiver buffers to store the telegrams. Only resolution is to define enougth buffers or to wait the maturity time (100ms standard) long after sending the next telegram. Besides that could sending more telegrams in a row overload a repeater system which is not able to fit the EnOcean sub telegram timing correct. So be carefully sending different telegrams in shorter periods than 40 ms.

Example 1:
This will cause a deadlock optionally, when buffers are full with received telegrams.

while (radio_sendTelegram(&rTel, NULL)==BUFF_FULL)
{};

Example 2:
When sending in while() the radio_getTelegram function must be called, to free a buffer.

while (radio_sendTelegram(&rTel, NULL)==BUFF_FULL)
{radio_getTelegram(&r2Tel, NULL);};

Example 3:
Try to send a telegram with a specified count of attempts. When still failed, handle situation.

RETURN_TYPE result;
for(uint8 i =0 ; i < 10;i++)
{
result = radio_sendTelegram(&rTel, NULL);
if(result == OK)
break;
}
if(result != OK)
{
//handle the situation
}
Note:
The parameter u32id of TEL_RADIO_TYPE structure defines, what id will be sent in the air. If this parameter is in range 0 ... 0xff7fffff than the chip ID will be sent. If the ID is 0xffffffff (BROADCAST_ID) the function returns BASEID_OUT_OF_RANGE.

Example 4:
Send the ID of the Dolphin chip

rTel.t4bs.u32id = 0;
// do not forget so set the other fields of rTel structure
if (radio_sendTelegram(&rTel, NULL)==OK)
{};

The user can also define a base ID by itself and use a band of different Ids, starting from base_ID+0 to base_ID+127 for telegrams Example 5:
Use user defined ID

uint8 buf[256]; // used to store temporary data
if (radio_setBaseId(0xff800000)==OK) // set base id (must be in range of 0xff800000 to 0xffffff80
{};
rTel.t4bs.u32id = 0xff800000+33;
// do not forget so set the other fields of rTel structure
if (radio_sendTelegram(&rTel, NULL)==OK)
{};
rTel.t4bs.u32id = 0xff800000+128;
if (radio_sendTelegram(&rTel, NULL)==OK)
{
// will not be reached, function returns with error code ID_OUT_OF_RANGE because maximum 127 is allowed
};
Note:
This function can only be used with the scheduller (line powered applications).
See also:
radio_getTelegram, radio_setBaseId,pwr_setSleepTimer
RETURN_TYPE radio_ulpPrepareTelegram ( TEL_RADIO_TYPE pu8TxRadioTelegram,
TEL_PARAM_TYPE puTxParam 
)

Ultra low power function. Use for energy autarkic devices without schedule. This function prepares the telegrams for transmission and palces the result to the radio Tx buffer Int. Be sure to set the correct telegram length. The function does the following steps:

  • sets the CHIP ID of the telegram
  • calculates the checksum or CRC
  • encodes the telegram
  • places the encoded bytes to radio Tx buffer
  • optionally when specified Destination ID encapsulate to ADT structure
Parameters:
[in]*pu8TxRadioTelegramTelegram to send
[in]*puTxParamParam for sending. (Destination ID) If value is NULL, than ADT encapsulation is not preformed.
Returns:
OK Telegram sent.
NOT_VALID_PARAM The length for the telegram was not defined.
Note:
Be sure to set the u8Length variable of the telegram
The ID bytes of the telegram will be overwritten with the CHIP ID
For sending telegrams with more than one sub telegram this function need only be once called, because the encoded telegram remains stored in the internal tx buffer.
This function can only be used in ultra low power applications without scheduller.
Minimum execution time: 436.125 micro seconds Maximum execution time: 815.25 micro seconds
See also:
radio_ulpSend3SubTels, radio_ulpSendTelegram, radio_ulpSubTelTiming
void radio_ulpSend3SubTels ( )

Ultra low power function. Use for energy autarkic devices without schedule. This function transmits three subtelegrams to the air from the radio Tx buffer Int. Before calling first time this function be sure to call the function radio_ulpPrepareTelegram. The function initiates transmission, performs a short term sleep after sending 1st and 2nd subtelegram and goes to standby mode while the 3rd sub telegram is sent. The sub telegram timing complains with the EnOcean standard. After that returns the control to the application.

Parameters:
-
Note:
This function can't be used with schedule! That means you can't use this function with radio receiver on OR with repeater OR with routing. Be sure to comment out any of the schedule initialisation routine - isr_timer0xxxx()- from the EO3000I_CFG file #INIT_EO3000I define!
Be sure to call misc_init prior using that function, because the random generator of the Dolphin chip is used to perform random sub telegram timing.
See also:
radio_ulpPrepareTelegram
void radio_ulpSendTelegram ( )

Ultra low power function. Use for energy autarkic devices without schedule. This function transmits one subtelegram to the air from the radio Tx buffer Int. Before calling first time this function be sure to call the function radio_ulpPrepareTelegram. The function initiates transmission and after that returns the control to the application.

Note:
This function can't be used with schedule! That means you can't use this function with radio receiver on OR with repeater OR with routing. Be sure to comment out any of the schedule initialisation routine - isr_timer0xxxx()- from the EO3000I_CFG file #INIT_EO3000I define!
The most efficient way using this function is to realise the subtelegram timing with short term sleep, i.e. to enter short term sleep mode after the function returns. If not going to short term sleep mode the Tx state-machine keeps running and will consume power.
Between the sub telegrams, a short term sleep or standby mode could be performed to save energy.
Be sure to enter deep sleep mode only when the sub telegram is sent completely by checking radio_getOngoingRxTx.
See also:
radio_ulpPrepareTelegram, radio_ulpSubTelTiming
void radio_getNoRxBusyBuffs ( uint8 *  pu8No)

Gets the number of busy Rx radio buffers. This function can be used to know how many telegram has to be still processed by the application until the radio Rx can be switched off.

Parameters:
[out]*pu8NoNumber of busy buffers
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!
The user is responsible to implement an EnOcean Radio Protocol conform subtelegram timing! See References, EnOcean Radio Protocol specification.
This function can only be used with the scheduller (line powered applications).
See also:
radio_getNoTxBusyBuffs
void radio_getNoTxBusyBuffs ( uint8 *  pu8No)

Gets the number of busy Tx radio buffers. This function can be used to know how many telegram has to be still sent by the schedule until the Tx radio can be switched off or the CPU can be put to sleep mode.

Parameters:
[out]*pu8NoNumber of busy buffers
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!
This function can only be used with the scheduller (line powered applications).
See also:
radio_getNoRxBusyBuffs
RETURN_TYPE radio_enableRx ( bit1  bEnable)

Enable the radio receiver hardware.

Parameters:
[in]bEnable1 - radio receiver ON 0 - radio receiver OFF
Returns:
OK The Radio Rx statemachine was started
LOCK_SET Failed to start the rx statemachine due to ongoing Radio Tx process
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!
This function can only be used with the scheduller (line powered applications).
void radio_readBaseId ( uint32 *  pu32BaseID)

Returns the base ID.

Parameters:
[out]pu32BaseIDPointer to store the base ID in
Returns:
-
Note:
This function can be used with the scheduller (line powered applications) and in ultra low power applications.
RETURN_TYPE radio_setBaseId ( uint32  u32BaseID)

Stores the base ID.

Parameters:
[in]u32BaseIDbase ID to change. Is allowed in range from 0xFF800000 to 0xFFFFFF80, the user may change it maximum 10 times
Returns:
OK ID stored BASEID_OUT_OF_RANGE base ID is not in allowed range of: 0xff800000 <= range <=0xffffff80, or the 7 least significant bits are not zero BASEID_MAX_REACHED base ID was changed 10 times, no more changes are allowed FLASH_HW_ERROR error while writing in FLASH memory
Note:
IMPORTANT: This function can only be called 10 times to change the base ID. There is no possibility to reset this constraint. Also power off/on will not allow more than 10 changes!
CONSTRAINTS: The 7 least significant bits of base ID needs to be zero so that the base ID matches with the mask 0xFFFFFF80. Valid base ID is for example: 0xFF800000, 0xFF800080, 0xFF800100 ... 0xFF811980, 0xFF811A00 ... 0xFFFFFF00, 0xFFFFFF80
It is not possible to use a base ID in components using smart acknowledge. The function smack_reclaim will only reclaim telegrams with the chip ID. And the functions of the post master, regardless if repeater or controller, will also use only the chip ID.
It is not possible to use a base ID with remote management, because all remote management answer telegrams use the chip ID.
It is possible to emulate BASE_ID + 127 ID's. So one module can emulate 128 senders using the BaseID
No BaseID with value 0xFFFFFFFF can be used
This function can be used with the scheduller (line powered applications) and in ultra low power applications.
void radio_getOngoingRxTx ( uint8 *  u8TxOn,
uint8 *  u8RxOn 
)

Returns the state of the current radio Rx receiving or Tx transmittion. It is usefull to se if there is actual ongoing transmission or receiving before entering to standby.

Parameters:
[out]*u8TxOnIf TRUE currently there is an ongoing transmission
[out]*u8RxOnIf TRUE currently there is an ongoing receiving
Returns:
-
Note:
This function can be used with the scheduller (line powered applications) and in ultra low power applications.
void radio_getRSSI ( uint16 *  pu16StRssi,
uint16 *  pu16LtRssi 
)

Returns the short term and long term RSSI signal

Parameters:
[out]pu16StRssiAddress of the variable where the Short Term Radio Signal Strength should be saved
[out]pu16LtRssiAddress of the variable where the Long Term Radio Signal Strength should be saved
Returns:
-
Note:
Two signals, the STRSSI and the LTRSSI are compared to each other to detect telegram start. The STRSSI is a filtered magnitude signal, indicating the possible presence of an incoming telegram, while the LTRSS represents a long term RSS indicating the background noise. The packet starts are detected as soon as the STRSSI rises above the LTRSSI value.
You can use the LTRSSI signal to detect if the radio channel is blocked by a transmitter sending continouse wave.
Don't use the STRSSI to detect the received telegram signal strength. Use instead the dBm parameter delivered by the radio_receiveTelegram function. The dBm parameter is the average signal strength calculated from the whole telegram signal.

Example:
Detect if there is a communication on the channel, and if yes send the signal strength through UART:

#define SIGNAL_STRENGTH 400
void main()
{
uint8 u8Buff[30];
uint16 pu16StRssi, pu16LtRssi;
mainInit();
pu16LtRssi=0;
while(1)
{
do
{
radio_getRSSI (&pu16StRssi, &pu16LtRssi);
} while (pu16LtRssi<SIGNAL_STRENGTH);
sprintf(u8Buff,"STRSS: %d, LTRSS: %d\n", pu16StRssi, pu16LtRssi);
while (uart_sendBuffer(u8Buff, strlen(u8Buff))!=OK);
io_togDigital(ADIO_5);
}
}
Note:
This function can only be used with the scheduller (line powered applications).
See also:
radio_rssiToDbm_asm
uint8 radio_rssiToDbm_asm ( uint16  u16RssiLna)

Calculates dBm from RSSI based on the calibration values in radio init specified by array u8RssiCalib.

Parameters:
RSSIsignal where the LSB bit is the LNA
Returns:
dBm value
Note:
This function can only be used with the scheduller (line powered applications).
See also:
radio_getRSSI