Home

CANpie Users Guide

1. Baudrate Definition for default baudrate 10 kBit s CP_BAUD_10K 20 kBit s CP_BAUD_20K 50 kBit s CP BAUD 50K 100 kBit s CP BAUD 100K 125 kBit s CP BAUD 125K 250 kBit s CP BAUD 250K 500 kBit s CP BAUD 500K 800 kBit s CP BAUD 800K 1 MBit s CP BAUD 1M Table 4 Standard baudrates 3 5 CAN statistic information If the pre defined baudrates do not meet the requirements it is possi ble to setup the CAN bittiming individually via the CpCoreBittim ing function Statistic information about a physical CAN interface can be gathered via the function CpCoreStatistic All counters are set to 0 upon initialisation of the CAN interface CpCoreDriverInit struct CpStats_s Total _U32 Total number of received data amp remote frames ulRcvMsgCount frames _U32 ulTrmMsgCount number of transmitted data amp remote rror events Total number of state change _U32 ulErrMsgCount typedef for this structure typedef struct CpStats_s _TsCpStats CANpie Users Guide API Overview Error Codes 3 6 Error Codes All functions that may cause an error condition will return an error code The CANpie error codes are within the value range from 0 to 127 The designer of the core functions might extend the error code table with hardware specific error codes which must be in the range from 128 to 255 Error Code CpE
2. CANpie Users Guide 21 Core Functions CpCoreBittiming Syntax Function Parameters Return value 4 2 CpCoreBittiming _TvCpStatus CpCoreBittiming _TsCpPort ptsPortv _TsCpBitTiming ptsBitrateV Set bittiming of CAN controller This function directly writes to the bit timing registers of the CAN con troller Usage of the function requires a detailed knowledge of the used CAN controller hardware ptsPortV Pointer to CAN port handle ptsBitrateV Pointer to bit timing structure Error code defined in the canpie h headerfile If no error occured the function will return CpErr OK Example void SetCustomBaudrate void _TsCpPort tsCanPortT logical CAN port _TsCpBitTiming tsBitTimeT CpCoreDriverInit CP CHANNEL 1 amp tsCanPortT WEE EE EE en setup Btr0 and Btrl with user defined values tsBitTimeT ubBtrO 0x3F tsBitTimeT ubBtrl 0x1C CpCoreBittiming amp tsCanPortT amp tsBitTimeT now we have a new baudrate setting Example 4 Setup of user defined bittiming 22 CANpie Users Guide CpCoreBufferEnable Core Functions 4 3 CpCoreBufferEnable Syntax _TvCpStatus CpCoreBufferEnable _TsCpPort ptsPortv _U08 ubBufferIdxV U08 ubEnableV Function Enable Disable a message buffer The functions enables or disables a message buffer for reception and transmission of messages The message buffer has to be configured by CpCoreBufferInit
3. CANoic Controller Area Network Programming Interface Environment Version 2 00 Users Guide f UE Keywords Syntax Examples Document Conventions Icons on the border of the page are used to mark certain paragraphs in this document The following icons are used Note This icon designates a note relating to the surrounding text It is rec ommended to read these sections Tip This icon designates a helpful tip relating to the surrounding text Warning This icon designates a warning relating to the surrounding text Please read these sections carefully Important keywords appear in the border column to help the reader when browsing through this document For function syntax and code examples the font face courier is used MicroControl GmbH amp Co KG 2006 2009 MicroControl GmbH amp Co KG Lindlaustrasse 2c 53844 Troisdorf Germay URL http canpie sourceforge net eMail canpie microcontrol net Contents le SCOPE 4 4 a0 EE sash tesass eed ae eed bak DT 3 1 1 hr 3 1 2 Abbreviations kee ere REDE EE BEDE RE 3 1 3 Definitions T EL Pre 4 1 4 Introduction to CAN 4 1 5 LICENSE pP 5 2 Driver Principle 4 22 e uS 7 2 1 Message Distribution 8 2 2 Data LY DES cede SEE eut p dur OE DER ED EED Ee 9 2 3 Naming Conventions 9 2 4 Initialization Process cus err se Re eee das 10 3 APLOVOPUIOW Ls asin
4. CpCoreAutobaud Start automatic baudrate detection CpCoreBaudrate Set the bitrate of the CAN controller via pre defined values CpCoreBittiming Set the bitrate of the CAN controller via the bit timing registers constant value CpCoreCanMode Set the mode of CAN controller CpCoreCanState Retrieve the mode of CAN controller CpCoreDriverlnit Initialize the CAN driver CpCoreDriverRelease Stop the CAN driver CpCoreHDI Read the Hardware Description Information HDI structure CpCorelntFunctions Install callback functions for different CAN con troller interrupts CpCoreMsgRead Get a received message out of the CAN con troller and put it into the Read FIFO CpCoreMsgWrite Get a message from the Write FIFO and put it into the CAN controller transmit CpCoreStatistic Get statistical information Table 6 Basic core functions CANpie Users Guide Core Functions For a FullCAN controller i e a CAN controller that has several mes sage buffers an extended set of powerful functions is provided Function Description CpCoreBufferEnable Temporarily enable disable a message buffer CpCoreBufferGetData Get message data from buffer CpCoreBufferGetDlc Get data length code from buffer CpCoreBufferlnit Initialize message buffer in a FullCAN controller CpCoreBufferRelease Release messge buffe
5. The priorities are laid down during system design in the form of corre sponding binary values and cannot be changed dynamically The iden tifier with the lowest binary number has the highest priority Bus access conflicts are resolved by bit wise arbitration on the identifiers involved by each node observing the bus level bit for bit This happens in ac cordance with the wired and mechanism by which the dominant state overwrites the recessive state The competition for bus allocation is lost by all nodes with recessive transmission and dominant observa tion All the losers automatically become receivers of the message with the highest priority and do not re attempt transmission until the bus is available again The CAN protocol supports two message frame formats the only es sential difference being in the length of the identifier The CAN stand ard frame also known as CAN 2 0 A supports a length of 11 bits for the identifier and the CAN extended frame also known as CAN 2 0 B supports a length of 29 bits for the identifier CANpie Users Guide License Scope 1 5 License CANpie is free software you can redistribute it and or modify it under the terms of the GNU Lesser General Public License as published by the Free Software Foundation either version 2 1 of the License or at your option any later version This code library is distributed in the hope that it will be useful but WITHOUT ANY WARRANTY without eve
6. Therefore Subsection 2d requires that any application sup plied function or table used by this function must be optional if the application does not supply it the square root function must still compute square roots These requirements apply to the modified work as a whole If identifiable sections of that work are not derived from the Library and can be reasonably considered independent and separate works in them selves then this License and its terms do not apply to those sections when you distribute them as sep arate works But when you distribute the same sections as part of a whole which is a work based on the Library the distribution of the whole must be on the terms of this License whose permissions for other licensees extend to the entire whole and thus to each and every part regardless of who wrote it Thus it is not the intent of this section to claim rights or contestyour rights to work written entirely by you rather the intent is to exercise the right to control the distribution of derivative or collective works based on the Library In addition mere aggregation of another work not based on the Library with the Library or with a work based on the Library on a volume of a storage or distribution medium does not bring the other work under the scope of this License Section 3 You may opt to apply the terms of the ordinary GNU General Public License instead of this License to a given copy of the Library To do this you
7. THE LIBRARY TO OPERATE WITH ANY OTHER SOFTWARE EVEN IF SUCH HOLDER OR OTHER PARTY HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES CANpie Users Guide 61 LGPL LICENSE 62 CANpie Users Guide Index B Index B Baudrate function call 21 C CpCanMsg s tuMsgld 15 ulMsgld 15 CpCoreBaudrate 21 22 CpCoreBufferGetData 23 24 CpCoreBufferGetDlc 25 CpCoreBufferlnit 26 CpCoreBufferRelease 27 CpCoreBufferSend 30 CpCoreBufferSetData 28 CpCoreBufferSetDlc 29 CpCoreCanMode 31 CpCoreCanState 32 CpCoreDriverlnit 33 CpCoreDriverlnit 10 CpCoreDriverRelease 34 CpCoreHDI 35 CpCoreMsgReceive 37 CpCoreMsgTransmit 38 CpCoreRegWrite 39 S Structure _TsCpCanMsg 14 _TsCpHdi 12 CpCanMsg_s 14 CpHdi_s 12 CpTime_s 14 CANpie Users Guide 63 Index 64 CANpie Users Guide MicroControl reserves the right to modify this manual and or product described herein without further notice Nothing in this manual nor in any of the data sheets and other supporting doc umentation shall be interpreted as conveying an express or im plied warranty representation or guarantee regarding the suitability of the products for any particular purpose MicroCon trol does not assume any liability or obligation for damages ac tual or otherwise of any kind arising out of the application use of the products or manuals The products described in this manual are not designed intend ed or authorized for use as component
8. disclaimer of warranty keep intact all the notices that refer to this License and to the absence of any warranty and distribute a copy of this License along with the Library You may charge a fee for the physical act of transferring a copy and you may at your option offer war ranty protection in exchange for a fee Section 2 You may modify your copy or copies of the Library or any portion of it thus forming a work based on the Library and copy and distribute such modifications or work under the terms of Section 1 above provided that you also meet all of these conditions a The modified work must itself be a software library b You must cause the files modified to carry prominent notices stating that you changed the files and the date of any change c You must cause the whole of the work to be licensed at no charge to all third parties under the terms of this License If a facility in the modified Library refers to a function or a table of data to be supplied by an applica tion program that uses the facility other than as an argument passed when the facility is invoked then you must make a good faith effort to ensure that in the event an application does not supply such function or table the facility still operates and performs whatever part of its purpose remains meaningful d For example a function in a library to compute square roots has a purpose that is entirely well de fined independent of the application
9. in advance In contrast to the CpCoreBufferRelease function the contents message buffer is not deleted but message reception and transmission can be suppressed by setting ubEnableV to 0 Parameters ptsPortV Pointer to CAN port handle ubBufferldxV Index of message buffer ubEnableV Flag to enable disable message buffer Return value Error code defined in the canpie h headerfile If no error occured the function will return CpErr OK CANpie Users Guide 23 Core Functions CpCoreBufferGetData Syntax Function Parameters Return value 4 4 CpCoreBufferGetData _TvCpStatus CpCoreBufferGetData _TsCpPort ptsPortV U08 ubBufferIdxV _U08 pubDestDataV Get data from message buffer The functions copies 8 data bytes from the FullCAN message buffer de fined by ubBufferIdxv The destination buffer must have space for 8 bytes The buffer has to be configured by CpCoreBufferInit in advance ptsPortV Pointer to CAN port handle ubBufferldxV Index of message buffer pubDestDataV Pointer to destination buffer Error code defined in the canpie h headerfile If no error occured the function will return CpErr OK 24 CANpie Users Guide CpCoreBufferGetDlc Core Functions 4 5 CpCoreBufferGetDlc Syntax _TvCpStatus CpCoreBufferGetDlc _TsCpPort ptsPortV U08 ubBufferIdxV U08 pubDlcV Function Get DLC of specified buffer This function retrieves the Data Length Code D
10. interrupt 2 2 Data types Due to different implementations of data types in the world of C com pilers the following data types are used for CANpie API The data types are defined in the header file compiler h Data Type Definition BIT Boolean value True or False U08 1 Byte value value range 0 28 1 0 255 _508 1 Byte value value range 27 27 1 128 127 _U16 2 Byte value value range 0 216 3 0 65535 516 2 Byte value value range 215 215 1 U32 4 Byte value value range 0 2 1 532 4 Byte value value range 2 2 1 Table 1 Data Type definitions 2 3 Naming Conventions As mentioned in chapter 2 CANpie is divided in core and user func tions All functions structures defines and constants in CANpie have the prefix Cp The following table shows the used nomenclature CANpie Prefix Core functions CpCore User functions CpUser Message access functions CpMsg Structures _TsCp Constants Defines CP Error Codes CpErr Table 2 Naming conventions All constants defines and error codes can be found in the header file canpie h CANpie Users Guide Driver Principle Initialization Process 2 4 Initialization Process The CAN driver is initialized with the function CpCoreDriverlnit This routine will setup the CAN controller but not configure a certain bi trate nor switch the CAN controller to act
11. must alter all the notices that refer to this License so that they refer to the ordinary GNU General Public License version 2 instead of to this License If a newer version CANpie Users Guide 57 LGPL LICENSE than version 2 of the ordinary GNU General Public License has appeared then you can specify that ver sion instead if you wish Do not make any other change in these notices Once this change is made in a given copy it is irreversible for that copy so the ordinary GNU General Public License applies to all subsequent copies and derivative works made from that copy This option is useful when you wish to copy part of the code of the Library into a program that is not a library Section 4 You may copy and distribute the Library or a portion or derivative of it under Section 2 in object code or executable form under the terms of Sections 1 and 2 above provided that you accompany it with the complete corresponding machine readable source code which must be distributed under the terms of Sections 1 and 2 above on a medium customarily used for software interchange If distribution of object code is made by offering access to copy from a designated place then offering equivalent access to copy the source code from the same place satisfies the requirement to distribute the source code even though third parties are not compelled to copy the source along with the object code Section 5 A program that contains no derivative
12. of any portion of the Library but is designed to work with the Library by being compiled or linked with it is called a Work that uses the Library Such a work in isolation is not a derivative work of the Library and therefore falls outside the scope of this License However linking a work that uses the Library with the Library creates an executable that is a derivative of the Library because it contains portions of the Library rather than a work that uses the library The executable is therefore covered by this License Section 6 states terms for distribution of such executa bles When a work that uses the Library uses material from a header file that is part of the Library the object code for the work may be a derivative work of the Library even though the source code is not Whether this is true is especially significant if the work can be linked without the Library or if the work is itself a library The threshold for this to be true is not precisely defined by law If such an object file uses only numerical parameters data structure layouts and accessors and small macros and small inline functions ten lines or less in length then the use of the object file is unrestrict ed regardless of whether it is legally a derivative work Executables containing this object code plus portions of the Library will still fall under Section 6 Otherwise if the work is a derivative of the Library you may distribute the object code for
13. such software library or work which has been distributed under these terms A work based on the Library means either the Library or any derivative work under copyright law that is to say a work containing the Library or a portion of it either verbatim or with modifications and or translated straightforwardly into another language Hereinafter translation is included without limitation in the term modification Source code for a work means the preferred form of the work for making modifications to it For a library complete source code means all the source code for all modules it contains plus any associated interface definition files plus the scripts used to control compilation and installation of the library Activities other than copying distribution and modification are not covered by this License they are 56 CANpie Users Guide LGPL LICENSE outside its scope The act of running a program using the Library is not restricted and output from such a program is covered only if its contents constitute a work based on the Library independent of the use of the Library in a tool for writing it Whether that is true depends on what the Library does and what the program that uses the Library does Section 1 You may copy and distribute verbatim copies of the Library s complete source code as you receive it in any medium provided that you conspicuously and appropriately publish on each copy an appropriate copyright notice and
14. to the recipients so that they can relink them with the library after making changes to the library and recompiling it And you must show them these terms so they know their rights We protect your rights with a two step method 1 we copyright the library and 2 we offer you this license which gives you legal permission to copy distribute and or modify the library To protect each distributor we want to make it very clear that there is no warranty for the free library Also if the library is modified by someone else and passed on the recipients should know that what they have is not the original version so that the original author s reputation will not be affected by problems that might be introduced by others Finally software patents pose a constant threat to the existence of any free program We wish to make sure that a company cannot effectively restrict the users of a free program by obtaining a restrictive li cense from a patent holder Therefore we insist that any patent license obtained for a version of the library must be consistent with the full freedom of use specified in this license Most GNU software including some libraries is covered by the ordinary GNU General Public License This license the GNU Lesser General Public License applies to certain designated libraries and is quite different from the ordinary General Public License We use this license for certain libraries in order to permit linking those libraries int
15. ANopen specification DS 301 version 4 1 CAN in Automation ATMELO1 Datasheet ATMEL microcontroller AT89C51CC01 CAN controller section 1 2 Abbreviations CAN Controller area network CAN ID CAN identifier CRC Cyclic redundancy check LSB Least significant bit byte MSB Most significant bit byte OSI Open systems interconnection PLS Physical layer signaling PMA Physical medium attachment RTR Remote transmission request CANpie Users Guide Scope Definitions 1 3 Definitions CAN base frame message that contains up to 8 byte and is identified by 11 bits as defined in ISO 11898 1 CAN extended frame message that contains up to 8 byte and is identified by 29 bits as defined in ISO 11898 1 CAN ID identifier for CAN data and remote frames as defined in ISO 11898 1 1 4 Introduction to CAN The CAN Controller Area Network protocol is an international stand ard defined in the ISO 11898 for high speed and ISO 11519 2 for low speed CAN is based on a broadcast communication mechanism This broad cast communication is achieved by using a message oriented transmis sion protocol These messages are identified by using a message identifier Such a message identifier has to be unique within the whole network and it defines not only the content but also the priority of the message The priority at which a message is transmitted compared to another less urgent message is specified by the identifier of each message
16. CAN message This function retrieves the data of a CAN message The parameter ub PosV must be within the range O 7 Parameters ptsCanMsgV Pointer to CAN message structure ubPosV Zero based index of byte position Return value Data value at specified position void MyDataRead TsCpCanMsg ptsCanMsgV t U08 ubByteOT read first data byte from CAN message check the data length code DLC first if CpMsgGetDlc ptsCanMsgV gt 0 ubByteOT CpMsgGetData ptsCanMsgV 0 Example 9 Get data byte from CAN message structure 42 CANpie Users Guide CpMsgGetDlc CAN Message Functions 5 2 CpMsgGetDlc Syntax _U08 CpMsgGetData _TsCpCanMsg ptsCanMsgV Function Read DLC value from CAN message This function retrieves the data length code DLC of a CAN message Parameters ptsCanMsgV Pointer to CAN message structure Return value Data length code void MyDataRead TsCpCanMsg ptsCanMsgV t U08 ubByteOT read first data byte from CAN message check the data length code DLC first if CpMsgGetDlc ptsCanMsgV gt 0 ubByteOT CpMsgGetData ptsCanMsgV 0 Example 10 Check data length code from CAN message structure CANpie Users Guide 43 CAN Message Functions CpMsgGetExtld Syntax Function Parameters Return value 5 3 CpMsgGetExtld _U32 CpMsgGetExtId _TsCpCanMsg ptsCanMsgV Read extended identifier The function retr
17. CpCoreBufferSend _TsCpPort ptsPortV U08 ubBufferldxV Send message from message buffer This function transmits a message from the specified message buffer ubBuf ferIdxV The message buffer has to be configured by a call to CpCoreBufferInit in advance ptsPortV Pointer to CAN port handle ubBufferldxV Index of message buffer Error code defined in the canpie h headerfile If no error occured the function will return CpErr OK 30 CANpie Users Guide CpCoreCanMode Core Functions Syntax Function Parameters Return value 4 11 CpCoreCanMode _TvCpStatus CpCoreCanMode _TsCpPort ptsPortV U08 ubModeV Set operating mode of CAN controller This function changes the operating mode of the CAN controller Pos sible values for mode are defined in the CP_MODE enumeration At least the modes CP_MODE_STOP and CP_MODE_START are supported Other modes depend on the CAN controller capabilities ptsPortV Pointer to CAN port handle ubModeV New CAN controller mode Parameter ubModeV Description CP_MODE_STOP set controller into Stop mode CP_MODE_START set controller into Operational mode CP_MODE_LISTEN_ONLY set controller into Listen Only mode CP_MODE_SLEEP set controller into sleep mode Error code defined in the canpie h headerfile If no error occured the function will return CpErr OK CANpie Users Guide 31 Core Functions CpCoreCanStatu
18. LC of the specified buffer ubBufferIdxv Parameters ptsPortV Pointer to CAN port handle a ubBufferldxV Index of message buffer pubDIcV Pointer to destination buffer for DLC Return value Error code defined in the canpie h headerfile If no error occured the function will return CpErr OK CANpie Users Guide 25 Core Functions CpCoreBufferlnit Syntax Function Parameters Return value Example 4 6 CpCoreBufferlnit _TvCpStatus CpCoreBufferInit _TsCpPort ptsPortV _TsCpCanMsg ptsCanMsgV U08 ubBufferIdxV U08 ubDirectionV Initialise a message buffer mailbox in a FullCAN controller This function initialises a message buffer in a FullCAN controller The number of the message buffer inside the FullCAN controller is specified via the parameter ubBu ferIdxV A message buffer can be relased via the function CpCoreBu ferRelease ptsPortV Pointer to CAN port handle ptsCanMsgV Pointer to a CAN message structure ubBufferldxV Index of message buffer ubDirectionV Direction of message receive or transmit CP BUFFER DIR RX receive CP BUFFER DIR TX transmit Error code defined in the canpie h headerfile If no error occured the function will return CpErr OK void MyAllocationFunction TsCpPort ptsCanPortV t _TsCpCanMsg tsMyCanMsgT temporary CAN message set message buffer 1 as transmit buffer ID 120 DLC 2 CpMsgSetStdId amp tsMyCanMsg
19. T 120 ID 120 CpMsgSetDlc amp tsMyCanMsgT 2 CpCoreBufferInit ptsCanPortV amp tsCanMsgT CP_BUFFER_1 CP_BUFFER_DIR_TX Example 5 Allocation of a message buffer 26 CANpie Users Guide CpCoreBufferRelease Core Functions Syntax Function Parameters Return value 4 7 CpCoreBufferRelease _TvCpStatus CpCoreBufferRelease _TsCpPort ptsPortV U08 ubBufferldxV Release message buffer of FullCAN controller The function releases the allocated message buffer specified by the pa rameter ubBufferIdxvV Both reception and transmission will be disabled on the specified message buffer afterwards ptsPortV Pointer to CAN port handle ubBufferldxV Index of message buffer Error code defined in the canpie h headerfile If no error occured the function will return CpErr OK CANpie Users Guide 27 Core Functions CpCoreBufferSetData Syntax Function Parameters Return value 4 8 CpCoreBufferSetData _TvCpStatus CpCoreBufferSetData _TsCpPort ptsPortV U08 ubBufferIdxV _U08 pubSrcDataV Set data in message buffer This function copies 8 data bytes into the message buffer defined by the parameter ubBufferIdxv The message buffer has to be config ured by CpCoreBufferInit in advance The source data pointer pubSrcDataV must point to an array of 8 bytes length ptsPortV Pointer to CAN port handle ubBufferldxV Index of me
20. a E dra eroe ei cR e ded 11 3 1 Physical CAN interface 11 3 2 Hardware Description Interface 12 3 3 Structure of a CAN message 14 3 4 BIttIMINg Em 16 3 5 CAN statistic information 17 3 6 Error COUES uc be E EUER den PEER 18 4 Core FUNCUONS virus sed we ww xara REEL A Y 19 4 1 CpCoreBaudrate sr We ss EE eva 21 4 2 CpCoreBittiMming ues eb xd Rohr DE Eb dd 22 4 3 CpCoreB llerEnable 4 42 x re n een 23 4 4 CpCoreBufferGetData 24 4 5 CpCoreBufferGetDlc 25 4 6 CpCoreBufferlnit sus e e RC es 26 4 7 CpCoreBufferRelease 27 4 8 CpCoreBufferSetData ss vcrb EE Ren 28 4 9 CpCoreBulferSetDlc sre aoro 29 4 10 CpCoreBufferSend 30 4 11 CpCoreCanMode 31 4 12 CpCoreCanStalus i o rr RR EE RD 32 4 13 CpCoreDriverlnit esu bv ve ES x Y hee DS 33 4 14 CpCoreDriverRelease i e nar Re 34 4 15 X CUUCDIe HDI nern er 35 CANpie Users Guide 1 Contents 4 16 CpCorelntFunctions 36 417 CpCoreMsgRead zu semer 37 4 18 CpCoreMSOWTLTI sis Re sem REY 38 4 19 CpEorestalisiic ss erac secrets teen 39 5 CAN Message Functions 41 5 1 CpMsgGetData 2 da xaxa vy dee REOR ra OR 42 5 2 CpMsgGetDle suisses eee 43 5 3 CpMsgGetExtld sans sur eot n 44 5 4 CpMsgGebtld sss spreek RR br 45 5 5 CpMsglsExtended 42 vac ar e 46 5 6 C
21. d the function will return CpErr OK 38 CANpie Users Guide CpCoreStatistic Core Functions Syntax Function Parameters Return value 4 19 CpCoreStatistic _TvCpStatus CpCoreStatistic _TsCpPort ptsPortV _TsCpStats ptsStatsV Get statistic information from CAN controller This function copies statistic information into the structure _TsStats which is passed via the pointer ptsStatsV ptsPortV Pointer to CAN port handle ptsStatsV Pointer to CAN statistic structure Error code defined in the canpie h headerfile Possible return values are CpErr CHANNEL Channel number is out of range CpErr SUPPORTED Function is not supported e CpErr OK Function returned without error condition CANpie Users Guide 39 Core Functions CpCoreStatistic 40 CANpie Users Guide CAN Message Functions 5 CAN Message Functions Access to the members of the CAN message structure CpCanMsg_s shall be performed via macros or functions calls This ensures upon change of the CAN message structure that the application does not have to be adopted The CAN message functions are implemented as conventionell func tions as well as macros The symbol CP CAN MSG MACRO defines which implementation is used CANpie Users Guide 41 CAN Message Functions CpMsgGetData 5 1 CoMsgGetData Syntax _U08 CpMsgGetData _TsCpCanMsg ptsCanMsgV U08 ubPosV Function Read data bytes from
22. he sample point allows tuning of the characteristics to suit the bus Early sampling allows more Time Quanta in the Phase Segment 2 so the Synchronization Jump Width can be programmed to its maximum This maximum capacity to shorten or lengthen the bit time decreases the sensitivity to node oscillator tolerances so that low er cost oscillators such as ceramic resonators may be used Late sam pling allows more Time Quanta in the Propagation Time Segment which allows a poorer bus topology and maximum bus length 29 In order to allow interoperability between CAN nodes of different ven di gt dorsitis essential that both the absolute bit length e g 1us and the U AI sample point are within certian limits The following table gives an ES overview of recommended bittiming setups Bitrate Binme R E Ee per 1 MBit s 1 us 75 90 87 5 800 kBit s 1 25 us 75 90 87 5 500 kBit s 2 us 85 90 87 5 250 kBit s 4 us 85 90 87 5 125 kBit s 8 us 85 90 87 5 50 kBit s 20 us 85 90 87 5 20 kBit s 50 us 85 90 87 5 10 kBit s 100 us 85 90 87 5 Table 3 Recommended bit timing setup 16 CANpie Users Guide CAN statistic information API Overview The default baudrates defined in table 3 can be setup via the core func tion CpCoreBaudrate The supplied parameter for the baudrate selection are taken from the enumeration CP_BAUD canpie h
23. ibute the Li brary is void and will automatically terminate your rights under this License However parties who have received copies or rights from you under this License will not have their licenses terminated so long as such parties remain in full compliance Section 9 CANpie Users Guide 59 LGPL LICENSE You are not required to accept this License since you have not signed it However nothing else grants you permission to modify or distribute the Library or its derivative works These actions are prohibited by law if you do not accept this License Therefore by modifying or distributing the Library or any work based on the Library you indicate your acceptance of this License to do so and all its terms and con ditions for copying distributing or modifying the Library or works based on it Section 10 Each time you redistribute the Library or any work based on the Library the recipient automatically receives a license from the original licensor to copy distribute link with or modify the Library subject to these terms and conditions You may not impose any further restrictions on the recipients exercise of the rights granted herein You are not responsible for enforcing compliance by third parties with this License Section 11 If as a consequence of a court judgment or allegation of patent infringement or for any other reason not limited to patent issues conditions are imposed on you whether by court order agree
24. ide Structure of a CAN message API Overview Identifier Data Fields Data Length Code Message Control Time Stamp User Data f E Aon y D The identifier field union tuMsgld may have 11 bits for standard frames CAN specification 2 0A or 29 bits for extended frames CAN specification 2 0B The three most significant bits are reserved 31 30 29 28 27 26 25 24 23 22 21 20 1918 17 16 15 14 13 12 11 10 9 8 7 6 5 4 3 2 1 O reserved 0 11 Bit Identifier res 0 29 Bit Identifier The data fields union tuMsgData may contain up to eight bytes for a CAN message If the data length code is less than 8 the value of the unused data bytes will be undefined The data length code field ubMsgDLC holds the number of valid bytes in the data field array The allowed range is 0 to 8 The message control field ubMsgCtrl contains information about the frame type code The EXT bit bit 0 defines an Extended Frame 29 bit identifier if set The RTR bit bit 1 defines a Remote Transmission Re quest if set The OVR bit bit 2 defines a Overrun during message re ception if set T 6 5 4 3 2 1 0 reserved OVR RTR EXT The time stamp field tsMsgTime defines the time when a CAN mes sage was received by the CAN controller The time stamp is a
25. ieves the value for the identifier of an extended frame CAN 2 0B ptsCanMsgV Pointer to CAN message structure Value for extended identifier in the range O 1FFFFFFFh 44 CANpie Users Guide CpMsgGetStdld CAN Message Functions 5 4 CpMsgGetStdid Syntax _U16 CpMsgGet StdId _TsCpCanMsg ptsCanMsgV Function Read standard identifier The function retrieves the value for the identifier of a standard frame CAN 2 0A Parameters ptsCanMsgV Pointer to CAN message structure Return value Value for standard identifier in the range 0 7FFh CANpie Users Guide 45 CAN Message Functions CpMsglsExtended 5 5 CpMsglsExtended Syntax _U08 CpMsgIsExtended _TsCpCanMsg ptsCanMsgV Function Test for extended frame Parameters ptsCanMsgV Pointer to CAN message structure Return value TRUE on extended frame FALSE on standard frame 46 CANpie Users Guide CpMsglsRemote CAN Message Functions 5 6 CpMsglsRemote Syntax U08 CpMsgIsRemote _TsCpCanMsg ptsCanMsgV Function Test for remote frame Parameters ptsCanMsgV Pointer to CAN message structure Return value TRUE on remote frame FALSE on data frame CANpie Users Guide 47 CAN Message Functions CpMsgClear 5 7 CpMsgClear Syntax void CpMsgClear _TsCpCanMsg ptsCanMsgV Function Clear CAN message structure The function clears the elements of a CAN message structure Parameters ptsCanMsgV Pointer to CAN message structure Re
26. ion Interrupt Handler 2 1 Message Distribution The message distribution is responsible for reading and writing CAN messages The key component for message distribution is the Interrupt Handler The Interrupt Handler is started by a hardware interrupt from the CAN controller The Interrupt Handler has to determine the inter rupt type receive transmit status change Application Receive Transmit FIFO FIFO Status Statistic Mailbox EN Message Handler In case of a receive interrupt the handler uses the Receive Message rou tine to get the CAN message from the controller and put it into the Re ceive FIFO First In First Out The Receive FIFO must be initialized by the application If the Receive FIFO is full no further messages will be queued and an error signal will be submitted In case of a transmit interrupt the Transmit FIFO is checked If there are messages in this queue the Transmit Message routine will write the next waiting message to the CAN controller If the Transmit FIFO is empty and the application puts a CAN message into the queue the Transmit Message routine will be called automatically CANpie Users Guide Data types Driver Principle Callback Functions Data Types The occurence of an interrupt may call a user defined handler function Handler functions are possible for the following conditions Receive interrupt Transmit interrupt Status change
27. ite to the author to ask for permission For software which is copyrighted by the Free Software Foundation write to the Free Software Foundation we sometimes make exceptions for this Our decision will be guided by the two goals of preserving the free status of all derivatives of our free software and of promoting the sharing and reuse of software generally NO WARRANTY Section 15 BECAUSE THE LIBRARY IS LICENSED FREE OF CHARGE THERE IS NO WARRANTY FOR THE LIBRARY TO THE EXTENT PERMITTED BY APPLICABLE LAW EXCEPT WHEN OTHERWISE STATED IN WRITING THE COPYRIGHT HOLDERS AND OR OTHER PARTIES PROVIDE THE LIBRARY AS IS WITHOUT WARRANTY OF ANY KIND EITHER EXPRESSED OR IMPLIED INCLUDING BUT NOT LIMITED TO THE IMPLIED WAR RANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE THE ENTIRE RISK AS TO THE QUALITY AND PERFORMANCE OF THE LIBRARY IS WITH YOU SHOULD THE LIBRARY PROVE DE FECTIVE YOU ASSUME THE COST OF ALL NECESSARY SERVICING REPAIR OR CORRECTION Section 16 IN NO EVENT UNLESS REQUIRED BY APPLICABLE LAW OR AGREED TO IN WRITING WILL ANY COPY RIGHT HOLDER OR ANY OTHER PARTY WHO MAY MODIFY AND OR REDISTRIBUTE THE LIBRARY AS PERMITTED ABOVE BE LIABLE TO YOU FOR DAMAGES INCLUDING ANY GENERAL SPECIAL INCIDEN TAL OR CONSEQUENTIAL DAMAGES ARISING OUT OF THE USE OR INABILITY TO USE THE LIBRARY INCLUDING BUT NOT LIMITED TO LOSS OF DATA OR DATA BEING RENDERED INACCURATE OR LOSSES SUSTAINED BY YOU OR THIRD PARTIES OR A FAILURE OF
28. ive operation The following core functions must be called in that order CpCoreDriverInit CpCoreBaudrate CpCoreBittiming CpCoreCanMode void MyCanInit void TsCpPort tsCanPortT logical CAN port WEE EE EE EE EE setup the CAN controller open a physical CAN port CpCoreDriverInit CP CHANNEL 1 amp tsCanPortT YYA setup 500 kBit s CpCoreBaudrate amp tsCanPortT CP BAUD 500K ff f occisis start CAN operation CpCoreCanMode amp tsCanPortT CP MODE START now we are operational Example 1 Initialization process of the CAN interface The function CpCoreDriverlnit must be called before any other core function in order to have a valid handle pointer to the open CAN in terface 10 CANpie Users Guide Physical CAN interface API Overview 3 API Overview This chapter gives an overview of the CANpie API It also discusses the used structures in detail 3 1 Physical CAN interface A target system may have more than one physical CAN interface The physical CAN interfaces are numbered from 0 N 1 N total number of physical CAN interfaces on the target system The header file can pie h provides an enumeration for the physical CAN interface the first CAN interface is CP CHANNEL 1 A physical CAN interface is opened via the function CpCoreDriverInit The function will setup a pointer to the structure TsCpPor
29. ment or otherwise that contradict the conditions of this License they do not excuse you from the conditions of this License If you cannot distribute so as to satisfy simultaneously your obligations under this License and any other pertinent obligations then as a consequence you may not distribute the Library at all For example if a patent license would not permit royalty free redistribution of the Library by all those who receive copies directly or indirectly through you then the only way you could satisfy both it and this License would be to refrain entirely from distribution of the Library If any portion of this section is held invalid or unenforceable under any particular circumstance the bal ance of the section is intended to apply and the section as a whole is intended to apply in other circum stances It is not the purpose of this section to induce you to infringe any patents or other property right claims or to contest validity of any such claims this section has the sole purpose of protecting the integrity of the free software distribution system which is implemented by public license practices Many people have made generous contributions to the wide range of software distributed through that system in re liance on consistent application of that system it is up to the author donor to decide if he or she is will ing to distribute software through any other system and a licensee cannot impose that choice This section is intended t
30. mp has a resolution of 1 microsecond Siehe Time Stamp auf Seite 15 User Data If this flag is set to 1 the element ulUserData of the structure CpCanMsg siis valid A constant that identifies the used CAN controller chip Possible values for this member are listed in the header file cp cc h Defines the number of the interrupt which is used If the flag IROHan dler is set to 0 the value of IRQNumber will be undefined Holds the major version number of the CANpie driver release Holds the minor version number of the CANpie driver release CANpie Users Guide API Overview Structure of a CAN message 3 3 Structure of a CAN message For transmission and reception of CAN messages a structure which holds all necessary informations is used CpCanMsg_s The structure is defined in the header file canpie h and has the following data fields struct CpCanMsg_s identifier field 11 29 bit union _Ul6 uwStd U32 ulExt tuMsgId data field 8 bytes union U08 aubByte 8 _Ul6 auwWord 4 U32 aulLong 2 tuMsgData Data length code U08 ubMsgDLC Extended frame remote frame U08 ubMsgCtrl dif CP CAN MSG TIME _TsCpTime tsMsgTime fendif dif CP CAN MSG USER U32 ulMsgUser fendif typedef for this structure typedef struct CpCanMsg s _TsCpCanMsg struct CpTime_s U32 ulSec1970 _U32 ulNanoSec 14 CANpie Users Gu
31. n absolute value based on Jan 1st 1970 00 00 The lowest possible resolution is one nanosecond 1 ns This is an optional field The structure CpTime_s is defined similar to struct timeval head er file time h in the LINUX kernel The field user data ulUserData can hold a 32 bit value which is de fined by the user This is an optional field It is recommended to access the structure elements via function calls or macros rather than dealing with bitmasks Please refer to CAN Mes sage Functions on page 41 for a detailed description CANpie Users Guide API Overview Bittiming 3 4 Bittiming To ensure correct sampling up to the last bit a CAN node needs to re synchronize throughout the entire frame This is done at the beginning of each message with the falling edge SOF and on each recessive to dominant edge One CAN bit time is specified as four non overlapping time segments Each segment is constructed from an integer multiple of the Time Quantum The Time Quantum or TQ is the smallest discrete timing res olution used by a CAN node The four time segments are the Synchronization Segment the Propagation Time Segment the Phase Segment 1 and the Phase Segment 2 The sample point is the point of time at which the bus level is read and interpreted as the value recessive or dominant of the respective bit Its location is at the end of Phase Segment 1 between the two Phase Segments Programming of t
32. n the implied warranty of MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE See the GNU Lesser General Public License for more details The license can be found as appendix to this manual CANpie Users Guide Scope License 6 CANpie Users Guide Driver Principle 2 Driver Principle One of the ideas of CANpie is to keep it independent from the hard ware This is of course difficult to achieve due to many different target platforms CAN interface for embedded control e CAN interface for PC without local processor CAN interface for PC with local processor CANpie tries to meet this requirement by providing a two level API consisting of core functions and user functions Application CAN hardware CANpie Structure User Functions The user functions always call the core functions they never access the hardware directly That means the user functions do not have to be modified when implementing the CANpie on an existing hardware Core Functions The core functions access the hardware directly so an adaption is nec cessary when implementing on a piece of hardware Core functions may also be called by the application CANpie supports more than one CAN channel on the hardware The actual number of CAN channels can be gathered via the Hardware De scription Interface refer to Hardware Description Interface on page 12 CANpie Users Guide 7 Driver Principle Message Distribut
33. ning the modified Library It is un derstood that the user who changes the contents of definitions files in the Library will not necessarily be able to recompile the application to use the modified definitions b Use a suitable shared library mechanism for linking with the Library A suitable mechanism is one that 1 uses at run time a copy of the library already present on the user s computer system rather than copying library functions into the executable and 2 will operate properly with a modified ver sion of the library if the user installs one as long as the modified version is interface compatible with the version that the work was made with c Accompany the work with a written offer valid for at least three years to give the same user the materials specified in Subsection 6a above for a charge no more than the cost of performing this distribution d If distribution of the work is made by offering access to copy from a designated place offer equivalent access to copy the above specified materials from the same place e Verify that the user has already received a copy of these materials or that you have already sent this user a copy For an executable the required form of the work that uses the Library must include any data and utility programs needed for reproducing the executable from it However as a special exception the materials to be distributed need not include anything that is normally distrib
34. o make thoroughly clear what is believed to be a consequence of the rest of this License Section 12 If the distribution and or use of the Library is restricted in certain countries either by patents or by cop yrighted interfaces the original copyright holder who places the Library under this License may add an explicit geographical distribution limitation excluding those countries so that distribution is permitted only in or among countries not thus excluded In such case this License incorporates the limitation as if written in the body of this License Section 13 The Free Software Foundation may publish revised and or new versions of the Lesser General Public Li cense from time to time Such new versions will be similar in spirit to the present version but may differ in detail to address new problems or concerns Each version is given a distinguishing version number If the Library specifies a version number of this License which applies to it and any later version you have the option of following the terms and con ditions either of that version or of any later version published by the Free Software Foundation If the Library does not specify a license version number you may choose any version ever published by the Free Software Foundation 60 CANpie Users Guide LGPL LICENSE Section 14 If you wish to incorporate parts of the Library into other free programs whose distribution conditions are incompatible with these wr
35. o non free programs CANpie Users Guide 55 LGPL LICENSE When a program is linked with a library whether statically or using a shared library the combination of the two is legally speaking a combined work a derivative of the original library The ordinary General Public License therefore permits such linking only if the entire combination fits its criteria of freedom The Lesser General Public License permits more lax criteria for linking other code with the library We call this license the Lesser General Public License because it does Less to protect the user s freedom than the ordinary General Public License It also provides other free software developers Less of an ad vantage over competing non free programs These disadvantages are the reason we use the ordinary General Public License for many libraries However the Lesser license provides advantages in certain special circumstances For example on rare occasions there may be a special need to encourage the widest possible use of a certain library so that it becomes a de facto standard To achieve this non free programs must be al lowed to use the library A more frequent case is that a free library does the same job as widely used non free libraries In this case there is little to gain by limiting the free library to free software only so we use the Lesser General Public License In other cases permission to use a particular library in non free programs enables a greate
36. oftware to make sure the software is free for all its users This license the Lesser General Public License applies to some specially designated software packages typically libraries of the Free Software Foundation and other authors who decide to use it You can use it too but we suggest you first think carefully about whether this license or the ordinary General Public License is the better strategy to use in any particular case based on the explanations below When we speak of free software we are referring to freedom of use not price Our General Public Li censes are designed to make sure that you have the freedom to distribute copies of free software and charge for this service if you wish that you receive source code or can get it if you want it that you can change the software and use pieces of it in new free programs and that you are informed that you can do these things To protect your rights we need to make restrictions that forbid distributors to deny you these rights or to ask you to surrender these rights These restrictions translate to certain responsibilities for you if you distribute copies of the library or if you modify it For example if you distribute copies of the library whether gratis or for a fee you must give the recip ients all the rights that we gave you You must make sure that they too receive or can get the source code If you link other code with the library you must provide complete object files
37. ossible return values D are e CpErr HARDWARE Hardware failure occured initialisation is not possible e CpErr INIT FAIL Software failure occured initialisation is not possible e CpErr OK Function returned without error condition CANpie Users Guide 33 Core Functions CpCoreDriverRelease Syntax Function Parameters Return value 4 14 CpCoreDriverRelease _TvCpStatus CpCoreDriverRelease _TsCpPort ptsPortV Release the CAN driver ptsPortV Pointer to CAN port handle Error code defined in the canpie h headerfile If no error occured the function will return CpErr OK 34 CANpie Users Guide CpCoreHDI Core Functions 4 15 CpCoreHDI Syntax _TvCpStatus CpCoreHDI _TsCpPort ptsPortV _TsCpHdi ptsHdiV Function Get Hardware Description Information This function retrieves information about the used hardware Parameters ptsPortV Pointer to CAN port handle ptsHdiV Pointer to the Hardware Description structure a Return value Error code defined in the canpie h headerfile If no error occured the function will return CpErr OK CANpie Users Guide 35 Core Functions CpCorelntFunctions 4 16 CpCorelntFunctions Syntax _TvCpStatus CpCoreIntFunctions _TsCpPort ptsPortV U08 p nRcvHandler TsCpCanMsg U08 _U08 pfnTrmHandler TsCpCanMsg U08 _U08 pfnErrHandler _U08 Function Install callback functions This function will in
38. pMsglsRemote 5424 Saddam s setae seed 47 5 7 CpMsgClear uaa owes Ron men 48 5 8 CpMsgSetData x iae dual Bee er HER eww 49 5 9 CpMsdselDIE ii EE REESE 50 5 10 CpMsgSetExtld iiu pa oup uon e Y OR sien 51 5 11 CpMsgSetRemote c sede eco dnb cede ORE Ee 52 53 12 CpMsgSetStdld oua pope ett cr pred 53 A LGPL HICENSE 423 0040 dek ad DE And Cede eed 55 B nde os sie eae N OER SEE aa ann EWE N 63 CANpie Users Guide References Scope 1 Scope The goal of this project is to define a Standard Application Program ming Interface API for access to the CAN bus The API provides func tionality for ISO OSI Layer 2 Data Link Layer It is not the intention of CANpie to incorporate higher layer functionality e g CANopen J1939 DeviceNet Whereever it is possible CANpie is independent from the used hard ware and operating system The function calls are unique for different kinds of hardware Also CANpie provides a method to gather informa tion about the features of the CAN hardware This is especially impor tant for an application designer who wants to write the code only once The API is designed for embedded control applications as well as for PC interface boards 1 1 References ISO11898 1 ISO 11898 1 Road vehicles Controller area network CAN Part 1 Data link layer and physical signaling ISO11898 2 ISO 11898 2 Road vehicles Controller area network CAN Part 2 High speed medium access unit DS 301 C
39. r in a FullCAN controller CpCoreBufferSetData Set message data CpCoreBufferSetDic Set data length code CpCoreBufferSend Send message out of specified buffer Table 7 Core functions for buffer manipulation Because the core functions are highly dependent on the hardware en vironment and the used operating system the CANpie source package ie can only supply function bodies for these functions J eg E U 1 20 CANpie Users Guide CpCoreBaudrate Core Functions Syntax Function Parameters Return value Example 4 1 CpCoreBaudrate _TvCpStatus CpCoreBaudrate _TsCpPort ptsPortV U08 ubBaudSelV Set Baudrate of CAN controller This function initializes the bit timing registers of a CAN controller to pre defined values The values are defined in the canpie h headerfile enumeration CP BAUD Please refer to Bittiming on page 16 for a detailled description of common bittiming values ptsPortV Pointer to CAN port handle ubBaudSelV Baudrate selection enumeration CP BAUD Error code defined in the canpie h headerfile If no error occured the function will return CpErr OK void MyCanInit void t TsCpPort tsCanPortT logical CAN port CpCoreDriverInit CP CHANNEL 1 amp tsCanPortT setup 500 kBit s CpCoreBaudrate amp tsCanPortT CP BAUD 500K now we have a new baudrate setting Example 3 Setup of baudrate
40. r number of people to use a large body of free software For example permission to use the GNU C Library in non free programs enables many more people to use the whole GNU operating system as well as its variant the GNU Linux operating system Although the Lesser General Public License is Less protective of the users freedom it does ensure that the user of a program that is linked with the Library has the freedom and the wherewithal to run that program using a modified version of the Library The precise terms and conditions for copying distribution and modification follow Pay close attention to the difference between a work based on the library and a work that uses the library The former contains code derived from the library whereas the latter must be combined with the library in order to run GNU LESSER GENERAL PUBLIC LICENSE TERMS AND CONDITIONS FOR COPYING DISTRIBUTION AND MODIFICATION Section 0 This License Agreement applies to any software library or other program which contains a notice placed by the copyright holder or other authorized party saying it may be distributed under the terms of this Lesser General Public License also called this License Each licensee is addressed as you A library means a collection of software functions and or data prepared so as to be conveniently linked with application programs which use some of those functions and data to form executables The Library below refers to any
41. rr_OK Description No error occured CpErr_GENERIC Reason is not specified CpErr_HARDWARE Hardware failure CpErr_INIT_FAIL Initialisation failed CpErr_CAN_MESSAGE CAN message format is not valid CpErr_CAN_ID identifier is not valid CpErr_CAN_DLC data length code is not valid CpErr_FIFO_EMPTY FIFO read or write is empty CpErr_FIFO_WAIT message waiting in FIFO read or write CpErr_FIFO_FULL FIFO read or write is full CpErr FIFO SIZE not enough memory for FIFO CpErr BUS PASSIVE CAN controller is in bus passive state CpErr BUS OFF CAN controller is in bus off state CpErr BUS WARNING CAN controller is in warning state CpErr CHANNEL channel number is out of range CpErr REGISTER register address out of range CpErr BITRATE bitrate is out of range not supported CpErr_BUFFER buffer index is out of range CpErr_NOT_SUPPORTED the function is not supported Table 5 CANpie error codes 18 CANpie Users Guide Core Functions 4 Core Functions The core functions provide the direct interface to the CAN controller hardware Please note that due to hardware limitations maybe certain functions are not implemented A call to an unsupported function will always return the error code CpErr_NOT_SUPPORTED Function CpCoreAcceptance Description Setup acceptance filter
42. s Syntax Function Parameters Return value 4 12 CpCoreCanStatus _TvCpStatus CpCoreCanState _TsCpPort ptsPortV U08 pubStateV Retrieve state of CAN controller This function retrieved the present state of the CAN controller Possible values are defined in the CP STATE enumeration The state of the CAN controller is copied to the variable pointer pubStateV ptsPortV Pointer to CAN port handle pubStateV Pointer to CAN controller state variable Possible state values Description CP_STATE ACTIVE CAN controller is active no errors CP_STATE STOPPED CAN controller is in stopped mode CP_STATE_SLEEPING CAN controller is in Sleep mode CP_STATE_BUS_WARN Warning level is reached CP_STATE_BUS_PASSIVE CAN controller is error passive CP_STATE_BUS_OFF CAN controller went into Bus Off CP_STATE_PHY_FAULT General failure of physical layer detected CP_STATE_PHY_H Fault on CAN H Low Speed CAN CP_STATE_PHY_L Fault on CAN L Low Speed CAN Error code defined in the canpie h headerfile If no error occured the function will return CpErr OK 32 CANpie Users Guide CpCoreDriverlnit Core Functions 4 13 CpCoreDriverlnit Syntax _TvCpStatus CpCoreDriverInit _U08 ubPhyIfV _TsCpPort ptsPortV Function Initialize the CAN driver Parameters ubPhylfV CAN channel of the hardware ptsPortV Pointer to CAN port handle Return value Error code defined in the canpie h headerfile P
43. s in systems intended to support or sustain life or any other application in which failure of the product could create a situation where personal injury or death may occur 2009 MicroControl GmbH amp Co KG Troisdorf CANpie Users Guide MicroControl Version 1 00 Page 65 o o9 MicroContrel Systemhaus fur Automatisierung MicroControl GmbH amp Co KG Lindlaustra e 2c D 53842 Troisdorf Fon 49 2241 25659 0 Fax 49 2241 25 65 9 11 http www microcontrol net
44. ssage buffer pubSrcDataV Pointer to source data buffer Error code defined in the canpie h headerfile If no error occured the function will return CpErr OK _U08 aubDataT 8 buffer for 8 bytes aubDataT 0 0x11 byte 0 set to llhex aubDataT 1 0x22 byte 1 set to 22hex copy the data to message buffer 1 CpCoreBufferSetData ptsCanPortV CP BUFFER 1 amp aubDataT lcdHsendEChssEmessSddgel1ililu uidcic CpCoreBufferSend ptsCanPortV CP BUFFER 1 Example 6 Manipulation of data in message buffer 28 CANpie Users Guide CpCoreBufferSetDlc Core Functions Syntax Function Parameters Return value 4 9 CpCoreBufferSetDlc _TvCpStatus CpCoreBufferSetDlc _TsCpPort ptsPortV U08 ubBufferIdxV U08 ubDlcV Set Data Length Code DLC of specified message buffer This function sets the Data Length Code DLC of the specified message buffer ubBufferIdxv The DLC value ubD1cV must be in the range from 0 to 8 The message buffer has to be configured by a call to Cp CoreBufferInit in advance ptsPortV Pointer to CAN port handle ubBufferldxV Index of message buffer ubDIcV DLC value Error code defined in the canpie h headerfile If no error occured the function will return CpErr OK CANpie Users Guide 29 Core Functions CpCoreBufferSend Syntax Function Parameters Return value 4 10 CpCoreBufferSend _TvCpStatus
45. stall three different callback routines in the interrupt handler If you do not want to install a callback for a certain interrupt condition the parameter must be set to NULL e The callback functions for receive and transmit interrupt have the fol lowing syntax _U08 Handler _TsCpCanMsg ptsCanMsgV _U08 ubBufferIldxV The callback function for the CAN status change error interrupt has the following syntax _U08 Handler _U08 ubStateV Parameters ptsPortV Pointer to CAN port handle pfnRcvHandler Pointer to callback function for receive interrupt pfnTrmHandler Pointer to callback function for transmit interrupt pfnErrHandler Pointer to callback function for error interrupt Return value Error code defined in the canpie h headerfile U08 MyCanReceive TsCpCanMsg ptsCanMsgV _U08 ubBufferIdxV switch CpMsgGetStdId ptsCanMsgV case 0x022 do something with ID 0x022 break main HIS CpCoreIntFunctions amp tsCanPortT MyReceiveFunc OL OL AA Example 7 Install a callback for receive interrupt 36 CANpie Users Guide CpCoreMsgRead Core Functions 4 17 CpCoreMsgRead Syntax _TvCpStatus CpCoreMsgRead _TsCpPort ptsPortV _TsCpCanMsg ptsBufferV _U32 ulBufferSizeV Function Read CAN message from queue This function reads up to uiBufferSizev number of CAN messages from the receive queue of the CAN driver and stores it into the location poin
46. t for further operations The ele ments of the structure TsCpPort depend on the used target system and are defined in the header file cp arch h which defines data types and structures for different architectures EE EE EE EE struct CpPortLinux_s cp_arch h brief Port structure for Linux kk 7 struct CpPortLinux_s logical CAN interface number prx first index is 0 value 1 denotes not assigned 57 int slLogIf physical CAN interface number pee first index is 0 value 1 denotes not assigned a int slPhyIf CAN message queue number x first index is 0 value 1 denotes not assigned int slQueue typedef struct CpPortLinux_s _TsCpPort Example 2 CAN port structure for a LINUX target For an embedded application with only one physical CAN interface the parameter to the CAN port can be omitted This reduces the code size and also increases execution speed This option is configured via the symbol CP_SMALL_CODE during the compilation process CANpie Users Guide API Overview Hardware Description Interface Support Flags 3 2 Hardware Description Interface The Hardware Description Interface provides a method to gather infor mation about the CAN hardware and the functionality of the driver For this purpose the following structure is defined struct CpHdi_s _U16 uwVersionNumber _U16 uwSupportFlags _U16 uwControllerType _U16 uwIRQNumber _U16
47. ted by ptsBufferV The parameter ulBufferSizevV holds the size of the buffer in number of messages before the function is called and the actual number of messages copied in the buffer after the func tion is called Parameters ptsPortV Pointer to CAN port handle ptsBufferV Pointer to buffer for CAN messages ulBufferSizeV Size of the message buffer Return value Error code defined in the canpie h headerfile If no error occured the function will return CpErr OK define RCV_BUFFER_SIZE 64 static _TsCpCanMsg atsRcvBufferS RCV BUFFER SIZE U08 MyCanRead TsCpPort ptsCanPortV t maximum receive buffer size U32 ulBufferSizeT RCV BUFFER SIZE CpCoreMsgRead ptsCanPortV atsRcvBufferS amp ulBufferSizeT if ulBufferSizeT 0 no messages in the receive queue else Example 8 Message read operation CANpie Users Guide 37 Core Functions CpCoreMsgWrite Syntax Function Parameters Return value 4 18 CpCoreMsgWrite _U08 CpCoreMsgWrite _TsCpPort ptsPortV _TsCpCanMsg ptsBufferV _U32 ulBufferSizeV Write CAN message to queue This function gets the next CAN message out of the Transmit FIFO and writes it to the appropriate registers of the CAN controller ptsPortV Pointer to CAN port handle ptsBufferV Pointer to buffer for CAN messages ulBufferSizeV Size of the message buffer Error code defined in the canpie h headerfile If no error occure
48. the work under the terms of Section 6 Any executables containing that work also fall under Section 6 whether or not they are linked directly with the Library itself Section 6 As an exception to the Sections above you may also combine or link a work that uses the Library with the Library to produce a work containing portions of the Library and distribute that work under terms of your choice provided that the terms permit modification of the work for the customer s own use and reverse engineering for debugging such modifications You must give prominent notice with each copy of the work that the Library is used in it and that the Library and its use are covered by this License You must supply a copy of this License If the work during execution displays copyright notices you must include the copyright notice for the Library among them as well as a reference directing the user to the copy of this License Also you must do one of these things 58 CANpie Users Guide LGPL LICENSE a Accompany the work with the complete corresponding machine readable source code for the Library including whatever changes were used in the work which must be distributed under Sections 1 and 2 above and if the work is an executable linked with the Library with the complete machine read able work that uses the Library as object code and or source code so that the user can modify the Library and then relink to produce a modified executable contai
49. tidV extended identifier value Return value None CANpie Users Guide 51 CAN Message Functions CpMsgSetRemote 5 11 CpMsgSetRemote Syntax void CpMsgSetRemote _TsCpCanMsg ptsCanMsgV Function Set RTR bit This function sets the remote transmission bit RTR in the CAN mes sage structure Parameters ptsCanMsgV Pointer to CAN message structure Return value None 52 CANpie Users Guide CpMsgSetStdid CAN Message Functions 5 12 CpMsgSetStdid Syntax void CpMsgSetStdId _TsCpCanMsg ptsCanMsgV _U16 uwStdIdV Function Set 11 bit identifier value Parameters ptsCanMsgV pointer to CAN message structure uwStdldV standard identifier value Return value None CANpie Users Guide 53 CAN Message Functions CpMsgSetStdld 54 CANpie Users Guide LGPL LICENSE A LGPL LICENSE Version 2 1 February 1999 Copyright C 1991 1999 Free Software Foundation Inc 59 Temple Place Suite 330 Boston MA 02111 1307 USA Everyone is permitted to copy and distribute verbatim copies of this license document but changing it is not allowed This is the first released version of the Lesser GPL It also counts as the successor of the GNU Library Public License version 2 hence the version number 2 1 Preamble The licenses for most software are designed to take away your freedom to share and change it By con trast the GNU General Public Licenses are intended to guarantee your freedom to share and change free s
50. turn value None 48 CANpie Users Guide CpMsgSetData CAN Message Functions 5 8 CoMsgSetData Syntax void CpMsgSetData _TsCpCanMsg ptsCanMsgV U08 ubPosV U08 ubValueV Function Write data bytes to CAN message This function sets the data of a CAN message The parameter ub PosV must be within the range 0 7 Parameters ptsCanMsgV Pointer to CAN message structure ubPosV Zero based index of byte position ubValueV Data value for CAN message Return value None CANpie Users Guide 49 CAN Message Functions CpMsgSetDlc 5 9 CpMsgSetDlc Syntax _U08 CpMsgSetDlc _TsCpCanMsg ptsCanMsgV U08 ubDlcV Function Set DLC value of CAN message This function sets the data length code DLC of a CAN message The value must be within the range O 8 Parameters ptsCanMsgV Pointer to CAN message structure ubDIcV Data length code value Return value None _TsCpCanMsg tsMyCanMsgT temporary CAN message struct clear message and setup CAN ID 100h and DLC 4 CpMsgClear amp tsMyCanMsgT CpMsgSetStdId amp tsMyCanMsgT 0x0100 set ID 0x0100 CpMsgSetDlc amp tsMyCanMsgT 4 set DLC 4 Example 11 Setup the data length code 50 CANpie Users Guide CpMsgSetExtld CAN Message Functions 5 10 CpMsgSetExtld Syntax void CpMsgSetExtId _TsCpCanMsg ptsCanMsgV _U32 ulExtIdV Function Set 29 bit identifier value Parameters ptsCanMsgV pointer to CAN message structure ulEx
51. uted in either source or binary form with the major components compiler kernel and so on of the operating system on which the execut able runs unless that component itself accompanies the executable It may happen that this requirement contradicts the license restrictions of other proprietary libraries that do not normally accompany the operating system Such a contradiction means you cannot use both them and the Library together in an executable that you distribute Section 7 You may place library facilities that are a work based on the Library side by side in a single library to gether with other library facilities not covered by this License and distribute such a combined library provided that the separate distribution of the work based on the Library and of the other library facilities is otherwise permitted and provided that you do these two things a Accompany the combined library with a copy of the same work based on the Library uncombined with any other library facilities This must be distributed under the terms of the Sections above b Give prominent notice with the combined library of the fact that part of it is a work based on the Library and explaining where to find the accompanying uncombined form of the same work Section 8 You may not copy modify sublicense link with or distribute the Library except as expressly provided under this License Any attempt otherwise to copy modify sublicense link with or distr
52. uwBufferMax _U16 uwRes _U32 ulTimeStampRes _U32 ulCanClock U32 ulBitrate typedef struct CpHdi_s _TsCpHdi The hardware description structure is available for every physical CAN channel if 6 5 4 3 2 1 0 User Timestam Software IRQ Frametype eS Data p ID Fiter Handler FUIICAN 2 0A 2 0B Frametype Bit O and Bit 1 of the structure member uwSupportFlags describe the frame support of the CAN controller The following values are defined 0 Standard Frame 11 bit identifier 2 0A 1 Extended Frame 29 bit identifier 2 0B passive 2 Extended Frame 29 bit identifier 2 0B active FullCAN If the flag FullCAN is set to 1 the CAN controller has more than one receive buffer and one transmit buffer Interrupt Handler If the flag IRQHandler is set to 1 the driver will use a hardware in terrupt If set to 0 no interrupt handler is implemented This also means that no callback functions can be used polling 12 CANpie Users Guide Hardware Description Interface API Overview Controller Type IRQNumber VersionMajor VersionMinor Software ID Filter If the flag Software ID Filter is set to 1 the driver has implemented the software ID filter for standard frames If the member is set to 0 the software filter is not available Timestamp If this flag is set to 1 the CAN driver will set a time stamp to all re ceived messages The time sta

CANpie Users Guide

Contents

Download Pdf Manuals

Related Search

Related Contents