API for the MCP2515 CAN bus controller. More...

Detailed Description

ID: mcp2515
Name: CAN Bus Controller
Manufacturer: seeed
Connection: spi gpio
Link: https://www.seeedstudio.com/CANBUS-Shield-p-2256.html

The MCP2515 is a stand-alone CAN controller developed to simplify applications that require interfacing with a CAN bus.

This driver was developed using the Grove CAN bus shield version 1.2.

An example using the loopback mode.

    // Instantiate a MCP2515 on SPI bus 0 using a hw CS pin (-1).
    upm::MCP2515 sensor(0, -1);
    cout << "Setting loopback mode..." << endl;
    // set the mode to loopback mode.  In loopback mode, transmitted
    // packets are sent directly to an appropriate receive buffer
    // without actually going out onto the CAN bus.
    sensor.setOpmode(MCP2515_OPMODE_LOOPBACK);
    // lets build up a packet and try loading it (8 bytes max).
    string myPayload = "01234567";
    cout << "Loading a packet of 8 numbers (0-7) into a TX buffer..." << endl;
    sensor.loadTXBuffer(MCP2515_TX_BUFFER0, 0, false, false, myPayload);
    // now lets try to transmit it
    cout << "Transmitting packet..." << endl;
    sensor.transmitBuffer(MCP2515_TX_BUFFER0, true);
    cout << "Transmit successful" << endl;
    // There should now be a packet waiting for us in RXB0
    if (sensor.rxStatusMsgs() == MCP2515_RXMSG_RXB0) {
        cout << "Packet received in RXB0, decoding..." << endl;
        // now lets retrieve and print it
        sensor.getRXMsg(MCP2515_RX_BUFFER0);
        sensor.printMsg();
    } else {
        cout << "No packet found, how strange." << endl;
    }
    cout << "Exiting..." << endl;

A simple transmit and receive example.

    // NOTE: This example assumes that only two devices are connected
    // to the CAN bus, and that both devices are running this example;
    // one in TX (transmit) mode, and one in RX (receive) mode.
    // If this is not the case, then in rx mode you may see other
    // packets from other devices, or not, depending on whether the
    // speed is correct for the network.  In tx mode, errors may be
    // generated on the bus, especially if the CAN bus speed does not
    // match the rest of the network.
    // You should start the receiver example first.  The transmitter
    // example will fail after about 5 seconds (timeout) of not being
    // able to transmit a message.
    // Instantiate a MCP2515 on SPI bus 0 using a hw CS pin (-1).
    upm::MCP2515 sensor(0, 9);
    // By default, after initialization, the baud rate is set to
    // 50Kbps, and the mode is NORMAL, so we don't need to set any of
    // that here.
    // our TX payload.  If transmitting, the first number will be
    // incremented (and rollover) on each transmission.
    string myPayload = "01234567";
    while (shouldRun) {
        if (do_tx) {
            cout << "Loading a packet of 8 numbers (0-7) into a TX buffer..." << endl;
            sensor.loadTXBuffer(MCP2515_TX_BUFFER0, 0, false, false, myPayload);
            // now lets try to transmit it
            cout << "Transmitting packet..." << endl;
            sensor.transmitBuffer(MCP2515_TX_BUFFER0, true);
            myPayload[0]++;
            cout << "Transmit successful" << endl;
            cout << endl;
            upm_delay_ms(500);
        } else {
            // RX mode
            // Look for a packet waiting for us in RXB0
            if (sensor.rxStatusMsgs() == MCP2515_RXMSG_RXB0) {
                cout << "Packet received in RXB0, decoding..." << endl;
                // now lets retrieve and print it
                sensor.getRXMsg(MCP2515_RX_BUFFER0);
                sensor.printMsg();
                cout << endl;
            }
            upm_delay_ms(100);
        }
    }
    cout << "Exiting..." << endl;

Public Member Functions
	MCP2515 (int bus, int csPin)

	~MCP2515 ()

void	reset ()

void	setOpmode (MCP2515_OPMODE_T opmode)

void	setSpeed (MCP2515_SPEED_T speed)

void	loadTXBuffer (MCP2515_TX_BUFFER_T bufnum, int id, bool ext, bool rtr, std::string payload)

void	transmitBuffer (MCP2515_TX_BUFFER_T bufnum, bool wait)

bool	isTXBufferFree (MCP2515_TX_BUFFER_T bufnum)

MCP2515_TX_BUFFER_T	findFreeTXBuffer ()

void	setTXBufferPriority (MCP2515_TX_BUFFER_T bufnum, MCP2515_TXP_T priority)

void	abortTX (MCP2515_TX_BUFFER_T bufnum)

void	setRXBufferMode (MCP2515_RX_BUFFER_T bufnum, MCP2515_RXMODE_T rxm)

MCP2515_RXMSG_T	rxStatusMsgs ()

MCP2515_MSGTYPE_T	rxStatusMsgType ()

MCP2515_FILTERMATCH_T	rxStatusFiltermatch ()

upm_result_t	getRXMsg (MCP2515_RX_BUFFER_T bufnum)

void	printMsg ()

int	msgGetID ()

bool	msgGetRTR ()

bool	msgGetEXT ()

int	msgGetFilterNum ()

int	msgGetPayloadLen ()

std::string	msgGetPayload ()

void	installISR (int pin, void(isr)(void ), void *arg)

void	uninstallISR ()

void	setIntrEnables (uint8_t enables)

uint8_t	getIntrFlags ()

void	setIntrFlags (uint8_t flags)

void	clearIntrFlags (uint8_t flags)

uint8_t	getErrorFlags ()

void	clearErrorFlags (uint8_t flags)

void	setFilter (MCP2515_RX_FILTER_T filter, bool ext, int id)

void	setMask (MCP2515_RX_MASK_T mask, bool ext, int id)

Protected Member Functions
std::string	busRead (uint8_t cmd, std::string args, int datalen)

void	busWrite (uint8_t cmd, std::string data)

void	writeReg (uint8_t reg, uint8_t value)

void	writeRegs (uint8_t reg, std::string buffer)

uint8_t	readReg (uint8_t reg)

void	bitModify (uint8_t addr, uint8_t mask, uint8_t value)

Protected Attributes
mcp2515_context	m_mcp2515

MCP2515_MSG_T	m_message

Constructor & Destructor Documentation

MCP2515	(	int	bus,
		int	csPin
	)

MCP2515 constructor.

Parameters

bus	spi bus to use
csPin	The GPIO pin to use for Chip Select (CS). Pass pass -1 if your CS is handled automatically by your SPI implementation (Edison).

Here is the caller graph for this function:

~MCP2515 ( )

MCP2515 Destructor

Member Function Documentation

void reset ( )

Reset the device.

void setOpmode ( MCP2515_OPMODE_T opmode )

Set the operating mode of the device. After initialization, the device mode will be set to NORMAL. Note that some operations require the device to be placed into CONFIG mode. This function will wait until the selected mode has been entered.

Parameters

opmode One of the MCP2515_OPMODE_T values.

void setSpeed ( MCP2515_SPEED_T speed )

Set the baud rate of the CAN bus. All devices on a given CAN bus must be operating at the correct speed. The device must be switched into CONFIG mode bofore this function will have any effect. On initialization, the default CAN bus speed will be set to 50Kbps.

Parameters

speed One of the MCP2515_SPEED_T values.

void loadTXBuffer	(	MCP2515_TX_BUFFER_T	bufnum,
		int	id,
		bool	ext,
		bool	rtr,
		std::string	payload
	)

Load a transmit buffer with the id, payload, and other information. This function does not actually transmit the buffer. There are 3 TX buffers available. The buffer must be free (ie: not awaiting transmit) before it can be loaded. Once a TX buffer has been successfully loaded, it can be transmitted with the TransmitBuffer() method.

Parameters

bufnum	The buffer to load. One of the MCP2515_TX_BUFFER_T values.
id	The integer representation of the CAN bus ID.
ext	True if the ID is an extended identifier, false otherwise.
rtr	True if this is a Remote Transfer Request, false otherwise.
payload	A string containing the payload bytes. Maximum length is 8.

void transmitBuffer	(	MCP2515_TX_BUFFER_T	bufnum,
		bool	wait
	)

Transmit a buffer already loaded by loadTXBuffer().

Parameters

bufnum	The buffer to transmit. One of the MCP2515_TX_BUFFER_T values.
wait	True if the function should wait until transmission is complete before returning, false otherwise.

bool isTXBufferFree ( MCP2515_TX_BUFFER_T bufnum )

Determine whether a TX buffer is available for use or not. A TX buffer is unavailable if a transmit request is pending on it, but transmission has not yet completed.

Parameters

bufnum The buffer to check. One of the MCP2515_TX_BUFFER_T values.

Returns: True if the buffer is availabe, false otherwise.

MCP2515_TX_BUFFER_T findFreeTXBuffer ( )

Find a free TX buffer and return it.

Returns: One of the MCP2515_TX_BUFFER_T values. If no buffers are available, MCP2515_TX_NO_BUFFERS will be returned.

void setTXBufferPriority	(	MCP2515_TX_BUFFER_T	bufnum,
		MCP2515_TXP_T	priority
	)

Set the transmit priority of a TX buffer. Higher priority buffers are always transmitted before lower priority buffers. This function can be called on a buffer at any time prior to actual transmission.

Parameters

bufnum	The buffer to set priority for. One of the MCP2515_TX_BUFFER_T values.
priority	The priority to set for the buffer. One of the MCP2515_TXP_T values.

void abortTX ( MCP2515_TX_BUFFER_T bufnum )

Abort a transmission that has been queued, but not yet completed. This will also free up the TX buffer for future use. Note, if you abort a transmission, but transmission has already started, this call will have no effect, and the buffer will complete transmission.

Parameters

bufnum The buffer to abort. One of the MCP2515_TX_BUFFER_T values.

void setRXBufferMode	(	MCP2515_RX_BUFFER_T	bufnum,
		MCP2515_RXMODE_T	rxm
	)

Set the mode for an RX buffer. The mode specifies, at a high level, what packets should be captured from the bus and placed into an RX buffer. See the datasheet for details, but the default, MCP2515_RXMODE_ANY_FILTER, should be sufficient in most cases. It is also possible to use this to restrict the types of CAN ids accepted (extended only, standard only) as well as a debug ANY_NOFILTER mode.

Parameters

bufnum	The buffer to set the mode for. One of the MCP2515_RX_BUFFER_T values.
rxm	The mode to set. One of the MCP2515_RXMODE_T values.

MCP2515_RXMSG_T rxStatusMsgs ( )

Return a bitmask indicating which of the 2 RX buffers have packets waiting in them. This can be 0 (no packets), 1(RXB0), 2(RXB1), or 3 (RXB0 and RXB1). This information is retrieved using the MCP2515_CMD_RX_STATUS command.

Returns: A bitmask indicating which RX buffers (if any) have packets in them. One of the MCP2515_RXMSG_T values.

MCP2515_MSGTYPE_T rxStatusMsgType ( )

Return the message type present in one of the RX buffers. RXB0 has the highest priority, so if both RX buffers are full, this function will only return data for the packet in RXB0. This information is retrieved using the MCP2515_CMD_RX_STATUS command.

Returns: One of the MCP2515_MSGTYPE_T values.

MCP2515_FILTERMATCH_T rxStatusFiltermatch ( )

Return the filter that matched an RX buffer. RXB0 has the highest priority, so if both RX buffers are full, this function will only return data for the packet in RXB0. This information is retrieved using the MCP2515_CMD_RX_STATUS command.

Returns: One of the MCP2515_FILTERMATCH_T values.

upm_result_t getRXMsg ( MCP2515_RX_BUFFER_T bufnum )

This function retrieves a message from the specified RX buffer. The message (MCP2515_MSG_T) contains all of the data in the packet, including id, rtr, ext, payload and payload length. In addition, after retrieving the message, the RX buffer is freed to receive further data from the CAN bus. The message is stored within the class.

Parameters

bufnum The buffer to retrieve. One of the MCP2515_RX_BUFFER_T values.

void printMsg ( )

This is a utility function prints the current (last received) messages decoded contents. This is of primary importance for debugging, and to simplify the examples somewhat.

The output will look similar to:

id 00000000 ext 0 rtr 0 filt 0 len 8 payload: 0xc8 0x01 0x02 0x03 0x04 0x05 0x06 0x07

int msgGetID ( )

inline

This method returns the id of a received message. It will only be valid after a successful completion of rxGetMsg().

Returns: ID of the last received message.

bool msgGetRTR ( )

inline

This method returns the RTR flag of a received message. It will only be valid after a successful completion of rxGetMsg().

Returns: True if the message has the RTR flag set, false otherwise.

bool msgGetEXT ( )

inline

This method returns the EXT (extended ID) flag of a received message. It will only be valid after a successful completion of rxGetMsg().

Returns: True if the message has an extended ID, false otherwise.

int msgGetFilterNum ( )

inline

This method returns the filter number that caused the message to be stored in the RX buffer. It will only be valid after a successful completion of rxGetMsg().

Returns: The filter number that was matched.

int msgGetPayloadLen ( )

inline

This method returns the length of the payload of the RX buffer. It will only be valid after a successful completion of rxGetMsg().

Returns: Length of the payload in bytes, max 8.

std::string msgGetPayload ( )

inline

This method returns the contents of the payload in the last received message. It will only be valid after a successful completion of rxGetMsg().

Returns: String containing the payload.

Here is the call graph for this function:

void installISR	(	int	pin,
		void()(void )	isr,
		void *	arg
	)

Installs an interrupt service routine (ISR) to be called when an interrupt occurs.

Parameters

pin	GPIO pin to use as the interrupt pin.
isr	Pointer to a function to be called on interrupt.
arg	Pointer to an object to be supplied as an argument to the ISR.

Here is the caller graph for this function:

void uninstallISR ( )

Uninstalls the previously installed ISR

Parameters

dev	Device context.

Here is the caller graph for this function:

void setIntrEnables ( uint8_t enables )

Set the interrupt enables register.

Parameters

enables A bitmask of interrupts to enable from MCP2515_CANINT_BITS_T.

Here is the caller graph for this function:

uint8_t getIntrFlags ( )

Retrieve the interrupt flags register.

Returns: A bitmask that will be filled with values from MCP2515_CANINT_BITS_T, indicating which interrupt flags are set.

Here is the caller graph for this function:

void setIntrFlags ( uint8_t flags )

This function allows you to set specific interrupt flags. If the corresponding interrupt enable is set, an interrupt will be generated.

Parameters

flags A bitmask of interrupt flags to set, from MCP2515_CANINT_BITS_T values.

Here is the caller graph for this function:

void clearIntrFlags ( uint8_t flags )

This function allows you to clear specific interrupt flags. See the datasheet. Some flags cannot be cleared until the underlying cause has been corrected.

Parameters

flags A bitmask of interrupt flags to clear, from MCP2515_CANINT_BITS_T values.

Here is the caller graph for this function:

uint8_t getErrorFlags ( )

Retrieve the error flags register

Returns: A bitmask that will be filled with values from MCP2515_EFLG_BITS_T, indicating which error flags are set.

Here is the caller graph for this function:

void clearErrorFlags ( uint8_t flags )

Clear error flags. Note, some flags cannot be cleared until the underlying issues is resolved.

Returns: A bitmask of values from MCP2515_EFLG_BITS_T, indicating which error flags to clear.

Here is the caller graph for this function:

void setFilter	(	MCP2515_RX_FILTER_T	filter,
		bool	ext,
		int	id
	)

This function allows you to set one of the 6 RX filters available. Filters 0 and 1 are for RXB0 only, while filters 2-5 are for RXB1. See the datasheet for details on how these filters (along with the masks) are used to select candidate CAN bus data for retrieval from the CAN bus.

These can only be set when the device is in CONFIG mode.

Parameters

filter	One of the 6 MCP2515_RX_FILTER_T values.
ext	True if the id is extended, false for standard.
id	Integer representation of a CAN bus ID.

Here is the caller graph for this function:

void setMask	(	MCP2515_RX_MASK_T	mask,
		bool	ext,
		int	id
	)

This function allows you to set one of the 2 RX masks. Mask 0 is for RXB0, mask 1 is for RXB1. The masks specify which bits in the filters are used for matching CAN bus data. See the datasheet for details on how these masks (along with the filters) are used to select candidate CAN bus data for retrieval from the CAN bus.

These can only be set when the device is in CONFIG mode.

Parameters

mask	One of the 2 MCP2515_RX_MASK_T values.
ext	True if the id is extended, false for standard.
id	Integer representation of a CAN bus ID.

Here is the caller graph for this function:

string busRead	(	uint8_t	cmd,
		std::string	args,
		int	datalen
	)

protected

Perform a bus read. This function is exposed here for those users wishing to perform their own low level accesses. This is a low level function, and should not be used unless you know what you are doing.

Parameters

cmd	The command to send.
args	String containing arguments, or empty for no arguments.
datalen	The length of the data to read.

Returns: A string containing the data.

Here is the caller graph for this function:

void busWrite	(	uint8_t	cmd,
		std::string	data
	)

protected

Perform a bus write. This function is exposed here for those users wishing to perform their own low level accesses. This is a low level function, and should not be used unless you know what you are doing.

Parameters

cmd	The command to send.
data	A string containing the data to write.
len	The number of bytes to write.

Here is the caller graph for this function:

void writeReg	(	uint8_t	reg,
		uint8_t	value
	)

protected

Write to a specific register. This function is exposed here for those users wishing to perform their own low level accesses. This is a low level function, and should not be used unless you know what you are doing.

Parameters

reg	The register to write to.
value	The byte to write.

Here is the caller graph for this function:

void writeRegs	(	uint8_t	reg,
		std::string	buffer
	)

protected

Write to multiple consecutive registers. This function is exposed here for those users wishing to perform their own low level accesses. This is a low level function, and should not be used unless you know what you are doing.

Parameters

reg	The register to start writing to.
buffer	A string containing data to write.

Here is the caller graph for this function:

uint8_t readReg ( uint8_t reg )

protected

Read a register. This function is exposed here for those users wishing to perform their own low level accesses. This is a low level function, and should not be used unless you know what you are doing.

Parameters

reg	The register to read.

Returns: The register contents.

Here is the caller graph for this function:

void bitModify	(	uint8_t	addr,
		uint8_t	mask,
		uint8_t	value
	)

protected

Perform a bit modify operation on a register. Only certain registers support this method of access - check the datasheet. This function is exposed here for those users wishing to perform their own low level accesses. This is a low level function, and should not be used unless you know what you are doing.

Parameters

addr	The address of the register to access.
mask	A bitmask used to mask off value bits.
value	The value to write (bits masked by mask).

Here is the caller graph for this function:

Collaboration diagram for MCP2515:

[legend]

The documentation for this class was generated from the following files:

src/mcp2515/mcp2515.hpp
src/mcp2515/mcp2515.cxx

Detailed Description

Public Member Functions

Protected Member Functions

Protected Attributes

Constructor & Destructor Documentation

Member Function Documentation