UPM

The UPM API is a high level sensor library for IoT devices using MRAA. See examples here. Back to index page.
SparkFun sensor images provided under CC BY-NC-SA-3.0.

MCP2515 Class

Module: mcp2515

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. A simple transmit and receive example.

Methods

MCP2515

(
  • bus
  • csPin
)
Number

MCP2515 constructor.

Parameters:

  • bus Number

    spi bus to use

  • csPin Number

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

Returns:

Number:

reset

()

Reset the device.

setOpmode

(
  • 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 MCP2515_OPMODE_T

    One of the MCP2515_OPMODE_T values.

setSpeed

(
  • 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 MCP2515_SPEED_T

    One of the MCP2515_SPEED_T values.

loadTXBuffer

(
  • bufnum
  • id
  • ext
  • rtr
  • 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 MCP2515_TX_BUFFER_T

    The buffer to load. One of the MCP2515_TX_BUFFER_T values.

  • id Number

    The integer representation of the CAN bus ID.

  • ext Boolean

    True if the ID is an extended identifier, false otherwise.

  • rtr Boolean

    True if this is a Remote Transfer Request, false otherwise.

  • payload String

    A string containing the payload bytes. Maximum length is 8.

transmitBuffer

(
  • bufnum
  • wait
)

Transmit a buffer already loaded by loadTXBuffer() .

Parameters:

  • bufnum MCP2515_TX_BUFFER_T

    The buffer to transmit. One of the MCP2515_TX_BUFFER_T values.

  • wait Boolean

    True if the function should wait until transmission is complete before returning, false otherwise.

isTXBufferFree

(
  • bufnum
)
Boolean

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 MCP2515_TX_BUFFER_T

    The buffer to check. One of the MCP2515_TX_BUFFER_T values.

Returns:

Boolean:

True if the buffer is availabe, false otherwise.

findFreeTXBuffer

() MCP2515_TX_BUFFER_T

Find a free TX buffer and return it.

Returns:

MCP2515_TX_BUFFER_T:

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

setTXBufferPriority

(
  • bufnum
  • 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 MCP2515_TX_BUFFER_T

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

  • priority MCP2515_TXP_T

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

abortTX

(
  • 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 MCP2515_TX_BUFFER_T

    The buffer to abort. One of the MCP2515_TX_BUFFER_T values.

setRXBufferMode

(
  • bufnum
  • 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 MCP2515_RX_BUFFER_T

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

  • rxm MCP2515_RXMODE_T

    The mode to set. One of the MCP2515_RXMODE_T values.

rxStatusMsgs

() MCP2515_RXMSG_T

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:

MCP2515_RXMSG_T:

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

rxStatusMsgType

() MCP2515_MSGTYPE_T

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:

MCP2515_MSGTYPE_T:

One of the MCP2515_MSGTYPE_T values.

rxStatusFiltermatch

() MCP2515_FILTERMATCH_T

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:

MCP2515_FILTERMATCH_T:

One of the MCP2515_FILTERMATCH_T values.

getRXMsg

(
  • bufnum
)
Upm_result_t

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 MCP2515_RX_BUFFER_T

    The buffer to retrieve. One of the MCP2515_RX_BUFFER_T values.

Returns:

Upm_result_t:

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

msgGetID

() Number

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

Returns:

Number:

ID of the last received message.

msgGetRTR

() Boolean

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

Returns:

Boolean:

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

msgGetEXT

() Boolean

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

Returns:

Boolean:

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

msgGetFilterNum

() Number

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:

Number:

The filter number that was matched.

msgGetPayloadLen

() Number

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

Returns:

Number:

Length of the payload in bytes, max 8.

msgGetPayload

() String

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:

String containing the payload.

installISR

(
  • pin
  • isr
  • arg
)

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

Parameters:

  • pin Number

    GPIO pin to use as the interrupt pin.

  • isr Function

    Pointer to a function to be called on interrupt.

  • arg Void *

    Pointer to an object to be supplied as an argument to the ISR.

uninstallISR

()

Uninstalls the previously installed ISR

setIntrEnables

(
  • enables
)

Set the interrupt enables register.

Parameters:

  • enables Number

    A bitmask of interrupts to enable from MCP2515_CANINT_BITS_T.

getIntrFlags

() Number

Retrieve the interrupt flags register.

Returns:

Number:

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

setIntrFlags

(
  • flags
)

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

Parameters:

  • flags Number

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

clearIntrFlags

(
  • 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 Number

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

getErrorFlags

() Number

Retrieve the error flags register

Returns:

Number:

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

clearErrorFlags

(
  • flags
)

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

Parameters:

  • flags Number

    undefined

setFilter

(
  • filter
  • ext
  • 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 MCP2515_RX_FILTER_T

    One of the 6 MCP2515_RX_FILTER_T values.

  • ext Boolean

    True if the id is extended, false for standard.

  • id Number

    Integer representation of a CAN bus ID.

setMask

(
  • mask
  • ext
  • 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 MCP2515_RX_MASK_T

    One of the 2 MCP2515_RX_MASK_T values.

  • ext Boolean

    True if the id is extended, false for standard.

  • id Number

    Integer representation of a CAN bus ID.