Collaboration diagram for RADIO functions:

Macros
#define	proc_crc8(u8CRC, u8Data) (u8CRC8Table[u8CRC ^ u8Data])

Functions
void	radio_init (uint8 u8NumBuffers, uint8 u8MaturityTime)
void	radio_init_mod (uint8 u8Param)
RETURN_TYPE	radio_getTelegram (TEL_RADIO_TYPE pu8RxRadioTelegram, TEL_PARAM_TYPE pu8TelParam)
RETURN_TYPE	radio_getTelegram2 (TEL_RADIO_TYPE2 pTelegram, TEL_PARAM_TYPE2 pParam)
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 ()
RETURN_TYPE	radio_sendTelegram2 (TEL_RADIO_TYPE2 pTelegram, TEL_PARAM_TYPE2 pParam)
void	radio_getNoRxBusyBuffs (uint8 *pu8No)
void	radio_getNoTxBusyBuffs (uint8 *pu8No)
RETURN_TYPE	radio_enableRx (bit1 bEnable)
void	radio_getOngoingRxTx (uint8 u8TxOn, uint8 u8RxOn)
void	radio_getRSSI (uint16 pu16StRssi, uint16 pu16LtRssi)
uint8	radio_rssiToDbm_asm (uint16 u16RssiLna)
void	dbg_enableSubTelInfo (uint8 u8Enabled, uint8 xdata pu8IntBuf, uint16 u16IntBufLen, uint8 xdata pu8AppBuf, uint16 u16AppBufLen)

Variables
code uint8	u8CRC8Table [256]

Detailed Description

Functions used for radio communication

Macro Definition Documentation

#define proc_crc8	(	u8CRC,
		u8Data
	)	(u8CRC8Table[u8CRC ^ u8Data])

CRC8 calculation for radio telegrams. Note that the CRC actual value is calculated from all the previous data.

Parameters:

u8CRC	Actual value of CRC
u8Data	Data to calculate the CRC from

Example:
Calculate a CRC for a radio telegram SYS_EX.

    uint8 u8Crc, i;
    TEL_RADIO_TYPE  rTelOut;
  u8Crc=0;
for (i=0;i<RADIO_DEC_LENGTH_SYS_EX-1;i++)
{
    u8Crc = proc_crc8(u8Crc,rTelOut.raw.bytes[i] );
}

Function Documentation

void radio_init	(	uint8	u8NumBuffers,
		uint8	u8MaturityTime
	)

Sets the radio parameters

Parameters:

[in]	Number	of the used radio buffers.
[in]	Used	maturity time in system.

Returns:

Note:: This function can be used with the scheduller (line powered applications) and in ultra low power applications.

void radio_init_mod ( uint8 u8Param )

Initialises the radio HW

Parameters:

[in] RADIO_INIT_PARAM u8Param

Returns:: -

Note:: This function can be used with the scheduller (line powered applications) and in ultra low power applications.

RETURN_TYPE radio_getTelegram	(	TEL_RADIO_TYPE *	pu8RxRadioTelegram,
		TEL_PARAM_TYPE *	pu8TelParam
	)

Gets a radio telegram stored in a radio rx buffer in ERP1 mode.

Parameters:

[out]	*pu8RxRadioTelegram	Address where the received telegram is copied to.
[out]	*pu8TelParam	Address 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.

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 strongest 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 strongest 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 EO3100I_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.; 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).

See also:: radio_sendTelegram, radio_waitEndMaturity

RETURN_TYPE radio_getTelegram2	(	TEL_RADIO_TYPE2 *	pTelegram,
		TEL_PARAM_TYPE2 *	pParam
	)

Gets a radio telegram stored in a radio rx buffer in ERP2 mode.

Parameters:

[out]	*pTelegram	Address where the received telegram is copied to.
[out]	*pParam	Address 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.

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 strongest 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 strongest dBm among all subtelegrams set the radio_waitEndMaturity to on.; Each received telegram will be stored in one of the available radio buffers. The amount of radio buffers is defined in EO3100I_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.; 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).

See also:: radio_sendTelegram2

void radio_waitEndMaturity ( bit1 bValue )

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

Parameters:

[in] bValue FALSE (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 in ERP1 mode 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]	*pu8TxRadioTelegram	Address of the first telegram byte.
[in]	*pu8TelParam	Param 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

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. Use send command in a infinite cyrcle until send is successful.; Be sure to let enough time between calling the radio_sendTelegram and consider return value. 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:

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

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

    TEL_RADIO_TYPE      rTel;
  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

    TEL_RADIO_TYPE      rTel;
  uint8                 buf[256];  // used to store temporary data
  if (misc_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 be used with the scheduller (line powered applications) and in ultra low power application with no scheduller.

See also:: radio_getTelegram, misc_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]	*pu8TxRadioTelegram	Telegram to send
[in]	*puTxParam	Param 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:: This is a function specific to the ERP1 library. This function does not exist in the ERP2 library.; 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.

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 is a function specific to the ERP1 library. This function does not exist in the ERP2 library.; 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 is a function specific to the ERP1 library. This function does not exist in the ERP2 library.; 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

RETURN_TYPE radio_sendTelegram2	(	TEL_RADIO_TYPE2 *	pTelegram,
		TEL_PARAM_TYPE2 *	pParam
	)

Sends a radio telegram with ERP2.

Parameters:

[in]	*pTelegram	Address of the first telegram byte.
[in]	*pParam	Param 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

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. Use send command in a infinite cyrcle until send is successful.; Be sure to let time between calling the radio_sendTelegram. Consider also the return value of the function. 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 many different telegrams in short time the receiver has to have enough receiver buffers to store the telegrams. If you find problems you may define more radio buffers or will have to wait the maturity time (100ms standard) long after sending the next telegram. Besides, sending at high rates can overload the repeater system which is not able to fit the EnOcean sub telegram timing correctly. If the repeater is active avoid calling this function in shorter periods than 40 ms.

Example 1:

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

Note:

Example 2:
Send the ID of the Dolphin chip with 1BS telegram

  TEL_RADIO_TYPE2       rTel2;
rTel2.raw.bytes[0]  =   0x21;   // Header: Only 32 bit Originator-ID, 1BS, no extended Header
rTel2.raw.bytes[1]  =   0;      // Id
rTel2.raw.bytes[2]  =   0;      // Id
rTel2.raw.bytes[3]  =   0;      // Id
rTel2.raw.bytes[4]  =   0;      // Id
rTel2.raw.bytes[5]  =   0x08;   // DATA
rTel2.raw.u8Length  =   7;      // Place for the CRC byte also in the telegram
radio_sendTelegram2(&rTel2, NULL);

Example 2:
Send the ID of the Dolphin chip with 4BS telegram

  TEL_RADIO_TYPE2       rTel2;
  rTel2.raw.bytes[0]    =   0x22;   // Header: Only 32 bit Originator-ID, no extended Header, 4BS telegram
rTel2.raw.bytes[1]  =   0;      // Id
rTel2.raw.bytes[2]  =   0;      // Id
rTel2.raw.bytes[3]  =   0;      // Id
rTel2.raw.bytes[4]  =   0;      // Id
rTel2.raw.bytes[5]  =   0x3;    // DATA byte 3
rTel2.raw.bytes[6]  =   0x4;
rTel2.raw.bytes[7]  =   0x5;
rTel2.raw.bytes[8]  =   0x6;    // DATA byte 0
rTel2.raw.u8Length  =   10;     // Length must include space for the CRC, which is calculated by the function
radio_sendTelegram2(&rTel2, NULL);

Note:: This function can be used with the scheduller (line powered applications) and in ultra low power application with no scheduller.

See also:: radio_getTelegram, misc_setBaseId, pwr_setSleepTimer

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] *pu8No Number 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] *pu8No Number 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] bEnable 1 - 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_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]	*u8TxOn	If TRUE currently there is an ongoing transmission
[out]	*u8RxOn	If 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]	pu16StRssi	Address of the variable where the Long Term Radio Signal Strength should be saved
[out]	pu16LtRssi	Address of the variable where the Short 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();
    radio_enableRx(1);
    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 radio settings in mod area.

Parameters:

RSSI	signal 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

Macros

Functions

Variables

Detailed Description

Macro Definition Documentation

Function Documentation