Arduino API

Arduino Library Function

MCPCAN(INT8U _CS)
Description: Constructor, specify the CAN-BUS Shield V1.0 SPI chip select pin.
Parameter:

_CS: Chip select
Return: None
Example:

MCPCAN CAN(4); //Instantiate a Object with MCPCAN class, D4 is Arduino SPI CS pin.

void init(void)
Description: Initialize SPI module; reset MCP2515.
Parameter：
None
Return: None
Example:

This function should be called at first, initialize CAN-BUS MCU.

INT8U begin(INT8U speedset)
Description: Initialize setting CAN-BUS buadrate, follow the init() function.
Parameter:

speedset: Baudrate: CAN_5KBPS, CAN_10KBPS, CAN_20KBPS, CAN_31K25BPS, CAN_33KBPS, CAN_40KBPS, CAN_50KBPS, CAN_80KBPS, CAN_83K3BPS, CAN_95KBPS, CAN_100KBPS, CAN_125KBPS, CAN_200KBPS, CAN_250KBPS, CAN_500KBPS, CAN_1000KBPS.
Return: If the initialization is successful, return "CAN_OK"; if initialization fails, return "CAN_FAILINIT".
Example:

begin(CAN_500KBPS);

INT8U sendMsgBuf(INT32U id, INT8U ext, INT8U len, INT8U *buf)
Introduction: Send a set of data frame
Parameter:

id: Data frame ID
ext: "ext = 0", it is a standard frame; "ext = 1", it is an extended frame.
len: data length, len < 8
buf: Data buffer point
Return: If success, returns "CAN_OK"; if timeout, returns "CAN_SENDMSGTIMEOUT"; If you fail to get the next free buffer, it returns "CAN_GETTXBFTIMEOUT".
Example:

unsigned char data[8] = {'D', 'F', 'R', 'O', 'B', 'O', 'T', '!'};
sendMsgBuf(0x06, 0, sizeof(data), data);

INT8U MCPCAN::setMsg(INT32U id, INT8U ext, INT8U len, INT8U rtr, INT8U *pData)
Introduction: Send remote sending request message.
Parameter:

id: Data frame ID
ext: "ext = 0", it is a standard frame; "ext = 1", it is an extended frame.
len: data length, len < 8
rtr: "rtr = 1", it is a Remote sending request frame; "rtr = 0", it is a data frame.
buf: Data buffer point
Return: If success, returns "CAN_OK"; if timeout, returns "CAN_SENDMSGTIMEOUT"; If you fail to get the next free buffer, it returns "CAN_GETTXBFTIMEOUT".
Example:

unsigned char data[8] = {'D', 'F', 'R', 'O', 'B', 'O', 'T', '!'};
setMsg(0x06, 0, sizeof(data), 0, data);

INT8U isRemoteRequest(void)
Introduction: Check whether it is a remote frame
Parameter:
None
Return: "1", Yes; "0", No

INT8U init_Mask(Masker_t Masker_num, INT8U ext, INT32U Data)
Introduction: Initialize the mask register
Parameter:

Masker_num: mask register name: MCP_RXM0、MCP_RXM1; If Masker_num = MCP_RXM0, initialize the mask register 0 (mask register 0 receives data from buffer0); if Masker_num = MCP_RXM1, initialize the mask register 1 (mask register 1 receives data from buffer1).
ext: "ext=0", configure standard frame with mask register setting; "ext = 1", configure extended frame with mask register setting.
Data: Write this data into mask register, to configure which register will be blocked.
Returns: if success, returns "MCP_OK"; if fail, returns "MCP_FAIL"
Example:

init_Mask(MCP_RXM0, 0, 0x3ff); //follow the init() function, before the begin() one. Implement a standard filter frame from 0~9 bit, 10 bit in all, because the binary form of "0x3ff" is "11 1111 1111".

INT8U checkReceive(void)
Introduction: check the validity of received data frame.
Parameter:
None
Return: If the shield receives the valid data frame, return "CAN_MSGAVAIL"; if no, return "CAN_NOMSG";
Example:

Check the validity of received data frame after CAN-BUS works. You can rotational call this function to detect it, refer to the following example.

INT8U init_Filter(Filter_t Filter_num, INT8U ext, INT32U Data)
Introduction: Initialize the message acceptance filter register.
Parameter:

Filter_num: Message acceptance filter number, could be MCP_RXF0, MCP_RXF1, MCP_RXF2, MCP_RXF3, MCP_RXF4, MCP_RXF5.
ext: if "ext=0", it means the message acceptance filter receive standard data frame message only; if "ext=1", it means the message acceptance filter receive extended data frame message only.
Data: Filtered message ID. Only the data frame with filtered id can be received by CAN controller. So an upcoming data frame whether can be received depends the value in MCP_RXM0/MCP_RXM1 in init_Mask() function, the value in MCP_RXF0 registers in init_Filter() function and upcoming message identifier ID. These three values can be looked up on the Table below. If every true result is received, then the message will be received by the CAN controller. Otherwise, it will be discarded.
Filter/Mask Register Truth Table

Note: X = Random Variable

E.g.
If you configure MCP_RXM0 with 0x7ff with init_Mask(MCP_RXM0, 0, 0x7ff), it means it will mask the 11 bit of the standard frame. Meanwhile the init_Filter(MCP_RXF0, 0, 0x20) function will configure MCP_RXF0 register as 0x20 (000 0010 0000), filter with 0x7ff (111 1111 1111). if every value is true, the ID will be received. But if there is a false value, this ID will be discarded. In this case, MCP2515 can receive the message with ID 0x20 only. And you can also modify init_Mask(MCP_RXM0, 0, 0x7ff) to init_Mask(MCP_RXM0, 0, 0x7DF), it also support 0x20 ID.
Return: "CAN_OK" means reading successfully; Contrarily, return "MCP_FA".
Example:

init_Mask(MCP_RXM0, 0, 0x7ff);
init_Filter(MCP_RXF0, 0, 0x04); //After init() function, before begin() function. Working withinit_Mask()function. Set 0x04 as CAN controller receiving ID.

INT8U readMsgBuf(INT8U *len, INT8U *buf)
Introduction: Read data from MCP2515 receiving buffer.
Parameter:

len: Save the receiving data length
buf: Save the receiving data
Return: "CAN_OK" means reading successfully; Contrarily, return "CAN_NOMSG".

INT8U readMsgBufID(INT32U *ID, INT8U *len, INT8U *buf)
Introduction: Read data from MCP2515 receiving buffer and read this data frame ID.
Parameter:

ID: Save the data frame ID
len: Save the receiving data length
buf: Save the receiving data
Return: "CAN_OK" means reading successfully; Contrarily, return "CAN_NOMSG".

INT8U checkError(void)
Introduction: MCP2515 control error inquiry
Parameter:
Nono
Return: "CAN_CTRLERROR" means it sends the control error; Contrarily, return "CAN_OK".

INT32U getCanId(void)
Introduction: Get the current data frame's ID
Parameter:
None
Return: Data frame ID

You can get the data frame ID with this command, after you receive the data frame. Refer to the following examples.

INT8U isExtendedFrame(void)
Introduction: Check whether it is a extended frame.
Parameter:
None
Return: "1", Yes; "0", No

This command is called in receiving interrupt handler function, to check whether the data frame is a standard data frame or an extended data frame.