1 <!DOCTYPE book PUBLIC "-//OASIS//DTD DocBook V4.1//EN"
4 <!-- DocBook file was created by LyX 1.3
5 See http://www.lyx.org/ for more information -->
8 Open Source Components for CAN Bus
11 P. P\'{\i}\v{s}a, F. Vacek
14 Department of Control Engineering, Faculty of Electrical Engineering
15 Karlovo nám\v{e}st\'{\i} 13, 121 35 Praha 2
22 This article deals with implementation of virtual CAN API, CANopen
23 slave device and CAN/CANopen monitor. This open source code, written
24 under OCERA project, is destined for Linux and RT Linux. The virtual
25 CAN API is the interface used to connect the application threads
26 either with the CAN hardware card or with other software layers
27 substituting CAN bus. The application thread can live either in the
28 Hard RT space (RT Linux) or in the Soft RT space (Linux). In the other
29 words we can say that VCA is a layer between the CAN driver and the
30 application threads. CANopen device is a software solution based on
31 CANopen FSM (Finite State Machine) threads, EDS (Electronic Data
32 Sheet) file and HDS (Handler Definition Sheet) file. The device can be
33 CANopen master or CANopen slave. CAN monitor is a component used to
34 scan a CAN bus. It can receive, send and log messages. If CAN device
35 EDS (Electronic Data Sheet) is available CanMonitor offers also basic
36 SDO functionality. Written in Java the CAN monitor is a multi-platform
37 application. </para> <para>Keywords: CAN, CANopen, Linux, RT-Linux,
38 LinCAN. </para> </abstract> <sect1> <title>Introduction </title>
39 <para>The OCERA CAN framework offers fundamental components for
40 development of CAN and CANopensolutions. The framework defines Virtual
41 CAN API, which defines interactions between CANdriver and other
42 components. Each CAN solution requires access to CAN bus. The Linux
43 LinCANdriver performs this role in OCERA CAN framework. The real-time
44 port of the LinCAN driverfor RT-Linux is developed under name ORTCAN.
45 </para> <para>The higher communication layers support is oriented to
46 industrial applications.The CANopen and DeviceNET protocols are used
47 in this area. The OCERA frameworkhas selected CANopen layer support
48 because OCERA industrial partners have moreinterest in this protocol.
49 </para> <para>The CANopen defines process data objects (PDO) and
50 device dictionary (servicedata objects SDO) access protocol and
51 communication profiles for commonly usedindustrial devices (sensors,
52 actuators, controllers). The concrete device specializedprofile is
53 distributed in the form of the Electronic Data Sheets (EDS). The
54 presentedframework can use existing EDS for purposes of the CAN
55 communication monitoring andtesting (CAN monitor component) or for
56 building new devices conforming suppliedcommunication profile (CAN
57 device component). The one CAN bus based network isrestricted to
58 territorial local communication. The provided CAN monitor
59 daemonconcept extends the possible distance between CAN monitor and
60 monitored CAN networkbecause all communication between monitored
61 system (CAN bus network) and host system running CAN monitor is
62 realized by means of TCP/IP protocol. </para> </sect1> <sect1>
66 The LinCAN driver is the loadable module for the Linux kernel which
67 implements CAN driver. The driver communicates and controls one or
68 more CAN controllers chips. Each chip/CAN interface is represented to
69 the applications as one or more CAN message objects accessible as
70 character devices. The application can open the character device and
71 use read/write system calls for CAN messages transmission or reception
72 through the connected message object. The parameters of the message
73 object can be modified by the IOCTL system call. The closing of the
74 character device releases resources allocated by the application. The
75 present version of the driver supports three most common CAN
76 controllers: </para> <itemizedlist> <listitem> <para>Intel
77 i82527 chips </para> </listitem> <listitem> <para>Philips
83 Philips SJA1000 chips in standard and PeliCAN mode
90 The intelligent CAN/CANopen cards should be supported by future
91 versions. One of such cards is P-CAN series of cards produced by
92 Unicontrols. The driver contains support for more than ten CAN cards
93 basic types with different combinations of the above mentioned chips.
94 Not all card types are held by OCERA members, but CTU has and tested
95 more SJA1000 type cards and will test some i82527 cards in near
96 future. </para> <sect2> <title>Driver Background </title>
97 <para>The development of the CAN drivers for Linux has long history.
98 We have been faced before two basic alternatives, start new project
99 from scratch or use some other project as basis of our development.
100 The first approach would probably lead faster to more simple and clean
101 internal architecture but it would mean to introduce new driver with
102 probably incompatible interface unusable for already existing
103 applications. The reimplementation of support for all existing cards
104 would take long time as well. More existing projects aimed to
105 development of a Linux CAN driver has been analyzed (LDDK CAN driver,
106 can4linux-0.9 by PORT GmbH, CanFestival, can-0.7.1 by Arnaud
107 Westenberg). The latest version has been selected as base for our
108 work, because this version of the driver had most mature support for
109 multiple cards of different kind. The internal infrastructure of this
110 driver did not fulfill our demands and most of it has been rewritten
111 between LinCAN 0.1 and 0.2 driver versions. The driver version 0.2
112 supports 2.2.x, 2.4.x and 2.6.0-test Linux kernels. </para>
113 </sect2> <sect2> <title>Driver Application Interface </title>
114 <para><figure><para><graphic
115 fileref="&graph1001;"></para><title><anchor
116 id="cap:lincan_arch1">LinCAN architecture</title></figure>The LinCAN
117 provides simultaneous queued communication for more concurrent running
118 applications. Even each of communication object can be used by one or
119 more applications, which connects to the communication object internal
120 representation by means of CAN FIFO queues. This enables to build
121 complex systems based even on card and chips, which provides only one
122 communication objects (for example SJA1000). </para> <para>The
123 driver can be configured to provide virtual CAN board (software
124 emulated message object) to test CAN components on the Linux system
125 without hardware required to connect to the real CAN bus. The example
126 configuration of the CAN network components connected to one real or
127 virtual communication object of LinCAN driver is shown in figure <xref
128 linkend="cap:lincan_arch1">. The communication object is used by the
129 CAN monitor daemon and two CANopen devices implemented by OCERA CanDev
130 component. The actual system dependent driver API is hidden to
131 applications under VCA library. The CAN monitor daemon translates CAN
132 messages to TCP/IP network for Java based platform independent CAN
133 monitor and C based test client. </para> <para>Each communication
134 object is represented as character device file. The devices can be
135 opened and closed by applications in blocking or non-blocking mode.
136 LinCAN client application state, chip and object configurations are
137 controlled by IOCTL system call. One or more CAN messages can be sent
138 or received through write/read system calls. The data read from or
139 written to the driver are formed from sequence of fixed size
140 structures representing CAN messages. </para>
141 <programlisting><![CDATA[struct canmsg_t {]]><![CDATA[ int
142 flags;]]><![CDATA[ int cob;]]><![CDATA[ unsigned long
143 id;]]><![CDATA[ canmsg_tstamp_t timestamp;]]><![CDATA[ unsigned short
144 length;]]><![CDATA[ unsigned char
145 data[CAN_MSG_LENGTH];]]><![CDATA[};]]> </programlisting> </sect2>
146 <sect2> <title>Driver Implementation </title> <para>The LinCAN
147 driver version 0.2 has rewritten infrastructure based on message FIFOs
148 organized into oriented edges between chip drivers (structure chip_t)
149 message objects representations (structure msgobj_t) and open device
150 file instances state (structure canuser_t). The complete relationship
151 between CAN hardware representation and open instances is illustrated
152 in the figure <xref linkend="cap:lincan_canhardware1">. </para>
153 <para><figure><para><graphic
154 fileref="&graph1002;"></para><title><anchor
155 id="cap:lincan_canqueue1">LinCAN message FIFO
156 implementation</title></figure>The message FIFO (structure
157 canque_fifo_t) initialization code allocates configurable number of
158 slots capable to hold one message. The all slots are linked to the
159 free list after initialization. The slot can be requested by FIFO
160 input side by function canque_fifo_get_inslot. The slot is filled by
161 message data and is linked into FIFO queue by function
162 canque_fifo_put_inslot. If previously requested slot is not
163 successfully filled by data, it can be released by
164 canque_fifo_abort_inslot. The output side of the FIFO tests presence
165 of ready slots by function canque_fifo_test_outslot. If the slot is
166 returned by this function, it is processed and released by function
167 canque_fifo_free_outslot. The processing can be postponed in the case
168 of bus error or higher priority message processing request by
169 canque_fifo_again_outslot function. All these functions are extremely
170 simple and fast, which enables to synchronize them by spin-lock
171 semaphores and guarantee atomic nature of them. The FIFO
172 implementation is illustrated in the figure <xref
173 linkend="cap:lincan_canqueue1">. </para>
174 <para><figure><para><graphic
175 fileref="&graph1003;"></para><title><anchor
176 id="cap:lincan_canends1">LinCAN driver message flow graph
177 edges</title></figure> The low level message FIFOs are wrapped by CAN
178 edges structures (canque_edge_t), which are used for message passing
179 between all components of the driver. The actual version of LinCAN
180 driver uses oriented edges to connect clients/users with chips and
181 communication objects. Each entity, which is able to hold edge ends,
182 has to be equipped by canque_ends_t structure. The input ends of
183 edges/FIFOs are held on inlist. The inactive/empty out ends of th
184 edges are held on a idle list and active out ends are held on a active
185 list corresponding to the edge priority. The canque_fifo_test_outslot
186 function can determine by examination of active lists if there is
187 message to accept/process. This concept makes possible to use same
188 type of edges for outgoing and incoming directions. The concept of
189 edges can be even used for message filtering by priority or acceptance
190 masks. It is prepared for future targeting messages to predefined
191 message objects according to their priority or type and for redundant
192 and fault tolerant message distribution into more CAN buses. Message
193 concentration, virtual nodes and other special processing can be
194 implemented above this concept as well. The example of interconnection
195 of one communication object with two users/open instances is
196 illustrated in the picture <xref linkend="cap:lincan_canends1">. Three
197 edges/FIFOs are in the active state and one edge/FIFO is empty in the
198 shown example. </para> <para><figure><para><graphic
199 fileref="&graph1004;"></para><title><anchor
200 id="cap:lincan_canhardware1">CAN hardware model in the LinCAN
201 driver</title></figure>The figure <xref
202 linkend="cap:lincan_canhardware1"> is example of object inside LinCAN
203 driver representing system with two boards, three chips and more
204 communication objects. Some of these objects are used by one or more
205 applications. The object open instances are represented as canuser_t
206 structures. </para> </sect2> </sect1> <sect1> <title>CanDevice
207 </title> <para>CANopen device is a software library based on CANopen
208 FSM (Finite State Machine). CANopen device should be compatible with
209 standard industrial CANopen devices according to CiA Draft Standard
210 301. There are two main CANopen device applications - CANmaster and
211 CANslave. </para> <para>CANslave is an application written in C,
212 which can read EDS (Electronic Data Sheet) file to build its OD
213 (Object Dictionary). When the EDS is loaded, one can upload/download
214 SDO object using CAN bus. </para> <para><figure><para><graphic
215 fileref="&graph1005;"></para><title><anchor
216 id="cap:slave_concept">CANslave concept</title></figure> </para>
217 <para>CANslave consist of next main components </para>
218 <itemizedlist> <listitem> <para>FSM </para> </listitem>
219 <listitem> <para>PDO handlers module </para> </listitem>
220 <listitem> <para>OD </para> </listitem> <listitem> <para>EDS
234 </term><listitem><para>(Finite State Machine) means set of RT-Linux
235 threads providing PDO and SDO communication via CAN driver . Slave FSM
236 also calls appropriate handler PDO communication and looks into the
237 slave's object dictionary using SDO API in case of SDO request.
243 </term><listitem><para>is an user written module containing handlers
244 for reading/writing PDO mapped object data from/to hardware. </para>
252 </term><listitem><para>(Electronic Data Sheet) is a text file
253 describing all objects in the slave OD (Object Dictionary). EDS is
254 parsed in order to create the slave OD. </para>
261 </term><listitem><para>(Handler Definition Sheet) means a text file
262 describing the linking PDO's COB-ID with required handler in order to
263 grant correspondence between the CANopen object value and
264 technological process data from the hardware. In other words it
265 describe how to get/set object value from/to hardware using PDO
266 handlers module functions. For example a thermometer with the analog
267 output connected to PC A/D converter card needs handler which reads
268 temperature from the card output port and gives it to the FSM. The
269 slave designer have to write this handler code and put link between
270 this handler and temperature_object in OD. The FSM source code remains
271 always the same, OCERA written. </para> </listitem>
272 </varlistentry> </variablelist> <para>According the application hard
273 real-time demands the CANslave can be placed either in the kernel
274 space or in the user one. </para> <sect2> <title>User space
275 CANslave concept </title>
277 This solution is suitable for debug purposes or in situations where
278 hard real-time is not so important condition. </para>
281 <graphic fileref="&graph1006;">
284 User space CANslave solution
289 As can be seen on figure above CAN driver sends the CAN messages to
290 CANslave FSM via VCA. FSM handles messages of two main categories,
291 process data (PDO) and service data (SDO, NMT, SFO). </para>
292 <para>The process data (PDO objects) are handled separately of the
293 service (SDO) ones. Slave FSM exploits CAN driver message buffers as
294 the buffers for the slave PDOs. This approach is necessary because
295 some CAN chips have such buffers integrated. On the other hand this
296 can speed up PDO object handling. Slave FSM role lies in updating this
297 buffers after device specific event such is timer event or process
298 object value change. The CAN driver sends objects from its buffers
299 when needed (after SYNC object or as a response to RTR object).
300 Consequently slave FSM has to read this buffers after WPDO object
301 arrival. </para> <para>The PDO handler module is used to
302 synchronize PDO mapped objects values and real world data examined or
303 set by computer hardware. Every PDO mapped object has assigned its
304 reading and writing routine called PDO handler. These handlers are
305 written by control system developer in order to fit general FSM
306 concept to specific hardware and real world process. </para>
307 <para>Some of SFO (Special Function Objects) are handled directly by
308 CAN driver. Such objects are the SYNC or RTR frames. </para>
309 <para>Service objects (SDO) are sent through the SDO API to OD driver.
310 OD driver is responsible for all object dictionary manipulations, that
311 means getting and setting object values. If the PDO mapping change
312 occurs due to SDO object processing, OD driver informs slave FSM (via
313 SDO API) to correct PDO handlers table to reflect PDO mapping status
314 in OD properly. </para> <para>OD driver communicates with OD
315 daemon, which resides in the user space, through RT FIFOs. OD daemon
316 offers set of primitives to provide basic manipulations with OD like
317 get/set object value, add object, delete object etc. OD daemon also
318 owns slave OD in its memory space. </para> <para>Slave OD can be
319 loaded onto OD daemon memory by EDS parser. EDS parser is the
320 graphical front end to the OD daemon connected with it via Unix
321 socket. This gives us the opportunity to control the daemon and slave
322 OD remotely using TCP/IP. EDS parser is also responsible to read HDS
323 and make appropriate changes in daemon OD and also (via daemon SDO
324 API) in slave FSM PDO handler table. This ensures that the proper
325 handlers will be called for certain PDO objects. </para> </sect2>
326 <sect2> <title>Kernel space CANslave concept </title>
327 <para>This solution is suitable for embedded devices or for hard
328 real-time control. </para> <para><figure><para><graphic
329 fileref="&graph1007;"></para><title>Kernel space CANslave
330 solution</title></figure> </para> <para>This architecture is very
331 similar to the previous one. The main difference lies in OD position
332 which is a part of OD driver module now. Every other part of slave
333 remain the same. OD driver module is compiled from source code
334 generated by EDS parser from the slave EDS, HDS and the empty OD
335 driver template. This means that in this case the OD is hardwired in
336 the CANslave source code. </para> <para>Benefits of the kernel
337 space solution </para> <itemizedlist> <listitem>
338 <para>Faster PDO and SDO object processing (in deterministic time
343 Slave does not need user space applications to work properly.
349 Slave can be implemented to other POSIX compliant real-time OS like
355 Suitable for CANopen slave realization in embedded systems.
362 Disadvantages of the kernel space solution
367 OD is static, its structure can not be dynamically changed during
373 EDS parser can not explore OD any more for debug purposes. Standard
374 EDS communication on CAN bus can be used for that purpose. </para>
387 CANmaster architecture is very similar to the user space slave one.
388 CAN driver, FSM, OD driver and OD daemon are the same. New blocks, PDO
389 processor and PDO object table are introduced and OD daemon contains
390 OD of all slaves connected till now. PDO processor is necessary to
391 give control system designer an opportunity to process (ie. subtract)
392 technology values stored in PDO and then send the result to the CAN
393 bus. CANmaster is also responsible for CANopen network management.
394 </para> <para><figure><para><graphic
395 fileref="&graph1008;"></para><title>CANmaster implementation</title>
409 CanMonitor is a component primary used to scan a CAN bus. It can log
410 messages and also send ones. If CAN device EDS (Electronic Data Sheet)
411 is available CanMonitor offers also basic SDO functionality as reading
412 from and writing to device OD. Package consists of three programs.
413 </para> <sect2> <title>canmond
416 Canmond works like CAN/CANopen proxy. It translates every CAN message
417 to the textual, platform independent form and send it to the all
418 connected applications. TCP connection allows clients to be placed
419 wherever on the Internet. This gives us also opportunity to read/send
420 CAN messages using a java applet in HTML browser. </para>
421 <para><figure><para><graphic fileref="&graph1009;"></para>
435 Testclient is an simple console application based application for
436 communication with canmond. It provides us basic operation on
437 CAN/CANopen bus like sending messages and SDO communication. </para>
445 CanMonitor is a GUI Java based application connected to the canmond.
446 Like testclient it provides us basic CAN/CANopen communication
447 primitives. If one has CANopen device EDS (Electronic Data Sheet), he
448 can load it to the CanMonitor and read/write CANopen objects just
449 clicking on the mouse. </para> <para><figure><para><graphic
450 fileref="&graph1010;"></para>
452 CanMonitor log screen
457 CAN monitor can serve as application showing all messages on CAN bus.
458 You can also send a raw CAN messages to the CAN bus clicking on Send
459 button. </para> <para>
461 <graphic fileref="&graph1011;">
464 CanMonitor OD tree view
469 With loaded EDS you can upload/download CANopen objects values
470 straight to the device object dictionary (OD). </para>
474 Hanz\'alek, Z. - P\'{\i}\v{s}a, P. - Vacek, F. - \v{S}ebek, Z. -
475 Smol\'{\i}k, P., 2002, Architecture and Components Integration -
476 Communication Components. OCERA - Workshop I, 2002, pp 1-40 </para>
projects / can-usb1.git / blob