Detailed Description

The CANopen Network Management (NMT) is used to change the state of a CANopen device (see CANopen Terms and Definitions). In addition, the network state can be monitored via the Network Management Error Control (NMT-EC) service. This module provides the following functionality:

NMT state change
NMT Error Control (heartbeat/node-guarding)
Send boot-up message
Callbacks for NMT state change

NMT state machine

A CANopen device moves through four states. The current state can be queried with CosNmtGetNodeState(); the possible return values are defined in NMT node state.

State	NODE_STATE value	Description
Initialization	NODE_STATE_BOOTUP	Device starts here after power-on or reset. SDO, PDO, and SYNC communication is not yet active.
Pre-Operational	NODE_STATE_PREOPERATIONAL	Entered automatically after initialization completes. SDO communication is active; PDO communication is inhibited.
Operational	NODE_STATE_OPERATIONAL	PDO communication is active. Normal device operation.
Stopped	NODE_STATE_STOPPED	All communication except NMT and heartbeat is inhibited.

NMT transitions and callbacks

NMT state transitions are triggered by NMT commands received on CAN-ID 0 from the NMT master. The following table maps each transition to the NMT command code and to the application callback that fires:

Transition	NMT command	Callback
Initialization → Pre-Operational	(automatic after boot-up)	CosMgrOnStart() then CosMgrOnBootUp()
Pre-Operational → Operational	Start Remote Node (01h)	CosNmtServiceOnStart()
Operational → Pre-Operational	Enter Pre-Operational (80h)	CosNmtServiceOnPreOperational()
Operational → Stopped	Stop Remote Node (02h)	CosNmtServiceOnStop()
Stopped → Pre-Operational	Enter Pre-Operational (80h)	CosNmtServiceOnPreOperational()
Stopped → Operational	Start Remote Node (01h)	CosNmtServiceOnStart()
Pre-Operational → Stopped	Stop Remote Node (02h)	CosNmtServiceOnStop()
Any → Initialization	Reset Node (81h) / Reset Communication (82h)	—

Additional event callbacks are triggered by NMT error control:

CosNmtServiceOnHeartbeatEvent() — a monitored node missed its heartbeat window
CosNmtServiceOnGuardingEvent() — node-guarding life time expired
CosNmtServiceOnError() — an NMT frame arrived with unknown or malformed content

All callback implementations reside in cos_user.c and must be supplied by the integrator.

Include dependency graph for cos_nmt.h:

Macros
#define	NODE_STATE_BOOTUP ((uint8_t)(0x00))
#define	NODE_STATE_STOPPED ((uint8_t)(0x04))
#define	NODE_STATE_OPERATIONAL ((uint8_t)(0x05))
#define	NODE_STATE_PREOPERATIONAL ((uint8_t)(0x7F))
#define	NODE_STATE_BUS_OFF ((uint8_t)(0xFF))

Functions
void	CosNmtChangeNodeState (uint8_t ubFailureV)
uint8_t	CosNmtCheckNodeReset (void)
uint8_t	CosNmtGetNodeState (void)
void	CosNmtServiceOnError (void)
void	CosNmtServiceOnGuardingEvent (void)
void	CosNmtServiceOnHeartbeatEvent (void)
void	CosNmtServiceOnPreOperational (void)
void	CosNmtServiceOnStart (void)
void	CosNmtServiceOnStop (void)
uint8_t	CosNmtSetHeartbeatCons (uint8_t ubEntryV, uint8_t ubNodeIdV, uint16_t uwTimeV)
void	CosNmtSetHeartbeatProd (uint16_t uwTimeV)

Function Documentation

◆ CosNmtChangeNodeState()

void CosNmtChangeNodeState ( uint8_t ubFailureV )

Parameters

[in] ubFailureV Error reason

This function changes the NMT state of the device depending on the contents of object 1029_h (error behaviour). The parameter ubFailureV defines the reason for the failure:

1 = communication error
2 .. N = Profile or manufacturer specific error

The maximum value for ubFailureV is defined by the symbol COS_DICT_OBJ_1029. For the failure type 'communication error' the function is called by the stack.

◆ CosNmtCheckNodeReset()

uint8_t CosNmtCheckNodeReset ( void )

Returns: Reset State

This function returns the node reset state (NODE_RESET_XXX).

◆ CosNmtGetNodeState()

uint8_t CosNmtGetNodeState ( void )

Returns: NMT node state

This function returns the current NMT state of the node. Possible return values are defined by NMT node state.

◆ CosNmtServiceOnError()

void CosNmtServiceOnError ( void )

Note: The code located in the file cos_user.c provides an example and has to be adopted to the application.

This function is called when the NMT state machine receives an unknown NMT command, i.e. a frame on CAN-ID 0 with a DLC that does not match or data that does not match any defined command code. The reaction on this event is application specific; it may be ignored or logged.

void  CosNmtServiceOnError(void)
{
   //---------------------------------------------------------------------------------------------------
   // An unknown or malformed NMT frame was received (CAN-ID 0).
   // No mandatory reaction is defined by the standard; the application may count or log the event.
   //
   // Example:
   //   CosEmcyErrorSet(eEMCY_301_CAN_GENERIC, (uint8_t *) 0);
   //
}

◆ CosNmtServiceOnGuardingEvent()

void CosNmtServiceOnGuardingEvent ( void )

Note: The code located in the file cos_user.c provides an example and has to be adopted to the application.

This function is called when a node-guarding life-time event occurs, i.e. the NMT master did not send the RTR guard frame within the guard time × life-time factor window (objects 100C_h and 100D_h). The typical reaction is to report an emergency via CosEmcyErrorSet() with error code eEMCY_301_CAN_LIFEGUARD.

void  CosNmtServiceOnGuardingEvent(void)
{
   CosEmcyErrorSet(eEMCY_301_CAN_LIFEGUARD, (uint8_t *) 0);
}

◆ CosNmtServiceOnHeartbeatEvent()

void CosNmtServiceOnHeartbeatEvent ( void )

Note: The code located in the file cos_user.c provides an example and has to be adopted to the application.

This function is called when a heartbeat consumer timeout fires, i.e. a monitored node did not transmit its heartbeat within the expected cycle window (object 1016_h). The typical reaction is to report an emergency via CosEmcyErrorSet() with error code eEMCY_301_CAN_LIFEGUARD.

void  CosNmtServiceOnHeartbeatEvent(void)
{
   CosEmcyErrorSet(eEMCY_301_CAN_LIFEGUARD, (uint8_t *) 0);
}

◆ CosNmtServiceOnPreOperational()

void CosNmtServiceOnPreOperational ( void )

Note: The code located in the file cos_user.c provides an example and has to be adopted to the application.

This function is called when the NMT state machine enters NODE_STATE_PREOPERATIONAL, triggered by the NMT command Enter Pre-Operational (80h). PDO communication is suspended at this point; SDO communication remains active. Use this callback to disable application outputs or enter a safe state.

void  CosNmtServiceOnPreOperational(void)
{
   //---------------------------------------------------------------------------------------------------
   // NMT Pre-Operational state: PDO communication is suspended, SDO remains active.
   // Disable application outputs or hold the last valid process values.
   //
   // Example:
   //   AppDisableOutputs();
   //
}

◆ CosNmtServiceOnStart()

void CosNmtServiceOnStart ( void )

Note: The code located in the file cos_user.c provides an example and has to be adopted to the application.

This function is called when the NMT state machine enters NODE_STATE_OPERATIONAL, triggered by the NMT command Start Remote Node (01h). PDO communication becomes active at this point. Use this callback to enable application outputs and trigger an initial PDO transmission via CosPdoSend().

void  CosNmtServiceOnStart(void)
{
   //---------------------------------------------------------------------------------------------------
   // this is an example for NMT start
   // it has to be adopted to the device profile / application
   //
   #if COS_PDO_TRM_NUMBER > 0
   CosPdoSend(0);
   #endif
 
   #if COS_PDO_TRM_NUMBER > 1
   CosPdoSend(1);
   #endif
 
   #if COS_PDO_TRM_NUMBER > 2
   CosPdoSend(2);
   #endif
 
   #if COS_PDO_TRM_NUMBER > 3
   CosPdoSend(3);
   #endif
 
}

◆ CosNmtServiceOnStop()

void CosNmtServiceOnStop ( void )

Note: The code located in the file cos_user.c provides an example and has to be adopted to the application.

This function is called when the NMT state machine enters NODE_STATE_STOPPED, triggered by the NMT command Stop Remote Node (02h). All communication except NMT and heartbeat is suspended. Use this callback to set outputs to a defined safe state.

void  CosNmtServiceOnStop(void)
{
   //---------------------------------------------------------------------------------------------------
   // NMT Stopped state: all PDO and SDO communication is suspended.
   // Set application outputs to a defined safe state and disable process data updates.
   //
   // Example:
   //   AppSetSafeOutputs();
   //
}

◆ CosNmtSetHeartbeatCons()

uint8_t CosNmtSetHeartbeatCons	(	uint8_t	ubEntryV,
		uint8_t	ubNodeIdV,
		uint16_t	uwTimeV )

Parameters

[in]	ubEntryV	heartbeat consumer entry (0 .. N)
[in]	ubNodeIdV	node-ID to monitor
[in]	uwTimeV	expected heartbeat cycle time

Returns: 0 on success

This function sets the heartbeat consumer time for the entry ubEntryV. The maximum number of entries is defined via the symbol COS_DICT_OBJ_1016. The parameter uwTimeV denotes the time in milli-seconds. If the heartbeat consumer time is setup for the own node-ID or the supplied node-ID is already in use, the function will return the value 1. On success, the value 0 is returned.

◆ CosNmtSetHeartbeatProd()

void CosNmtSetHeartbeatProd ( uint16_t uwTimeV )

Parameters

[in] uwTimeV heartbeat cycle time

This function sets the heartbeat producer time. The parameter uwTimeV denotes the time in milli-seconds. By default, the heartbeat producer time is set to 0 during initialization.

Detailed Description

NMT state machine

NMT transitions and callbacks

Macros

Functions

Function Documentation

◆ CosNmtChangeNodeState()

◆ CosNmtCheckNodeReset()

◆ CosNmtGetNodeState()

◆ CosNmtServiceOnError()

◆ CosNmtServiceOnGuardingEvent()

◆ CosNmtServiceOnHeartbeatEvent()

◆ CosNmtServiceOnPreOperational()

◆ CosNmtServiceOnStart()

◆ CosNmtServiceOnStop()

◆ CosNmtSetHeartbeatCons()

◆ CosNmtSetHeartbeatProd()