CAN Library

The mikroPascal 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

sub procedure CANSysInit(dim CANx as ^TCANStruct)

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(dim CANx as ^TCANStruct, dim bitratekB as word) as byte

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 in the following way :

Value	Description
CAN_OK	CAN device initialized.
CAN_ERROR	CAN device not initialized.

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

sub function readCANReg(dim CANx as ^ TCANStruct, dim reg as byte) as byte

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

sub procedure writeCANReg(dim CANx as ^TCANStruct, dim val as byte, dim reg as byte)

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

sub procedure canEnableInt(dim CANx as ^TCANStruct, dim ints as byte)

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

sub procedure canDisableInt(dim CANx as ^TCANStruct, dim ints as byte)

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

sub procedure canClearIntFlag(dim CAN as ^TCANStruct, dim ints as byte)

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

sub function canGetStatus(dim CANx as ^TCANStruct) as byte

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

sub procedure canSetSpeed(dim CANx as ^TCANStruct, dim bitrate as word)

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

sub function canSetFilter(dim CANx as ^TCANStruct, dim canID as longword, dim options as byte) as byte

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 enum defined in the following way :

Value	Description
CAN_OK	CAN filter was set.
CAN_ERROR	CAN filter was not set.

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(dim CANx as ^TCANStruct, dim TCANMsg as ^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 TCANMsgas record
    dim frameFormat as byte                    ' CAN frame format (standard / extended)
    dim RTR         as byte                    ' RTR
    dim ID          as longword                ' Message identifier
    dim len         as byte                    ' Data length (0-8)
    dim buf         as byte[8]                 ' Data buffer
end structure

Returns

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

Value	Description
CAN_OK	Message was added to the transmit queue.
CAN_ERROR	Queue is full, message was not added, bit TXOR in canGetStatus set.

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

For many applications a queue with length "1" will be sufficient. Only applications with a high busload or very slow bus speed might need a queue of length "3" or more.

canPullMessage

Prototype

sub function canPullMessage(dim CANx as ^TCANStruct, dim TCANMsg as ^pReceiveBuf) as byte

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 TCANMsgas record
    dim frameFormat as byte                    ' CAN frame format (standard / extended)
    dim RTR         as byte                    ' RTR
    dim ID          as longword                ' Message identifier
    dim len         as byte                    ' Data length (0-8)
    dim buf         as byte[8]                 ' Data buffer
end structure

Returns

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

Value	Description
CAN_OK	Message was pulled from receive queue.
CAN_ERROR	Queue empty, no message received.

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

sub function canRXQueueCount(dim CANx as ^TCANStruct) as byte

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