Emergency

The emergency component provides an interface to the emergency history in the object dictionary and handles the emergency message transmission to the CANopen network.

Module Context

classDiagram
  CO_NODE o-- CO_EMCY : Node
  CO_EMCY_TBL o-- CO_EMCY : Root
  CO_EMCY_HIST *-- CO_EMCY : Hist
  class CO_EMCY {
    -uint8_t Cnt
    -uint8_t Err
    +COEmcyClr(error)
    +COEmcyCnt() int16_t
    +COEmcyGet(error) int16_t
    +COEmcyHistReset()
    +COEmcyReset(silent)
    +COEmcySet(error, user)
  }

Structure Data

The class CO_EMCY is defined within co_emcy.h and is responsible for emergency management functions. The following data members are in this class:

Data Member	Type	Description
Cnt[]	uint8_t	error register object entry bit counters
Err[]	uint8_t	individual emergency status storage
Hist	CO_EMCY_HIST	emergency history management object
Node	CO_NODE*	pointer to parent node
Root	CO_EMCY_TBL*	pointer to application emergency table

Info

The data within this structure must never be manipulated without the corresponding class member functions. This can lead to unpredictable behavior of the node.

Member Functions

The following table describes the API functions of the emergency module. These functions are implemented within the source file: co_emcy.c/h

COEmcyClr()

The EMCY message is transmitted if the error was previously detected.

Prototype

void COEmcyClr(CO_EMCY *emcy, uint8_t error);

Arguments

Parameter	Description
emcy	pointer to EMCY object
error	error code identifier in application EMCY table

Returned Value

• none

Example

The following example demonstrates the clearing of a possible detected emergency event APP_EMCY_2 within the application of the CANopen node AppNode.

  :
COEmcyClr(&(AppNode.Emcy), APP_EMCY_2);
  :

Note

The emergency identifier APP_EMCY_2 must be defined within the application-specific configuration.

COEmcyCnt()

When calling this function, all EMCY error status will stay unchanged.

Prototype

int16_t COEmcyCnt(CO_EMCY *emcy);

Arguments

Parameter	Description
emcy	pointer to EMCY object

Returned Value

• >=0 : success with the number of currently detected EMCY errors
• <0 : an error is detected inside of this function

Example

The following example calculates the current number of detected emergency events within the application of the CANopen node AppNode.

int16_t emcy;
  :
emcy = COEmcyCnt(&(AppNode.Emcy));
if (emcy < 0) {

  /* error handling */

} else {

  /* emcy holds number of detected emergencies */

}
  :

COEmcyGet()

When calling this function, the EMCY error status will stay unchanged.

Prototype

int16_t COEmcyGet(CO_EMCY *emcy, uint8_t error);

Arguments

Parameter	Description
emcy	pointer to EMCY object
error	error code identifier in application EMCY table

Returned Value

• =0 : success with error is not detected
• =1 : success with an error was detected before
• <0 : an error is detected inside of this function

Example

The following example reads the current status of a possible detected emergency event APP_EMCY_2 within the application of the CANopen node AppNode.

int16_t warning;
  :
warning = COEmcyGet(&(AppNode.Emcy), APP_EMCY_2);
if (warning < 0) {

  /* error handling */

} else {

  /* warning holds current emergency status */

}
  :

Note

The emergency identifier APP_EMCY_2 must be defined within the application-specific configuration.

COEmcyHistReset()

There is no EMCY message transmission due to this function call.

Prototype

void COEmcyHistReset(CO_EMCY *emcy);

Arguments

Parameter	Description
emcy	pointer to EMCY object

Returned Value

• none

Example

The following example clears all emergency history entries within the object dictionary of the CANopen node AppNode.

  :
COEmcyHistReset(&(AppNode.Emcy));
  :

COEmcyReset()

The EMCY message transmission can be suppressed by setting the parameter silent to 1.

Prototype

void COEmcyReset(CO_EMCY *emcy, uint8_t silent);

Arguments

Parameter	Description
emcy	pointer to EMCY object
silent	disables the EMCY message transmission for the state changes, made by this function

Returned Value

• none

Example

The following example clears all detected emergency within the application of the CANopen node AppNode. The corresponding emergency state change messages will be sent.

  :
COEmcyReset(&(AppNode.Emcy), 0);
  :

COEmcySet()

The EMCY message is transmitted if the error is detected for the first time. The given manufacturer-specific fields are optional, e.g. the pointer may be 0 to set all manufacturer-specific values to 0.

Prototype

void COEmcySet(CO_EMCY *emcy, uint8_t err, CO_EMCY_USR *user);

Arguments

Parameter	Description
emcy	pointer to EMCY object
err	error code identifier in application EMCY table
user	manufacturer-specific fields in EMCY history and/or EMCY message

Returned Value

• none

Example

The following example demonstrates the detection of an emergency event APP_EMCY_2 within the application of the CANopen node AppNode. The specific user information data for this event is: 0x1234567890.

CO_EMCY_USR usr;
  :
usr.Emcy[0] = 0x12;
usr.Emcy[1] = 0x34;
usr.Emcy[2] = 0x56;
usr.Emcy[3] = 0x78;
usr.Emcy[4] = 0x90;
COEmcySet(&(AppNode.Emcy), APP_EMCY_2, &usr);
  :

Note

The specific user information data field is optional. If not used, the last parameter during calling COEmcySet() can be 0 (zero). The emergency identifier APP_EMCY_2 must be defined within the application-specific configuration.