CAN Library

The mikroC PRO for FT90x provides a library (driver) for working with the CAN module.

The CAN is a very robust protocol that has error detection and signalization, self–checking and fault confinement. Faulty CAN data and remote frames are re-transmitted automatically, similar to the Ethernet.

Data transfer rates depend on distance. For example, 1 Mbit/s can be achieved at network lengths below 40m while 250 Kbit/s can be achieved at network lengths below 250m. The greater distance the lower maximum bitrate that can be achieved. The lowest bitrate defined by the standard is 200Kbit/s. Cables used are shielded twisted pairs.

Two CAN bus controllers are supported by this library. The controllers have the following features :

Conforms to Bosch CAN 2.0B specification,
Data rate up to 1Mbps,
Hardware message filtering (dual/single filters),
64-byte receive FIFO,
16-byte transmit buffer,
No overload frames are generated,
Normal & Listen Only modes supported,
Single Shot transmission,
Ability to abort transmission,
Readable error counters,
Last Error Code.

Important :

Consult the CAN standard about CAN bus termination resistance.

CANSysInit

Prototype

void CANSysInit(TCANStruct *CANx);

Description

Initializes system registers for CAN module usage.

Parameters

CANx: CAN module selection parameter. Valid values :

Value	Description
CAN0	CAN0 module.
CAN1	CAN1 module.

Returns

Nothing.

Requires

MCU with the CAN module.

MCU must be connected to the CAN transceiver (MCP2551 or similar) which is connected to the CAN bus.

Example

// initialize system registers for CAN0 module usage
CANSysInit(&CAN0);

Notes

None.

canInit

Prototype

CAN_STATUS canInit(TCANStruct *CANx, uint16_t bitratekB);

Description

This routine initializes CAN device. This is basic initialization which sets mode of operation.

Parameters

CANx: CAN module selection parameter. Valid values :

Value	Description
CAN0	CAN0 module.
CAN1	CAN1 module.

bitratekB: the desired CAN bus speed. The bitrate is in kB/s and the allowed values are 1000, 500, 250, 125, 50, 25 and 10.

Returns

This routine returns CAN_STATUS status message via enum defined in the following way :

typedef enum
{
  CAN_OK,         // CAN device initialized
  CAN_ERROR,      // error occured, CAN device not initialized
  CAN_RX_OVERRUN
} CAN_STATUS;

Requires

MCU with the CAN module.

MCU must be connected to the CAN transceiver (MCP2551 or similar) which is connected to the CAN bus.

Example

Notes

None.

readCANReg

Prototype

uint8_t readCANReg(TCANStruct *CANx, uint8_t reg);

Description

This routine reads any CAN register.

Parameters

CANx: CAN module selection parameter. Valid values :

Value	Description
CAN0	CAN0 module.
CAN1	CAN1 module.

reg: desired CAN register.

Value	Description
MR	mode register.
CMD	command register.
SR	status register.
ISR_IACK	interrupt status / acknowledge register.
IMR	interrupt mask register.
BTR0	receive message counter register.
BTR1	bus timing register 0.
CAN1	bus timing register 1.
TXBUF0	transmit buffer register 0.
TXBUF1	transmit buffer register 1.
TXBUF2	transmit buffer register 2.
TXBUF3	transmit buffer register 3.
RXBUF0	receive buffer register 0.
RXBUF1	receive buffer register 1.
RXBUF2	receive buffer register 2.
RXBUF3	receive buffer register 3.
ACR0	acceptance code register 0.
ACR1	acceptance code register 1.
ACR2	acceptance code register 2.
ACR3	acceptance code register 3.
AMR0	acceptance mask register 0.
AMR1	acceptance mask register 1.
AMR2	acceptance mask register 2.
AMR3	acceptance mask register 3.
ECC	error code capture register.
RXERR	RX error counter register.
TXERR	TX error counter register.
ALC	management address register.

Returns

This routine returns CAN register value.

Requires

MCU with the CAN module.

MCU must be connected to the CAN transceiver (MCP2551 or similar) which is connected to the CAN bus.

Example

Notes

None.

writeCANReg

Prototype

void writeCANReg(TCANStruct *CANx, uint8_t val, uint8_t reg);

Description

This routine writes a value to any CAN register.

Parameters

CANx: CAN module selection parameter. Valid values :

Value	Description
CAN0	CAN0 module.
CAN1	CAN1 module.

val: value to be written to the register.

reg: desired CAN register.

Value	Description
MR	mode register.
CMD	command register.
SR	status register.
ISR_IACK	interrupt status / acknowledge register.
IMR	interrupt mask register.
BTR0	receive message counter register.
BTR1	bus timing register 0.
CAN1	bus timing register 1.
TXBUF0	transmit buffer register 0.
TXBUF1	transmit buffer register 1.
TXBUF2	transmit buffer register 2.
TXBUF3	transmit buffer register 3.
RXBUF0	receive buffer register 0.
RXBUF1	receive buffer register 1.
RXBUF2	receive buffer register 2.
RXBUF3	receive buffer register 3.
ACR0	acceptance code register 0.
ACR1	acceptance code register 1.
ACR2	acceptance code register 2.
ACR3	acceptance code register 3.
AMR0	acceptance mask register 0.
AMR1	acceptance mask register 1.
AMR2	acceptance mask register 2.
AMR3	acceptance mask register 3.
ECC	error code capture register.
RXERR	RX error counter register.
TXERR	TX error counter register.
ALC	management address register.

Returns

Nothing.

Requires

MCU with the CAN module.

MCU must be connected to the CAN transceiver (MCP2551 or similar) which is connected to the CAN bus.

Example

Notes

None.

canEnableInt

Prototype

void canEnableInt(TCANStruct *CANx, uint8_t ints);

Description

This routine enables CAN interrupts.

Parameters

CANx: CAN module selection parameter. Valid values :

Value	Description
CAN0	CAN0 module.
CAN1	CAN1 module.

ints: interrupt to be enabled. Valid values :

Value	Description
CAN_ARB_LOST_INT	Arbitration Lost Interrupt. Set when the CAN core has lost arbitration during transmission of its own message and become a receiver.
CAN_ERR_WARNING_INT	Error Warning Interrupt. Set when there is a change in Error Status or Bus Off Status bits or Status register.
CAN_ERR_PASSIVE_INT	Error Passive Interrupt. Set when CAN core has reached or exceed error passive level.
CAN_RX_INT	Receive Interrupt. Set when there is at least one message in the RX FIFO.
CAN_TX_INT	Transmission Interrupt. Set after a successful transmission.
CAN_BUS_ERR_INT	Bus Error Interrupt. Set when the CAN core encounters a bus error while transmitting or receiving a message.
CAN_DATA_OVERRUN_INT	Data Overrun Interrupt. Set when the RX FIFO overrun has occurred.

Returns

Nothing.

Requires

MCU with the CAN module.

MCU must be connected to the CAN transceiver (MCP2551 or similar) which is connected to the CAN bus.

Example

Notes

None.

canDisableInt

Prototype

void canDisableInt(TCANStruct *CANx, uint8_t ints);

Description

This routine disables CAN interrupts.

Parameters

CANx: CAN module selection parameter. Valid values :

Value	Description
CAN0	CAN0 module.
CAN1	CAN1 module.

ints: interrupt to be disabled. Valid values :

Value	Description
CAN_ARB_LOST_INT	Arbitration Lost Interrupt. Set when the CAN core has lost arbitration during transmission of its own message and become a receiver.
CAN_ERR_WARNING_INT	Error Warning Interrupt. Set when there is a change in Error Status or Bus Off Status bits or Status register.
CAN_ERR_PASSIVE_INT	Error Passive Interrupt. Set when CAN core has reached or exceed error passive level.
CAN_RX_INT	Receive Interrupt. Set when there is at least one message in the RX FIFO.
CAN_TX_INT	Transmission Interrupt. Set after a successful transmission.
CAN_BUS_ERR_INT	Bus Error Interrupt. Set when the CAN core encounters a bus error while transmitting or receiving a message.
CAN_DATA_OVERRUN_INT	Data Overrun Interrupt. Set when the RX FIFO overrun has occurred.

Returns

Nothing.

Requires

MCU with the CAN module.

MCU must be connected to the CAN transceiver (MCP2551 or similar) which is connected to the CAN bus.

Example

Notes

None.

canClearIntFlag

Prototype

void canClearIntFlag(TCANStruct *CANx, uint8_t ints);

Description

This routine clears CAN interrupt status flags.

Parameters

CANx: CAN module selection parameter. Valid values :

Value	Description
CAN0	CAN0 module.
CAN1	CAN1 module.

ints: interrupt whose status flag is to be cleared. Valid values :

Value	Description
CAN_ARB_LOST_INT	Arbitration Lost Interrupt. Set when the CAN core has lost arbitration during transmission of its own message and become a receiver.
CAN_ERR_WARNING_INT	Error Warning Interrupt. Set when there is a change in Error Status or Bus Off Status bits or Status register.
CAN_ERR_PASSIVE_INT	Error Passive Interrupt. Set when CAN core has reached or exceed error passive level.
CAN_RX_INT	Receive Interrupt. Set when there is at least one message in the RX FIFO.
CAN_TX_INT	Transmission Interrupt. Set after a successful transmission.
CAN_BUS_ERR_INT	Bus Error Interrupt. Set when the CAN core encounters a bus error while transmitting or receiving a message.
CAN_DATA_OVERRUN_INT	Data Overrun Interrupt. Set when the RX FIFO overrun has occurred.

Returns

Nothing.

Requires

MCU with the CAN module.

MCU must be connected to the CAN transceiver (MCP2551 or similar) which is connected to the CAN bus.

Example

Notes

None.

canGetStatus

Prototype

uint8_t canGetStatus(TCANStruct *CANx);

Description

This routine returns the global status variable value.

Parameters

CANx: CAN module selection parameter. Valid values :

Value	Description
CAN0	CAN0 module.
CAN1	CAN1 module.

Returns

Returns an 8-bit status variable. The bits order and values in the status variable are :

INIT : 1 after a completed initialization, 0 if not yet initialized or init failed.
CERR : 1 if a CAN bit or frame error occured.
ERPA : 1 if a CAN "error passive" occured.
RXOR : 1 if a receive queue overrun occured.
TXBUSY : 1 if the transmit buffer is being locked for MCU.
Reserved.
Reserved.
BOFF : 1 if a CAN "bus off" error occured.

Requires

MCU with the CAN module.

MCU must be connected to the CAN transceiver (MCP2551 or similar) which is connected to the CAN bus.

Example

Notes

None.

canSetSpeed

Prototype

void canSetSpeed(TCANStruct *CANx, uint16_t bitrate);

Description

This routine sets the CAN bus speed.

Parameters

CANx: CAN module selection parameter. Valid values :

Value	Description
CAN0	CAN0 module.
CAN1	CAN1 module.

bitrate: the desired CAN bus speed. The bitrate is in kB/s and the allowed values are 1000, 500, 250, 125, 50, 25 and 10.

Returns

Nothing.

Requires

MCU with the CAN module.

MCU must be connected to the CAN transceiver (MCP2551 or similar) which is connected to the CAN bus.

Example

Notes

None.

canSetFilter

Prototype

CAN_STATUS canSetFilter(TCANStruct *CANx, uint32_t canID, uint8_t options);

Description

This routine sets the CAN filter.

Parameters

CANx: CAN module selection parameter. Valid values :

Value	Description
CAN0	CAN0 module.
CAN1	CAN1 module.

canID: ID to be received by filter.

canID: options for setting the filter. Valid values :

Value	Description
DEFAULT	Filter is enabled, standard frame, single filter config, RTR bit is not included.
DISABLE_FILTER	Filter is disabled.
DUAL_FILTER	If this option is selected, use dual filter config. Otherwise use single filter.
FILTER_2	Effective only when `DUAL_FILTER` is selected. If chosen, set filter 2, else filter 1.
EXTENDED_FRAME	If this option is selected, set the filter for extended frame.
INCLUDE_RTR	If this option is selected, RTR bit will be included in the filter.
RTR_1	Effective only when `INCLUDE_RTR` is selected. If chosen, RTR = 1, else RTR = 0.

Returns

This routine returns CAN_STATUS status message via enum defined in the following way :

typedef enum
{
  CAN_OK,         // filter was set
  CAN_ERROR,      // could not set filter
  CAN_RX_OVERRUN
} CAN_STATUS;

Requires

MCU with the CAN module.

MCU must be connected to the CAN transceiver (MCP2551 or similar) which is connected to the CAN bus.

Example

Notes

None.

canPushMessage

Prototype

CAN_STATUS canPushMessage(TCANStruct *CANx, TCANMsg *pTransmitBuf);

Description

Function implements a CAN transmit queue. With each function call a message is added to the queue.

Parameters

CANx: CAN module selection parameter. Valid values :

Value	Description
CAN0	CAN0 module.
CAN1	CAN1 module.

pTransmitBuf: data structure with message to be sent :

typedef struct
{
  TCANFrameFormatEnum frameFormat; // CAN frame format (standard / extended)
  uint8_t RTR;                     // RTR
  uint32_t ID;                     // Message identifier
  uint8_t len;                     // Data length (0-8)
  uint8_t buf[8];                  // Data buffer
} TCANMsg;

CAN frame format enum (TCANFrameFormatEnum) is defined as following :

// CAN frame format definitions
typedef enum 
{
  CAN_STD_FRAME,
  CAN_EXT_FRAME
} TCANFrameFormatEnum;

Returns

This routine returns CAN_STATUS status message via enum defined in the following way :

typedef enum
{
  CAN_OK,         // message was pushed to the transmit queue
  CAN_ERROR,      // queue is full, message was not added, bit TXOR in canGetStatus() set
  CAN_RX_OVERRUN  
} CAN_STATUS;

Requires

MCU with the CAN module.

MCU must be connected to the CAN transceiver (MCP2551 or similar) which is connected to the CAN bus.

Example

Notes

None.

canPullMessage

Prototype

CAN_STATUS canPullMessage(TCANStruct *CANx, TCANMsg *pReceiveBuf);

Description

Function implements a CAN receive queue. With each function call a message is pulled from the queue.

Parameters

CANx: CAN module selection parameter. Valid values :

Value	Description
CAN0	CAN0 module.
CAN1	CAN1 module.

pReceiveBuf: data structure for the received message:

typedef struct
{
  TCANFrameFormatEnum frameFormat; // CAN frame format (standard / extended)
  uint8_t RTR;                     // RTR
  uint32_t ID;                     // Message identifier
  uint8_t len;                     // Data length (0-8)
  uint8_t buf[8];                  // Data buffer
} TCANMsg;

CAN frame format enum (TCANFrameFormatEnum) is defined as following :

// CAN frame format definitions
typedef enum 
{
  CAN_STD_FRAME,
  CAN_EXT_FRAME
} TCANFrameFormatEnum;

Returns

This routine returns CAN_STATUS status message via enum defined in the following way :

typedef enum
{
  CAN_OK,         // message was pulled from receive queue
  CAN_ERROR,      // queue empty, no message received
  CAN_RX_OVERRUN  // RX queue overrun occured
} CAN_STATUS;

Requires

MCU with the CAN module.

MCU must be connected to the CAN transceiver (MCP2551 or similar) which is connected to the CAN bus.

Example

Notes

None.

canRXQueueCount

Prototype

uint8_t canRXQueueCount(TCANStruct *CANx);

Description

Function gets the number of messages currently in the RX queue.

Parameters

CANx: CAN module selection parameter. Valid values :

Value	Description
CAN0	CAN0 module.
CAN1	CAN1 module.

Returns

The number of messages in the RX queue.

Requires

MCU with the CAN module.

MCU must be connected to the CAN transceiver (MCP2551 or similar) which is connected to the CAN bus.

Example

Notes

None.

Want more examples and libraries?
Find them on