Collaboration diagram for Remote management functions:

Functions
void	reman_init (uint16 *pu16Param, uint8 u8ParamToSet)
void	reman_setRPC (uint16 *pu16RpcList, uint8 u8RpcCount)
RETURN_TYPE	reman_receiveTelegram (TEL_RADIO_TYPE pu8RadioTel, TEL_PARAM_TYPE pInParam, uint16 u16FnNumber, uint16 u16DataSize)
RETURN_TYPE	reman_receiveTelegramController (TEL_RADIO_TYPE pu8RadioTel, TEL_PARAM_TYPE pInParam, uint16 u16FnNumber, uint16 u16RmDataSize)
RETURN_TYPE	reman_sendMessage (uint8 *u8Data, uint16 u16DataSize, uint16 u16FunctionCode, uint8 u8SendWithDelay)
RETURN_TYPE	reman_sendMessageController (uint8 *u8Data, uint16 u16DataSize, uint16 u16FunctionCode, uint16 u16Manufacturer, uint32 u32DestinationID, uint8 u8SendWithDelay)
RETURN_TYPE	reman_processSend ()
void	reman_getCode (uint32 *u32Code)
void	reman_setCode (uint32 u32code)
void	reman_getRpcManufacturerID (uint16 *u16RpcManufacturerID)
void	reman_setError (uint16 u16ErrorCode)

System defines
These defines are system specific.
#define	RM_DEFAULTMANID 0x7FF
	Default Manufacturer ID.
#define	RM_DEFAULTEEP 0x000
	Default EEP.
#define	RM_ANSWER_START 0x600
	Begin of the answer function codes.
#define	RM_RPC_START 0x200
	Value from which rpc codes begin.
#define	LOCK_INIT_VALUE 0xFFFFFFFF
	Initial value of a blank flash page.
#define	EXIT_NO_FURTHER_ANALYSIS 0x00
	Return value when user application does not do anything further.

Enums
Enums used in remote management module.
enum	RM_LEARN_FLAG { START_LEARN = 0x01, NEXT_CHANNEL, STOP_LEARN, SMACK_START_SIMPLE_LEARN, SMACK_START_ADVANCED_LEARN, SMACK_STOP_LEARN }
	Learn flags for RMCC remote learn. More...
enum	RM_FN { RM_NOT_DEFINED = 0x00, RM_FN_UNLOCK = 0x01, RM_FN_LOCK = 0x02, RM_FN_SET_CODE = 0x03, RM_FN_QUERY_ID = 0x04, RM_FN_ACTION_COMMAND = 0x05, RM_FN_PING_COMMAND = 0x06, RM_FN_QUERY_FUNCTION_COMMAND = 0x07, RM_FN_QUERY_STATUS = 0x08, RM_FN_REMOTE_LEARN = RM_RPC_START + 0x01, RM_FN_REMOTE_CLEAR = RM_RPC_START + 0x02, RM_FN_REMOTE_WRITE = RM_RPC_START + 0x03, RM_FN_REMOTE_READ = RM_RPC_START + 0x04, RM_FN_SMACK_SETTING_READ = RM_RPC_START + 0x05, RM_FN_SMACK_SETTING_WRITE = RM_RPC_START + 0x06, RM_FN_QUERY_ID_ANS = RM_ANSWER_START + RM_FN_QUERY_ID, RM_FN_QUERY_ID_ANS_EXT = 0x704, RM_FN_PING_COMMAND_ANS = RM_ANSWER_START + RM_FN_PING_COMMAND, RM_FN_QUERY_FUNCTION_COMMAND_ANS = RM_ANSWER_START + RM_FN_QUERY_FUNCTION_COMMAND, RM_FN_QUERY_STATUS_ANS = RM_ANSWER_START + RM_FN_QUERY_STATUS, RM_FN_REMOTE_READ_ANS = RM_ANSWER_START + RM_FN_REMOTE_READ, RM_FN_SMACK_SETTING_ANS = RM_ANSWER_START + RM_FN_SMACK_SETTING_READ, RM_FN_LEARNED_SENSORS_ANS = RM_ANSWER_START + RM_FN_SMACK_SETTING_READ +1 }
	Remote manager function codes. More...
enum	RM_RETURN_CODE { RM_RETURN_CODE_OK = 0x00, RM_RETURN_CODE_WRONG_ID = 0x01, RM_RETURN_CODE_WRONG_CODE = 0x02, RM_RETURN_CODE_WRONG_EEP = 0x03, RM_RETURN_CODE_WRONG_MANID = 0x04, RM_RETURN_CODE_WRONG_DATA_SIZE = 0x05, RM_RETURN_CODE_NO_CODE_SET = 0x06, RM_RETURN_CODE_NOT_SENT = 0x07, RM_RETURN_CODE_RPC_FAILED = 0x08, RM_RETURN_CODE_MESSAGE_TIME_OUT = 0x09, RM_RETURN_CODE_TOO_LONG_MESSAGE = 0x0A, RM_RETURN_CODE_MESSAGE_PART_ALREADY_RECEIVED = 0x0B, RM_RETURN_CODE_MESSAGE_NOT_RECEIVED = 0x0C, RM_RETURN_CODE_ADDRESS_OUT_OF_RANGE = 0x0D, RM_RETURN_CODE_DATA_SIZE_EXCEEDED = 0x0E, RM_RETURN_CODE_WRONG_DATA = 0x0F }
	Return codes from RMCC and RPC functions. Values are used in Query Status commands. More...
enum	SETTINGS_TYPE { MB_SETTINGS = 0x01, LEARNED_SENSORS_CONTROLLER }
	Smack read settings types - applied for the RPC RM_FN_SMACK_SETTING_READ. More...
enum	OPERATION_TYPE { ADDFLASH_MB = 0x01, DELETEFLASH_MB, LEARNIN, LEARNOUT }
	Smack write settings operation types. More...

Detailed Description

The Remote Management allows EnOcean devices to be configured and maintained through the air interface using radio or serial telegrams. Sensors or switches shall be learned into or deleted from already installed actuators or gateways which are hard to access. The Remote Management uses the SYS_EX telegrams which can be adressed using the ADT encapsulation.Before using the Remote Management module be sure to read the Remote Management_V1.2.pdf specification.The initialization of the REMAN module is done through Dolphin APIConfigurator. The generated settings are saved to the file EO3100I_CFG.h.

Enumeration Type Documentation

enum RM_LEARN_FLAG

Learn flags for RMCC remote learn.

Enumerator:

START_LEARN	Defines to enable learn mode.
NEXT_CHANNEL	Defines to jump to next chanell.
STOP_LEARN	Defines to stop the actual learn mode.
SMACK_START_SIMPLE_LEARN	Defines to start Smart Ack simple learn mode, can be applied only on modules where SMACK is implemented.
SMACK_START_ADVANCED_LEARN	Defines to start Smart Ack advanced learn mode, can be applied only on modules where SMACK is implemented.
SMACK_STOP_LEARN	Defines to stop Smart Ack learn mode, can be applied only on modules where SMACK is implemented.

enum RM_FN

Remote manager function codes.

Enumerator:

RM_NOT_DEFINED	Not definet function code, represents the null value.
RM_FN_UNLOCK	Unlock command.
RM_FN_LOCK	Lock command.
RM_FN_SET_CODE	Set security command.
RM_FN_QUERY_ID	Query ID command.
RM_FN_ACTION_COMMAND	Test command.
RM_FN_PING_COMMAND	Ping command.
RM_FN_QUERY_FUNCTION_COMMAND	Query supported RPC functions command.
RM_FN_QUERY_STATUS	Query debug status of remote manager.
RM_FN_REMOTE_LEARN	Remote learn RPC code.
RM_FN_REMOTE_CLEAR	Remote clear RPC code, structure to be defined.
RM_FN_REMOTE_WRITE	Remote write RPC code.
RM_FN_REMOTE_READ	Remote read RPC code.
RM_FN_SMACK_SETTING_READ	RPC for Smack query setting.
RM_FN_SMACK_SETTING_WRITE	RPC for Smack write setting.
RM_FN_QUERY_ID_ANS	Query ID answer.
RM_FN_QUERY_ID_ANS_EXT	Ext Query ID answer.
RM_FN_PING_COMMAND_ANS	Ping answer.
RM_FN_QUERY_FUNCTION_COMMAND_ANS	Query supported RPC functions answer.
RM_FN_QUERY_STATUS_ANS	Query status answer.
RM_FN_REMOTE_READ_ANS	Remote read answer.
RM_FN_SMACK_SETTING_ANS	RPC Smack query setting answer.
RM_FN_LEARNED_SENSORS_ANS	RPC Smack query sensor answer.

enum RM_RETURN_CODE

Return codes from RMCC and RPC functions. Values are used in Query Status commands.

Enumerator:

RM_RETURN_CODE_OK	OK return code.
RM_RETURN_CODE_WRONG_ID	Wrong target ID code.
RM_RETURN_CODE_WRONG_CODE	Wrong securty code return code.
RM_RETURN_CODE_WRONG_EEP	Wrong EEP.
RM_RETURN_CODE_WRONG_MANID	Wrong Manufacturer ID.
RM_RETURN_CODE_WRONG_DATA_SIZE	Function misses data to execute.
RM_RETURN_CODE_NO_CODE_SET	No security code set return code.
RM_RETURN_CODE_NOT_SENT	Answer / telegram not send.
RM_RETURN_CODE_RPC_FAILED	RPC failed.
RM_RETURN_CODE_MESSAGE_TIME_OUT	Previous message was chain period time-out.
RM_RETURN_CODE_TOO_LONG_MESSAGE	Too long message, the sum of to transfer data extends the internal buffer.
RM_RETURN_CODE_MESSAGE_PART_ALREADY_RECEIVED	In merge process the actual message part was already received. Indicates an possible error state.
RM_RETURN_CODE_MESSAGE_NOT_RECEIVED	Previous message was not received completly.
RM_RETURN_CODE_ADDRESS_OUT_OF_RANGE	Specified address is out of range.
RM_RETURN_CODE_DATA_SIZE_EXCEEDED	Unable to process requested data size.
RM_RETURN_CODE_WRONG_DATA	Data are not in expected range.

enum SETTINGS_TYPE

Smack read settings types - applied for the RPC RM_FN_SMACK_SETTING_READ.

Enumerator:

MB_SETTINGS	Read out mail box settings.
LEARNED_SENSORS_CONTROLLER	Read out learned sensors. Only from controller.

enum OPERATION_TYPE

Smack write settings operation types.

Enumerator:

ADDFLASH_MB	Defines to add a specified Mail Box.
DELETEFLASH_MB	Defines to delete a specified Mail Box.
LEARNIN	Defines to Learn In a specified sensor. Only controller.
LEARNOUT	Defines to Learn Out a specified sensor. Only controller.

Function Documentation

void reman_init	(	uint16 *	pu16Param,
		uint8	u8ParamToSet
	)

Initialise the remote manager module. This function must be called before the remote manager is used. It initialises the specific module variables.

Parameters:

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

Returns:: -

Note:: This function is using TIMER0 so make sure to call it only after isr_timer0Init!; If the application does store the secure code not in the flash cell given in pu16Param, then call reman_setCode after calling reman_init to set the code in RAM for the REMAN module.

void reman_setRPC	(	uint16 *	pu16RpcList,
		uint8	u8RpcCount
	)

Sets the pointer to RPC list. This information is used by query function.

Parameters:

[in]	pu16RpcList	Pointer to RPC list array
[in]	u8RpcCount	Nubmer of RPCs defined in pu16RpcList

Returns:: -

Example:

code uint16 reman_rpc[] =   {
        RM_FN_REMOTE_LEARN, RM_DEFAULTMANID,
        RM_FN_REMOTE_WRITE, RM_DEFAULTMANID,
        RM_FN_REMOTE_READ,  RM_DEFAULTMANID };
...
reman_setRPC(reman_rpc, 3);

RETURN_TYPE reman_receiveTelegram	(	TEL_RADIO_TYPE *	pu8RadioTel,
		TEL_PARAM_TYPE *	pInParam,
		uint16 *	u16FnNumber,
		uint16 *	u16DataSize
	)

Function processes radio telegrams and produces remote management messages. If one or multiple chained SYS_EX telegrams was received the reman_receiveTelegram returns OK. Then u16FnNumber is set to requected remote management function number, the u16DataSize is set to received message length. If the function receives RMC command (e.g. ping, query id, unlock, etc.) it is processed immediately (except Action RMCC). RPC and Action RMCC has to be processed by the application. The SetCode RMCC is processed inside the function but saving of the code has to be handled by the application (be sure to check out examples)!

If QueryId or Ping RMCC is received, the functions will create the answer. This answer will be send by function reman_processSend later on, because a certain delay has to be inserted between chained telegrams. The reman_processSend must be called periodically in applicaiton loop.

Parameters:

[in]	*rTel	Received telegram.
[in]	*prpInput	Input parameters structure. For more details see TEL_PARAM_TYPE

Returns:: OK Remote management message received.; NOT_VALID_PARAM The rTel is not an SYS_EX telegram or the DestinationID of prpInput does not match .; NO_RX_TEL The SEQ or SourceID of rTel does not match. During running transmisson if second remote management controller tries to communicate.

Note:: To send remote management messages the function reman_processSend needs to be called periodically.

See also:: reman_processSend

RETURN_TYPE reman_receiveTelegramController	(	TEL_RADIO_TYPE *	pu8RadioTel,
		TEL_PARAM_TYPE *	pInParam,
		uint16 *	u16FnNumber,
		uint16 *	u16RmDataSize
	)

This function has the same functionality as reman_receiveTelegram except it does not process RMCC commands. This function should be used only in reman controller application.

Parameters:

[in]	*rTel	Received telegram.
[in]	*prpInput	Input parameters structure. For more details see TEL_PARAM_TYPE

Returns:: OK Remote management message received.; NOT_VALID_PARAM The rTel is not an SYS_EX telegram or the DestinationID of prpInput does not match .; NO_RX_TEL The SEQ or SourceID of rTel does not match. During running transmisson if second remote management controller tries to communicate.

Note:: To send remote management messages the function reman_processSend needs to be called periodically.

See also:: reman_processSend

RETURN_TYPE reman_sendMessage	(	uint8 *	u8Data,
		uint16	u16DataSize,
		uint16	u16FunctionCode,
		uint8	u8SendWithDelay
	)

Function initialise the internal sending state machine. The telegram is sent after then by reman_processSend function. It also locks the whole remote management module for sending. That means all incoming telegrams are dropped until all telegrams are sent. If sending more than 4 bytes then the data is divided into multiple telegrams which are send with certain time difference one after another. This function should be use to answer RPC commands. The answer is send back to controller which send the last RPC.

Parameters:

[in]	*u8Data	Buffer where the data to be sent is stored.
[in]	*u16DataSize	Length of the *u8Data field
[in]	u16FunctionCode	The remote management function answer number.
[in]	u8SendWithDelay	TRUE if the first message has to be sent with random delay. When answering to broadcast message this has to be TRUE. Otherwise FALSE.

Returns:: OK The sending statemachine was intialised.; OUT_OF_RANGE The u16DataSize exceeded the maximal remote message length.

Note:: To send remote management messages the function reman_processSend needs to be called periodically.

See also:: reman_processSend

RETURN_TYPE reman_sendMessageController	(	uint8 *	u8Data,
		uint16	u16DataSize,
		uint16	u16FunctionCode,
		uint16	u16Manufacturer,
		uint32	u32DestinationID,
		uint8	u8SendWithDelay
	)

This function has the same functionality as reman_sendMessage but additionaly the destination ID can be specified. This function should be used only in reman controller application.

Parameters:

[in]	*u8Data	Buffer where the data to be sent is stored.
[in]	*u16DataSize	The input parameters structure. For more details see TEL_PARAM_TYPE
[in]	u16FunctionCode	The remote management function answer number.
[in]	u16Manufacturer	RPC function manufacturer. Default is RM_DEFAULTMANID.
[in]	u32DestinationID	Destination ID.
[in]	u8SendWithDelay	TRUE if the first message has to be sent with random delay. When answering to broadcast message this has to be TRUE. Otherwise FALSE.

Returns:: OK The sending statemachine was intialised.; BUFF_FULL The u16DataSize exceeded the maximal remote message length.

Note:: To send remote management messages the function reman_processSend needs to be called periodically.

See also:: reman_processSend

RETURN_TYPE reman_processSend ( )

Periodically called funtion to ensure answers to broadcast messages. The function handels the random delay whitout blocking calls.

It is nesseccaty to call the function periodically in user application.

Returns:: OK The whole remote management message was send.; TELEGRAM_WAIT Waiting random before answering the broadcast or IDX_TEL_DELAY time between two chainged telegrams.; NO_TX_TEL There are no more telegrams to send. The remote management module is not locked for sending.; NEW_TX_TEL Part of the message was actually send using radio_sendTelegram.

Note:: After calling reman_sendMessage() the remote management message is queued to be sent. In order to to send remote management message over the air it has to be split into multiple SYS_EX telegrams. This splitting and sending is handled by the reman_processSend(). The reman_processSend() has to be called periodically and each time it checks if there is a message to be send. If there is a message to be sends the reman_processSend() splits it to SYS_EX telegrams and sends it using the radio_sendTelegram().

The reman_processSend() directly calls the radio_sendTelegram() therefore in order to send remote management message it is only required to call reman_sendMessage() once and then call reman_processSend() periodically in the main loop.

In generally the remote management module (reman_* functions) can be seen as an extra layer between the application and radio_* functions. The remote management module provides a transformation from SYS_EX telegrams to remote management messages and vice versa.

Note:: To send remote management messages the function reman_processSend needs to be called periodically.; Modifying the IDX_TEL_DELAY can speed up the transmission of the chained telegrams, but the performance of the REMAN Controller or gateway (like TCM300) has to be considerd. I.e. The TCM300 in serial gateway mode with 9600 Baudrate can't process more than 58 chained SYS_EX telegrams per second. The value of 50ms is optimised for TCM300 9600 Baud. If the IDX_TEL_DELAY is smaller it is not assured it will work with all the Controllers.

void reman_getCode ( uint32 * u32Code )

Retrieves the lock code for remote management module from RAM. After the code was set by the controller the application should store this

code in flash at specfied address IDX_CODE_ADDR.

Parameters:

[out] u32Code Lock code

Returns:: -

void reman_setCode ( uint32 u32code )

Sets the lock code for remote management module. This function does only save the code in RAM and does not store in flash.

After the code was set by the controller the application should store this code in flash at specfied address IDX_CODE_ADDR or somewhere else, which is in control of the application.

Parameters:

[in] u32Code Lock code

Returns:: -

void reman_getRpcManufacturerID ( uint16 * u16RpcManufacturerID )

Retrieves the ManufacturerID for the last RPC command received.

Parameters:

[out] u16Code ManufacturerID of last RPC

Returns:: -

void reman_setError ( uint16 u16ErrorCode )

Sets the last return code of last executed functions. This information is used by query status functions. By default the last error code is set to RM_RETURN_CODE_OK.

Parameters:

[in] u16ErrorCode Error code. See RM_RETURN_CODE

Returns:: -

Functions

System defines

Enums

Detailed Description

Enumeration Type Documentation

Function Documentation