Heartbeat consumer
CANopen_301

## Files

file | CO_HBconsumer.h
| CANopen Heartbeat consumer protocol.

## Data Structures

struct | CO_HBconsNode_t
| One monitored node inside CO_HBconsumer_t. More...
struct | CO_HBconsumer_t
| Heartbeat consumer object. More...

## Enumerations

enum | CO_HBconsumer_state_t { CO_HBconsumer_UNCONFIGURED = 0x00U, CO_HBconsumer_UNKNOWN = 0x01U, CO_HBconsumer_ACTIVE = 0x02U, CO_HBconsumer_TIMEOUT = 0x03U }
| Heartbeat state of a node. More...

## Functions

CO_ReturnError_t | CO_HBconsumer_init (CO_HBconsumer_t *HBcons, CO_EM_t *em, CO_SDO_t *SDO, const uint32_t HBconsTime[], CO_HBconsNode_t monitoredNodes[], uint8_t numberOfMonitoredNodes, CO_CANmodule_t *CANdevRx, uint16_t CANdevRxIdxStart)
| Initialize Heartbeat consumer object. More...
CO_ReturnError_t | CO_HBconsumer_initEntry (CO_HBconsumer_t *HBcons, uint8_t idx, uint8_t nodeId, uint16_t consumerTime_ms)
| Initialize one Heartbeat consumer entry. More...
void | CO_HBconsumer_initCallbackPre (CO_HBconsumer_t *HBcons, void *object, void(*pFunctSignal)(void *object))
| Initialize Heartbeat consumer callback function. More...
void | CO_HBconsumer_initCallbackNmtChanged (CO_HBconsumer_t *HBcons, uint8_t idx, void *object, void(*pFunctSignal)(uint8_t nodeId, uint8_t idx, CO_NMT_internalState_t state, void *object))
| Initialize Heartbeat consumer NMT changed callback function. More...
void | CO_HBconsumer_initCallbackHeartbeatStarted (CO_HBconsumer_t *HBcons, uint8_t idx, void *object, void(*pFunctSignal)(uint8_t nodeId, uint8_t idx, void *object))
| Initialize Heartbeat consumer started callback function. More...
void | CO_HBconsumer_initCallbackTimeout (CO_HBconsumer_t *HBcons, uint8_t idx, void *object, void(*pFunctSignal)(uint8_t nodeId, uint8_t idx, void *object))
| Initialize Heartbeat consumer timeout callback function. More...
void | CO_HBconsumer_initCallbackRemoteReset (CO_HBconsumer_t *HBcons, uint8_t idx, void *object, void(*pFunctSignal)(uint8_t nodeId, uint8_t idx, void *object))
| Initialize Heartbeat consumer remote reset detected callback function. More...
void | CO_HBconsumer_process (CO_HBconsumer_t *HBcons, bool_t NMTisPreOrOperational, uint32_t timeDifference_us, uint32_t *timerNext_us)
| Process Heartbeat consumer object. More...
int8_t | CO_HBconsumer_getIdxByNodeId (CO_HBconsumer_t *HBcons, uint8_t nodeId)
| Get the heartbeat producer object index by node ID. More...
CO_HBconsumer_state_t | CO_HBconsumer_getState (CO_HBconsumer_t *HBcons, uint8_t idx)
| Get the current state of a heartbeat producer by the index in OD 0x1016. More...
int8_t | CO_HBconsumer_getNmtState (CO_HBconsumer_t *HBcons, uint8_t idx, CO_NMT_internalState_t *nmtState)
| Get the current NMT state of a heartbeat producer by the index in OD 0x1016. More...

## Detailed Description

CANopen Heartbeat consumer protocol.

Heartbeat consumer monitors Heartbeat messages from remote nodes. If any monitored node don't send his Heartbeat in specified time, Heartbeat consumer sends emergency message. If all monitored nodes are operational, then variable allMonitoredOperational inside CO_HBconsumer_t is set to true. Monitoring starts after the reception of the first HeartBeat (not bootup).

Heartbeat set up is done by writing to the OD registers 0x1016 or by using the function CO_HBconsumer_initEntry()

See also
  NMT and Heartbeat

## Enumeration Type Documentation

## CO_HBconsumer_state_t

enum CO_HBconsumer_state_t

Heartbeat state of a node.

Enumerator
CO_HBconsumer_UNCONFIGURED | Consumer entry inactive.
CO_HBconsumer_UNKNOWN | Consumer enabled, but no heartbeat received yet.
CO_HBconsumer_ACTIVE | Heartbeat received within set time.
CO_HBconsumer_TIMEOUT | No heatbeat received for set time.

## Function Documentation

## CO_HBconsumer_init()

CO_ReturnError_t CO_HBconsumer_init | ( | CO_HBconsumer_t * | HBcons,
|  | CO_EM_t * | em,
|  | CO_SDO_t * | SDO,
|  | const uint32_t | HBconsTime[],
|  | CO_HBconsNode_t | monitoredNodes[],
|  | uint8_t | numberOfMonitoredNodes,
|  | CO_CANmodule_t * | CANdevRx,
|  | uint16_t | CANdevRxIdxStart
| ) |  |

Initialize Heartbeat consumer object.

Function must be called in the communication reset section.

Parameters

  HBcons | This object will be initialized.
  em | Emergency object.
  SDO | SDO server object.
  HBconsTime | Pointer to Consumer Heartbeat Time array from Object Dictionary (index 0x1016). Size of array is equal to numberOfMonitoredNodes.
  monitoredNodes | Pointer to the externaly defined array of the same size as numberOfMonitoredNodes.
  numberOfMonitoredNodes | Total size of the above arrays.
  CANdevRx | CAN device for Heartbeat reception.
  CANdevRxIdxStart | Starting index of receive buffer in the above CAN device. Number of used indexes is equal to numberOfMonitoredNodes.

Returns
  CO_ReturnError_t CO_ERROR_NO or CO_ERROR_ILLEGAL_ARGUMENT.

## CO_HBconsumer_initEntry()

CO_ReturnError_t CO_HBconsumer_initEntry | ( | CO_HBconsumer_t * | HBcons,
|  | uint8_t | idx,
|  | uint8_t | nodeId,
|  | uint16_t | consumerTime_ms
| ) |  |

Initialize one Heartbeat consumer entry.

Calling this function has the same affect as writing to the corresponding entries in the Object Dictionary (index 0x1016)

Remarks
  The values in the Object Dictionary must be set manually by the calling function so that heartbeat consumer behaviour matches the OD value.

Parameters

  HBcons | This object.
  idx | index of the node in HBcons object
  nodeId | see OD 0x1016 description
  consumerTime_ms | in milliseconds. see OD 0x1016 description

Returns

## CO_HBconsumer_initCallbackPre()

void CO_HBconsumer_initCallbackPre | ( | CO_HBconsumer_t * | HBcons,
|  | void * | object,
|  | void(*)(void *object) | pFunctSignal
| ) |  |

Initialize Heartbeat consumer callback function.

Function initializes optional callback function, which should immediately start processing of CO_HBconsumer_process() function. Callback is called after HBconsumer message is received from the CAN bus.

Parameters

  HBcons | 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_HBconsumer_initCallbackNmtChanged()

void CO_HBconsumer_initCallbackNmtChanged | ( | CO_HBconsumer_t * | HBcons,
|  | uint8_t | idx,
|  | void * | object,
|  | void(*)(uint8_t nodeId, uint8_t idx, CO_NMT_internalState_t state, void *object) | pFunctSignal
| ) |  |

Initialize Heartbeat consumer NMT changed callback function.

Function initializes optional callback function, which is called when NMT state from the remote node changes.

Parameters

  HBcons | This object.
  idx | index of the node in HBcons object (only when CO_CONFIG_HB_CONS_CALLBACK_MULTI is enabled)
  object | Pointer to object, which will be passed to pFunctSignal(). Can be NULL.
  pFunctSignal | Pointer to the callback function. Not called if NULL.

## CO_HBconsumer_initCallbackHeartbeatStarted()

void CO_HBconsumer_initCallbackHeartbeatStarted | ( | CO_HBconsumer_t * | HBcons,
|  | uint8_t | idx,
|  | void * | object,
|  | void(*)(uint8_t nodeId, uint8_t idx, void *object) | pFunctSignal
| ) |  |

Initialize Heartbeat consumer started callback function.

Function initializes optional callback function, which is called for the first received heartbeat after activating hb consumer or timeout. Function may wake up external task, which handles this event.

Parameters

  HBcons | This object.
  idx | index of the node in HBcons 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_HBconsumer_initCallbackTimeout()

void CO_HBconsumer_initCallbackTimeout | ( | CO_HBconsumer_t * | HBcons,
|  | uint8_t | idx,
|  | void * | object,
|  | void(*)(uint8_t nodeId, uint8_t idx, void *object) | pFunctSignal
| ) |  |

Initialize Heartbeat consumer timeout callback function.

Function initializes optional callback function, which is called when the node state changes from active to timeout. Function may wake up external task, which handles this event.

Parameters

  HBcons | This object.
  idx | index of the node in HBcons 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_HBconsumer_initCallbackRemoteReset()

void CO_HBconsumer_initCallbackRemoteReset | ( | CO_HBconsumer_t * | HBcons,
|  | uint8_t | idx,
|  | void * | object,
|  | void(*)(uint8_t nodeId, uint8_t idx, void *object) | pFunctSignal
| ) |  |

Initialize Heartbeat consumer remote reset detected callback function.

Function initializes optional callback function, which is called when a bootup message is received from the remote node. Function may wake up external task, which handles this event.

Parameters

  HBcons | This object.
  idx | index of the node in HBcons 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_HBconsumer_process()

void CO_HBconsumer_process | ( | CO_HBconsumer_t * | HBcons,
|  | bool_t | NMTisPreOrOperational,
|  | uint32_t | timeDifference_us,
|  | uint32_t * | timerNext_us
| ) |  |

Process Heartbeat consumer object.

Function must be called cyclically.

Parameters

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

## CO_HBconsumer_getIdxByNodeId()

int8_t CO_HBconsumer_getIdxByNodeId | ( | CO_HBconsumer_t * | HBcons,
|  | uint8_t | nodeId
| ) |  |

Get the heartbeat producer object index by node ID.

Parameters

  HBcons | This object.
  nodeId | producer node ID

Returns
  index. -1 if not found

## CO_HBconsumer_getState()

CO_HBconsumer_state_t CO_HBconsumer_getState | ( | CO_HBconsumer_t * | HBcons,
|  | uint8_t | idx
| ) |  |

Get the current state of a heartbeat producer by the index in OD 0x1016.

Parameters

  HBcons | This object.
  idx | object sub index

Returns
  CO_HBconsumer_state_t

## CO_HBconsumer_getNmtState()

int8_t CO_HBconsumer_getNmtState | ( | CO_HBconsumer_t * | HBcons,
|  | uint8_t | idx,
|  | CO_NMT_internalState_t * | nmtState
| ) |  |

Get the current NMT state of a heartbeat producer by the index in OD 0x1016.

NMT state is only available when heartbeat is enabled for this index!

Parameters

  | HBcons | This object.
  | idx | object sub index
  [out] | nmtState | of this index

Return values

  0 | NMT state has been received and is valid
  -1 | not valid