Skip to content

Callback Interface#

Application Callback Functions#

This chapter gives an overview of the component Callback Interface. The listed functions are available for programming the application-specific reactions on several events of the CANopen device.

CONodeFatalError()#

This mandatory function is called, after detecting a fatal error within the stack, and no way out of the situation (panic). The function is intended to allow the implementation of a pre-defined shutdown sequence and setting the device in a safe state.

void CONodeFatalError(void)
{
  /* Place here your fatal error handling.
   * There is most likely a programming error.
   * !! Please don't ignore this errors. !!
   */
  for (;;);
}

COTmrLock()#

These mandatory function pair is called during timer management and is the right place to add a locking mechanism for the timer management structure. The simplest implementation is disabling and re-enabling the timer hardware interrupt. In more advanced scenarios there could be a timer mutex or spin-lock, depending on the RTOS and number of active cores.

void COTmrLock(void)
{
  /* This function helps to guarantee the consistancy
   * of the internal timer management while interrupted
   * by the used timer interrupt. Most likely you need
   * at this point on of the following mechanisms:
   * - disable the used hardware timer interrupt
   * - get a 'timer-mutex' from your RTOS (ensure to
   *   call COTmrService() in a timer triggered task)
   */
}

void COTmrUnlock(void)
{
  /* This function helps to guarantee the consistancy
   * of the internal timer management while interrupted
   * by the used timer interrupt. Most likely you need
   * at this point on of the following mechanisms:
   * - (re)enable the used hardware timer interrupt
   * - release the 'timer-mutex' from your RTOS (ensure
   *   to call COTmrService() in a timer triggered task)
   */
}

COIfCanReceive()#

This optional function is called for each CAN frame, which is not consumed (processed) by the CANopen stack. The CAN frame pointer is checked to be valid before the CANopen stack calls this function.

void COIfCanReceive(CO_IF_FRM *frm)
{
  /* Optional: place here some code, which is called
   * when you need to handle CAN messages, which are
   * not part of the CANopen protocol.
   */
}

Arguments

Parameter Description
frm The received CAN frame

COLssStore()#

This optional function is called with new configuration data, which is set by the LSS service. If the configuration data should stay unchanged, the argument is 0. The CAN frame pointer is checked to be valid before the CANopen stack calls this function.

int16_t COLssStore(uint32_t baudrate, uint8_t nodeId)
{
  /* Optional: place here some code, which is called
   * when LSS client is in use and the CANopen node
   * needs to store updated values.
   */
  return (0u);
}

Arguments

Parameter Description
baudrate The configured baudrate for storage
nodeId The configured node id for storage

Returned Value

  • ==0 : configuration stored
  • !=0 : error is detected

COLssLoad()#

This optional function is called during reset communication to load the stored LSS configuration. If no storage for the configuration data is found, the referenced argument should stay unchanged. The CAN frame pointer is checked to be valid before the CANopen stack calls this function.

int16_t COLssLoad(uint32_t *baudrate, uint8_t *nodeId)
{
  /* Optional: place here some code, which is called
   * when LSS client is in use and the CANopen node
   * is initialized.
   */
  return (0u);
}

Arguments

Parameter Description
baudrate Reference to the baudrate, which should be set to storage value
nodeId Reference to the node-id, which should be set to storage value

Returned Value

  • ==0 : configuration loaded
  • !=0 : error is detected

CONmtModeChange()#

This optional function is called when the NMT mode is changed. The nmt object pointer is checked to be valid before the CANopen stack calls this function.

void CONmtModeChange(CO_NMT *nmt, CO_MODE mode)
{
  /* Optional: place here some code, which is called
   * when a NMT mode change is initiated.
   */
}

Arguments

Parameter Description
nmt reference to NMT structure
mode the new mode

CONmtResetRequest()#

This optional function is called when the NMT reset is requested via CAN network. The nmt object pointer is checked to be valid before the CANopen stack calls this function.

void CONmtResetRequest(CO_NMT *nmt, CO_NMT_RESET reset)
{
  /* Optional: place here some code, which is called
   * when a NMT reset is requested by the network.
   */
}

Arguments

Parameter Description
nmt reference to NMT structure
reset the requested reset type

CONmtHbConsEvent()#

This optional function is called when a heartbeat consumer monitor timer elapses, before receiving the corresponding heartbeat message. The node pointer is checked to be valid before the CANopen stack calls this function.

void CONmtHbConsEvent(CO_NMT *nmt, uint8_t nodeId)
{
  /* Optional: place here some code, which is called
   * called when heartbeat consumer is in use and
   * detects an error on monitored node(s).
   */
}

Arguments

Parameter Description
nmt reference to NMT structure
nodeId The nodeId of the missed heartbeat message

CONmtHbConsChange()#

This optional function is called when a heartbeat consumer monitor detects a state change, of a monitored node. The node pointer is checked to be valid before the CANopen stack calls this function.

void CONmtHbConsChange(CO_NMT *nmt, uint8_t nodeId, CO_MODE mode)
{
  /* Optional: place here some code, which is called
   * when heartbeat consumer is in use and detects a
   * NMT state change on monitored node(s).
   */
}

Arguments

Parameter Description
nmt reference to NMT structure
nodeId The nodeId of the monitored node
mode The new received node state of the monitored node

COPdoTransmit()#

This optional function is called just before the PDO transmission will send the PDO message frame to the CANopen network.

void COPdoTransmit(CO_IF_FRM *frm)
{
  /* Optional: place here some code, which is called
   * just before a PDO is transmitted. You may adjust
   * the given CAN frame which is send afterwards.
   */
}

Arguments

Parameter Description
frm Pointer to PDO message frame

COPdoReceive()#

This optional function is called just before the PDO reception will distribute the PDO message frame into the object dictionary. This callback function is able to consume the PDO message frame, e.g. the distribution into the object dictionary will be skipped. Furthermore without consuming the PDO message frame, this function could modify the received data before distribution takes place.

int16_t COPdoReceive(CO_IF_FRM *frm)
{
  /* Optional: place here some code, which is called
   * right after receiving a PDO. You may adjust
   * the given CAN frame which is written into the
   * object dictionary afterwards or suppress the
   * write operation.
   */
  return(0u);
}

Arguments

Parameter Description
frm Pointer to received PDO message frame

Returned Value

  • =0 : CAN message frame is not consumed
  • >0 : CAN message frame is consumed

COPdoSyncUpdate()#

This optional function is called after a synchronized PDO is received and the data is distributed into the object dictionary.

void COPdoSyncUpdate(CO_RPDO *pdo)
{
  /* Optional: place here some code, which is called
   * right after the object dictionary update due to
   * a synchronized PDO.
   */
}

Arguments

Parameter Description
pdo Pointer to received and synchronous processed RPDO

COParaDefault()#

This optional function will be called during restoring the default values of a parameter group. The function is responsible for setting the factory defaults in the current parameter group memory. The parameter group info pointer is checked to be valid before the CANopen stack calls this function.

int16_t COParaDefault(CO_PARA *pg)
{
  /* Optional: place here some code, which is called
   * when a parameter group is restored to factory
   * settings.
   */
}

Arguments

Parameter Description
pg Ptr to parameter group info

Returned Value

  • =0 : parameter default values successful set
  • <0 : error is detected and function aborted

CORpdoWriteData()#

This optional function is called during PDO distribution of the PDO message frame into the object dictionary when mapped data value consumes more than 4 bytes.

void CORpdoWriteData(CO_IF_FRM *frm, uint8_t pos, uint8_t size, CO_OBJ *obj)
{
  /* Optional: place here some code, which is called
   * when a PDO is received with mapped values with
   * a size larger than 4 byte.
   */
}

Arguments

Parameter Description
frm Ptr to PDO message frame
pos The start index in the CAN message frame payload
size The mapped value size in bytes
obj Ptr to the target object entry

COTpdoReadData()#

This optional function is called during PDO transmission when a mapped data value consumes more than 4 bytes.

void COTpdoReadData(CO_IF_FRM *frm, uint8_t pos, uint8_t size, CO_OBJ *obj)
{
  /* Optional: place here some code, which is called
   * when a PDO is constructed for transmission which
   * needs a mapped values with a size larger than 4 byte.
   */
}

Arguments

Parameter Description
frm Ptr to PDO message frame
pos The start index in the CAN message frame payload
size The mapped value size in bytes
obj Ptr to the source object entry