Interface between CAN hardware and CANopenNode. More...

Collaboration diagram for Driver:

Topics
	Stack configuration
	Stack configuration and enabling macros.

	Basic definitions


	Reception of CAN messages


	Transmission of CAN messages


	Critical sections


	Default CANopen identifiers


	CAN error status bitmasks

Files
file	CO_driver.h
	Interface between CAN hardware and CANopenNode.

Data Structures
struct	CO_CANmodule_t
	Complete CAN module object. More...

struct	CO_storage_entry_t
	Data storage object for one entry. More...

Macros
#define	CO_VERSION_MAJOR 4
	Major version number of CANopenNode.

#define	CO_VERSION_MINOR 0
	Minor version number of CANopenNode.

#define	CO_IS_RESTRICTED_CAN_ID(CAN_ID)
	Restricted CAN-IDs.

Enumerations
enum	CO_ReturnError_t { CO_ERROR_NO = 0 , CO_ERROR_ILLEGAL_ARGUMENT = -1 , CO_ERROR_OUT_OF_MEMORY = -2 , CO_ERROR_TIMEOUT = -3 , CO_ERROR_ILLEGAL_BAUDRATE = -4 , CO_ERROR_RX_OVERFLOW = -5 , CO_ERROR_RX_PDO_OVERFLOW = -6 , CO_ERROR_RX_MSG_LENGTH = -7 , CO_ERROR_RX_PDO_LENGTH = -8 , CO_ERROR_TX_OVERFLOW = -9 , CO_ERROR_TX_PDO_WINDOW = -10 , CO_ERROR_TX_UNCONFIGURED = -11 , CO_ERROR_OD_PARAMETERS = -12 , CO_ERROR_DATA_CORRUPT = -13 , CO_ERROR_CRC = -14 , CO_ERROR_TX_BUSY = -15 , CO_ERROR_WRONG_NMT_STATE = -16 , CO_ERROR_SYSCALL = -17 , CO_ERROR_INVALID_STATE = -18 , CO_ERROR_NODE_ID_UNCONFIGURED_LSS }
	Return values of some CANopen functions. More...

Functions
void	CO_CANsetConfigurationMode (void *CANptr)
	Request CAN configuration (stopped) mode and wait until it is set.

void	CO_CANsetNormalMode (CO_CANmodule_t *CANmodule)
	Request CAN normal (operational) mode and wait until it is set.

CO_ReturnError_t	CO_CANmodule_init (CO_CANmodule_t CANmodule, void CANptr, CO_CANrx_t rxArray[], uint16_t rxSize, CO_CANtx_t txArray[], uint16_t txSize, uint16_t CANbitRate)
	Initialize CAN module object.

void	CO_CANmodule_disable (CO_CANmodule_t *CANmodule)
	Switch off CANmodule.

CO_ReturnError_t	CO_CANrxBufferInit (CO_CANmodule_t CANmodule, uint16_t index, uint16_t ident, uint16_t mask, bool_t rtr, void object, void(CANrx_callback)(void object, void *message))
	Configure CAN message receive buffer.

CO_CANtx_t *	CO_CANtxBufferInit (CO_CANmodule_t *CANmodule, uint16_t index, uint16_t ident, bool_t rtr, uint8_t noOfBytes, bool_t syncFlag)
	Configure CAN message transmit buffer.

CO_ReturnError_t	CO_CANsend (CO_CANmodule_t CANmodule, CO_CANtx_t buffer)
	Send CAN message.

void	CO_CANclearPendingSyncPDOs (CO_CANmodule_t *CANmodule)
	Clear all synchronous TPDOs from CAN module transmit buffers.

void	CO_CANmodule_process (CO_CANmodule_t *CANmodule)
	Process can module - verify CAN errors.

static uint8_t	CO_getUint8 (const void *buf)
	Get uint8_t value from memory buffer.

static uint16_t	CO_getUint16 (const void *buf)
	Get uint16_t value from memory buffer, see CO_getUint8.

static uint32_t	CO_getUint32 (const void *buf)
	Get uint32_t value from memory buffer, see CO_getUint8.

static uint8_t	CO_setUint8 (void *buf, uint8_t value)
	Write uint8_t value into memory buffer.

static uint8_t	CO_setUint16 (void *buf, uint16_t value)
	Write uint16_t value into memory buffer, see CO_setUint8.

static uint8_t	CO_setUint32 (void *buf, uint32_t value)
	Write uint32_t value into memory buffer, see CO_setUint8.

Detailed Description

Interface between CAN hardware and CANopenNode.

CANopenNode is designed for speed and portability. It runs efficiently on devices from simple 16-bit microcontrollers to PC computers. It can run in multiple threads. Reception of CAN messages is pre-processed with very fast functions. Time critical objects, such as PDO or SYNC are processed in real-time thread and other objects are processed in normal thread. See Flowchart in README.md for more information.

CANopenNode Object

CANopenNode is implemented as a collection of different objects, for example SDO, SYNC, Emergency, PDO, NMT, Heartbeat, etc. Code is written in C language and tries to be object oriented. So each CANopenNode Object is implemented in a pair of .h/.c files. It basically contains a structure with all necessary variables and some functions which operates on it. CANopenNode Object is usually connected with one or more CAN receive or transmit Message Objects. (CAN message Object is a CAN message with specific 11-bit CAN identifier (usually one fixed or a range).)

Hardware interface of CANopenNode

It consists of minimum three files:

CO_driver.h file declares common functions. This file is part of the CANopenNode. It is included from each .c file from CANopenNode.
CO_driver_target.h file declares microcontroller specific type declarations and defines some macros, which are necessary for CANopenNode. This file is included from CO_driver.h.
CO_driver.c file defines functions declared in CO_driver.h.

CO_driver_target.h and CO_driver.c files are specific for each different microcontroller and are not part of CANopenNode. There are separate projects for different microcontrollers, which usually include CANopenNode as a git submodule. CANopenNode only includes those two files in the example directory and they are basically empty. It should be possible to compile the CANopenNode/example on any system, however compiled program is not usable. CO_driver.h contains documentation for all necessary macros, types and functions.

See CANopenNode/Wiki for a known list of available implementations of CANopenNode on different systems and microcontrollers. Everybody is welcome to extend the list with a link to his own implementation.

Implementation of the hardware interface for specific microcontroller is not always an easy task. For reliable and efficient operation it is necessary to know some parts of the target microcontroller in detail (for example threads (or interrupts), CAN module, etc.).

Macro Definition Documentation

◆ CO_IS_RESTRICTED_CAN_ID

#define CO_IS_RESTRICTED_CAN_ID ( CAN_ID )

Value:

    (((CAN_ID) <= 0x7FU) || (((CAN_ID) >= 0x101U) && ((CAN_ID) <= 0x180U))                                             \
     || (((CAN_ID) >= 0x581U) && ((CAN_ID) <= 0x5FFU)) || (((CAN_ID) >= 0x601U) && ((CAN_ID) <= 0x67FU))               \
     || (((CAN_ID) >= 0x6E0U) && ((CAN_ID) <= 0x6FFU)) || ((CAN_ID) >= 0x701U))

Restricted CAN-IDs.

Macro for verifying 'Restricted CAN-IDs', as specified by standard CiA301. They shall not be used for SYNC, TIME, EMCY, PDO and SDO.

Enumeration Type Documentation

◆ CO_ReturnError_t

enum CO_ReturnError_t

Return values of some CANopen functions.

If function was executed successfully it returns 0 otherwise it returns <0.

Enumerator
CO_ERROR_NO	Operation completed successfully.
CO_ERROR_ILLEGAL_ARGUMENT	Error in function arguments.
CO_ERROR_OUT_OF_MEMORY	Memory allocation failed.
CO_ERROR_TIMEOUT	Function timeout.
CO_ERROR_ILLEGAL_BAUDRATE	Illegal baudrate passed to function CO_CANmodule_init()
CO_ERROR_RX_OVERFLOW	Previous message was not processed yet.
CO_ERROR_RX_PDO_OVERFLOW	previous PDO was not processed yet
CO_ERROR_RX_MSG_LENGTH	Wrong receive message length.
CO_ERROR_RX_PDO_LENGTH	Wrong receive PDO length.
CO_ERROR_TX_OVERFLOW	Previous message is still waiting, buffer full.
CO_ERROR_TX_PDO_WINDOW	Synchronous TPDO is outside window.
CO_ERROR_TX_UNCONFIGURED	Transmit buffer was not configured properly.
CO_ERROR_OD_PARAMETERS	Error in Object Dictionary parameters.
CO_ERROR_DATA_CORRUPT	Stored data are corrupt.
CO_ERROR_CRC	CRC does not match.
CO_ERROR_TX_BUSY	Sending rejected because driver is busy. Try again
CO_ERROR_WRONG_NMT_STATE	Command can't be processed in current state.
CO_ERROR_SYSCALL	Syscall failed.
CO_ERROR_INVALID_STATE	Driver not ready.
CO_ERROR_NODE_ID_UNCONFIGURED_LSS	Node-id is in LSS unconfigured state. If objects are handled properly, this may not be an error.

Function Documentation

◆ CO_CANsetConfigurationMode()

void CO_CANsetConfigurationMode ( void * CANptr )

Request CAN configuration (stopped) mode and wait until it is set.

Parameters

CANptr Pointer to CAN device

◆ CO_CANsetNormalMode()

void CO_CANsetNormalMode ( CO_CANmodule_t * CANmodule )

Request CAN normal (operational) mode and wait until it is set.

Parameters

CANmodule CO_CANmodule_t object.

◆ CO_CANmodule_init()

CO_ReturnError_t CO_CANmodule_init	(	CO_CANmodule_t *	CANmodule,
		void *	CANptr,
		CO_CANrx_t	rxArray[],
		uint16_t	rxSize,
		CO_CANtx_t	txArray[],
		uint16_t	txSize,
		uint16_t	CANbitRate )

Initialize CAN module object.

Function must be called in the communication reset section. CAN module must be in Configuration Mode before.

Parameters

CANmodule	This object will be initialized.
CANptr	Pointer to CAN device.
rxArray	Array for handling received CAN messages
rxSize	Size of the above array. Must be equal to number of receiving CAN objects.
txArray	Array for handling transmitting CAN messages
txSize	Size of the above array. Must be equal to number of transmitting CAN objects.
CANbitRate	Valid values are (in kbps): 10, 20, 50, 125, 250, 500, 800, 1000. If value is illegal, bitrate defaults to 125.

Return CO_ReturnError_t: CO_ERROR_NO or CO_ERROR_ILLEGAL_ARGUMENT.

◆ CO_CANmodule_disable()

void CO_CANmodule_disable ( CO_CANmodule_t * CANmodule )

Switch off CANmodule.

Call at program exit.

Parameters

CANmodule CAN module object.

◆ CO_CANrxBufferInit()

CO_ReturnError_t CO_CANrxBufferInit	(	CO_CANmodule_t *	CANmodule,
		uint16_t	index,
		uint16_t	ident,
		uint16_t	mask,
		bool_t	rtr,
		void *	object,
		void(*	CANrx_callback )(void object, void message) )

Configure CAN message receive buffer.

Function configures specific CAN receive buffer. It sets CAN identifier and connects buffer with specific object. Function must be called for each member in rxArray from CO_CANmodule_t.

Parameters

CANmodule	This object.
index	Index of the specific buffer in rxArray.
ident	11-bit standard CAN Identifier. If two or more CANrx buffers have the same ident, then buffer with lowest index has precedence and other CANrx buffers will be ignored.
mask	11-bit mask for identifier. Most usually set to 0x7FF. Received message (rcvMsg) will be accepted if the following condition is true: (((rcvMsgId ^ ident) & mask) == 0).
rtr	If true, 'Remote Transmit Request' messages will be accepted.
object	CANopen object, to which buffer is connected. It will be used as an argument to CANrx_callback. Its type is (void), CANrx_callback will change its type back to the correct object type.
CANrx_callback	Pointer to function, which will be called, if received CAN message matches the identifier. It must be fast function.

Return CO_ReturnError_t: CO_ERROR_NO CO_ERROR_ILLEGAL_ARGUMENT or CO_ERROR_OUT_OF_MEMORY (not enough masks for configuration).

◆ CO_CANtxBufferInit()

CO_CANtx_t * CO_CANtxBufferInit	(	CO_CANmodule_t *	CANmodule,
		uint16_t	index,
		uint16_t	ident,
		bool_t	rtr,
		uint8_t	noOfBytes,
		bool_t	syncFlag )

Configure CAN message transmit buffer.

Function configures specific CAN transmit buffer. Function must be called for each member in txArray from CO_CANmodule_t.

Parameters

CANmodule	This object.
index	Index of the specific buffer in txArray.
ident	11-bit standard CAN Identifier.
rtr	If true, 'Remote Transmit Request' messages will be transmitted.
noOfBytes	Length of CAN message in bytes (0 to 8 bytes).
syncFlag	This flag bit is used for synchronous TPDO messages. If it is set, message will not be sent, if current time is outside synchronous window.

Returns: Pointer to CAN transmit message buffer. 8 bytes data array inside buffer should be written, before CO_CANsend() function is called. Zero is returned in case of wrong arguments.

◆ CO_CANsend()

CO_ReturnError_t CO_CANsend	(	CO_CANmodule_t *	CANmodule,
		CO_CANtx_t *	buffer )

Send CAN message.

Parameters

CANmodule	This object.
buffer	Pointer to transmit buffer, returned by CO_CANtxBufferInit(). Data bytes must be written in buffer before function call.

Returns: CO_ReturnError_t: CO_ERROR_NO, CO_ERROR_TX_OVERFLOW or CO_ERROR_TX_PDO_WINDOW (Synchronous TPDO is outside window).

◆ CO_CANclearPendingSyncPDOs()

void CO_CANclearPendingSyncPDOs ( CO_CANmodule_t * CANmodule )

Clear all synchronous TPDOs from CAN module transmit buffers.

CANopen allows synchronous PDO communication only inside time between SYNC message and SYNC Window. If time is outside this window, new synchronous PDOs must not be sent and all pending sync TPDOs, which may be on CAN TX buffers, may optionally be cleared.

This function checks (and aborts transmission if necessary) CAN TX buffers when it is called. Function should be called by the stack in the moment, when SYNC time was just passed out of synchronous window.

Parameters

CANmodule This object.

◆ CO_CANmodule_process()

void CO_CANmodule_process ( CO_CANmodule_t * CANmodule )

Process can module - verify CAN errors.

Function must be called cyclically. It should calculate CANerrorStatus bitfield for CAN errors defined in CAN error status bitmasks.

Parameters

CANmodule This object.

◆ CO_getUint8()

static uint8_t CO_getUint8 ( const void * buf )

inlinestatic

Get uint8_t value from memory buffer.

Parameters

buf	Memory buffer to get value from.

Returns: Value

◆ CO_setUint8()

static uint8_t CO_setUint8	(	void *	buf,
		uint8_t	value )

inlinestatic

Write uint8_t value into memory buffer.

Parameters

buf	Memory buffer.
value	Value to be written into buf.

Returns: number of bytes written.

Topics

Files

Data Structures

Macros

Enumerations

Functions

Detailed Description

CANopenNode Object

Hardware interface of CANopenNode

Macro Definition Documentation

◆ CO_IS_RESTRICTED_CAN_ID

Enumeration Type Documentation

◆ CO_ReturnError_t

Function Documentation

◆ CO_CANsetConfigurationMode()

◆ CO_CANsetNormalMode()

◆ CO_CANmodule_init()

◆ CO_CANmodule_disable()

◆ CO_CANrxBufferInit()

◆ CO_CANtxBufferInit()

◆ CO_CANsend()

◆ CO_CANclearPendingSyncPDOs()

◆ CO_CANmodule_process()

◆ CO_getUint8()

◆ CO_setUint8()