Detailed Description

CANopen defines communication profiles based on ISO 11898-1. The basic profiles are defined in EN 50325-4. The SRCP (Safety-related communication profile and protocols, i.e. CANopen Safety) is based on the basic profiles in EN 50325-4 and the SCL (Safety Communication Layer, EN 61784–3) specification.

The SRCP is based on the producer/consumer model. The pairing of producers and consumers is an important part of the relationship that provides the high integrity needed for SRLD (Safety-related logical device). The SCL is specified using SR (Safety-related) data objects (SRDOs). These objects are serving as the interface between the SR application objects and the link layer connections. An SRDO ensures the integrity of the safety data transfers.

The CANopen Master Functional Safety module is an optional software package for the CANopen Master protocol stack. The maximum number of SRDOs which can be processed by the CANopen Master protocol stack is defined by the symbol COM_SRDO_NUMBER.

In all functions the value range for the parameter ubSrdoNumberV is 1 to COM_SRDO_NUMBER.

Include dependency graph for com_safety.h:

Data Structures
struct	ComSrdo_s

Macros
#define	COM_SAFETY_VERSION_MAJOR 1

#define	COM_SAFETY_VERSION_MINOR 2

Enumerations
enum	ComSafetyEvent_e { eCOM_SAFETY_EVENT_APPLICATION = 1 , eCOM_SAFETY_EVENT_COMMUNICATION , eCOM_SAFETY_EVENT_DATA_STORE }

enum	ComSafetyState_e { eCOM_SAFETY_STATE_INIT = 0x01 , eCOM_SAFETY_STATE_SAFE = 0xA5 , eCOM_SAFETY_STATE_WORK = 0xCC }

enum	ComSafetySrdoDir_e { eCOM_SAFETY_SRDO_DIR_NOT_VALID = 0 , eCOM_SAFETY_SRDO_DIR_TRANSMIT , eCOM_SAFETY_SRDO_DIR_RECEIVE }

Functions
void	ComSafetyEvent (uint8_t ubNetV, enum ComSafetyEvent_e teEventV)

ComStatus_tv	ComSafetyGetConfiguration (uint8_t ubNetV, uint8_t ubNodeIdV, uint8_t ubSrdoNumberV)

uint16_t	ComSafetyGetCrcValue (ComSrdo_ts *ptsSrdoV)

ComStatus_tv	ComSafetyGetSdoStatus (uint8_t ubNetV, uint8_t ubNodeIdV, uint8_t ubSrdoNumberV, enum ComSdoStat_e *pteStatusV)

ComStatus_tv	ComSafetyGetSignature (uint8_t ubNetV, uint8_t ubNodeIdV, uint8_t ubSrdoNumberV, uint16_t *puwSignatureV)

enum ComSafetyState_e	ComSafetyGetState (uint8_t ubNetV, uint32_t *pulLifeCounterV)

ComStatus_tv	ComSafetySetConfiguration (uint8_t ubNetV, uint8_t ubNodeIdV, uint8_t ubSrdoNumberV)

ComStatus_tv	ComSafetySetConfigurationValid (uint8_t ubNetV, uint8_t ubNodeIdV)

ComStatus_tv	ComSafetySetSignature (uint8_t ubNetV, uint8_t ubNodeIdV, uint8_t ubSrdoNumberV, uint16_t uwSignatureV)

ComStatus_tv	ComSafetySetState (uint8_t ubNetV, enum ComSafetyState_e teSafetyStateV)

ComStatus_tv	ComSafetySrdoAssignMaster (uint8_t ubNetV, uint8_t ubNodeIdV, uint8_t ubSrdoNumberV)

enum ComSafetyState_e	ComSafetySrdoGetData (uint8_t ubNetV, uint8_t ubNodeIdV, uint8_t ubSrdoNumberV, uint8_t *pubDestDataV)

ComStatus_tv	ComSafetySrdoInit (uint8_t ubNetV, uint8_t ubNodeIdV, uint8_t ubSrdoNumberV, ComSrdo_ts *ptsSrdoV)

void	ComSafetySrdoRcvDataUpdate (uint8_t ubNetV, uint8_t ubNodeIdV, uint8_t ubSrdoNumberV)

ComStatus_tv	ComSafetySrdoRelease (uint8_t ubNetV, uint8_t ubNodeIdV, uint8_t ubSrdoNumberV)

enum ComSafetyState_e	ComSafetySrdoSetData (uint8_t ubNetV, uint8_t ubNodeIdV, uint8_t ubSrdoNumberV, uint8_t *pubSrcDataV)

void	ComSafetySrdoTrmDataUpdate (uint8_t ubNetV, uint8_t ubNodeIdV, uint8_t ubSrdoNumberV)

void	ComSafetyTriggerGfc (uint8_t ubNetV)

Enumeration Type Documentation

◆ ComSafetyEvent_e

enum ComSafetyEvent_e

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

Enumerator
eCOM_SAFETY_EVENT_APPLICATION	Safety event caused by application
eCOM_SAFETY_EVENT_COMMUNICATION	Safety event caused by communication failure
eCOM_SAFETY_EVENT_DATA_STORE	Safety event caused by data storage failure

◆ ComSafetySrdoDir_e

enum ComSafetySrdoDir_e

The possible values for the SRDO direction are listed in this enumeration. The direction is always seen from the devices point of view.

Enumerator
eCOM_SAFETY_SRDO_DIR_NOT_VALID	SRDO is not valid
eCOM_SAFETY_SRDO_DIR_TRANSMIT	SRDO producer
eCOM_SAFETY_SRDO_DIR_RECEIVE	SRDO consumer

◆ ComSafetyState_e

enum ComSafetyState_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 ComSafetyGetState() function.

Enumerator
eCOM_SAFETY_STATE_INIT	State machine is in initialisation state
eCOM_SAFETY_STATE_SAFE	State machine is in safe state
eCOM_SAFETY_STATE_WORK	State machine is in working state

Function Documentation

◆ ComSafetyEvent()

void ComSafetyEvent	(	uint8_t	ubNetV,
		enum ComSafetyEvent_e	teEventV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[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:

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

if (someThingGoesWrong)
{
   ComSafetyEvent(ubNetV, eCOM_SAFETY_EVENT_APPLICATION);
}

◆ ComSafetyGetConfiguration()

ComStatus_tv ComSafetyGetConfiguration	(	uint8_t	ubNetV,
		uint8_t	ubNodeIdV,
		uint8_t	ubSrdoNumberV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubNodeIdV	Node-ID value
[in]	ubSrdoNumberV	SRDO number

See also: ComSafetySetConfiguration()

Returns: Value of enumeration ComErr_e

This function is used to read the SRDO configuration parameter (Index 130x_h) and the SRDO mapping parameter (Index 138x_h) of a SR device defined by a node-ID value of ubNodeIdV. The data is copied into a ComSrdo_s structure which must have been assigned to the CANopen Safety module by ComSafetySrdoInit() in advance.

◆ ComSafetyGetCrcValue()

uint16_t ComSafetyGetCrcValue ( ComSrdo_ts * ptsSrdoV )

Parameters

[in] ptsSrdoV Pointer to SRDO structure

Returns: CRC signature value

This function calculates the CRC signature value according to the CRC generator defined in EN 50325-4 for the SRDO structure defined by the pointer ptsSrdoV.

◆ ComSafetyGetSdoStatus()

ComStatus_tv ComSafetyGetSdoStatus	(	uint8_t	ubNetV,
		uint8_t	ubNodeIdV,
		uint8_t	ubSrdoNumberV,
		enum ComSdoStat_e *	pteStatusV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubNodeIdV	Node-ID value
[in]	ubSrdoNumberV	SRDO number
[in]	pteStatusV	Pointer to SDO transfer status

Returns: Value of enumeration ComErr_e

This function evaluates the current SDO transfer status. It can be used to check if a Safety configuration data transfer has been completed (e.g. ComSafetyGetConfiguration(), ComSafetySetConfiguration(), etc). As long as the function returns a value less than eCOM_SDO_STAT_SUCCESS the data transfer is in progress.

//------------------------------------------------------------------------------------
// Wait until the SDO data transfer is completed
//
do {
   ComSafetyGetSdoStatus(eCOM_NET_1, 3, 1, &teStatusT);
} while (teStatusT < eCOM_SDO_STAT_SUCCESS);

◆ ComSafetyGetSignature()

ComStatus_tv ComSafetyGetSignature	(	uint8_t	ubNetV,
		uint8_t	ubNodeIdV,
		uint8_t	ubSrdoNumberV,
		uint16_t *	puwSignatureV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubNodeIdV	Node-ID value
[in]	ubSrdoNumberV	SRDO number
[in,out]	puwSignatureV	Pointer to SRDO signature value

Returns: Value of enumeration ComErr_e

See also: ComSafetySetSignature()

This function is used to read the Safety configuration signature value (Index 13FF_h) of a SR device with a node-ID of ubNodeIdV. The parameter ubSrdoNumberV defines the SRDO number of the SR device, the valid value range is 1 to COM_SRDO_NUMBER. The signature value is copied into the variable which is passed to the function by the pointer puwSignatureV.

The function returns immediately after the SDO request has been triggered, the status of the SDO transfer can be evaluated by calling ComSafetyGetSdoStatus().

◆ ComSafetyGetState()

enum ComSafetyState_e ComSafetyGetState	(	uint8_t	ubNetV,
		uint32_t *	pulLifeCounterV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in,out]	pulLifeCounterV	Optional life counter

Returns: State of Safety FSA

See also: ComSafetySetSate()

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 COM_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 (ComSafetyGetState(eCOM_NET_1, &ulMyLifeCounterT) == eCOM_SAFETY_STATE_WORK)
{
   if (ulMyLifeCounterT > ulLastCounterS)
   {
      // is still alive, save life counter
      ulLastCounterS = ulMyLifeCounterT;
 
      // do some more application stuff
 
    }
}

◆ ComSafetySetConfiguration()

ComStatus_tv ComSafetySetConfiguration	(	uint8_t	ubNetV,
		uint8_t	ubNodeIdV,
		uint8_t	ubSrdoNumberV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubNodeIdV	Node-ID value
[in]	ubSrdoNumberV	SRDO number

See also: ComSafetyGetConfiguration()

Returns: Value of enumeration ComErr_e

This function is used to write the SRDO configuration parameter (Index 130x_h) and the SRDO mapping parameter (Index 138x_h) to a SR device defined by a node-ID value of ubNodeIdV. The data is copied from a ComSrdo_s structure which must have been assigned to the CANopen Safety module by ComSafetySrdoInit() in advance.

The function returns immediately after the SDO request has been triggered, the status of the SDO transfer can be evaluated by calling ComSafetyGetSdoStatus().

◆ ComSafetySetConfigurationValid()

ComStatus_tv ComSafetySetConfigurationValid	(	uint8_t	ubNetV,
		uint8_t	ubNodeIdV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubNodeIdV	Node-ID value

Returns: Value of enumeration ComErr_e

This function is used to write the configuration valid parameter (Index 13FE_h) to a SR device defined by a node-ID value of ubNodeIdV.

The function returns immediately after the SDO request has been triggered, the status of the SDO transfer can be evaluated by calling ComSafetyGetSdoStatus().

◆ ComSafetySetSignature()

ComStatus_tv ComSafetySetSignature	(	uint8_t	ubNetV,
		uint8_t	ubNodeIdV,
		uint8_t	ubSrdoNumberV,
		uint16_t	uwSignatureV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubNodeIdV	Node-ID value
[in]	ubSrdoNumberV	SRDO number
[in]	uwSignatureV	SRDO signature value

Returns: Value of enumeration ComErr_e

See also: ComSafetyGetSignature()

This function is used to write the Safety configuration signature value (Index 13FF_h) to a SR device with a node-ID of ubNodeIdV. The parameter ubSrdoNumberV defines the SRDO number of the SR device, the valid value range is 1 to COM_SRDO_NUMBER. The signature value is defined by the value uwSignatureV.

The function returns immediately after the SDO request has been triggered, the status of the SDO transfer can be evaluated by calling ComSafetyGetSdoStatus().

◆ ComSafetySetState()

ComStatus_tv ComSafetySetState	(	uint8_t	ubNetV,
		enum ComSafetyState_e	teSafetyStateV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	teSafetyStateV	State of Safety FSA

Returns: Value of enumeration ComErr_e

See also: ComSafetySetSate()

This function sets the state of the Safety FSA. It has to be called by the application after all CANopen slave devices have been switched to working state in order to set the CANopen Master Safety FSA into working state.

if (allMyDevicesAreInWorkingState)
{
   ComSafetySetState(eCOM_NET_1, eCOM_SAFETY_STATE_WORK);
}

◆ ComSafetySrdoAssignMaster()

ComStatus_tv ComSafetySrdoAssignMaster	(	uint8_t	ubNetV,
		uint8_t	ubNodeIdV,
		uint8_t	ubSrdoNumberV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubNodeIdV	Node-ID value
[in]	ubSrdoNumberV	SRDO number

Returns: Value of enumeration ComErr_e

See also: ComSafetySrdoInit()

This function is used to attach a SRDO to the CANopen Master stack. In order to setup the direction of the SRDO the direction field inside the ComSrdo_s structure (ComSrdo_s::ubDirection) is evaluated. The direction is defined from the CANopen slave point of view. This means a direction value of eCOM_SAFETY_SRDO_DIR_RECEIVE will setup a Transmit SRDO on the CANopen Master.

The SRDO assignment is addressed by a node-ID value of ubNodeIdV and a SRDO number ubSrdoNumberV. The valid value range for the parameter ubSrdoNumberV is 1 to COM_SRDO_NUMBER.

◆ ComSafetySrdoGetData()

enum ComSafetyState_e ComSafetySrdoGetData	(	uint8_t	ubNetV,
		uint8_t	ubNodeIdV,
		uint8_t	ubSrdoNumberV,
		uint8_t *	pubDestDataV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubNodeIdV	Node-ID value
[in]	ubSrdoNumberV	SRDO number
[in]	pubDestDataV	Pointer to destination data

Returns: State of Safety FSA

See also: ComSafetySrdoSetData()

The function transfers data from the SRDO defined by the parameter ubSrdoNumberV to the application. The first SRDO starts at 1. 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, node-ID 4
//
ComSafetySrdoGetData(eCOM_NET_1, 4, 1, &aubSrdoDataT[0]);

The function returns a code defined by the enumeration ComSafetyState_e.

◆ ComSafetySrdoInit()

ComStatus_tv ComSafetySrdoInit	(	uint8_t	ubNetV,
		uint8_t	ubNodeIdV,
		uint8_t	ubSrdoNumberV,
		ComSrdo_ts *	ptsSrdoV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubNodeIdV	Node-ID value
[in]	ubSrdoNumberV	SRDO number
[in]	ptsSrdoV	Pointer to SRDO structure

Returns: Value of enumeration ComErr_e

See also: ComSafetySrdoRelease()

This function is used to initialise and register a SRDO structure to the CANopen Safety module. The structure is supplied by the pointer ptsSrdoV and must remain static during run-time. All data elements of the SRDO structure (ComSrdo_s) are initialised with zero.

The structure is assigned to a SR device defined by a node-ID value of ubNodeIdV and a SRDO number ubSrdoNumberV. The valid value range for the parameter ubSrdoNumberV is 1 to COM_SRDO_NUMBER.

◆ ComSafetySrdoRcvDataUpdate()

void ComSafetySrdoRcvDataUpdate	(	uint8_t	ubNetV,
		uint8_t	ubNodeIdV,
		uint8_t	ubSrdoNumberV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubNodeIdV	Node-ID value
[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 com_user.c.

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

static uint8_t  aubSrdoDataS[8];
 
ComSafetySrdoRcvDataUpdate(uint8_t ubNetV, uint8_t ubNodeIdV, uint8_t ubSrdoNumberV)
{
   ComSafetySrdoGetData(ubNetV, ubNodeIdV, ubSrdoNumberV, &aubSrdoDataS[0]);
}

◆ ComSafetySrdoRelease()

ComStatus_tv ComSafetySrdoRelease	(	uint8_t	ubNetV,
		uint8_t	ubNodeIdV,
		uint8_t	ubSrdoNumberV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubNodeIdV	Node-ID value
[in]	ubSrdoNumberV	SRDO number

Returns: Value of enumeration ComErr_e

See also: ComSafetySrdoInit()

This function is used to release a SRDO structure from the CANopen Safety module. The structure is addressed by a node-ID value of ubNodeIdV and a SRDO number ubSrdoNumberV. The valid value range for the parameter ubSrdoNumberV is 1 to COM_SRDO_NUMBER.

◆ ComSafetySrdoSetData()

enum ComSafetyState_e ComSafetySrdoSetData	(	uint8_t	ubNetV,
		uint8_t	ubNodeIdV,
		uint8_t	ubSrdoNumberV,
		uint8_t *	pubSrcDataV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubNodeIdV	Node-ID value
[in]	ubSrdoNumberV	SRDO number
[in]	pubSrcDataV	Pointer to source data

Returns: State of Safety FSA

See also: ComSafetySrdoGetData()

The function transfers data from the application to the SRDO defined by the parameter ubSrdoNumberV. The first SRDO starts at 1. 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, node-ID 5
//
ComSafetySrdoSetData(eCOM_NET_1, 5, 1, &aubSrdoDataT[0]);

The function returns a code defined by the enumeration ComSafetyState_e.

◆ ComSafetySrdoTrmDataUpdate()

void ComSafetySrdoTrmDataUpdate	(	uint8_t	ubNetV,
		uint8_t	ubNodeIdV,
		uint8_t	ubSrdoNumberV
	)

Parameters

[in]	ubNetV	CANopen Network channel
[in]	ubNodeIdV	Node-ID value
[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 com_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];
 
ComSafetySrdoTrmDataUpdate(uint8_t ubNetV, uint8_t ubNodeIdV, uint8_t ubSrdoNumberV)
{
   ComSafetySrdoSetData(ubNetV, ubNodeIdV, ubSrdoNumberV, &aubSrdoDataS[0]);
}

◆ ComSafetyTriggerGfc()

void ComSafetyTriggerGfc ( uint8_t ubNetV )

Parameters

[in] ubNetV CANopen Network channel

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
   //
   ComSafetyTriggerGfc(ubNetV);
 
   //---------------------------------------------------------------------------------
   // trigger internal safety state machine
   //
   ComSafetyEvent(ubNetV, eCOM_SAFETY_EVENT_APPLICATION);
}

Detailed Description

Data Structures

Macros

Enumerations

Functions

Enumeration Type Documentation

◆ ComSafetyEvent_e

◆ ComSafetySrdoDir_e

◆ ComSafetyState_e

Function Documentation

◆ ComSafetyEvent()

◆ ComSafetyGetConfiguration()

◆ ComSafetyGetCrcValue()

◆ ComSafetyGetSdoStatus()

◆ ComSafetyGetSignature()

◆ ComSafetyGetState()

◆ ComSafetySetConfiguration()

◆ ComSafetySetConfigurationValid()

◆ ComSafetySetSignature()

◆ ComSafetySetState()

◆ ComSafetySrdoAssignMaster()

◆ ComSafetySrdoGetData()

◆ ComSafetySrdoInit()

◆ ComSafetySrdoRcvDataUpdate()

◆ ComSafetySrdoRelease()

◆ ComSafetySrdoSetData()

◆ ComSafetySrdoTrmDataUpdate()

◆ ComSafetyTriggerGfc()