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.