Collaboration diagram for Smart Acknowledge functions:

Data Structures
struct	LEARN_RESULT
	Smart acknowledge learn result structure. It is used to Controller to evalute learn result. More...
struct	MAILBOX_FLASH
	Strucutre for memory occupied by MailBoxes in flash. More...
struct	MAILBOX_XRAM
	Strucutre for memory occupied by MailBox in xram. More...

Enumerations
enum	SMACK_RESULT { SMACK_OK = 0, NO_MORE_MAILBOX, FLASH_FAILURE, NO_RECLAIM_MESSAGE, COLLECTING, RESULT_READY, NO_RESULT, LEARN_ON_SIMPLE, LEARN_ON_ADVANCED, LEARN_TIMEOUT, OTHER_MESSAGE }
	Smart Acknowledge result used in Controller and Sensor application to indicate return or status. More...
enum	SIGNAL_INDEX { RESERVED = 0, MAILBOX_EMPTY, MAILBOX_DOES_NOT_EXIST, RESET }
	Signal telegram message index. More...
enum	SMACK_RECLAIM_TYPE { LEARN_RECLAIM = 0, DATA_RECLAIM }
	Smart acknowledge reclaim type. More...
enum	LRN_MSG_IDX { LRN_REP = 1, LRN_ACK }
	Smart acknowledge learn answer telegram message index. More...
enum	SMACK_TASK { NOTHING = 0, ADD_MB, DELETE_MB }
	Smart acknoweldge mailbox handling task. More...

Functions
void	smack_init (uint16 *pu16Param, uint8 u8ParamToSet)
SMACK_RESULT	smack_process (uint8 *pu8ShadowBuffer)
SMACK_RESULT	smack_processController (uint8 *pu8ShadowBuffer)
SMACK_RESULT	smack_LearnOff ()
void	smack_LearnOn (uint8 u8Extended, uint32 u32TimeOut)
SMACK_RESULT	smack_reclaim (SMACK_RECLAIM_TYPE u8ReclaimType, uint8 u7MailBoxIdx, TEL_RADIO_TYPE pRxRadioTelegram, TEL_PARAM_TYPE pu8TelParam)
SMACK_RESULT	smack_getLearnResult (LEARN_RESULT *pAppLrnRes)
void	smack_finalizeLearn (LEARN_RESULT *pLrnRes, uint8 u8AckCode, uint16 u16ResponseTime)
RETURN_TYPE	smack_sendDataTelegram (TEL_RADIO_TYPE pu8TxRadioTelegram, TEL_PARAM_TYPE pu8TelParam)

Variables
volatile MAILBOX_FLASH xdata	gMbfAct
	Variable determines the MailBox that should be writen/deleted as next. It is a intern variable of smack module. It is only avaivable because of Remote Management.
volatile SMACK_TASK xdata	gSmTask
	Variable determines operation that should be perfomed with gMbfAct. It is a intern variable of smack module. It is only avaivable because of Remote Management.
volatile uint8 xdata	u8gGERssiDbm

Reclaim choice encoded defines
Defines are used for checking in radio_tx for reclaim telegrams.
#define	RECLAIM_CHOICE_ENCODED_B0 0xA2
	First byte of encoded Reclaim Choice.
#define	RECLAIM_CHOICE_ENCODED_B1 0xD0
	Second byte of encoded Reclaim Choice.

Reclaim telegram defines
For faster Reclaim telegram processing we access telegram data with pointer and relative possition. Defines are constant. Also masks to separate reclaim type from mailbox index are listened.
#define	REC_TYPE_POS 4
	Possition of the reclaim type.
#define	REC_SRC_ID_POS 0
	Possition of the Source Id.
#define	REC_TYPE_MASK 0x80
	Mask to get relcaim type.
#define	REC_MBIDX_MASK 0x7F
	Mask to get mailbox index.

Learn request telegram defines
For faster Learn Request telegram processing we access telegram data with pointer and relative possition. Defines are constant.
#define	LRN_REQ_REQ_CODE_POS 1
	Possition of the learn request code.
#define	LRN_REQ_EEP_POS 5
	Possition of the EEP.
#define	LRN_REQ_RSSI_POS 6
	Possition of the RSSI.
#define	LRN_REQ_CANDIDATE_POS 7
	Possition of the Candidate Id.
#define	LRN_REQ_SRC_ID_POS (RADIO_DEC_LENGTH_SM_LRN_REQ-LEN_SRCID_STAT_CHCK)
	Possition of the source Id.
#define	LRN_REQ_STATUS_POS (RADIO_DEC_LENGTH_SM_LRN_REQ-2)
	Possition of the status field.

Learn answer telegram defines
For faster Learn answer telegram processing we access telegram data with pointer and relative possition. Defines are constant. Learn answer can encapsulate Learn Reply or Learn Acknowledge.
#define	LRN_ANS_MSG_IDX_POS 1
	Possition of the message index.
#define	LRN_ANS_RESPONSE_TIME_POS 2
	Possition of the response time.
#define	LRN_ANS_ACK_CODE_POS 4
	Possition of Acknowledge code.
#define	LRN_ANS_REP_SENSOR_ID_POS 5
	Possition of Sensor Id in Learn Reply.
#define	LRN_ANS_ACK_MB_IDX_POS 5
	Possition of Mailbox Index in Learn Acknowledge.

Learn request code defines
In Learn Request telegram Learn Request code share one byte with Manufacturer Id. For accessing values we use bite masks and bit operations.
#define	REQ_CODE_MASK 0xF8
	Request code mask of the sharing byte in learn request telegram with Manufacturer Id.
#define	MAN_CODE_MASK 0x07
	Manufacturer Id mask of the sharing byte in learn request telegram with request code.
#define	SENSOR_DEFAULT_REQ_CODE 0x1F
	Default request code send by Sensor.

Priority flags defines
Priority of the Post Master Candidate is evaluated by a hierarchically priority system. So the Flag bits have also a priority. The highest priority has the already post master flag. At the end the highest priority is taken as result. In evaluation process the flags are used to set the properities: ALREDY POST MASTER / CANDIDATE PLACE FOR NEXT MAILBOX / NO PLACE FOR NEXT MAILBOX GOOD RSSI / NOT GOOD RSSI LOCAL / REMOTE Note: TRUE - 1 means the first choice
#define	PF_LOCAL 0x1
#define	PF_RSSI_OK 0x2
#define	PF_PLACE_OK 0x4
#define	PF_PM 0x8
#define	PF_REP 0x10

Learn acknowledge code defines
Learn Acknowledge code is separated into main and second part. The main part idetify the operation and the second gives additional infromation about it. For accessing main and second part we use bit masks and bit operations.
#define	ACK_CODE_LEARN_IN 0x00
	Main acknowledge code for Learn In.
#define	ACK_CODE_LEARN_DISCARD 0x10
	Main acknowledge code for discard Learn In.
#define	ACK_CODE_LEARN_OUT 0x20
	Main acknowledge code for Learn Out.
#define	ACK_CODE_MAIN_MASK 0xF0
	Mask for main acknowledge code.
#define	ACK_CODE_SECOND_MASK 0x0F
	Mask for second acknowledge code.

Discard reason defines
Discard reason gives more infromation about the reason why was the LearnIn discarted. It is saved in second part of a Learn Acknowledge code.
#define	ACK_CODE_EEP_NOT_ACCEPTED 0x01
	Second acknowledge code for discard Learn In - EEP not accepted.
#define	ACK_CODE_PM_NO_PLACE 0x02
	Second acknowledge code for discard Learn In - declared Post Master has no place for next MailBox.
#define	ACK_CODE_CONTROLLER_NO_PLACE 0x03
	Second acknowledge code for discard Learn In - Controller has no place to Learn In next Sensor.
#define	ACK_CODE_NO_GOOD_RSSI 0x04
	RSSI was not good enough.

learn mode defines
Learn modes of smart ack controller.
#define	SIMPLE_LEARNMODE 0x00
	Simple learnmode is used, when only Smart Ack Controller should be selected as postmaster. All learn requests received by repeater will be ignored.
#define	ADVANCED_LEARNMODE 0x01
	Advanced learnmode is used, when also repeater can be selected as postmaster. But when Controller reaches sensor, controller is selected.
#define	ADVANCED_LEARNMODE_SELECT_REPEATER 0x02
	Anvanced learnmode select repeater is used, when always the best available repeater will be selected as postmaster. Controller is only selected, when no repeater is in system.

Other defines
#define	NO_MAILBOX_FOUND 0xFF
	Code for no MailBox found.
#define	MAX_RESPONSE_TIME 550
	Maximum value of response time [ms] - in case of LRN reclaim it must be at least 500.

Detailed Description

The smack module enables Smart Acknowledge functionality for Controller, Repeater and Sensor in Dolphin API. Functions handle all time and energy critical parts of communication. The functions for line powered Smack Acknowledge actors are same. Controller and Repeater use the same functions, but Controller can addtioanlly learn Sensors so it uses special functions for this purpose.

The initialization of the SMACK module is done through Dolphin APIConfigurator. The generated settings are saved to the file EO3100I_CFG.h.

Note:: By default, smack functionality is switched OFF.; If the repeater is active and has enabled SmartACK postmaster functionality, telegrams located in the mailbox of the postmaster are not available for the application. These telegrams are filtered on the lower API layers and are not received by radio_getTelegram.

Enumeration Type Documentation

enum SMACK_RESULT

Smart Acknowledge result used in Controller and Sensor application to indicate return or status.

Enumerator:

SMACK_OK	Ok message.
NO_MORE_MAILBOX	No more free MailBox available.
FLASH_FAILURE	Flash write or read failure.
NO_RECLAIM_MESSAGE	No reclaim message received.
COLLECTING	Module is collecting learn request telegrams.
RESULT_READY	Result from learn request collecting process is ready.
NO_RESULT	No result from learn request collecting process is ready.
LEARN_ON_SIMPLE	Module is in simple Learn Mode.
LEARN_ON_ADVANCED	Module is in advanced Learn Mode.
LEARN_TIMEOUT	Module just switched of the Learn Mode because of learn period timeout.
OTHER_MESSAGE	Received other radio telegram while reclaim.

enum SIGNAL_INDEX

Signal telegram message index.

Enumerator:

RESERVED	RESERVED.
MAILBOX_EMPTY	Smart acknowledge - reclaimed mailbox is empty.
MAILBOX_DOES_NOT_EXIST	Smart acknowledge - reclaimed mailbox does not exists.
RESET	Smart acknowledge - rest learn process.

enum SMACK_RECLAIM_TYPE

Smart acknowledge reclaim type.

Enumerator:

LEARN_RECLAIM	Learn reclaim type.
DATA_RECLAIM	Data reclaim type.

enum LRN_MSG_IDX

Smart acknowledge learn answer telegram message index.

Enumerator:

LRN_REP	Learn reply message index.
LRN_ACK	Learn acknowledge message index.

enum SMACK_TASK

Smart acknoweldge mailbox handling task.

Enumerator:

NOTHING	Do nothing.
ADD_MB	Add MailBox.
DELETE_MB	Delete MailBox.

Function Documentation

void smack_init	(	uint16 *	pu16Param,
		uint8	u8ParamToSet
	)

Function initialises the Smart Acknowledge mode to work.

Parameters:

[in]	*pu8Param	Pointer to the list of parameters to set. See SMACK_PARAM_IDX
[in]	u8ParamToSet	It has to be SET_ALL_PARAM to set all parameters from SMACK_PARAM_IDX of the list

Returns:: -

Note:: When using smack mode be sure you use the isr_timer0_smack_PM_Init() function instead of isr_timer0Init().

See also:: isr_timer0_smack_PM_Init, SMACK_PARAM_IDX

SMACK_RESULT smack_process ( uint8 * pu8ShadowBuffer )

Function ensures Smart Acknowledge functionality. Nearly all functionality is implemented in interrupt, but some operations like writing to flash memory must be performed in user application. The function is used by the smack repeaters only (Devices that do not what to learn in Smack Sensors). The devices never go to active Smack Learn mode.

Parameters:

[in] *pu8ShadowBuffer Memory used for buffering flash operations. It is used only temporary and it must point to xram memory space with size of one flash page - 256 b.

Returns:: SMACK_OK Process executed commnon operations. Status in Learn Off.; FLASH_FAILURE The embedded flash operation failed. - FLASH ERROR; NO_MORE_MAILBOX The embedded flash operation could not write next MB, because no free memory. Should not occure, bsc. SMACK handels memory.

Note:: The execution time of the function is usualy short, but if flash write operation is needed it can execute much longer.; To read some global variables that are accessed also by interrupt functions the function temporary disables TIMER0 interrupt irq.

See also:: mem_writeFlash

SMACK_RESULT smack_processController ( uint8 * pu8ShadowBuffer )

Function ensures Smart Acknowledge functionality. Nearly all functionality is implemented in interrupt, but some operations like writing to flash memory must be performed in user application. The function is also an interface for user application to get Smart Acknoweldge module status. The status is passed as return value. The function makes time - out for learn mode. It must be called repeatelly, but specially when learn mode is active. The function calls the smack_process function.

Parameters:

[in] *pu8ShadowBuffer Memory used for buffering flash operations. It is used only temporary and it must point to xram memory space with size of one flash page - 256 b.

Returns:: SMACK_OK Process executed commnon operations. Status in Learn Off.; COLLECTING Smart acknowledge module is collecting Learn request messages now. It is important now to limit radio sending operations, because they can avoid receving Learn request messages.; RESULT_READY Smart Acknowledge has finished collecting and evaluating Learn Request messages. The result can be fetched with smack_getLearnResult.; LEARN_ON_SIMPLE The module is in simple learn mode.; LEARN_ON_ADVANCED The module is in advanced learn mode.; FLASH_FAILURE The embedded flash operation failed. - FLASH ERROR; NO_MORE_MAILBOX The embedded flash operation could not write next MB, because no free memory. Should not occure, bsc. SMACK handels memory.

Note:: The execution time of the function is usualy short, but if flash write operation is needed it can execute much longer.; To read some global variables that are accessed also by interrupt functions the function temporary disables TIMER0 interrupt irq.

See also:: mem_writeFlash; smack_process

SMACK_RESULT smack_LearnOff ( )

Function checks if the module is not collecting Learn Request messages and then it disables learn mode.

Returns:: SMACK_OK Learn mode is disabled.; COLLECTING Learn mode can not be disabled because it collects learn request messages.

void smack_LearnOn	(	uint8	u8Extended,
		uint32	u32TimeOut
	)

Function activates the learn mode and activates the learn period timer.

Parameters:

[in]	u8Extended	If TRUE enables the advanced learn mode.
[in]	u32TimeOut	Time-Out for the learn mode in ms. When time is 0 then default period of 60 000 ms is used.

Note:: Default Learn mode is simple. That means that only Controller can be Post Master, all repeater are ignored. In advanced learn mode also Repeater can become Post Master.

SMACK_RESULT smack_reclaim	(	SMACK_RECLAIM_TYPE	u8ReclaimType,
		uint8	u7MailBoxIdx,
		TEL_RADIO_TYPE *	pRxRadioTelegram,
		TEL_PARAM_TYPE *	pu8TelParam
	)

Function is only used in SmartACK sensor and sends one DATA or LEARN RECLAIM telegram and then reclaims the answer. The receiver will be switched on, till the answer is received or a timeout of 5 ms elapsed. After the function returns, the receiver is disabled.

Parameters:

[in]	u8ReclaimType	LEARN_RECLAIM = send learn reclaim; DATA_RECLAIM = send data reclaim
[in]	u7MailBoxIdx	Mailbox index for the mailbox to reclaim
[out]	*pRxRadioTelegram	Radio structure of reclaimed telegram
[out]	*pu8TelParam	Parameter structure of reclaimed telegram

Returns:: SMACK_OK Radio telegram received and copied in radio and parameter structures; NO_RECLAIM_MESSAGE There was no or a not to me addressed reclaim message received

Note:: As this function does only perform one reclaim cycle, it can be called as much as the application wants to try reclaims.; Due to the smart acknowledge concept it is not possilbe to use smack_reclaim with scheduler operation. When using timer0 as scheduler, it is not necessary to use smart ack for communication, because the system is line powered.

Maximum execution time: 8 ms

See also:: radio_getTelegram

SMACK_RESULT smack_getLearnResult ( LEARN_RESULT * pAppLrnRes )

If there is any, then the function copies the Learn Result from learn request process.

Parameters:

[out] *pAppLrnRes Learn result structure where the learn result about the last learn request process should be copied. LEARN_RESULT

Returns:: SMACK_OK Learn result is copied.; NO_RESULT Learn result is not copied, because non is available.

Note:: To read some global variables that are accessed also by interrupt functions the function temporary disables TIMER0 interrupt irq.

void smack_finalizeLearn	(	LEARN_RESULT *	pLrnRes,
		uint8	u8AckCode,
		uint16	u16ResponseTime
	)

Function finalises learn process. It is called also when LearnIn, LearnOut. It handels all MailBox operations and eventually declares PostMaster. The parameter u8AckCode signals the wished final operation (i.e. LearnIn, LearnOut). It is possible to delete mailboxes manually.

Parameters:

[in]	*pLrnRes	The Learn Result that was obtained from smack_getLearnResult. LEARN_RESULT
[in]	u8AckCode	Learn Acknowledge code indicates the Controller decision about the learn finalization.
[in]	u16ResponseTime	Response time for sensor in ms in which the controller can prepare the data and send it to the postmaster. Only actuall if learn finalization is LearnIn.

Note:

In order the funtion maybe calls radio_sendTelegram function - to transmit learn reply.

You can delete Smart Acknowledge mailboxes by two ways manualy:

If the mailboxes are local (no repeater in system) the easiest way is to delete the flash page where the smart Acknowledge mailboxes are stored.
If the mailboxes are local or in a repeater, the best thing is to use the smack_finalizeLearn function to learn out the sensors. It is nessessary to call smack_processController function after each call to execute the learn out.

See also:: smack_getLearnResult, radio_sendTelegram

RETURN_TYPE smack_sendDataTelegram	(	TEL_RADIO_TYPE *	pu8TxRadioTelegram,
		TEL_PARAM_TYPE *	pu8TelParam
	)

Function enables the controller to communicate with learned Sensors. It either put the telegram to local stored MailBox in case Controller is also Post Master. Otherwise the function sends the telegram to Post Master. The Sensor Id is in TEL_PARAM_TYPE as input parameter *pu8TelParam. The input parameters are like in radio_sendTelegram and the return type too.

Parameters:

[in]	*pu8TxRadioTelegram
[in]	*pu8TelParam

Returns:: OK Telegram sent.; BUFF_FULL No free Tx buffer available for transmission.; NOT_VALID_PARAM No Sensor Id listened. Or he 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:: To send telegram the function calls radio_sendTelegram.

See also:: radio_sendTelegram

Data Structures

Enumerations

Functions

Variables

Reclaim choice encoded defines

Reclaim telegram defines

Learn request telegram defines

Learn answer telegram defines

Learn request code defines

Priority flags defines

Learn acknowledge code defines

Discard reason defines

learn mode defines

Other defines

Detailed Description

Enumeration Type Documentation

Function Documentation