CANopen Emergency protocol. More...

Collaboration diagram for Emergency:

Topics
	CANopen Error register


	CANopen Error code


	Error status bits

Files
file	CO_Emergency.h
	CANopen Emergency protocol.

Data Structures
struct	CO_EM_fifo_t
	Fifo buffer for emergency producer and error history. More...

struct	CO_EM_t
	Emergency object. More...

Macros
#define	CO_errorReport(em, errorBit, errorCode, infoCode) CO_error(em, true, errorBit, errorCode, infoCode)
	Report error condition, for description of parameters see CO_error.

#define	CO_errorReset(em, errorBit, infoCode) CO_error(em, false, errorBit, CO_EMC_NO_ERROR, infoCode)
	Reset error condition, for description of parameters see CO_error.

Functions
CO_ReturnError_t	CO_EM_init (CO_EM_t em, CO_CANmodule_t CANdevTx, const OD_entry_t OD_1001_errReg, CO_EM_fifo_t fifo, uint8_t fifoSize, OD_entry_t OD_1014_cobIdEm, uint16_t CANdevTxIdx, OD_entry_t OD_1015_InhTime, OD_entry_t OD_1003_preDefErr, OD_entry_t OD_statusBits, CO_CANmodule_t CANdevRx, uint16_t CANdevRxIdx, const uint8_t nodeId, uint32_t errInfo)
	Initialize Emergency object.

void	CO_EM_initCallbackPre (CO_EM_t em, void object, void(pFunctSignal)(void object))
	Initialize Emergency callback function.

void	CO_EM_initCallbackRx (CO_EM_t em, void(pFunctSignalRx)(const uint16_t ident, const uint16_t errorCode, const uint8_t errorRegister, const uint8_t errorBit, const uint32_t infoCode))
	Initialize Emergency received callback function.

void	CO_EM_process (CO_EM_t em, bool_t NMTisPreOrOperational, uint32_t timeDifference_us, uint32_t timerNext_us)
	Process Error control and Emergency object.

void	CO_error (CO_EM_t *em, bool_t setError, const uint8_t errorBit, uint16_t errorCode, uint32_t infoCode)
	Set or reset error condition.

static bool_t	CO_isError (CO_EM_t *em, const uint8_t errorBit)
	Check specific error condition.

static uint8_t	CO_getErrorRegister (CO_EM_t *em)
	Get error register.

Detailed Description

CANopen Emergency protocol.

Error control and Emergency is used for control internal error state and for sending a CANopen Emergency message.

In case of error condition stack or application calls CO_errorReport() function with indication of the error. Specific error condition is reported (with CANopen Emergency message) only the first time after it occurs. Internal state of specific error condition is indicated by internal bitfield variable, with space for maximum CO_CONFIG_EM_ERR_STATUS_BITS_COUNT bits. Meaning for each bit is described by Error status bits. Specific error condition can be reset by CO_errorReset() function. In that case Emergency message is sent with CO_EM_NO_ERROR indication.

Some error conditions are informative and some are critical. Critical error conditions set the corresponding bit in CANopen Error register. Critical error conditions for generic error are specified by CO_CONFIG_ERR_CONDITION_GENERIC macro. Similar macros are defined for other error bits in in CANopen Error register.

Emergency producer

If CO_CONFIG_EM has CO_CONFIG_EM_PRODUCER enabled, then CANopen Emergency message will be sent on each change of any error condition. Emergency message contents are:

Byte	Description
0..1	CANopen Error code
2	CANopen Error register
3	Index of error condition (see Error status bits).
4..7	Additional informative argument to CO_errorReport() function.

Error history

If CO_CONFIG_EM has CO_CONFIG_EM_HISTORY enabled, then latest errors can be read from Pre Defined Error Field (object dictionary, index 0x1003). Contents corresponds to bytes 0..3 from the Emergency message.

Emergency consumer

If CO_CONFIG_EM has CO_CONFIG_EM_CONSUMER enabled, then callback can be registered by CO_EM_initCallbackRx() function.

Function Documentation

◆ CO_EM_init()

CO_ReturnError_t CO_EM_init	(	CO_EM_t *	em,
		CO_CANmodule_t *	CANdevTx,
		const OD_entry_t *	OD_1001_errReg,
		CO_EM_fifo_t *	fifo,
		uint8_t	fifoSize,
		OD_entry_t *	OD_1014_cobIdEm,
		uint16_t	CANdevTxIdx,
		OD_entry_t *	OD_1015_InhTime,
		OD_entry_t *	OD_1003_preDefErr,
		OD_entry_t *	OD_statusBits,
		CO_CANmodule_t *	CANdevRx,
		uint16_t	CANdevRxIdx,
		const uint8_t	nodeId,
		uint32_t *	errInfo )

Initialize Emergency object.

Function must be called in the communication reset section.

Parameters

	em	This object will be initialized.
	fifo	Fifo buffer for emergency producer and error history. It must be defined externally. Its size must be capacity+1. See also CO_EM_t, fifo.
	fifoSize	Size of the above fifo buffer. It is usually equal to the length of the OD array 0x1003 + 1. If fifoSize is smaller than 2, then emergency producer and error history will not work and 'fifo' may be NULL.
	CANdevTx	CAN device for Emergency transmission.
	OD_1001_errReg	OD entry for 0x1001 - "Error register", entry is required, without IO extension.
	OD_1014_cobIdEm	OD entry for 0x1014 - "COB-ID EMCY", entry is required, IO extension is required.
	CANdevTxIdx	Index of transmit buffer in the above CAN device.
	OD_1015_InhTime	OD entry for 0x1015 - "Inhibit time EMCY", entry is optional (can be NULL), IO extension is optional for runtime configuration.
	OD_1003_preDefErr	OD entry for 0x1003 - "Pre-defined error field". Emergency object has own memory buffer for this entry. Entry is optional, IO extension is required.
	OD_statusBits	Custom OD entry for accessing errorStatusBits from CO_EM_t. Entry must have variable of size (CO_CONFIG_EM_ERR_STATUS_BITS_COUNT/8) bytes available for read/write access on subindex 0. Emergency object has own memory buffer for this entry. Entry is optional, IO extension is required.
	CANdevRx	CAN device for Emergency consumer reception.
	CANdevRxIdx	Index of receive buffer in the above CAN device.
	nodeId	CANopen node ID of this device (for default emergency producer)
[out]	errInfo	Additional information in case of error, may be NULL.

Returns: CO_ReturnError_t CO_ERROR_NO in case of success.

◆ CO_EM_initCallbackPre()

void CO_EM_initCallbackPre	(	CO_EM_t *	em,
		void *	object,
		void(*	pFunctSignal )(void *object) )

Initialize Emergency callback function.

Function initializes optional callback function, which should immediately start processing of CO_EM_process() function. Callback is called from CO_errorReport() or CO_errorReset() function. Those functions are fast and may be called from any thread. Callback should immediately start mainline thread, which calls CO_EM_process() function.

Parameters

em	This object.
object	Pointer to object, which will be passed to pFunctSignal(). Can be NULL
pFunctSignal	Pointer to the callback function. Not called if NULL.

◆ CO_EM_initCallbackRx()

void CO_EM_initCallbackRx	(	CO_EM_t *	em,
		void(*	pFunctSignalRx )(const uint16_t ident, const uint16_t errorCode, const uint8_t errorRegister, const uint8_t errorBit, const uint32_t infoCode) )

Initialize Emergency received callback function.

Function initializes optional callback function, which executes after error condition is received.

ident argument from callback contains CAN-ID of the emergency message. If ident == 0, then emergency message was sent from this device.

Remarks: Depending on the CAN driver implementation, this function is called inside an ISR or inside a mainline. Must be thread safe.

Parameters

em	This object.
pFunctSignalRx	Pointer to the callback function. Not called if NULL.

◆ CO_EM_process()

void CO_EM_process	(	CO_EM_t *	em,
		bool_t	NMTisPreOrOperational,
		uint32_t	timeDifference_us,
		uint32_t *	timerNext_us )

Process Error control and Emergency object.

Function must be called cyclically. It verifies some communication errors, calculates OD object 0x1001 - "Error register" and sends emergency message if necessary.

Parameters

	em	This object.
	NMTisPreOrOperational	True if this node is NMT_PRE_OPERATIONAL or NMT_OPERATIONAL state.
	timeDifference_us	Time difference from previous function call in [microseconds].
[out]	timerNext_us	info to OS - see CO_process().

◆ CO_error()

void CO_error	(	CO_EM_t *	em,
		bool_t	setError,
		const uint8_t	errorBit,
		uint16_t	errorCode,
		uint32_t	infoCode )

Set or reset error condition.

Function can be called on any error condition inside CANopen stack or application. Function first checks change of error condition (setError is true and error bit wasn't set or setError is false and error bit was set before). If changed, then Emergency message is prepared and record in history is added. Emergency message is later sent by CO_EM_process() function.

Function is short and thread safe.

Parameters

em	Emergency object.
setError	True if error occurred or false if error resolved.
errorBit	from Error status bits.
errorCode	from CANopen Error code.
infoCode	32 bit value is passed to bytes 4...7 of the Emergency message. It contains optional additional information.

◆ CO_isError()

static bool_t CO_isError	(	CO_EM_t *	em,
		const uint8_t	errorBit )

inlinestatic

Check specific error condition.

Function returns true, if specific internal error is present.

Parameters

em	Emergency object.
errorBit	from Error status bits.

Returns: true if Error is present.

◆ CO_getErrorRegister()

static uint8_t CO_getErrorRegister ( CO_EM_t * em )

inlinestatic

Get error register.

Parameters

em	Emergency object.

Returns: Error register or 0 if doesn't exist.

Topics

Files

Data Structures

Macros

Functions

Detailed Description

Emergency producer

Error history

Emergency consumer

Function Documentation

◆ CO_EM_init()

◆ CO_EM_initCallbackPre()

◆ CO_EM_initCallbackRx()

◆ CO_EM_process()

◆ CO_error()

◆ CO_isError()

◆ CO_getErrorRegister()