Callback Functions

Callback Functions

This section describes the configuration definitions and function implementation of all possible callback functions. The presented source code lines represents the default configuration. For details on the callback function behavior, parameters, types and return values see the description of the default implementations of the callback functions.

CO_CB_FATAL_ERR_EN

#define CO_CB_FATAL_ERROR_EN    0

Setting this definition to 1 enables the application specific hook function for fatal error handling. This function has to be implemented somewhere in the application project. The function prototype is:

void CO_NodeFatalError(void);

This hook function is called after detecting a fatal error within the stack. Typically reasons for calling this functions are configuration errors or programming errors when using the API. The function is intended to allow the implementation of a pre-defined shutdown sequence and setting the device in a safety state.

The default implementation, which is used when setting this define to 0, will stop execution with an endless loop. It is highly recommended to implement an application specific version of this function.

void CO_NodeFatalError(void)
{
    for (;;);
}

CO_CB_PARA_LOAD_EN

#define CO_CB_PARA_LOAD_EN      0

Setting this definition to 1 enables the application specific hook function for loading parameters from NVM memory. This function has to be implemented somewhere in the application project. The function prototype is:

CPU_INT16S CO_ParaLoad(CO_PARA *pg);

This hook function is called during reset and power-up events, including the NMT reset node and reset communication request. The function is intended to access the NVM and setting the parameter variables to the stored values.

Note: This function requires the enabled parameter support (see CO_OBJ_PARA.EN).

The default implementation, which is used when setting this define to 0, will initialize the given parameter group with the specified factory default values.

CPU_INT16S CO_ParaLoad(CO_PARA *pg)
{
    CPU_INT08U *ident;
    CPU_INT08U *ptr;
    CPU_INT08U *src;
    CPU_INT32U  num;
    CPU_INT16S  result = 0; 
 
    ident = (CPU_INT08U*)pg->Ident;
    ptr   = pg->Start;
    src   = pg->Default;
    for (num = 0; num < pg->Size; num++) {
        *ptr = *src;
        ptr++;
        src++;
    }
    return (result);
}

The callback parameter and return value are summarized in the following table:

CO_CB_PARA_SAVE_EN

#define CO_CB_PARA_SAVE_EN      0

Setting this definition to 1 enables the application specific hook function for storing parameters in NVM memory. This function has to be implemented somewhere in the application project. The function prototype is:

CPU_INT16S CO_ParaSave(CO_PARA *pg);

This hook function is called during storing a parameter group. The function is intended to save the parameter variable values to the NVM.

Note: This function requires the enabled parameter support (see CO_OBJ_PARA_EN).

The default implementation, which is used when setting this define to 0, will do nothing.

CPU_INT16S CO_ParaSave(CO_PARA *pg)
{
    return (0);
}

The callback parameter and return value are summarized in the following table:

CO_CB_PARA_DEFAULT_EN

#define CO_CB_PARA_DEFAULT_EN   0

Setting this definition to 1 enables the application specific hook function for restoring the factory default values for the parameter group. This function has to be implemented somewhere in the application project. The function prototype is:

CPU_INT16S CO_ParaDefault(CO_PARA *pg);

This hook function is called during the restoring a parameter group event. The function is intended to restore the default parameter variable values within the NVM.

Note: This function requires the enabled parameter support (see CO_OBJ_PARA.EN).

The default implementation, which is used when setting this define to 0, will initialize the given parameter group with the specified factory default values.

CPU_INT16S CO_ParaDefault(CO_PARA *pg)
{
    CPU_INT08U *ident;
    CPU_INT08U *ptr;
    CPU_INT08U *src;
    CPU_INT32U  num;
    CPU_INT16S  result = 0; 
 
    ident = (CPU_INT08U*)pg->Ident;
    ptr   = pg->Start;
    src   = pg->Default;
    for (num = 0; num < pg->Size; num++) {
        *ptr = *src;
        ptr++;
        src++;
    }
    return (result);
}

The callback parameter and return value are summarized in the following table:

CO_CB_IF_RECEIVE_EN

#define CO_CB_IF_RECEIVE_EN     0

Setting this definition to 1 enables the application specific hook function for handling the CAN frames, which are not consumed (e.g. used) by the CANopen stack. This function has to be implemented somewhere in the application project. The function prototype is:

void CO_IfReceive(CO_IF_FRM *frm);

This hook function is called after processing a received CAN frame within the receive task, and the CAN frame is not matching any CANopen CAN frame. The function is intended to allow a proprietary customer protocol in parallel of the standard CANopen communication.

The default implementation, which is used when setting this define to 0, will ignore the additional CAN messages.

void CO_IfReceive(CO_IF_FRM *frm)
{
    (void)frm;
}

The callback parameter and return value are summarized in the following table:

CO_CB_TPDO_TRANSMIT_EN

#define CO_CB_TPDO_TRANSMIT_EN  0

Setting this definition to 1 enables the application specific hook function for modifying the PDO CAN frames before transmission. This function has to be implemented somewhere in the application project. The function prototype is:

void CO_TPdoTransmit(CO_IF_FRM *frm);

This hook function is called just before transmission of the build transmit PDO CAN frame. The function is intended to allow a 'last minute' customer specific modification on the TPDO.

The default implementation, which is used when setting this define to 0, will do nothing.

void CO_TPdoTransmit(CO_IF_FRM *frm)
{
    (void)frm;
}

The callback parameter and return value are summarized in the following table:

CO_CB_RPDO_RECEIVE_EN

#define CO_CB_RPDO_RECEIVE_EN   0

Setting this definition to 1 enables the application specific hook function for checking, filtering or modifying the CAN frames of a received PDO. This function has to be implemented somewhere in the application project. The function prototype is:

CPU_INT16S CO_RPdoReceive(CO_IF_FRM *frm);

This hook function is called after the reception of a RPDO CAN frame. The function is intended to allow a filter mechanism or modifications on the RPDO before distribution of the CAN frame into the CANopen stack.

The default implementation, which is used when setting this define to 0, will do nothing.

CPU_INT16S CO_RPdoReceive(CO_IF_FRM *frm)
{
    (void)frm;
    return (0);
}

The callback parameter and return value are summarized in the following table:

CO_CB_NMT_CHANGE_EN

#define CO_CB_NMT_CHANGE_EN   0

Setting this definition to 1 enables the application specific hook function for performing application specific actions on NMT mode changes. This function has to be implemented somewhere in the application project. The function prototype is:

void CO_NmtModeChange(CO_NMT *nmt, CO_MODE mode);

This hook function is called during the CANopen activities for a specific NMT mode change. The function is intended to allow the application to perform specific functions on NMT mode change events from the CANopen network (e.g. Reset, Stop, etc..).

The default implementation, which is used when setting this define to 0, will do nothing.

void CO_NmtModeChange(CO_NMT *nmt, CO_MODE mode)
{
    (void)nmt;
    (void)mode;
}

The callback parameters are summarized in the following table: