Collaboration diagram for MISC functions:

Functions
void	misc_init ()
RETURN_TYPE	misc_packetToRadio (PACKET_SERIAL_TYPE pu8packet, TEL_RADIO_TYPE pu8radio, TEL_PARAM_TYPE *pu8param)
RETURN_TYPE	misc_radioToPacket (TEL_RADIO_TYPE pu8radio, TEL_PARAM_TYPE pu8param, PACKET_SERIAL_TYPE *pu8packet)
void	misc_rndInit (uint16 u16Seed)
uint8	misc_rndGet ()
void	misc_getId (uint32 *pu32ID)
uint8	misc_isLocalId (uint32 *u32ID)
void	misc_getStackReserve (uint8 *pu8StackAval)
void	misc_readBaseId (uint32 *pu32BaseID)
RETURN_TYPE	misc_setBaseId (uint32 u32BaseID)
uint8 xdata *	misc_getID2 (TEL_RADIO_TYPE2 xdata rTel2, uint8 xdata u8IDLength, uint8 xdata *u8DestIDLength)
uint8	misc_getRORG2 (TEL_RADIO_TYPE2 xdata *rTel2)
uint8	misc_radio2ToMessage (TEL_RADIO_TYPE2 xdata rTel2, TEL_PARAM_TYPE2 xdata pTel2, MESSAGE_TYPE xdata *msg)
uint8	misc_messageToRadio2 (MESSAGE_TYPE xdata msg, TEL_RADIO_TYPE2 xdata rTel2, TEL_PARAM_TYPE2 xdata *pTel2)
uint8	misc_packetToRadio2 (PACKET_SERIAL_TYPE pu8packet, TEL_RADIO_TYPE2 xdata rTel2, TEL_PARAM_TYPE2 xdata *pu8param)
uint8	misc_radio2ToPacket (TEL_RADIO_TYPE2 xdata rTel2, TEL_PARAM_TYPE2 xdata pTel2, PACKET_SERIAL_TYPE *pu8packet)
void	misc_getApiVersion (uint8 *pu8Ver)
RETURN_TYPE	misc_radio2ToRadio1 (TEL_RADIO_TYPE2 rTel2, TEL_PARAM_TYPE2 pTel2, TEL_RADIO_TYPE rTel1, TEL_PARAM_TYPE pTel1)

Detailed Description

The MISC group contains miscellaneous functions and tools like:

random number generation
ERP to ESP2 conversion and vice-vers

Function Documentation

void misc_init ( )

Miscalaneous API initialisation. This function enables all the interrupt - it has to be called as the last init function.

Parameters:

-

Returns:: OK Telegram conversion succesful

RETURN_TYPE misc_packetToRadio	(	PACKET_SERIAL_TYPE *	pu8packet,
		TEL_RADIO_TYPE *	pu8radio,
		TEL_PARAM_TYPE *	pu8param
	)

Converts a serial packet to a radio telegram.

Parameters:

[in]	*pu8packet	Pointer to a packet
[out]	*pu8radio	Pointer to a radio telegram.
[out]	*pu8param	Pointer to a radio telegram parameter structure.

Returns:: OK Telegram conversion succesful; NOT_VALID_TEL Conversion failed. The packet does not contains radio telegram or the data length mismatch.

See also:: misc_radioToPacket, esp3_page, erp_page

RETURN_TYPE misc_radioToPacket	(	TEL_RADIO_TYPE *	pu8radio,
		TEL_PARAM_TYPE *	pu8param,
		PACKET_SERIAL_TYPE *	pu8packet
	)

Converts a radio telegram to a serial packet. Copies radio telegram + telegram param to packet data buffer.

Parameters:

[in]	*pu8radio	Pointer to a radio telegram.
[in]	*pu8param	Pointer to a radio telegram parameter structure.
[out]	*pu8packet	Pointer to a packet

Returns:: OK Telegram conversion succesful; NOT_VALID_TEL Conversion failed. The radio telegram length mismatch.

Note:: Make sure that the size of the data buffer of the packet is at least 27 bytes

See also:: misc_packetToRadio, esp3_page, erp_page

void misc_rndInit ( uint16 u16Seed )

Initialises pseudo random bit stream. Function uses u16Seed to initialise the function's random-number generator, giving it a new seed value.

Parameters:

[in] u16Seed Seed value for pseudo-random generator.

Returns:: -

Note:: This function need not to be called, because it will automaticaly be called when using misc_init(). But then always the same series of random values will be created after reset. If you want to have different random series you have to call this function once with your own seed value, which should be always different. In an ULP application with deep sleep you can f.e. save the seed in RAM0 and create the next seed with random value. Example:

// Do not forget to initialise ram0 seek variable with sensefull init value at first power on reset!
typedef struct
{
    union
    {
        uint16  u16Seed;
        struct
        {
            uint8   u8SeedHi;
            uint8   u8SeedLo;
        } seed;
    } seed;
} RAM0_SHADOW;
RAM0_SHADOW         data    sctgram0;
mem_readRAM0((uint8*)&sctgram0, 0x00, sizeof(RAM0_SHADOW));
// Initialise random generator and next seed
misc_rndInit(sctgram0.seed.u16Seed);
do
{
    sctgram0.seed.seed.u8SeedLo = misc_rndGet()+19;
    sctgram0.seed.seed.u8SeedHi = misc_rndGet()+7;
} while (sctgram0.seed.u16Seed == 0);
mem_writeRAM0((uint8*)&sctgram0, 0x00, sizeof(RAM0_SHADOW));

Note:: The first random value, which is returned by misc_rndGet, is always the lower byte of the given seed value! When using the upper algorithm to calculate a new seed value at each reset, then it could be, that the seed values will repeat after a while, depending of the amound of misc_rndGet calls. To be sure, always to start with a really random value, it is recommended, to use analog measurement noise to feed the misc_rndInit function using the returned values of io_ulpMeasAnalog function, or, if radio is switched on, the io_getAnalogRnd function to use as random generator.
If it is no problem to always generate the same series of random numbers, the function misc_rndInit should never be used.; 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:: misc_rndGet

uint8 misc_rndGet ( )

Returns an 8-bit random number. If you want different series of random values after reset, it is recommended to call misc_rndInit function first with different seek values to initialise the random number generator.

Parameters:

-

Returns:: uint8 random value

Note:: This function will also be used by the Dolphin API itself!; 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:: misc_rndInit.

void misc_getId ( uint32 * pu32ID )

Returns the 32-bit unique ID of this Chip

Parameters:

[out] *pu32ID Pointer to ID

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!

uint8 misc_isLocalId ( uint32 * u32ID )

Checks the 32-bit unique ID of this Chip with param.

Parameters:

[in] *u32ID Pointer to ID

Returns:: uint8 true (1) match false (0) no match

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!

void misc_getStackReserve ( uint8 * pu8StackAval )

This function gets the available stack space in bytes. This value shows not the current stack space but the information how many bytes were already used by the stack pointer during the application execution. This function can be used for debug purposes in the APP. If this value is very small -> around 3,4 bytes there is a high risk of stack overflow. Prior using this function the interanl data has to be initialised to 0x00. This can be set up in the startup.a51 file.

Parameters:

[out] *pu8StackAval Pointer to the number of available bytes for stack.

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:: Stack Analysis

void misc_readBaseId ( uint32 * pu32BaseID )

Returns the base ID.

Parameters:

[out] pu32BaseID Pointer 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 misc_setBaseId ( uint32 u32BaseID )

Stores the base ID.

Parameters:

[in] u32BaseID base 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.

uint8 xdata* misc_getID2	(	TEL_RADIO_TYPE2 xdata *	rTel2,
		uint8 xdata *	u8IDLength,
		uint8 xdata *	u8DestIDLength
	)

Returns the ID(s) information in a ERP2 telegram.

Parameters:

[in]	rTel2	ERP2 telegram to get the ID(s) information from
[out]	u8IDLength	ORIGITNATOR-ID field length
[out]	u8DestIDLength	DESTINATION-ID field length

Returns:: NULL Telegram HEADER field bits 7..5 contain a not valid code; Amount telegram bytes. For telegram shorter than 6 bytes, which do not contain ID.; ORIGINATOR-ID address. For correct telegrams with length > 6 bytes.

uint8 misc_getRORG2 ( TEL_RADIO_TYPE2 xdata * rTel2 )

Returns the R-ORG code of the ERP2 telegram.

Parameters:

[in] rTel2 ERP2 telegram to get R-ORG information from

Returns:: R-ORG Telegram R-ORG value

uint8 misc_radio2ToMessage	(	TEL_RADIO_TYPE2 xdata *	rTel2,
		TEL_PARAM_TYPE2 xdata *	pTel2,
		MESSAGE_TYPE xdata *	msg
	)

Converts ERP2 radio telegram to message. This function is helpful when working with security module. The sec_ functions only works with MESSAGE_TYPE.

Parameters:

[in]	rTel2	ERP2 telegram
[in]	pTel2	ERP2 telegram parameters
[out]	msg	Output message

Returns:: OK Conversion successful

See also:: misc_messageToRadio2

uint8 misc_messageToRadio2	(	MESSAGE_TYPE xdata *	msg,
		TEL_RADIO_TYPE2 xdata *	rTel2,
		TEL_PARAM_TYPE2 xdata *	pTel2
	)

Converts ERP2 radio telegram to message. This function is helpful when working with security module. The sec_ functions only works with MESSAGE_TYPE.

Parameters:

[in]	msg	Message
[out]	rTel2	ERP2 telegram
[out]	pTel2	ERP2 telegram parameters

Returns:: OK Conversion successful

See also:: misc_radio2ToMessage

uint8 misc_packetToRadio2	(	PACKET_SERIAL_TYPE *	pu8packet,
		TEL_RADIO_TYPE2 xdata *	rTel2,
		TEL_PARAM_TYPE2 xdata *	pu8param
	)

Converts a serial packet type 0x0A to an ERP2 telegram.

Parameters:

[in]	*pu8packet	Pointer to a packet
[out]	*rTel2	Pointer to a ERP2 telegram
[out]	*pu8param	Pointer to a radio telegram parameter structure

Returns:: OK Telegram conversion successful; NOT_VALID_TEL Conversion failed. The packet does not contains radio telegram or the data length mismatch.

See also:: misc_radio2ToPacket

uint8 misc_radio2ToPacket	(	TEL_RADIO_TYPE2 xdata *	rTel2,
		TEL_PARAM_TYPE2 xdata *	pTel2,
		PACKET_SERIAL_TYPE *	pu8packet
	)

Converts a ERP2 telegram to a serial packet type 0x0A. Copies radio telegram + telegram param to packet data buffer.

Parameters:

[in]	*rTel2	Pointer to a radio telegram.
[in]	*pTel2	Pointer to a radio telegram parameter structure.
[out]	*pu8packet	Pointer to a packet

Returns:: OK Telegram conversion successful; NOT_VALID_TEL Conversion failed. The radio telegram length mismatch.

Note:: Make sure that the size of the data buffer of the packet is at least 64 bytes

See also:: misc_packetToRadio2

void misc_getApiVersion ( uint8 * pu8Ver )

Returns API version number.

Parameters:

[out] pu8Ver API software version number in 4 byte code.

Returns:: -

Note:: The function writes in the address pointed by the pointer and in the 3 consecutive byte addresses. Be sure pu8Ver points to an array or variable of at least 4 bytes of length.

RETURN_TYPE misc_radio2ToRadio1	(	TEL_RADIO_TYPE2 *	rTel2,
		TEL_PARAM_TYPE2 *	pTel2,
		TEL_RADIO_TYPE *	rTel1,
		TEL_PARAM_TYPE *	pTel1
	)

Converts a ERP2 telegram structure to an ERP1 radio telegram structure.

Parameters:

[in]	*rTel2	Pointer to an ERP2 telegram.
[in]	*pTel2	Pointer to an ERP2 telegram parameter structure.
[out]	*rTel1	Pointer to an ERP1 telegram.
[out]	*pTel1	Pointer to an ERP1 telegram parameter structure.

Returns:: OK Telegram conversion successful; NO_RX_TEL Conversion failed. Not possible to converThe radio telegram length mismatch.

See also:: misc_packetToRadio2

Functions

Detailed Description

Function Documentation