Hardware manual

ManualsBrandsRenesas ManualsComputer equipmentRX600 Series

APPLICATION NOTE

R01AN0339EU0203 Rev. 2.03 Page 1 of 29

Mar 23, 2013

RX600 Series

CAN Application Programming Interface

Introduction

This application note introduces the Renesas CAN Application Programming Interface and explains how to use it to

send, receive, and monitor data on the CAN bus. It also explains briefly some features of the CAN peripheral.

Bundled with this application note comes the CAN API driver source code files config_r_can_rapi.h, r_can_api.h, and

r_can_api.c. Note that there are alternative ways to write the driver functions. For example you may want to write your

own driver functions to tailor a specific behavior.

The RX CAN peripheral has 32 CAN mailboxes to read from and write to in order to communicate over CAN. These

mailboxes are message ‘buffers’ and will hold the CAN data frame until it is overwritten by another incoming frame, or

rewritten by the application. Each mailbox can be configured dynamically to transmit or receive. Usually, most are

configured to receive and a few to transmit.

A CAN API is also available from Renesas for the CAN equipped MCUs in the families R32C, M32C, M16C, R8C, for

SH RCAN-ET MCUs SH7286, SH7137, and for the SH7216. Most, if not all, CAN MCUs are available on Renesas

Starter Kit boards. Demonstration source code for the API is available for all these devices and runs the same demo

across all of these devices so that they can be connected and run together.

The term ‘mailbox’, or in some literature ‘message box’ or ‘message buffer’ refers to the physical location where

messages are stored inside the MCU’s CAN peripheral. In this document we will use the term ‘mailbox’.

Target Device

RX600 Series of MCUs with CAN.

R01AN0339EU0203

Rev. 2.03

Mar 23, 2013

Summary of content (32 pages)

PAGE 1
APPLICATION NOTE RX600 Series CAN Application Programming Interface R01AN0339EU0203 Rev. 2.03 Mar 23, 2013 Introduction This application note introduces the Renesas CAN Application Programming Interface and explains how to use it to send, receive, and monitor data on the CAN bus. It also explains briefly some features of the CAN peripheral. Bundled with this application note comes the CAN API driver source code files config_r_can_rapi.h, r_can_api.h, and r_can_api.c.
PAGE 2
RX600 Series CAN Application Programming Interface Contents 1. CAN Basics ....................................................................................................................................... 3 2. The CAN Peripheral .......................................................................................................................... 3 3. Communication Layers .....................................................................................................................
PAGE 3
RX600 Series 1. CAN Application Programming Interface CAN Basics CAN was designed to provide reliable, error-free network communication for applications in which safety and real-time operation cannot be compromised. Its main attributes can be summarized as follows: • High reliability and noise immunity • Fewer connections • Flexible architecture • Error handling through peripherals • Low wiring cost • Scalability The MCU and bus connectors need only two pins.
PAGE 4
RX600 Series 3. CAN Application Programming Interface Communication Layers The figure below shows the CAN communication layers, with the application layer at the top and the hardware layer at the bottom. Figure 1. CAN physical and source code layers. In this document we will not discuss any higher level protocols such as CANopen or DeviceNet. (For some Renesas CAN MCUs there is a CANopen solution. Contact your sales representative.) 4.
PAGE 5
RX600 Series 6. CAN Application Programming Interface Adding the CAN API to Your Project Follow the steps below to add the CAN API code to your project. These steps assume that the Flash API has already been added to your project. 1. Copy the r_can_api directory (packaged with this application note) to your project directory. 2. Add the file r_can_api.c to your project. 3. Add an include path to the r_can_api directory. 4. Add an include path to the r_can_api\src directory. 5.
PAGE 6
RX600 Series CAN Application Programming Interface CAN Bitrate Settings See API R_CAN_SetBitrate below and the file config_r_can_rapi.h. 8. The CAN API The API is a set of functions that allow you to use CAN without having to commit attention to all the details of setting up the CAN peripheral, to be able to easily have your application communicate with other nodes on the network.
PAGE 7
RX600 Series CAN Application Programming Interface R_CAN_SW_WAKEUP_ERR The CAN peripheral did not wake up from Sleep mode. R_CAN_SW_SLEEP_ERR The CAN peripheral did enter Sleep mode. R_CAN_SW_HALT_ERR The CAN peripheral did not enter Halt mode. R_CAN_SW_RST_ERR The CAN peripheral did not enter Reset mode. R_CAN_SW_TSRC_ERR Time Stamp error. R_CAN_SW_SET_TX_TMO Waiting for previous transmission to finish timed out. R_CAN_SW_SET_RX_TMO Waiting for previous reception to complete timed out.
PAGE 8
RX600 Series CAN Application Programming Interface R_CAN_Create Initializes the CAN peripheral, sets bitrate, masks, mailbox defaults and configures CAN interrupts This function will by default invoke the rest of the initialization functions. It also sets the CAN interrupt levels. It will also call all other relevant set-up functions such as • R_CAN_SetBitrate() • R_CAN_RxSetMask () • R_CAN_PortSet () Format uint32_t R_CAN_Create(const uint32_t ch_nr); Arguments ch_nr 0,1,2,3 Which CAN bus to use.
PAGE 9
RX600 Series CAN Application Programming Interface R_CAN_PortSet Configures the MCU and transceiver port pins This function is responsible for configuring the MCU and transceiver port pins. Transceiver port pins such as Enable will vary depending on design, and this function must then be modified. The function is also used to enter the CAN port test modes, such as Listen Only.
PAGE 10
RX600 Series CAN Application Programming Interface R_CAN_Control Set CAN operating modes Controls transition to CAN operating modes determined by the CAN Control register. For example, the Halt mode should be used to later configure a receive mailbox. Format uint32_t R_CAN_Control( const uint32_t const uint32_t ch_nr, action_type ); Arguments ch_nr 0,1,2,3 Which CAN bus to use. The number of available channels depends on part. 1-4 channels may be available.
PAGE 11
RX600 Series CAN Application Programming Interface R_CAN_SetBitrate Sets the CAN bitrate (communication speed) The baud rate and bit timing must always be set during the configuration process. It can be changed later on if reset mode is entered. Format void R_CAN_SetBitrate(const uint32_t ch_nr); Arguments ch_nr 0,1,2,3 Which CAN bus to use. 1-4 channels may be available. Return Values - Properties Prototyped in r_can_api.h Implemented in r_can_api.
PAGE 12
RX600 Series CAN Application Programming Interface R_CAN_TxSet and R_CAN_TxSetXid Set up a mailbox to transmit R_CAN_TxSet will write to a mailbox the specified ID, data length and data frame payload, then set the mailbox to transmit mode and send a frame onto the bus by calling R_CAN_Tx(). R_CAN_TxSetXid does the same, except if this function is used, the ID will be a 29-bit ID.
PAGE 13
RX600 Series CAN Application Programming Interface R_CAN_Tx Starts actual message transmission onto the CAN bus This API will wait until the mailbox finishes handling a prior frame, then set the mailbox to transmit mode. Format uint32_t R_CAN_Tx( const uint32_t const uint32_t ch_nr, mbox_nr ); Arguments ch_nr 0,1,2,3 Which CAN bus to use. 1-4 channels may be available. mbox_nr 0-32 Which CAN mailbox to use.
PAGE 14
RX600 Series CAN Application Programming Interface R_CAN_TxCheck Check for successful data frame transmission. Use to check a mailbox for a successful data frame transmission. Format uint32_t R_CAN_TxCheck( const uint32_t const uint32_t ch_nr, mbox_nr ); Arguments ch_nr 0,1,2,3 Which CAN bus to use. 1-4 channels may be available. mbox_nr 0-32 Which CAN mailbox to use. Return Values R_CAN_OK Transmission was completed successfully. R_CAN_SW_BAD_MBX Bad mailbox number.
PAGE 15
RX600 Series CAN Application Programming Interface R_CAN_TxStopMsg Stop a mailbox that has been asked to transmit a frame Format uint32_t R_CAN_TxStopMsg( const uint32_t const uint32_t ch_nr, mbox_nr ); Arguments ch_nr 0,1,2,3 Which CAN bus to use. 1-4 channels may be available. mbox_nr 0-32 Which CAN mailbox to use. Return Values R_CAN_OK Action completed successfully. R_CAN_SW_BAD_MBX Bad mailbox number. R_CAN_BAD_CH_NR The channel number does not exist.
PAGE 16
RX600 Series CAN Application Programming Interface R_CAN_RxSet and R_CAN_RxSetXid Set up a mailbox to receive R_CAN_RxSet The API sets up a given mailbox to receive data frames with the given CAN ID. Incoming data frames with the same ID will be stored in the mailbox. R_CAN_RxSetXid does the same thing, except if this function is used, the ID will be a 29-bit ID.
PAGE 17
RX600 Series CAN Application Programming Interface R_CAN_RxPoll Checks if a mailbox has received a message Format uint32_t R_CAN_RxPoll( const uint32_t const uint32_t ch_nr, mbox_nr ); Arguments ch_nr 0,1,2,3 Which CAN bus to use. 1-4 channels may be available. mbox_nr 0-32 Which CAN mailbox to check. Return Values R_CAN_OK There is a message waiting. R_CAN_NOT_OK No message waiting or pending. R_CAN_RXPOLL_TMO Message pending but timed out. R_CAN_SW_BAD_MBX Bad mailbox number.
PAGE 18
RX600 Series CAN Application Programming Interface R_CAN_RxRead Read the CAN data frame content from a mailbox The API checks if a given mailbox has received a message. If so, a copy of the mailbox’s dataframe will be written to the given structure. Format uint32_t R_CAN_RxRead( const uint32_t const uint32_t can_std_frame_t * const ch_nr, mbox_nr, frame_p ); Arguments ch_nr 0,1,2,3 Which CAN bus to use. 1-4 channels may be available. mbox_nr 0-32 Which CAN mailbox to check.
PAGE 19
RX600 Series CAN Application Programming Interface R_CAN_RxSetMask Sets the CAN ID Acceptance Masks To accept only one ID, set mask to all ones. To accept all messages, set mask to all zeros. To accept a range of messages, set the corresponding ID bits to zero. Format void R_CAN_RxSetMask( const uint32_t const uint32_t const uint32_t ch_nr, mbox_nr, sid_mask_value ); Arguments ch_nr 0,1,2,3 Which CAN bus to use. 1-4 channels may be available. mbox_nr 0-32 Which CAN mailbox to check.
PAGE 20
RX600 Series CAN Application Programming Interface Fast filtering of messages with Acceptance Filter Support If you have used a mask to receive a broad range of message IDs, you must filter for the actual desired messages with firmware. To increase the speed of this search one may use the Acceptance Filter Support instead. The Acceptance Filter Support Unit (ASU) provides a faster search compared to software filtering of messages using a mask (with the R_CAN_RxSetMask API).
PAGE 21
RX600 Series CAN Application Programming Interface R_CAN_CheckErr Check for bus errors The API checks the CAN status, or Error State, of the CAN peripheral. Format uint32_t R_CAN_CheckErr(const uint32_t ch_nr); Parameters ch_nr 0,1,2,3 Which CAN bus to use. 1-4 channels may be available. urn Values CAN_STATE_ERROR_ACTIVE CAN Bus Status: Normal operation.
PAGE 22
RX600 Series CAN Application Programming Interface Error Active Normal TEC or REC < 128 11 consecutive recessive bits detected 128 times TEC or REC > 127 Error Passive No Errors sent TEC > 255 Bus Off No communication Figure 4. CAN Error States. Error Active When a node is in Error Active state it communicates with the bus normally. If the unit detects an error, it transmits an active Error flag. Once it counts 127 errors, it switches to the Error Passive state.
PAGE 23
RX600 Series CAN Application Programming Interface Figure 5. Handling recovery from Bus Off for the application. (The MCU detects recovery of the bus on its own.) A node will automatically resume the normal Error Active state again after seeing 11 consecutive recessive bits on the bus 128 times. Note that the time a node spends in Bus Off could be very short, e.g. less than a millisecond.
PAGE 24
RX600 Series CAN Application Programming Interface /* Tell user if CAN bus status changed. All Status bits are read only. */ if (error_bus_status[ch_nr] != error_bus_status_prev[ch_nr]) { switch (error_bus_status[ch_nr]) { /* Error Active. */ case R_CAN_STATUS_ERROR_ACTIVE: /* Only report if there was a previous error.
PAGE 25
RX600 Series CAN Application Programming Interface The CAN error interrupt can be used to check the error state of the node, although polling with the API regularly is usually sufficient since low level error handling is done by the peripheral. The API can be called from the error ISR to determine the error state, and then flag the application if a state transition has occurred. Most often the Transmit or Receive Error Counter will have just incremented.
PAGE 26
RX600 Series CAN Application Programming Interface Figure 6. CAN Internal Loopback mode. This lets you test the functionality of a node without having a CAN bus connected. Internal Loopback can be convenient when testing as this mode allows the CAN controller to run without sending CAN errors due to no Acks received when the node is alone on the bus, it acknowledges transmitted frames itself. 10.
PAGE 27
RX600 Series CAN Application Programming Interface Figure 8. A node in Listen Only mode will not acknowledge messages or send Error frames etc Listen Only is useful for bringing up a new node that has been added to an existing CAN bus. The mode can be used for a recently connected node’s application to ensure that frames have properly been received before going live. A common usage is to detect a bus’s communication speed before letting the new unit go ‘live’.
PAGE 28
RX600 Series CAN Application Programming Interface 11. Time Stamp The timestamp function captures the value of the on-chip time stamp to a mailbox when a message is received. By examining the time stamp you can for example determine the sequence of messages if they are spread out over multiple receive mailboxes to determine the order of the messages.
PAGE 29
RX600 Series CAN Application Programming Interface Website and Support Renesas Electronics Website http://www.renesas.com/ Inquiries http://www.renesas.com/inquiry All trademarks and registered trademarks are the property of their respective owners. R01AN0339EU0203 Rev. 2.
PAGE 30
Revision Record Rev. 1.00 1.10 Date Jun 1, 2010 Jun 6, 2011 1.11 Oct 2, 2011 2.00 Jan 10, 2011 2.01 May 16, 2012 Oct 10, 2012 2.02 Nov 13, 2012 2.03 Mar 23, 2013 Description Page Summary — First edition issued AN# changed from REU05B0145 to R01AN0339EU. Added RX62T and RX630 projects. 4 Changed CAPI_CFG_CAN_ISR to CAPI_CFG_CANx_ISR. 6 Added API return code "R_CAN_NOT_OK". All Changed “config_r_can_rap.h” to “config_r_can_rapi.h”. Changed Properties to RX600 Series 1 All Added Extended CAN.
PAGE 31
General Precautions in the Handling of MPU/MCU Products The following usage notes are applicable to all MPU/MCU products from Renesas. For detailed usage notes on the products covered by this document, refer to the relevant sections of the document as well as any technical updates that have been issued for the products. 1. Handling of Unused Pins Handle unused pins in accord with the directions given under Handling of Unused Pins in the manual.
PAGE 32
Notice 1. Descriptions of circuits, software and other related information in this document are provided only to illustrate the operation of semiconductor products and application examples. You are fully responsible for the incorporation of these circuits, software, and information in the design of your equipment. Renesas Electronics assumes no responsibility for any losses incurred by you or third parties arising from the use of these circuits, software, or information. 2.