cos_mgr.h File Reference

Detailed Description

This module holds all functions for the initialization and control of the CANopen slave. Some functions of this module need to be adopted to the target application:

• CosMgrGetNodeId()
• CosMgrGetNominalBitrate()
• CosMgrGetProductCode()
• CosMgrGetSerialNumber()
• CosMgrOnBootUp()
• CosMgrOnBusOff()
• CosMgrOnStart()

These functions are located in the cos_user.c file. Please refer to Initialization Process for details about the CosMgrInit() function and also check the Complete Startup Process for reference.

Include dependency graph for cos_mgr.h:

Macros
#define	COS_CONF_SLAVE   ((uint16_t) 0x0000)
#define	COS_CONF_MASTER   ((uint16_t) 0x0001)
#define	COS_CONF_AUTOSTART   ((uint16_t) 0x0002)
#define	COS_CONF_FD   ((uint16_t) 0x0004)
#define	COS_CONF_J1939   ((uint16_t) 0x0010)

Functions
uint8_t	CosMgrGetBitrate (void)
uint16_t	CosMgrGetConfiguration (void)
int32_t	CosMgrGetDataBitrate (void)
uint8_t	CosMgrGetFrameFormat (void)
uint8_t	CosMgrGetNodeId (void)
int32_t	CosMgrGetNominalBitrate (void)
uint32_t	CosMgrGetProductCode (void)
uint32_t	CosMgrGetSerialNumber (void)
uint8_t	CosMgrInit (uint8_t ubCanIfV, uint16_t uwConfigV)
void	CosMgrOnBootUp (void)
void	CosMgrOnBusOff (void)
void	CosMgrOnStart (uint8_t ubCallerResultV)
uint8_t	CosMgrProcess (void)
void	CosMgrProfileUpdate (uint16_t uwIndexV, uint8_t ubSubIndexV)
uint8_t	CosMgrRelease (void)
uint8_t	CosMgrStart (uint8_t ubNodeIdV, int32_t slBitrateNomSelV, int32_t slBitrateDatSelV)

Function Documentation

CosMgrGetBitrate()

uint8_t CosMgrGetBitrate

(

void

)

Deprecated

Use CosMgrGetDataBitrate() and CosMgrGetNominalBitrate() instead

Returns

Constant value for bit-rate

Note

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

This routine checks for the bit-rate. The code of this routine has to be adopted to the specific target. The function returns a constant for the bit-rate that is specified in the canpie.h file.

CosMgrGetConfiguration()

uint16_t CosMgrGetConfiguration

(

void

)

Returns

Constant value for stack configuration

This function returns the protocol stack configuration, i.e. the bit-masked values defined by COS_CONF.

CosMgrGetDataBitrate()

int32_t CosMgrGetDataBitrate

(

void

)

Returns

Constant value for data bit rate

Note

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

This routine checks for the data bit rate. The code of this routine has to be adopted to the specific target. The function returns a constant for the bit rate that is specified in the canpie.h file. If CAN FD is not supported, the function shall return eCP_BITRATE_NONE.

CosMgrGetFrameFormat()

uint8_t CosMgrGetFrameFormat

(

void

)

Returns

CAN message frame format

This function returns the CAN message frame format that shall be used for message buffer configuration. The value depends on the the stack configuration as shown in the table:

CosMgrInit() - uwConfigV	data bit rate	Frame Format
COS_CONF_FD not set	not evaluated	CP_MSG_FORMAT_CBFF
COS_CONF_FD set	eCP_BITRATE_NONE	CP_MSG_FORMAT_FBFF
COS_CONF_FD set	valid bit-rate	CP_MSG_FORMAT_FBFF | CP_MSG_CTRL_BRS_BIT

CosMgrGetNodeId()

uint8_t CosMgrGetNodeId

(

void

)

Returns

node-ID

Note

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

This routine checks for the node-ID. The code of this routine has to be adopted to the specific target. The function returns a value in the range from 1 to 127.

CosMgrGetNominalBitrate()

int32_t CosMgrGetNominalBitrate

(

void

)

Returns

Constant value for nominal bit rate

Note

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

This routine checks for the nominal bit rate. The code of this routine has to be adopted to the specific target. The function returns a constant for the bit rate that is specified in the canpie.h file.

CosMgrGetProductCode()

uint32_t CosMgrGetProductCode

(

void

)

Returns

Product Code

Note

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

This routine returns the Product Code of the module. The Product Number is used within in Identity Object (index 1018:02h).

CosMgrGetSerialNumber()

uint32_t CosMgrGetSerialNumber

(

void

)

Returns

Serial Number

Note

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

This routine returns the Serial Number of the module, which must be a unique value for a product family. The Serial Number is used within the Identity Object (index 1018:04h).

CosMgrInit()

uint8_t CosMgrInit	(	uint8_t	ubCanIfV,
		uint16_t	uwConfigV )

Parameters

ubCanIfV	- Physical CAN interface
uwConfigV	- Initial configuration

Returns

Error Code

The function returns eCOS_ERR_NONE on success. It is responsible for the following tasks:

• Initialize the CANopen state machine
• Initialize LED management

Possible values for uwConfigV are:

• COS_CONF_SLAVE for Classical CANopen
• COS_CONF_FD for CANopen FD

CosMgrOnBootUp()

void CosMgrOnBootUp

(

void

)

This callback is invoked from the CAN transmit handler the moment the Boot-up message has physically left the bus. At this point the device is visible to the network in NMT Pre-Operational state.

Use this callback for application startup tasks that must happen after the device has announced itself on the bus, e.g. enabling hardware outputs or driving safe initial values.

Note

Execution context: the callback is called from the CAN transmit handler (interrupt context in interrupt-driven builds). Keep the implementation short and avoid blocking calls.

Difference to CosMgrOnStart(): CosMgrOnStart() is called inside CosMgrStart() before the Boot-up message is queued — use it to configure stack settings (heartbeat producer time, SYNC period, EMCY code registration). CosMgrOnBootUp() fires after the Boot-up message has been transmitted — use it for hardware startup that requires the device to be on the bus.

See also

CosMgrOnStart(), CosMgrStart()

CosMgrOnBusOff()

void CosMgrOnBusOff

(

void

)

This callback is invoked when the CAN controller has entered the Bus-Off state. All CAN communication is suspended by the stack automatically.

Typical response in this callback:

• Set application outputs to a defined safe state (e.g. disable actuators).
• Do not call CosMgrStart() from within this callback.

Bus-Off recovery is managed by the stack. Once the controller has recovered, CosMgrProcess() returns eCOS_ERR_NODE_RESET. The application should then call CosMgrStart() from the main loop to restart the CANopen stack.

CosMgrOnStart()

void CosMgrOnStart

(

uint8_t

ubCallerResultV

)

Parameters

[in]

ubCallerResultV

Result of CANopen service initialization

This event is called inside CosMgrStart() before the Boot-up message is queued for transmission. Use it to configure stack settings such as heartbeat producer time, SYNC period, device type, and EMCY code registration. The device is not yet visible on the network at this point.

Note

Difference to CosMgrOnBootUp(): CosMgrOnBootUp() fires after the Boot-up message has physically been transmitted and the device is in NMT Pre-Operational state. Use it for hardware startup tasks that require the device to be on the bus.

The parameter ubCallerResultV holds the state of the initialization process. Possible values are defined by the CosErr_e enumeration. On successful initialization the value for ubCallerResultV is eCOS_ERR_NONE.

The following example shows how to change default settings for the heartbeat and the SYNC producer, as well as registration of EMCY codes.

void CosMgrOnStart(uint8_t ubCallerResultV)
{
   //---------------------------------------------------------------------------------------------------
   // Device Profile : CiA 401
   //
   Cos301_SetDeviceType(1, 0x000F0191);
 
   //---------------------------------------------------------------------------------------------------
   // Register possible EMCY codes
   //
   CosEmcyErrorRegister(eEMCY_301_MAINS_VOLTAGE,         EMCY_ERR_VOLT_INP_LOW, eCO_ERR_REG_VOLTAGE,     0);
   CosEmcyErrorRegister(eEMCY_301_DEVICE_TEMPERATURE,    EMCY_ERR_TEMP_DEVICE,  eCO_ERR_REG_TEMPERATURE, 0);
 
   //---------------------------------------------------------------------------------------------------
   // Check status of initialization
   //
   switch (ubCallerResultV)
   {
      case eCOS_ERR_NONE:
         // no error
         break;
 
      case eCOS_ERR_CAN_INIT:
         // failed to initialise CAN interface
         break;
 
      case eCOS_ERR_VALUE_NODE_ID:
         // node-ID not valid
         break;
 
      case eCOS_ERR_PARM_LOAD:
         // could not load parameters from NVM
         break;
 
      default:
         break;
 
   }
 
   //---------------------------------------------------------------------------------------------------
   // Set SYNC producer to 2 sec
   //
   CosSyncSetProducer(2000);
 
   //---------------------------------------------------------------------------------------------------
   // Set heartbeat producer to 1 sec
   //
   CosNmtSetHeartbeatProd(1000);
}

CosMgrProcess()

uint8_t CosMgrProcess

(

void

)

Returns

Status of the CANopen Slave protocol stack

This function must be called repeatedly from the application main loop. It performs all background processing required by the CANopen stack:

• In polling mode (COS_MGR_INT = 0): reads pending CAN messages from all receive buffers and dispatches them to the appropriate service handlers (NMT, SDO/USDO, PDO, SYNC, …). In interrupt mode (COS_MGR_INT = 1) this step is skipped as messages are already dispatched by the CAN receive callback.
• Dispatches pending SYNC events and triggers synchronous PDO processing.
• Detects NMT reset-node or reset-communication commands.
• Executes NVM load/store operations requested by the object dictionary.
• Runs background processing for optional services (secure configuration, USDO).

Possible return values and the expected application response:

Return value	Meaning	Application action
eCOS_ERR_NONE	Normal operation	Call again on next cycle
eCOS_ERR_NODE_RESET	NMT reset command received, or Bus-Off / Stop state	Call CosMgrStart() to restart
eCOS_ERR_NODE_INIT	CosMgrStart() has not been called yet	Call CosMgrStart() first

CosMgrProfileUpdate()

void CosMgrProfileUpdate	(	uint16_t	uwIndexV,
		uint8_t	ubSubIndexV )

Parameters

uwIndexV	parameter index
ubSubIndexV	parameter sub-index

This function is called by the stack when a parameter of a device profile is modified. It can be used to control the interaction between the CANopen slave stack and the application. The implementation of this function depends on the application.

CosMgrRelease()

uint8_t CosMgrRelease

(

void

)

Returns

Error Code

This routine stops the CANopen protocol stack. The function returns eCOS_ERR_NONE on success.

CosMgrStart()

uint8_t CosMgrStart	(	uint8_t	ubNodeIdV,
		int32_t	slBitrateNomSelV,
		int32_t	slBitrateDatSelV )

Parameters

ubNodeIdV	- Device node-ID (NID)
slBitrateNomSelV	- Nominal bit rate value
slBitrateDatSelV	- Data bit rate value

Returns

Error Code

See also

CosMgrOnBootUp(), CosMgrOnStart()

This routine starts the CANopen protocol stack on the given node-ID and bit rate. The initialization routines from other CANopen services are called and the Boot-up message is sent. The function returns eCOS_ERR_NONE on success.

In case the device shall be started in classical CANopen mode the parameter slBitrateDatSelV must be set to eCP_BITRATE_NONE.

Attention

The parameter slBitrateDatSelV was added in major version 6 for CANopen FD support. When migrating from an earlier version, add eCP_BITRATE_NONE as the third argument to retain classical CANopen behaviour.