cos_safety.h File Reference

Detailed Description

This module implements the variables and callback functions for the add-on CANopen Safety. The module adds the following objects to the object dictionary:

Index	Description	Function / Variable	Configuration Symbol
1300h	GFC parameter	CosSafety_Idx1300()	COS_SRDO_NUMBER
1301h	SRDO communication parameter	CosSafetyComParameter()	COS_SRDO_NUMBER
..	..	..	..
1308h	SRDO communication parameter	CosSafetyComParameter()	COS_SRDO_NUMBER
1381h	SRDO mapping parameter	CosSafetyMapParameter()	COS_SRDO_NUMBER
..	..	..	..
1388h	SRDO mapping parameter	CosSafetyMapParameter()	COS_SRDO_NUMBER
13FEh	Configuration valid	CosSafety_Idx13FE()	COS_SRDO_NUMBER
13FFh	Safety configuration signature	CosSafety_Idx13FF()	COS_SRDO_NUMBER

Include dependency graph for cos_safety.h:

Macros
#define	COS_SAFETY_VERSION_MAJOR   1
#define	COS_SAFETY_VERSION_MINOR   4

Enumerations
enum	CosSafetyEvent_e {   eCOS_SAFETY_EVENT_APPLICATION = 1 ,   eCOS_SAFETY_EVENT_COMMUNICATION ,   eCOS_SAFETY_EVENT_DATA_STORE }
enum	CosSafetyState_e {   eCOS_SAFETY_STATE_INIT = 0x01 ,   eCOS_SAFETY_STATE_SAFE = 0xA5 ,   eCOS_SAFETY_STATE_WORK = 0xCC }

Functions
void	CosSafetyEvent (enum CosSafetyEvent_e teEventV)
enum CosSafetyState_e	CosSafetyGetState (uint32_t *pulLifeCounterV)
uint8_t	CosSafetySetMapEntries (uint8_t ubSrdoNumberV, uint8_t ubEntryNumberV, uint32_t ulMapObjectV, uint32_t ulMapObjectInvertedV)
enum CosSafetyState_e	CosSafetySrdoGetData (uint8_t ubSrdoNumberV, uint8_t *pubDestDataV)
void	CosSafetySrdoRcvDataUpdate (uint8_t ubSrdoNumberV)
enum CosSafetyState_e	CosSafetySrdoSetData (uint8_t ubSrdoNumberV, uint8_t *pubSrcDataV)
void	CosSafetySrdoTrmDataUpdate (uint8_t ubSrdoNumberV)
void	CosSafetyTriggerGfc (void)

Enumeration Type Documentation

CosSafetyEvent_e

enum CosSafetyEvent_e

The possible values for Safety events are listed in this enumeration. The event is evaluated by the function CosSafetyEvent(). All events will trigger a switch from a working state (eCOS_SAFETY_STATE_WORK) to a safe state (eCOS_SAFETY_STATE_SAFE).

Enumerator
eCOS_SAFETY_EVENT_APPLICATION	Safety event caused by application
eCOS_SAFETY_EVENT_COMMUNICATION	Safety event caused by communication failure
eCOS_SAFETY_EVENT_DATA_STORE	Safety event caused by data storage failure

CosSafetyState_e

enum CosSafetyState_e

The possible values of the CANopen Safety state machine are listed in this enumeration. The current state value can be evaluated by calling the CosSafetyGetState() function.

Enumerator
eCOS_SAFETY_STATE_INIT	State machine is in initialization state
eCOS_SAFETY_STATE_SAFE	State machine is in safe state
eCOS_SAFETY_STATE_WORK	State machine is in working state

Function Documentation

CosSafetyEvent()

void CosSafetyEvent

(

enum CosSafetyEvent_e

teEventV

)

Parameters

[in]

teEventV

Safety event reason

This function triggers the internal safety state machine. Each event will cause a transition into the safe state. The following events are covered by the CANopen protocol stack:

• eCOS_SAFETY_EVENT_COMMUNICATION
• eCOS_SAFETY_EVENT_DATA_STORE

If a failure is discovered by the application, the function is called with the parameter eCOS_SAFETY_EVENT_APPLICATION.

if (someThingGoesWrong)
{
   CosSafetyEvent(eCOS_SAFETY_EVENT_APPLICATION);
}

CosSafetyGetState()

enum CosSafetyState_e CosSafetyGetState

(

uint32_t *

pulLifeCounterV

)

Parameters

[in,out]

pulLifeCounterV

Optional life counter

Returns

State of Safety FSA

This function returns the state of the Safety FSA. It has to be called by the application cyclically. The optional pointer pulLifeCounterV allows to read the current tick value of the Safety FSA. The counter value is incremented with a period of COS_TIMER_PERIOD. If the life counter is not required the pointer can be set to 0L.

uint32_t ulMyLifeCounterT;
static uint32_t ulLastCounterS = 0;
 
if (CosSafetyGetState(&ulMyLifeCounterT) == eCOS_SAFETY_STATE_WORK)
{
   if (ulMyLifeCounterT > ulLastCounterS)
   {
      // is still alive, save life counter
      ulLastCounterS = ulMyLifeCounterT;
 
      // do some more application stuff
 
    }
}

CosSafetySetMapEntries()

uint8_t CosSafetySetMapEntries	(	uint8_t	ubSrdoNumberV,
		uint8_t	ubEntryNumberV,
		uint32_t	ulMapObjectV,
		uint32_t	ulMapObjectInvertedV
	)

Parameters

[in]	ubSrdoNumberV	SRDO number
[in]	ubEntryNumberV	Entry number
[in]	ulMapObjectV	Mapping entry for plain data
[in]	ulMapObjectInvertedV	Mapping entry for inverted data

Returns

Protocol stack error code

The function configures the mapping for a SRDO. defined by the parameter ubSrdoNumberV to the application. The first SRDO starts at 0. The parameter ubEntryNumberV defines which sub-indices of the mapping entry are configured: the value 0 configures sub-index 1 with the value of ulMapObjectV and sub-index 2 with the value of ulMapObjectInvertedV.

The function has to be called by the application before CosMgrStart() is executed.

The following code snippet shows an example SRDO mapping setup.

Index	Sub-Index	Value
1381h	00h	04h
1381h	01h	20040108h
1381h	02h	20240108h
1381h	03h	20040208h
1381h	04h	20240208h

CosSafetySetMapEntries(0, 0, 0x20040108, 0x20240108);
CosSafetySetMapEntries(0, 1, 0x20040208, 0x20240208);
 
// Now the CANopen stack can be started
CosMgrStart(ubNodeIdV, eCP_BITRATE_500K, eCP_BITRATE_NONE);

The function returns a code defined by the enumeration CosErr_e.

CosSafetySrdoGetData()

enum CosSafetyState_e CosSafetySrdoGetData	(	uint8_t	ubSrdoNumberV,
		uint8_t *	pubDestDataV
	)

Parameters

[in]	ubSrdoNumberV	SRDO number
[in]	pubDestDataV	Pointer to destination data

Returns

State of Safety FSA

See also

CosSafetySrdoGetData()

The function transfers data from the SRDO defined by the parameter ubSrdoNumberV to the application. The first SRDO starts at 0. The parameter pubDestDataV is a pointer to an array of at least 8 bytes of data (i.e. the CAN payload).

uint8_t  aubSrdoDataT[8];
aubSrdoDataT[0] = 0x11;
aubSrdoDataT[1] = 0x22;
aubSrdoDataT[2] = 0x33;
// read data from first SRDO
CosSafetySrdoGetData(0, &aubSrdoDataT[0]);

The function returns a code defined by the enumeration CosSafetyState_e.

CosSafetySrdoRcvDataUpdate()

void CosSafetySrdoRcvDataUpdate

(

uint8_t

ubSrdoNumberV

)

Parameters

[in]

ubSrdoNumberV

SRDO number

This function is called by the framework in order to update SR data which is received by the device via a SRDO. The implementation of the function is application specific. The function implementation is located in the file cos_user.c.

The following code snippet shows how to copy data from a SRDO consumer:

static uint8_t  aubSrdoDataS[8];
 
CosSafetySrdoRcvDataUpdate(uint8_t ubSrdoNumberV)
{
   CosSafetySrdoGetData(ubSrdoNumberV, &aubSrdoDataS[0]);
}

CosSafetySrdoSetData()

enum CosSafetyState_e CosSafetySrdoSetData	(	uint8_t	ubSrdoNumberV,
		uint8_t *	pubSrcDataV
	)

Parameters

[in]	ubSrdoNumberV	SRDO number
[in]	pubSrcDataV	Pointer to source data

Returns

State of Safety FSA

See also

CosSafetySrdoGetData()

The function transfers data from the application to the SRDO defined by the parameter ubSrdoNumberV. The first SRDO starts at 0. The parameter pubSrcDataV is a pointer to an array of at least 8 bytes of data (i.e. the CAN payload).

uint8_t  aubSrdoDataT[8];
aubSrdoDataT[0] = 0x11;
aubSrdoDataT[1] = 0x22;
aubSrdoDataT[2] = 0x33;
// write data to first SRDO
CosSafetySrdoSetData(0, &aubSrdoDataT[0]);

The function returns a code defined by the enumeration CosSafetyState_e.

CosSafetySrdoTrmDataUpdate()

void CosSafetySrdoTrmDataUpdate

(

uint8_t

ubSrdoNumberV

)

Parameters

[in]

ubSrdoNumberV

SRDO number

This function is called by the framework in order to update SR data which is transmitted by the device via a SRDO. The implementation of the function is application specific. The function implementation is located in the file cos_user.c.

The maximum update rate is defined by the SRDO parameter refresh-time (sub-index 2 of the SRDO communication parameter).

The following code snippet shows how to copy data into a SRDO producer:

static uint8_t  aubSrdoDataS[8];
 
CosSafetySrdoTrmDataUpdate(uint8_t ubSrdoNumberV)
{
   CosSafetySrdoSetData(ubSrdoNumberV, &aubSrdoDataS[0]);
}

CosSafetyTriggerGfc()

void CosSafetyTriggerGfc

(

void

)

This function may be called be the application to trigger a global fail-safe command (GFC). The GFC itself is NSR and shall be transmitted event-driven.

As a reaction, all other SR devices will enter the safe state.

if (someThingGoesWrong)
{
   // tell all other devices immediately there is a failure
   CosSafetyTriggerGfc();
   // trigger internal safety state machine
   CosSafetyEvent(eCOS_SAFETY_EVENT_APPLICATION);
}