Driver API for CAN Bus Peripheral (Driver_CAN.h) More...

Content
	Status Error Codes
	Status codes of the CAN driver.

	CAN Unit Events
	Callback unit events notified via ARM_CAN_SignalUnitEvent.

	CAN Object Events
	Callback objects events notified via ARM_CAN_SignalObjectEvent.

	CAN Control Codes
	Codes to configure the CAN driver.

Data Structures
struct	ARM_DRIVER_CAN
	Access structure of the CAN Driver. More...

struct	ARM_CAN_CAPABILITIES
	CAN Device Driver Capabilities. More...

struct	ARM_CAN_STATUS
	CAN Status. More...

struct	ARM_CAN_MSG_INFO
	CAN Message Information. More...

struct	ARM_CAN_OBJ_CAPABILITIES
	CAN Object Capabilities. More...

Typedefs
typedef void(*	ARM_CAN_SignalUnitEvent_t )(uint32_t event)
	Pointer to ARM_CAN_SignalUnitEvent : Signal CAN Unit Event.

typedef void(*	ARM_CAN_SignalObjectEvent_t )(uint32_t obj_idx, uint32_t event)
	Pointer to ARM_CAN_SignalObjectEvent : Signal CAN Object Event.

Functions
ARM_DRIVER_VERSION	ARM_CAN_GetVersion (void)
	Get driver version.

ARM_CAN_CAPABILITIES	ARM_CAN_GetCapabilities (void)
	Get driver capabilities.

int32_t	ARM_CAN_Initialize (ARM_CAN_SignalUnitEvent_t cb_unit_event, ARM_CAN_SignalObjectEvent_t cb_object_event)
	Initialize CAN interface and register signal (callback) functions.

int32_t	ARM_CAN_Uninitialize (void)
	De-initialize CAN interface.

int32_t	ARM_CAN_PowerControl (ARM_POWER_STATE state)
	Control CAN interface power.

uint32_t	ARM_CAN_GetClock (void)
	Retrieve CAN base clock frequency.

int32_t	ARM_CAN_SetBitrate (ARM_CAN_BITRATE_SELECT select, uint32_t bitrate, uint32_t bit_segments)
	Set bitrate for CAN interface.

int32_t	ARM_CAN_SetMode (ARM_CAN_MODE mode)
	Set operating mode for CAN interface.

ARM_CAN_OBJ_CAPABILITIES	ARM_CAN_ObjectGetCapabilities (uint32_t obj_idx)
	Retrieve capabilities of an object.

int32_t	ARM_CAN_ObjectSetFilter (uint32_t obj_idx, ARM_CAN_FILTER_OPERATION operation, uint32_t id, uint32_t arg)
	Add or remove filter for message reception.

int32_t	ARM_CAN_ObjectConfigure (uint32_t obj_idx, ARM_CAN_OBJ_CONFIG obj_cfg)
	Configure object.

int32_t	ARM_CAN_MessageSend (uint32_t obj_idx, ARM_CAN_MSG_INFO msg_info, const uint8_t data, uint8_t size)
	Send message on CAN bus.

int32_t	ARM_CAN_MessageRead (uint32_t obj_idx, ARM_CAN_MSG_INFO msg_info, uint8_t data, uint8_t size)
	Read message received on CAN bus.

int32_t	ARM_CAN_Control (uint32_t control, uint32_t arg)
	Control CAN interface.

ARM_CAN_STATUS	ARM_CAN_GetStatus (void)
	Get CAN status.

void	ARM_CAN_SignalUnitEvent (uint32_t event)
	Signal CAN unit event.

void	ARM_CAN_SignalObjectEvent (uint32_t obj_idx, uint32_t event)
	Signal CAN object event.

Description

Driver API for CAN Bus Peripheral (Driver_CAN.h)

The Controller Area Network Interface Bus (CAN) implements a multi-master serial bus for connecting microcontrollers and devices, also known as nodes, to communicate with each other in applications without a host computer. CAN is a message-based protocol, designed originally for automotive applications, but meanwhile used also in many other surroundings. The complexity of the node can range from a simple I/O device up to an embedded computer with a CAN interface and sophisticated software. The node may also be a gateway allowing a standard computer to communicate over a USB or Ethernet port to the devices on a CAN network. Devices are connected to the bus through a host processor, a CAN controller, and a CAN transceiver.

The CAN Driver API allows to implement CAN Interfaces that conform to the following CAN specifications available from BOSCH:

CAN 2.0B: CAN Specification 2.0B (released Sep. 1991) which is now superseded by ISO 11898-1.
CAN FD: CAN with Flexible Data Rate introduced in 2012 (released April 17th, 2012).

Wikipedia offers more information about the CAN Bus.

CAN 2.0B Every CAN CMSIS-Driver supports the CAN 2.0B standard

CAN 2.0B supports:

message can contain up to 8 data bytes
bitrates of up to 1Mbits/s
Remote Frame requests

CAN FD

Support for CAN FD depends on the hardware. A CMSIS-Driver that supports CAN FD has the capability ARM_CAN_CAPABILITIES data field fd_mode = 1, which can be retrieved with the function ARM_CAN_GetCapabilities.

CAN FD supports:

message can contain up to 64 data bytes
faster data transfers with faster bitrate used during the data phase

CAN FD does not support Remote Frame requests.

Block Diagram

The CAN Driver API defines a CAN interface for middleware components. The CAN Driver supports multiple nodes, which are able to send and receive messages, but not simultaneously.

CAN Node Schematic

CAN API

The following header files define the Application Programming Interface (API) for the CAN interface:

Driver_CAN.h : Driver API for CAN Bus Peripheral

The driver implementation is a typical part of the Device Family Pack (DFP) that supports the peripherals of the microcontroller family.

Driver Functions

The driver functions are published in the access struct as explained in Common Driver Functions

ARM_DRIVER_CAN : access struct for CAN driver functions

Example Code

The following example code shows the usage of the CAN interface.

#include <stdio.h>
#include <string.h>
#include "cmsis_os.h"
 
#include "Driver_CAN.h"
 
// CAN Driver Controller selector
#define  CAN_CONTROLLER         1       // CAN Controller number
 
#define _CAN_Driver_(n)         Driver_CAN##n
#define  CAN_Driver_(n)        _CAN_Driver_(n)
extern   ARM_DRIVER_CAN         CAN_Driver_(CAN_CONTROLLER);
#define  ptrCAN               (&CAN_Driver_(CAN_CONTROLLER))
 
uint32_t                        rx_obj_idx  = 0xFFFFFFFFU;
uint8_t                         rx_data[8];
ARM_CAN_MSG_INFO                rx_msg_info;
uint32_t                        tx_obj_idx  = 0xFFFFFFFFU;
uint8_t                         tx_data[8];
ARM_CAN_MSG_INFO                tx_msg_info;
 
static void Error_Handler (void) { while (1); }
 
void CAN_SignalUnitEvent (uint32_t event) {}
 
void CAN_SignalObjectEvent (uint32_t obj_idx, uint32_t event) {
 
  if (obj_idx == rx_obj_idx) {                  // If receive object event
    if (event == ARM_CAN_EVENT_RECEIVE) {       // If message was received successfully
      if (ptrCAN->MessageRead(rx_obj_idx, &rx_msg_info, rx_data, 8U) > 0U) {
                                                // Read received message
        // process received message ...
      }
    }
  }
  if (obj_idx == tx_obj_idx) {                  // If transmit object event
    if (event == ARM_CAN_EVENT_SEND_COMPLETE) { // If message was sent successfully
      // acknowledge sent message ...
    }
  }
}
 
int main (void) {
  ARM_CAN_CAPABILITIES     can_cap;
  ARM_CAN_OBJ_CAPABILITIES can_obj_cap;
  int32_t                  status;
  uint32_t                 i, num_objects;
 
  can_cap = ptrCAN->GetCapabilities (); // Get CAN driver capabilities
  num_objects = can_cap.num_objects;    // Number of receive/transmit objects
 
  status = ptrCAN->Initialize    (CAN_SignalUnitEvent, CAN_SignalObjectEvent);  // Initialize CAN driver
  if (status != ARM_DRIVER_OK ) { Error_Handler(); }
 
  status = ptrCAN->PowerControl  (ARM_POWER_FULL);                              // Power-up CAN controller
  if (status != ARM_DRIVER_OK ) { Error_Handler(); }
 
  status = ptrCAN->SetMode       (ARM_CAN_MODE_INITIALIZATION);                 // Activate initialization mode
  if (status != ARM_DRIVER_OK ) { Error_Handler(); }
 
  status = ptrCAN->SetBitrate    (ARM_CAN_BITRATE_NOMINAL,              // Set nominal bitrate
                                  100000U,                              // Set bitrate to 100 kbit/s
                                  ARM_CAN_BIT_PROP_SEG(5U)   |          // Set propagation segment to 5 time quanta
                                  ARM_CAN_BIT_PHASE_SEG1(1U) |          // Set phase segment 1 to 1 time quantum (sample point at 87.5% of bit time)
                                  ARM_CAN_BIT_PHASE_SEG2(1U) |          // Set phase segment 2 to 1 time quantum (total bit is 8 time quanta long)
                                  ARM_CAN_BIT_SJW(1U));                 // Resynchronization jump width is same as phase segment 2
  if (status != ARM_DRIVER_OK ) { Error_Handler(); }
 
  for (i = 0U; i < num_objects; i++) {                                          // Find first available object for receive and transmit
    can_obj_cap = ptrCAN->ObjectGetCapabilities (i);                            // Get object capabilities
    if      ((rx_obj_idx == 0xFFFFFFFFU) && (can_obj_cap.rx == 1U)) { rx_obj_idx = i; }
    else if ((tx_obj_idx == 0xFFFFFFFFU) && (can_obj_cap.tx == 1U)) { tx_obj_idx = i; break; }
  }
  if ((rx_obj_idx == 0xFFFFFFFFU) || (tx_obj_idx == 0xFFFFFFFFU)) { Error_Handler(); }
 
  // Set filter to receive messages with extended ID 0x12345678 to receive object
  status = ptrCAN->ObjectSetFilter(rx_obj_idx, ARM_CAN_FILTER_ID_EXACT_ADD, ARM_CAN_EXTENDED_ID(0x12345678U), 0U);
  if (status != ARM_DRIVER_OK ) { Error_Handler(); }
 
  status = ptrCAN->ObjectConfigure(tx_obj_idx, ARM_CAN_OBJ_TX);                 // Configure transmit object
  if (status != ARM_DRIVER_OK ) { Error_Handler(); }
 
  status = ptrCAN->ObjectConfigure(rx_obj_idx, ARM_CAN_OBJ_RX);                 // Configure receive object
  if (status != ARM_DRIVER_OK ) { Error_Handler(); }
  
  status = ptrCAN->SetMode (ARM_CAN_MODE_NORMAL);                               // Activate normal operation mode
  if (status != ARM_DRIVER_OK ) { Error_Handler(); }
  
  memset(&tx_msg_info, 0U, sizeof(ARM_CAN_MSG_INFO));                           // Clear message info structure
  tx_msg_info.id = ARM_CAN_EXTENDED_ID(0x12345678U);                            // Set extended ID for transmit message
  tx_data[0]     = 0xFFU;                                                       // Initialize transmit data
  while (1) {
    tx_data[0]++;                                                               // Increment transmit data
    status = ptrCAN->MessageSend(tx_obj_idx, &tx_msg_info, tx_data, 1U);        // Send data message with 1 data byte
    if (status != 1U) { Error_Handler(); }
    for (i = 0U; i < 1000000U; i++) { __nop(); }                                // Wait a little while
  }
}

CAN Message Objects

The CMSIS-Driver for the CAN interface provides multiple CAN message objects, which can be seen as individual communication channels. The number of available CAN message objects depends on the CAN peripheral. The function ARM_CAN_GetCapabilities returns the maximum number of available CAN message objects. The number is encoded in the structure ARM_CAN_CAPABILITIES in the data field num_objects. CAN message objects are addressed with the functions listed below, whereby the parameter obj_idx addresses an individual object. The valid range for obj_idx is [0 .. (num_objects - 1)].

Function	Description
ARM_CAN_ObjectGetCapabilities	Retrieves message object capabilities such as receive, transmit, Remote Frame automatic handling and CAN Message Filtering.
ARM_CAN_ObjectSetFilter	Allows to set-up CAN ID filtering for the message object.
ARM_CAN_ObjectConfigure	Allows to configure the message object for receive, transmit or Remote Frame automatic handling.
ARM_CAN_MessageRead	Read received message from the message object.
ARM_CAN_MessageSend	Send CAN message or send Remote Frame or set CAN message to be sent automatically on reception of matching Remote Frame on the message object.
ARM_CAN_SignalObjectEvent	Callback function that signals a message transfer or a received message overrun.

Each CAN message object may have different capabilities. Before using a CAN message object, call the function ARM_CAN_ObjectGetCapabilities to verify the available features.

CAN Message Filtering

The CMSIS-Driver for the CAN interface supports ID filtering for the receiving message objects. The receiving CAN node examines the identifier to decide if it was relevant. This filtering is done by the CAN peripheral according the settings configured with the function ARM_CAN_ObjectSetFilter.

The function ARM_CAN_ObjectGetCapabilities retrieves the filter capabilities of the CAN message objects stored in ARM_CAN_OBJ_CAPABILITIES.

Data Fields	CAN Messages Object can be filtered with ...
exact_filtering	an exact ID value set by using the function ARM_CAN_ObjectSetFilter with control = ARM_CAN_FILTER_ID_EXACT_ADD.
range_filtering	a range ID value set by using the function ARM_CAN_ObjectSetFilter with control = ARM_CAN_FILTER_ID_RANGE_ADD.
mask_filtering	a mask ID value set by as using the function ARM_CAN_ObjectSetFilter with control = ARM_CAN_FILTER_ID_MASKABLE_ADD.
multiple_filters	... several filters to capture multiple ID values, or ID value ranges.

CAN message filtering using an exact ID

Example: accept in message object #1 only frames with extended ID = 0x1567.

status = ptrCAN->ObjectSetFilter (1, ARM_CAN_FILTER_ID_EXACT_ADD, ARM_CAN_EXTENDED_ID(0x1567), 0);