NMT and Heartbeat
CANopen_301

## Files

file | CO_NMT_Heartbeat.h
| CANopen Network management and Heartbeat producer protocol.

## Data Structures

struct | CO_NMT_t
| NMT consumer and Heartbeat producer object. More...

## Enumerations

enum | CO_NMT_internalState_t { CO_NMT_UNKNOWN = -1, CO_NMT_INITIALIZING = 0, CO_NMT_PRE_OPERATIONAL = 127, CO_NMT_OPERATIONAL = 5, CO_NMT_STOPPED = 4 }
| Internal network state of the CANopen node. More...
enum | CO_NMT_command_t { CO_NMT_ENTER_OPERATIONAL = 1, CO_NMT_ENTER_STOPPED = 2, CO_NMT_ENTER_PRE_OPERATIONAL = 128, CO_NMT_RESET_NODE = 129, CO_NMT_RESET_COMMUNICATION = 130 }
| Commands from NMT master. More...
enum | CO_NMT_reset_cmd_t { CO_RESET_NOT = 0, CO_RESET_COMM = 1, CO_RESET_APP = 2, CO_RESET_QUIT = 3 }
| Return code from CO_NMT_process() that tells application code what to reset. More...
enum | CO_NMT_control_t { CO_NMT_ERR_REG_MASK = 0x00FFU, CO_NMT_STARTUP_TO_OPERATIONAL = 0x0100U, CO_NMT_ERR_ON_BUSOFF_HB = 0x1000U, CO_NMT_ERR_ON_ERR_REG = 0x2000U, CO_NMT_ERR_TO_STOPPED = 0x4000U, CO_NMT_ERR_FREE_TO_OPERATIONAL = 0x8000U }
| NMT control bitfield for NMT internal state. More...

## Functions

CO_ReturnError_t | CO_NMT_init (CO_NMT_t *NMT, const OD_entry_t *OD_1017_ProducerHbTime, CO_EM_t *em, uint8_t nodeId, CO_NMT_control_t NMTcontrol, uint16_t firstHBTime_ms, CO_CANmodule_t *NMT_CANdevRx, uint16_t NMT_rxIdx, uint16_t CANidRxNMT, CO_CANmodule_t *NMT_CANdevTx, uint16_t NMT_txIdx, uint16_t CANidTxNMT, CO_CANmodule_t *HB_CANdevTx, uint16_t HB_txIdx, uint16_t CANidTxHB)
| Initialize NMT and Heartbeat producer object. More...
void | CO_NMT_initCallbackPre (CO_NMT_t *NMT, void *object, void(*pFunctSignal)(void *object))
| Initialize NMT callback function after message preprocessed. More...
void | CO_NMT_initCallbackChanged (CO_NMT_t *NMT, void(*pFunctNMT)(CO_NMT_internalState_t state))
| Initialize NMT callback function. More...
CO_NMT_reset_cmd_t | CO_NMT_process (CO_NMT_t *NMT, CO_NMT_internalState_t *NMTstate, uint32_t timeDifference_us, uint32_t *timerNext_us)
| Process received NMT and produce Heartbeat messages. More...
static CO_NMT_internalState_t | CO_NMT_getInternalState (CO_NMT_t *NMT)
| Query current NMT state. More...
static void | CO_NMT_setInternalState (CO_NMT_t *NMT, CO_NMT_internalState_t state)
| Set internal NMT state. More...
CO_ReturnError_t | CO_NMT_sendCommand (CO_NMT_t *NMT, CO_NMT_command_t command, uint8_t nodeID)
| Send NMT master command. More...

## Detailed Description

CANopen Network management and Heartbeat producer protocol.

CANopen device can be in one of the CO_NMT_internalState_t

- Initializing. It is active before CANopen is initialized.
- Pre-operational. All CANopen objects are active, except PDOs.
- Operational. Process data objects (PDOs) are active too.
- Stopped. Only Heartbeat producer and NMT consumer are active.

NMT master can change the internal state of the devices by sending CO_NMT_command_t.

### NMT message contents:

Byte | Description
--- | ---
0 | CO_NMT_command_t
1 | Node ID. If zero, command addresses all nodes.

### Heartbeat message contents:

Byte | Description
--- | ---
0 | CO_NMT_internalState_t

See CO_Default_CAN_ID_t for CAN identifiers.

## Enumeration Type Documentation

## CO_NMT_internalState_t

enum CO_NMT_internalState_t

Internal network state of the CANopen node.

Enumerator
CO_NMT_UNKNOWN | -1, Device state is unknown (for heartbeat consumer)
CO_NMT_INITIALIZING | 0, Device is initializing
CO_NMT_PRE_OPERATIONAL | 127, Device is in pre-operational state
CO_NMT_OPERATIONAL | 5, Device is in operational state
CO_NMT_STOPPED | 4, Device is stopped

## CO_NMT_command_t

enum CO_NMT_command_t

Commands from NMT master.

Enumerator
CO_NMT_ENTER_OPERATIONAL | 1, Start device
CO_NMT_ENTER_STOPPED | 2, Stop device
CO_NMT_ENTER_PRE_OPERATIONAL | 128, Put device into pre-operational
CO_NMT_RESET_NODE | 129, Reset device
CO_NMT_RESET_COMMUNICATION | 130, Reset CANopen communication on device

## CO_NMT_reset_cmd_t

enum CO_NMT_reset_cmd_t

Return code from CO_NMT_process() that tells application code what to reset.

Enumerator
CO_RESET_NOT | 0, Normal return, no action
CO_RESET_COMM | 1, Application must provide communication reset.
CO_RESET_APP | 2, Application must provide complete device reset
CO_RESET_QUIT | 3, Application must quit, no reset of microcontroller (command is not requested by the stack.)

## CO_NMT_control_t

enum CO_NMT_control_t

NMT control bitfield for NMT internal state.

Variable of this type is passed to CO_NMT_init() function. It controls behavior of the CO_NMT_internalState_t of the device according to CANopen error register.

Internal NMT state is controlled also with external NMT command, CO_NMT_setInternalState() or CO_NMT_sendCommand() functions.

Enumerator
CO_NMT_ERR_REG_MASK | First 8 bits can be used to specify bitmask for the CO_errorRegister_t, to get relevant bits for the calculation.
CO_NMT_STARTUP_TO_OPERATIONAL | If bit is set, then device enters NMT operational state after the initialization phase, otherwise it enters NMT pre-operational state.
CO_NMT_ERR_ON_BUSOFF_HB | If bit is set and device is operational, it enters NMT pre-operational or stopped state, if CAN bus is off or heartbeat consumer timeout is detected.
CO_NMT_ERR_ON_ERR_REG | If bit is set and device is operational, it enters NMT pre-operational or stopped state, if masked CANopen error register is different than zero.
CO_NMT_ERR_TO_STOPPED | If bit is set and CO_NMT_ERR_ON_xx condition is met, then device will enter NMT stopped state, otherwise it will enter NMT pre-op state.
CO_NMT_ERR_FREE_TO_OPERATIONAL | If bit is set and device is pre-operational, it enters NMT operational state automatically, if conditions from CO_NMT_ERR_ON_xx are all false.

## Function Documentation

## CO_NMT_init()

CO_ReturnError_t CO_NMT_init | ( | CO_NMT_t * | NMT,
|  | const OD_entry_t * | OD_1017_ProducerHbTime,
|  | CO_EM_t * | em,
|  | uint8_t | nodeId,
|  | CO_NMT_control_t | NMTcontrol,
|  | uint16_t | firstHBTime_ms,
|  | CO_CANmodule_t * | NMT_CANdevRx,
|  | uint16_t | NMT_rxIdx,
|  | uint16_t | CANidRxNMT,
|  | CO_CANmodule_t * | NMT_CANdevTx,
|  | uint16_t | NMT_txIdx,
|  | uint16_t | CANidTxNMT,
|  | CO_CANmodule_t * | HB_CANdevTx,
|  | uint16_t | HB_txIdx,
|  | uint16_t | CANidTxHB
| ) |  |

Initialize NMT and Heartbeat producer object.

Function must be called in the communication reset section.

Parameters

  NMT | This object will be initialized.
  OD_1017_ProducerHbTime | OD entry for 0x1017 -"Producer heartbeat time", entry is required, IO extension is optional for runtime configuration.
  em | Emergency object.
  nodeId | CANopen Node ID of this device.
  NMTcontrol | Control variable for calculation of NMT internal state, based on error register, startup and runtime behavior.
  firstHBTime_ms | Time between bootup and first heartbeat message in milliseconds. If firstHBTime_ms is greater than "Producer Heartbeat time" (OD object 0x1017), latter is used instead. Entry is required, IO extension is optional.
  NMT_CANdevRx | CAN device for NMT reception.
  NMT_rxIdx | Index of receive buffer in above CAN device.
  CANidRxNMT | CAN identifier for NMT receive message.
  NMT_CANdevTx | CAN device for NMT master transmission.
  NMT_txIdx | Index of transmit buffer in above CAN device.
  CANidTxNMT | CAN identifier for NMT transmit message.
  HB_CANdevTx | CAN device for HB transmission.
  HB_txIdx | Index of transmit buffer in the above CAN device.
  CANidTxHB | CAN identifier for HB message.

Returns
  CO_ReturnError_t CO_ERROR_NO on success.

## CO_NMT_initCallbackPre()

void CO_NMT_initCallbackPre | ( | CO_NMT_t * | NMT,
|  | void * | object,
|  | void(*)(void *object) | pFunctSignal
| ) |  |

Initialize NMT callback function after message preprocessed.

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

Parameters

  NMT | 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_NMT_initCallbackChanged()

void CO_NMT_initCallbackChanged | ( | CO_NMT_t * | NMT,
|  | void(*)(CO_NMT_internalState_t state) | pFunctNMT
| ) |  |

Initialize NMT callback function.

Function initializes optional callback function, which is called after NMT State change has occurred. Function may wake up external task which handles NMT events. The first call is made immediately to give the consumer the current NMT state.

Parameters

  NMT | This object.
  pFunctNMT | Pointer to the callback function. Not called if NULL.

## CO_NMT_process()

CO_NMT_reset_cmd_t CO_NMT_process | ( | CO_NMT_t * | NMT,
|  | CO_NMT_internalState_t * | NMTstate,
|  | uint32_t | timeDifference_us,
|  | uint32_t * | timerNext_us
| ) |  |

Process received NMT and produce Heartbeat messages.

Function must be called cyclically.

Parameters

  | NMT | This object.
  [out] | NMTstate | If not NULL, CANopen NMT internal state is returned.
  | timeDifference_us | Time difference from previous function call in microseconds.
  [out] | timerNext_us | info to OS - see CO_process().

Returns
  CO_NMT_reset_cmd_t

## CO_NMT_getInternalState()

static CO_NMT_internalState_t CO_NMT_getInternalState | ( | CO_NMT_t * | NMT | ) |

inlinestatic

Query current NMT state.

Parameters

  NMT | This object.

Returns
  CO_NMT_internalState_t

## CO_NMT_setInternalState()

static void CO_NMT_setInternalState | ( | CO_NMT_t * | NMT,
|  | CO_NMT_internalState_t | state
| ) |  |

inlinestatic

Set internal NMT state.

Functions sets state directly, without any checking. CO_NMT_process() may also switch between states automatically, see CO_NMT_control_t.

Parameters

  NMT | This object.
  state | New state.

## CO_NMT_sendCommand()

CO_ReturnError_t CO_NMT_sendCommand | ( | CO_NMT_t * | NMT,
|  | CO_NMT_command_t | command,
|  | uint8_t | nodeID
| ) |  |

Send NMT master command.

This functionality may only be used from NMT master, as specified by standard CiA302-2. Standard provides one exception, where application from slave node may send NMT master command: "If CANopen object 0x1F80 has value of 0x2, then NMT slave shall execute the NMT service start remote node (CO_NMT_ENTER_OPERATIONAL) with nodeID set to 0."

Parameters

  NMT | This object.
  command | NMT command from CO_NMT_command_t.
  nodeID | Node ID of the remote node. 0 for all nodes including self.

Returns
  CO_ERROR_NO on success or CO_ReturnError_t from CO_CANsend().