CANSPI Library

The SPI module is available with a number of the FT90x MCUs. The mikroPascal PRO for FT90x provides a library (driver) for working with mikroElektronika's CANSPI Add-on boards (with MCP2515 or MCP2510) via SPI interface.

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.

CAN supports two message formats:

Standard format, with 11 identifier bits and
Extended format, with 29 identifier bits

Important :

Consult the CAN standard about CAN bus termination resistance.
An effective CANSPI communication speed depends on SPI and certainly is slower than “real” CAN.
The library uses the SPI module for communication. User must initialize appropriate SPI module before using the CANSPI Library.
For MCUs with multiple SPI modules it is possible to initialize both of them and then switch by using the SPIM_Set_Active routine.
Number of SPI modules per MCU differs from chip to chip. Please, read the appropriate datasheet before utilizing this library.
CANSPI module refers to mikroElektronika's CANSPI Add-on board connected to SPI module of MCU.

Library Dependency Tree

External dependencies of CANSPI Library

The following variables must be defined in all projects using CANSPI Library:	Description :	Example :
`dim CanSpi_CS as sbit sfr external`	Chip Select line.	`dim CanSpi_CS as sbit at GPIO_PIN25_bit`
`dim CanSpi_Rst as sbit sfr external`	Reset line.	`dim CanSpi_Rst as sbit at GPIO_PIN26_bit`

CANSPISetOperationMode

Prototype	sub procedure CANSPISetOperationMode(dim mode as byte, dim WAIT as byte)
Description	Sets the CANSPI module to requested mode.
Parameters	`mode:` CANSPI module operation mode. Valid values: `CANSPI_OP_MODE` constants. See CANSPI_OP_MODE constants. `WAIT:` CANSPI mode switching verification request. If `WAIT == 0`, the call is non-blocking. The function does not verify if the CANSPI module is switched to requested mode or not. Caller must use `CANSPIGetOperationMode` to verify correct operation mode before performing mode specific operation. If `WAIT != 0`, the call is blocking – the function won’t “return” until the requested mode is set.
Returns	Nothing.
Requires	The CANSPI routines are supported only by MCUs with the SPI module. MCU has to be properly connected to mikroElektronika's CANSPI Extra Board or similar hardware. See connection example at the bottom of this page.
Example	' set the CANSPI module into configuration mode (wait inside CANSPISetOperationMode until this mode is set) CANSPISetOperationMode(_CANSPI_MODE_CONFIG, 0xFF)
Notes	None.

CANSPIGetOperationMode

Prototype	sub function CANSPIGetOperationMode() as byte
Description	The function returns current operation mode of the CANSPI module. Check CANSPI_OP_MODE constants or device datasheet for operation mode codes.
Parameters	None.
Returns	Current operation mode.
Requires	The CANSPI routines are supported only by MCUs with the SPI module. MCU has to be properly connected to mikroElektronika's CANSPI Extra Board or similar hardware. See connection example at the bottom of this page.
Example	' check whether the CANSPI module is in Normal mode and if it is do something. if (CANSPIGetOperationMode() = _CANSPI_MODE_NORMAL) then ... end if
Notes	None.

CANSPIInitialize

Prototype	sub procedure CANSPIInitialize(dim SJW, BRP, PHSEG1, PHSEG2, PROPSEG, CANSPI_CONFIG_FLAGS as char)
Description	Initializes the CANSPI module. Stand-Alone CAN controller in the CANSPI module is set to: Disable CAN capture Continue CAN operation in Idle mode Do not abort pending transmissions Fcan clock : 4*Tcy (Fosc) Baud rate is set according to given parameters CAN mode : Normal Filter and mask registers IDs are set to zero Filter and mask message frame type is set according to CANSPI_CONFIG_FLAGS value `SAM`, `SEG2PHTS`, `WAKFIL` and `DBEN` bits are set according to CANSPI_CONFIG_FLAGS value.
Parameters	`SJW` as defined in MCU's datasheet (CAN Module) `BRP` as defined in MCU's datasheet (CAN Module) `PHSEG1` as defined in MCU's datasheet (CAN Module) `PHSEG2` as defined in MCU's datasheet (CAN Module) `PROPSEG` as defined in MCU's datasheet (CAN Module) `CANSPI_CONFIG_FLAGS` is formed from predefined constants. See CANSPI_CONFIG_FLAGS constants.
Returns	Nothing.
Requires	External dependencies of the library from the top of the page must be defined before using this function. The CANSPI routines are supported only by MCUs with the SPI module. The SPI module needs to be initialized. See the SPIM1_Init and SPIM1_Init_Advanced routines. MCU has to be properly connected to mikroElektronika's CANSPI Extra Board or similar hardware. See connection example at the bottom of this page.
Example	' CANSPI module connections dim CanSpi_CS as sbit at GPIO_PIN25_bit dim CanSpi_Rst as sbit at GPIO_PIN26_bit ' End CANSPI module connections ... ' Initialize SPI1 module SPIM1_Init_Advanced(_SPI_MASTER_CLK_RATIO_128, _SPI_CFG_POLARITY_IDLE_LOW or _SPI_CFG_PHASE_CAPTURE_FALLING, _SPI_SS_LINE_NONE) CANSPIInitialize(1,3,3,3,1,Can_Init_Flags) ' initialize external CANSPI module
Notes	CANSPI mode NORMAL will be set on exit.

CANSPISetBaudRate

Prototype	sub procedure CANSPISetBaudRate(dim SJW, BRP, PHSEG1, PHSEG2, PROPSEG, CANSPI_CONFIG_FLAGS as byte)
Returns	Nothing.
Description	Sets the CANSPI module baud rate. Due to complexity of the CAN protocol, you can not simply force a bps value. Instead, use this function when the CANSPI module is in Config mode. `SAM`, `SEG2PHTS` and `WAKFIL` bits are set according to CANSPI_CONFIG_FLAGS value. Refer to datasheet for details.
Parameters	`SJW` as defined in MCU's datasheet (CAN Module) `BRP` as defined in MCU's datasheet (CAN Module) `PHSEG1` as defined in MCU's datasheet (CAN Module) `PHSEG2` as defined in MCU's datasheet (CAN Module) `PROPSEG` as defined in MCU's datasheet (CAN Module) `CANSPI_CONFIG_FLAGS` is formed from predefined constants. See CANSPI_CONFIG_FLAGS constants.
Returns	Nothing.
Requires	The CANSPI module must be in Config mode, otherwise the function will be ignored. See CANSPISetOperationMode. The CANSPI routines are supported only by MCUs with the SPI module. MCU has to be properly connected to mikroElektronika's CANSPI Extra Board or similar hardware. See connection example at the bottom of this page.
Example	' set required baud rate and sampling rules dim CANSPI_CONFIG_FLAGS as byte ... CANSPISetOperationMode(_CANSPI_MODE_CONFIG,0xFF) ' set CONFIGURATION mode (CANSPI1 module mast be in config mode for baud rate settings) CANSPI_CONFIG_FLAGS = _CANSPI_CONFIG_SAMPLE_THRICE and _CANSPI_CONFIG_PHSEG2_PRG_ON and _CANSPI_CONFIG_STD_MSG and _CANSPI_CONFIG_DBL_BUFFER_ON and _CANSPI_CONFIG_VALID_XTD_MSG and _CANSPI_CONFIG_LINE_FILTER_OFF CANSPISetBaudRate(1, 1, 3, 3, 1, CANSPI_CONFIG_FLAGS)
Notes	None.

CANSPISetMask

Prototype	sub procedure CANSPISetMask(dim CANSPI_MASK as byte, dim val as longint, dim CANSPI_CONFIG_FLAGS as byte)
Description	Configures mask for advanced filtering of messages. The parameter `value` is bit-adjusted to the appropriate mask registers.
Parameters	`CANSPI_MASK:` CAN module mask number. Valid values: `CANSPI_MASK` constants. See CANSPI_MASK constants. `val:` mask register value. This value is bit-adjusted to appropriate buffer mask registers `CANSPI_CONFIG_FLAGS:` selects type of message to filter. Valid values: `_CANSPI_CONFIG_ALL_VALID_MSG`, `_CANSPI_CONFIG_MATCH_MSG_TYPE & _CANSPI_CONFIG_STD_MSG`, `_CANSPI_CONFIG_MATCH_MSG_TYPE & _CANSPI_CONFIG_XTD_MSG`. See CANSPI_CONFIG_FLAGS constants.
Returns	Nothing.
Requires	The CANSPI module must be in Config mode, otherwise the function will be ignored. See CANSPISetOperationMode. The CANSPI routines are supported only by MCUs with the SPI module. MCU has to be properly connected to mikroElektronika's CANSPI Extra Board or similar hardware. See connection example at the bottom of this page.
Example	' set the appropriate filter mask and message type value CANSPISetOperationMode(_CANSPI_MODE_CONFIG,0xFF) ' set CONFIGURATION mode (CANSPI1 module must be in config mode for mask settings) ' Set all B1 mask bits to 1 (all filtered bits are relevant): ' Note that -1 is just a cheaper way to write 0xFFFFFFFF. ' Complement will do the trick and fill it up with ones. CANSPISetMask(_CANSPI_MASK_B1, -1, _CANSPI_CONFIG_MATCH_MSG_TYPE and _CANSPI_CONFIG_XTD_MSG)
Notes	None.

CANSPISetFilter

Prototype	sub procedure CANSPISetFilter(dim CAN_FILTER as byte, dim val as longint, dim CANSPI_CONFIG_FLAGS as byte)
Description	Configures message filter. The parameter `value` is bit-adjusted to the appropriate filter registers.
Parameters	`CANSPI_FILTER:` CAN module filter number. Valid values: `CANSPI_FILTER` constants. See CANSPI_FILTER constants. `val:` filter register value. This value is bit-adjusted to appropriate filter registers `CANSPI_CONFIG_FLAGS:` selects type of message to filter. Valid values: `_CANSPI_CONFIG_STD_MSG` and `_CANSPI_CONFIG_XTD_MSG`. See CANSPI_CONFIG_FLAGS constants.
Returns	Nothing.
Requires	The CANSPI module must be in Config mode, otherwise the function will be ignored. See CANSPISetOperationMode. The CANSPI routines are supported only by MCUs with the SPI module. MCU has to be properly connected to mikroElektronika's CANSPI Extra Board or similar hardware. See connection example at the bottom of this page.
Example	' set the appropriate filter value and message type CANSPI1SetOperationMode(_CANSPI_MODE_CONFIG,0xFF) ' set CONFIGURATION mode (CANSPI1 module must be in config mode for filter settings) ' Set id of filter B1_F1 to 3: CANSPI1SetFilter(_CANSPI_FILTER_B1_F1, 3, _CANSPI_CONFIG_XTD_MSG)
Notes	None.

CANSPIRead

Prototype	sub function CANSPIRead(dim byref id as longint, dim byref Data_ as byte[8], dim byref DataLen as byte, dim byref CAN_RX_MSG_FLAGS as byte) as byte
Description	If at least one full Receive Buffer is found, it will be processed in the following way: Message ID is retrieved and stored to location provided by the `id` parameter Message data is retrieved and stored to a buffer provided by the `data` parameter Message length is retrieved and stored to location provided by the `dataLen` parameter Message flags are retrieved and stored to location provided by the `CANSPI_RX_MSG_FLAGS` parameter
Parameters	`id:` message identifier address `data:` an array of bytes up to 8 bytes in length `dataLen:` data length address `CANSPI_RX_MSG_FLAGS:` message flags address. For message receive flags format refer to `CANSPI_RX_MSG_FLAGS` constants. See CANSPI_RX_MSG_FLAGS constants.
Returns	`0` if nothing is received `0xFFFF` if one of the Receive Buffers is full (message received)
Requires	The CANSPI module must be in a mode in which receiving is possible. See CANSPISetOperationMode. The CANSPI routines are supported only by MCUs with the SPI module. MCU has to be properly connected to mikroElektronika's CANSPI Extra Board or similar hardware. See connection example at the bottom of this page.
Example	' check the CANSPI1 module for received messages. If any was received do something. dim msg_rcvd, rx_flags, data_len as byte data as byte[8] msg_id as longint ... CANSPISetOperationMode(_CANSPI_MODE_NORMAL,0xFF) ' set NORMAL mode (CANSPI1 module must be in mode in which receive is possible) ... rx_flags = 0 ' clear message flags if (msg_rcvd = CANSPIRead(msg_id, data, data_len, rx_flags)) then ... end if
Notes	None.

CANSPIWrite

Prototype	sub function CANSPIWrite(dim id as longint, dim byref Data_ as byte[8], dim DataLen, CANSPI_TX_MSG_FLAGS as byte) as byte
Description	If at least one empty Transmit Buffer is found, the function sends message in the queue for transmission.
Parameters	`id:` CAN message identifier. Valid values: 11 or 29 bit values, depending on message type (standard or extended) `Data:` data to be sent `DataLen:` data length. Valid values: `0..8` `CANSPI_TX_MSG_FLAGS:` message flags. Valid values: `CANSPI_TX_MSG_FLAGS` constants. See CANSPI_TX_MSG_FLAGS constants.
Returns	`0` if all Transmit Buffers are busy `0xFFFF` if at least one Transmit Buffer is available
Requires	The CANSPI module must be in mode in which transmission is possible. See CANSPISetOperationMode. The CANSPI routines are supported only by MCUs with the SPI module. MCU has to be properly connected to mikroElektronika's CANSPI Extra Board or similar hardware. See connection example at the bottom of this page.
Example	' send message extended CAN message with the appropriate ID and data dim tx_flags as byte data as byte[8] msg_id as longint ... CANSPISetOperationMode(_CAN_MODE_NORMAL,0xFF) ' set NORMAL mode (CANSPI1 must be in mode in which transmission is possible) tx_flags = _CANSPI_TX_PRIORITY_0 and _CANSPI_TX_XTD_FRAME ' set message flags CANSPIWrite(msg_id, data, 2, tx_flags)
Notes	None.

CANSPI Constants

There is a number of constants predefined in the CANSPI library. You need to be familiar with them in order to be able to use the library effectively. Check the example at the end of the chapter.

CANSPI_OP_MODE Constants

The CANSPI_OP_MODE constants define CANSPI operation mode. Function CANSPISetOperationMode expects one of these as it's argument:

Copy Code To Clipboard

const
    _CANSPI_MODE_BITS   as byte = $E0    Use this to access opmode  bits
    _CANSPI_MODE_NORMAL as byte = 0
    _CANSPI_MODE_SLEEP  as byte = $20
    _CANSPI_MODE_LOOP   as byte = $40
    _CANSPI_MODE_LISTEN as byte = $60
    _CANSPI_MODE_CONFIG as byte = $80

CANSPI_CONFIG_FLAGS Constants

The CANSPI_CONFIG_FLAGS constants define flags related to the CANSPI module configuration. The functions CANSPIInit, CANSPISetBaudRate, CANSPISetMask and CANSPISetFilter expect one of these (or a bitwise combination) as their argument:

Copy Code To Clipboard

const
    _CANSPI_CONFIG_DEFAULT        as byte  = $FF   ' 11111111

    _CANSPI_CONFIG_PHSEG2_PRG_BIT as byte  = $01
    _CANSPI_CONFIG_PHSEG2_PRG_ON  as byte  = $FF   ' XXXXXXX1
    _CANSPI_CONFIG_PHSEG2_PRG_OFF as byte  = $FE   ' XXXXXXX0

    _CANSPI_CONFIG_LINE_FILTER_BIT as byte = $02
    _CANSPI_CONFIG_LINE_FILTER_ON  as byte = $FF   ' XXXXXX1X
    _CANSPI_CONFIG_LINE_FILTER_OFF as byte = $FD   ' XXXXXX0X

    _CANSPI_CONFIG_SAMPLE_BIT      as byte = $04
    _CANSPI_CONFIG_SAMPLE_ONCE     as byte = $FF   ' XXXXX1XX
    _CANSPI_CONFIG_SAMPLE_THRICE   as byte = $FB   ' XXXXX0XX

    _CANSPI_CONFIG_MSG_TYPE_BIT    as byte = $08
    _CANSPI_CONFIG_STD_MSG         as byte = $FF   ' XXXX1XXX
    _CANSPI_CONFIG_XTD_MSG         as byte = $F7   ' XXXX0XXX

    _CANSPI_CONFIG_DBL_BUFFER_BIT  as byte = $10
    _CANSPI_CONFIG_DBL_BUFFER_ON   as byte = $FF   ' XXX1XXXX
    _CANSPI_CONFIG_DBL_BUFFER_OFF  as byte = $EF   ' XXX0XXXX

    _CANSPI_CONFIG_MSG_BITS        as byte = $60
    _CANSPI_CONFIG_ALL_MSG         as byte = $FF   ' X11XXXXX
    _CANSPI_CONFIG_VALID_XTD_MSG   as byte = $DF   ' X10XXXXX
    _CANSPI_CONFIG_VALID_STD_MSG   as byte = $BF   ' X01XXXXX
    _CANSPI_CONFIG_ALL_VALID_MSG   as byte = $9F   ' X00XXXXX

You may use bitwise and to form config byte out of these values. For example:

Copy Code To Clipboard

init  = _CANSPI_CONFIG_SAMPLE_THRICE    and
        _CANSPI_CONFIG_PHSEG2_PRG_ON    and
        _CANSPI_CONFIG_STD_MSG          and
        _CANSPI_CONFIG_DBL_BUFFER_ON    and
        _CANSPI_CONFIG_VALID_XTD_MSG    and
        _CANSPI_CONFIG_LINE_FILTER_OFF
...
CANSPIInitialize(1, 1, 3, 3, 1, init)   ' initialize CANSPI

CANSPI_TX_MSG_FLAGS Constants

CANSPI_TX_MSG_FLAGS are flags related to transmission of a CANSPI message:

Copy Code To Clipboard

 const
    _CANSPI_TX_PRIORITY_BITS as byte = $03
    _CANSPI_TX_PRIORITY_0    as byte = $FC   ' XXXXXX00
    _CANSPI_TX_PRIORITY_1    as byte = $FD   ' XXXXXX01
    _CANSPI_TX_PRIORITY_2    as byte = $FE   ' XXXXXX10
    _CANSPI_TX_PRIORITY_3    as byte = $FF   ' XXXXXX11

    _CANSPI_TX_FRAME_BIT     as byte  = $08
    _CANSPI_TX_STD_FRAME     as byte  = $FF  ' XXXXX1XX
    _CANSPI_TX_XTD_FRAME     as byte  = $F7  ' XXXXX0XX

    _CANSPI_TX_RTR_BIT       as byte = $40
    _CANSPI_TX_NO_RTR_FRAME  as byte = $FF   ' X1XXXXXX
    _CANSPI_TX_RTR_FRAME     as byte = $BF   ' X0XXXXXX

You may use bitwise and to adjust the appropriate flags. For example:

Copy Code To Clipboard

' form value to be used with CANSendMessage:
send_config  = _CANSPI_TX_PRIORITY_0    and
               _CANSPI_TX_XTD_FRAME     and
               _CANSPI_TX_NO_RTR_FRAME
...
CANSPIWrite(id, data, 1, send_config)

CANSPI_RX_MSG_FLAGS Constants

CANSPI_RX_MSG_FLAGS are flags related to reception of CANSPI message. If a particular bit is set then corresponding meaning is TRUE or else it will be FALSE.

Copy Code To Clipboard

const
    _CANSPI_RX_FILTER_BITS  as byte = $07   ' Use this to access filter bits
    _CANSPI_RX_FILTER_1     as byte = $00
    _CANSPI_RX_FILTER_2     as byte = $01
    _CANSPI_RX_FILTER_3     as byte = $02
    _CANSPI_RX_FILTER_4     as byte = $03
    _CANSPI_RX_FILTER_5     as byte = $04
    _CANSPI_RX_FILTER_6     as byte = $05

    _CANSPI_RX_OVERFLOW     as byte = $08   ' Set if Overflowed else cleared
    _CANSPI_RX_INVALID_MSG  as byte = $10   ' Set if invalid else cleared
    _CANSPI_RX_XTD_FRAME    as byte = $20   ' Set if XTD message else cleared
    _CANSPI_RX_RTR_FRAME    as byte = $40   ' Set if RTR message else cleared
    _CANSPI_RX_DBL_BUFFERED as byte = $80   ' Set if this message was hardware double-buffered

You may use bitwise and to adjust the appropriate flags. For example:

Copy Code To Clipboard

if (MsgFlag and _CANSPI_RX_OVERFLOW) <> 0 then
  ...
  ' Receiver overflow has occurred.
  ' We have lost our previous message.
end if

CANSPI_MASK Constants

The CANSPI_MASK constants define mask codes. Function CANSPISetMask expects one of these as it's argument:

Copy Code To Clipboard

const
    _CANSPI_MASK_B1 as byte = 0
    _CANSPI_MASK_B2 as byte = 1

CANSPI_FILTER Constants

The CANSPI_FILTER constants define filter codes. Functions CANSPISetFilter expects one of these as it's argument:

Copy Code To Clipboard

const
    _CANSPI_FILTER_B1_F1 as byte = 0
    _CANSPI_FILTER_B1_F2 as byte = 1
    _CANSPI_FILTER_B2_F1 as byte = 2
    _CANSPI_FILTER_B2_F2 as byte = 3
    _CANSPI_FILTER_B2_F3 as byte = 4
    _CANSPI_FILTER_B2_F4 as byte = 5

Want more examples and libraries?
Find them on