1 \documentclass[12pt,english,a4paper]{book}
2 \usepackage[T1]{fontenc}
3 \usepackage[latin9]{inputenc}
12 \DeclareGraphicsExtensions{.jpg}
13 \DeclareGraphicsExtensions{.png}
14 \hypersetup{colorlinks=true, linkcolor=blue, filecolor=blue, pagecolor=blue, urlcolor=blue}
16 %%%%\%%%%%%%% titre, auteurs, date, etc...%%%%%%%%%%%%%%%%%%
17 \title{\Huge The CanFestival CANOpen stack manual}
18 \author{Edouard TISSERANT}
21 \setcounter{secnumdepth}{5}
22 \renewcommand\thesection{\arabic{section} -}
23 \renewcommand\thesubsection{\arabic{section}.\arabic{subsection})}
24 \renewcommand\thesubsubsection{\arabic{section}.\arabic{subsection}.\arabic{subsubsection})}
25 \renewcommand\theparagraph{\alph{paragraph})}
26 \renewcommand\thesubparagraph{\roman{subparagraph})}
28 \newcommand{\canopen}{CANopen }
31 {\centering\textsf{\huge The CanFestival \canopen stack manual.}}
33 \renewcommand{\contentsname}{CanFestival v3.0 Manual}
34 \setcounter{tocdepth}{2} \tableofcontents{}
38 \section{Introduction}
40 CanFestival is an OpenSource (LGPL and GPL) \canopen framework.
42 \subsection{The CanFestival project}
44 This project, initiated by Edouard TISSERANT in 2001, has grown thanks
45 to Francis DUPIN and other contributors.
47 Today, CanFestival focuses on providing an ANSI-C platform independent
48 \canopen stack that can be implemented as master or slave nodes on
49 PCs, Real-time IPCs, and Microcontrollers.
51 CanFestival is a project supported by Lolitech.
54 \subsection{What is \canopen}
56 CANopen is a CAN based high level protocol. It defines some protocols
60 \item Configure a CAN network.
61 \item Transmit data to a specific node or in broadcast.
62 \item Administrate the network. For example detecting a not responding node.
64 The documentation can be found on the CAN in Automation website :
66 \href{http://www.can-cia.de/canopen}{http://www.can-cia.de/canopen}
68 The most important document about \canopen is the normative CiA Draft
69 Standard 301, version 4.02. You can now download the specification
70 from the CAN in Automation website at no cost.
72 To continue reading this document, let us assume that you have read
73 some papers introducing \canopen .
76 \section{CanFestival Features}
81 The \canopen library is coming with some tools :
84 \item Object Dictionary editor GUI. WxPython Model-View-Controler based
85 GUI, that helps a lot in generating object dictionary source code for
87 \item A configure script, that let you chose compile time options such as
88 target CPU/HOST, CAN and TIMER drivers.\\
89 This script has not been generated with autoconf, it has been made
90 keeping micro-controller target in mind.
93 \subsection{Multi-Platform}
96 \item Library source code is C-ANSI.
97 \item Driver and examples coding conventions merely depend on target specific
99 \item Unix compatible interfaces and examples should compile and run on
100 any Unix system (tested on GNU/Linux and GNU/FreeBSD).
103 \subsection{\canopen standard conformance}
105 \subsubsection{DS-301}
107 Supported features should conform to DS301. V.4.02 13 february 2002.
110 \item NMT master and slave
111 \item Heartbeat consumer and producer
112 \item NodeGuard slave reponder and basic master without tracking
114 \item SDO multiples client and server, segmented and expedited
115 \item PDO : TPDO and RPDO, with respect to transmission type
116 \item PDO mapping from/to OD variables bit per bit.
117 \item EMCY : Send and receive and keeps track of emergency objects
118 \item Data types : 8 to 64 bits values, fixed length strings.
121 \subsubsection{DS-302}
123 Only concise DFC is supported.
125 \section{How to start}
127 \subsection{Host requirements}
129 What you need on your development workstation.
131 \subsubsection{Object Dictionary Editor GUI}
135 \item wxPython modules installed (at least version 2.6.3).
136 \item Gnosis xml tools. (Optional can also be installed locally to the project
137 automatically with the help of a Makefile. Please see {}``Using Dictionary
141 \subsubsection{Linux and Unix-likes}
144 \item Linux, FreeBSD, Cygwin or any Unix environment with GNU toolchain.
145 \item The GNU C compiler (gcc) or any other ANSI-C compiler for your target
147 \item Xpdf, and the official 301\_v04000201.pdf file in order to get GUI
148 context sensitive help.
153 \subsubsection{Windows (for native win32 target)}
156 \item Visual Studio Express 2005 or worst.
157 \item Microsoft platform SDK (requires Genuine Advantage)
158 \item Cygwin (for configuration only)
161 \subsection{How to get CanFestival}
163 Please always use CVS, this is the best way to get the most reactive
164 support from the developer community :
168 cvs -d:pserver:anonymous@lolitech.dyndns.org:/canfestival login
171 (type return, without entering a password)
176 cvs -z3 -d:pserver:anonymous@lolitech.dyndns.org:/canfestival co -P CanFestival-3
181 \section{Understanding Canfestival}
183 \subsection{CanFestival Project tree layout}
185 Simplified directory structure.
188 ./src ANSI-C source of \canopen stack
189 ./include Exportables Header files
190 ./drivers Interfaces to specific platforms/HW
191 ./drivers/unix Linux and Cygwin OS interface
192 ./drivers/win32 Native Win32 OS interface
193 ./drivers/timers_xeno Xenomai timers/threads (Linux only)
194 ./drivers/timers_kernel Linux kernel timer/threads
195 ./drivers/timers_unix Posix timers/threads (Linux, Cygwin)
196 ./drivers/can_virtual_kernel Fake CAN network (kernel space)
197 ./drivers/can_serial Serial point to point and PTY hub (*nix only)
198 ./drivers/can_peak_linux PeakSystem CAN library interface
199 ./drivers/can_peak_win32 PeakSystem PCAN-Light interface
200 ./drivers/can_uvccm_win32 Acacetus's RS232 CAN-uVCCM interface
201 ./drivers/can_virtual Fake CAN network (Linux, Cygwin)
202 ./drivers/hcs12 HCS12 full target interface
204 ./examples/TestMasterSlave 2 nodes, NMT SYNC SDO PDO, win32+unix
205 ./examples/TestMasterMicroMod 1 node, control Peak I/O Module, unix
206 ./examples/gene_SYNC_HCS12 Just send periodic SYNC on HCS12
207 ./examples/win32test Ask some DS301 infos to a node (win32)
208 ./objdictgen Object Dictionary editor GUI
209 ./objdictgen/config Pre-defined OD profiles
210 ./objdictgen/examples Some examples/test OD
211 ./doc Documentation source
216 \subsection{Implement CanFestival in your application}
219 \includegraphics[width=12cm]{Pictures/10000201000003F9000002CF880931E7}
226 \subsection{CanFestival CAN interfaces}
228 Because most CAN controllers and drivers implement FIFOs, CanFestival
229 consider sending message as a non blocking operation.
231 In order to prevent reentrent calls to the stack, messages reception
232 is implemented differently on {\textmu}C and OS.:
235 \item {\textmu}C must provide interruption masking, mutually excluding timer and CAN receive interrupts.\\
240 \includegraphics[width=12cm]{Pictures/10000201000003CA0000016604E6A5EF}
243 \item OS must provide a receive thread, a timer thread and a mutex. CAN
244 reception should be a bloking operation.\\
249 \includegraphics[width=12cm]{Pictures/10000201000003F9000002CF8B0CDAEA}
254 \subsection{CanFestival event scheduling}
256 A \canopen node must be able to take delayed actions.
258 For instance, periodic sync emission, heartbeat production or SDO timeout
259 need to set some alarms that will be called later and do the job.
261 {\textmu}C generally do not have enough free timers to handle all
262 the \canopen needs directly. Moreover, CanFestival internal data
263 may be corrupt by reentrant calls.
265 CanFestival implement a micro -scheduler (timer.c). It uses only one
266 timer to mimic many timers. It manage an alarm table, and call alarms
270 \includegraphics[width=12cm]{Pictures/100000000000022C000000DEDAD2140C}
273 Scheduler can handle short clock value ranges limitation found on
274 some {\textmu}C. As an example, value range for a 16bit clock counter
275 with 4{\textmu}s tick is crossed within 0.26 seconds... Long alarms
278 Chronogram illustrate a long alarm (A) and a short periodic alarm
279 (B), with a A value {\textgreater} clock range {\textgreater}
280 B value. Values t0...t8 are successive setTimer call parameter values.
281 t1 illustrates an intermediate call to TimeDispatch, caused by a delay
282 longer than clock range. Because of long alarm segmentation, at the
283 end of t1, TimeDispatch call will not trig any alarm callback.
286 \includegraphics[width=12cm]{Pictures/1000000000000396000000FFC42573DA}
290 \section{Linux Target}
292 Linux target is default configure target.
295 \subsection{Linux Compilation and installation}
297 Call ./configure -- help to see all available compile time options.
299 After invoking ./configure with your platform specific switches, just
305 ./configure [options]
313 \subsubsection{Standard Linux node}
317 ./configure --timers=unix
321 To do a \canopen node running on PC -Linux, you need :
324 \item A working linux distribution
325 \item One or more Peak system PC CAN interface and the last Peak Linux driver
329 \subsubsection{Real -Time Linux node}
333 ./configure --timers=xeno
338 To do a \canopen node running on PC -Linux, you need :
341 \item A working Linux distribution patched with XENOMAI 2.1 or greater.
342 \item One or more Peak system PC CAN interface and the last Peak Real Time
343 Linux driver installed.
346 \subsubsection{Linux kernel node}
348 To do a CANopen node running on PC-Linux in kernel space, you need:
352 \item A working Linux distribution with pre-built 2.6.x.x kernel sources
353 \item A CAN card driver compatible with CanFestival
357 \subsubsection{CAN devices}
359 Currently supported CAN devices and corresponding configure switch:
362 \paragraph{Peak systems}
366 ./configure --can=peak_linux
370 PeakSystems CAN interface is automatically chosen as default CAN interface
371 if libpcan is present in the system.
373 Please download driver at \href{http://www.peak-system.com/linux}{http://www.peak
374 -system.com/linux} and follow instructions in order to install driver
378 \paragraph{Socket -Can (http://socketcan.berlios.de)}
382 ./configure --can=socket
389 ./configure --can=serial
392 The CAN serial driver implements a 1:1 serial connection between 2 CAN devices.
393 For example, you can connect 2 CANFestival applications via a NULL modem cable.
395 Also with this driver comes a software hub, for up to 16 CANFestival apps to
396 be connected on a single PC, with an optional connection to another CAN driver.
397 Note that only the serial driver is supported at this time. The hub uses ptys
398 (pseudo ttys) available on a *nix like system.
405 ./configure --can=lincan
409 \paragraph{Virtual CAN interfaces (for test/debug)}
413 ./configure --can=virtual
414 or, for kernel space:
415 ./configure --can=kernel_virtual
419 Virtual CAN interface use Unix pipes to emulate a virtual CAN network.
420 Each message issued from a node is repeat to all other nodes. Currently
421 only works with nodes running in the same process, and does not support
425 \subsection{Testing your CanFestival installation}
427 \subsection{User space}
429 Sample provided in /example/TestMasterSlave is installed into your
430 system during installation.
438 Default CAN driver library is libcanfestival\_can\_virtual.so., which
439 will simply pass CAN messages through Unix pipes between Master and
442 You may also want to specify different can interface and define some
443 CAN ports. Another example using Peak{\textquotesingle}s dual PCMCIA
444 (configure and install with --can=peak) :
448 TestMasterSlave -l libcanfestival_can_peak.so -s 40 -m 41
452 \subsection{Kernel space}
460 It's based on TestMasterSlave example
461 and has the same functionality. Uses virtual can driver as default
462 too. After successful installation you can insert the module by typing:
463 modprobe canf\_ktest Module control is done by simple console 'canf\_ktest\_console'
464 which is used to start/stop sending data.
467 \section{Windows Targets}
469 CanFestival can be compiled and run on Windows platform. It is possible
470 to use both Cygwin and win32 native runtime environment.
472 \subsection{Object Dictionary Editor GUI installation.}
474 Please refer to \hyperlink{a821UsingDictionaryEditorGUIoutline}{8.2.1)Using
475 Dictionary Editor GUI}
479 \subsubsection{Requirements}
481 Cygwin have to be installed with those packages :
489 Currently, the only supported CAN devices are PeakSystems ones, with
490 PcanLight driver and library.
492 Please download driver at \href{http://www.peak-system.com/themen/download_gb.html}{http://www.peak
493 -system.com/themen/download\_gb.html} \ and follow instructions
494 in order to install driver on your system.
496 Install Cygwin as required, and the driver for your Peak CAN device.
498 Open a Cygwin terminal, and follow those instructions:
501 \subsubsection{Cygwin configuration and compilation}
504 \paragraph{A single node with PcanLight and Peak CAN -USB adapter}
506 Download the PCAN-Light Zip file for your HW ( URL from download
511 wget http://www.peak -system.com/files/usb.zip
515 Extract its content into your cygwin home (it will create a {}``Disk''
524 Configure CanFestival3 providing path to the desired PcanLight implementation:
529 export PCAN_INCLUDE=~/Disk/PCAN-Light/Api/
530 export PCAN_HEADER=Pcan_usb.h
531 export PCAN_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_usb.lib
532 ./configure --can=peak_win32
537 In order to test, you have to use another CanFestival node, connect
542 cp ~/Disk/PCAN-Light/Pcan_usb.dll .
543 ./examples/TestMasterSlave/TestMasterSlave \
544 -l drivers/can\_peak\_win32/cygcan\_peak\_win32.dll \
549 Then, on the other node :
553 ./TestMasterSlave -l my_driver.so -S none -M 500K
557 Now messages are being exchanged between master and slave node.
559 \paragraph{Two nodes with PcanLight and Peak dual PCMCIA -CAN adapter}
561 Download the PCAN-Light Zip file for your HW ( URL from download
566 wget http://www.peak-system.com/files/pccard.zip
570 Extract its content into your cygwin home (it will create a {}``Disk''
579 The configure CanFestival3 providing path to the desired PcanLight
584 export PCAN_INCLUDE=~/Disk/PCAN-Light/Api/
585 export PCAN_HEADER=Pcan_pcc.h
586 export PCAN_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_pcc.lib
587 export PCAN2_HEADER=Pcan_2pcc.h
588 export PCAN2_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_2pcc.lib
592 In order to test, just connect together both CAN ports of the PCMCIA
593 card. Don{\textquotesingle}t forget 120ohms terminator.
597 cp ~/Disk/PCAN-Light/Pcan_pcc.dll .
598 cp ~/Disk/PCAN-Light/Pcan_2pcc.dll .
599 ./examples/TestMasterSlave/TestMasterSlave \
600 -l drivers/can_peak_win32/cygcan_peak_win32.dll
604 Messages are then exchanged between master and slave node, both inside
605 TestMasterSlave{\textquotesingle}s process.
607 \subsection{Visual Studio C++}
609 \subsubsection{Requirements}
611 Minimal Cygwin installation is required at configuration time in order
612 to create specific header files (config.h and cancfg.h). Once this
613 files created, cygwin is not necessary any more.
615 Project and solution files have been created and tested with Visual
616 Studio Express 2005. Be sure to have installed Microsoft Platform
617 SDK, as recommended at the end of Visual Studio installation.
620 \subsubsection{Configuration with cygwin}
622 Follow instructions given at \hyperlink{Cygwin configuration and compilation}{Cygwin
623 configuration and compilation}, but do neither call make nor do tests,
624 just do configuration steps. This will create headers files accordingly
625 to your configuration parameters, and the desired CAN hardware.
628 \subsubsection{Compilation with Visual Studio}
630 You can either load independent {}``{*}.vcproj'' project files
631 along your own projects in your own solution or load the provided
632 {}``CanFestival -3.vc8.sln'' solution files directly.
634 Build CanFestival -3 project first.
637 \paragraph{PcanLight and the can\_peak\_win32 project.}
639 Chosen Pcan\_xxx.lib and eventually Pcan\_2xxx.lib files must be added
640 to can\_peak\_win32 \ \ project before build of the DLL.
643 \subsubsection{Testing}
645 Copy eventually needed dlls (ie : Pcan\_Nxxx.lib) into Release or
646 Debug directory, and run the test program:
650 TestMasterSlave.exe -l can_peak_win32.dll
657 \subsubsection{Requirements}
659 Download from : http://sourceforge.net/project/showfiles.php?group\_id=2435
662 \item MSYS-1.0.10.exe
663 \item MinGW-5.1.3.exe
664 \item mingwPORT (which contains wget-1.9.1)
666 Please download driver at http://www.peak-system.com/themen/download\_gb.html
667 and follow instructions in order to install driver on your system.
668 Install MSYS and MingW as required, and the driver for your Peak CAN
669 device. Open a MSYS terminal, and follow those instructions:\\
673 \item extract wget-1.9.1-mingwPORT.tar.bz2
674 \item copy wget.exe in c:\textbackslash{} msys\textbackslash{} 1.0\textbackslash{}
676 \item start MSYS and check the file /etc/fstab contain the line c:/MinGW
680 \subsubsection{MSYS configuration and compilation}
682 Instructions for compilation are nearly the same as CYGWIN part.
685 \paragraph{A single node with PcanLight and Peak CAN-USB adapter}
687 Download the PCAN-Light Zip file for your HW ( URL from download page
691 wget http://www.peak-system.com/files/usb.zip
694 Extract its content into your MSYS's home (it will create a \char`\"{}
695 Disk\char`\"{} directory):
703 Configure CanFestival3 providing path to the desired PcanLight implementation:
707 export PCAN_INCLUDE=~/Disk/PCAN-Light/Api/
708 export PCAN_HEADER=Pcan_usb.h
709 export PCAN_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_usb.lib
710 ./configure --can=peak_win32
714 In order to test, you have to use another CanFestival node, connect
719 cp ~/Disk/PCAN-Light/Pcan_usb.dll .
720 ./examples/TestMasterSlave/TestMasterSlave \
721 -l drivers/can_peak_win32/cygcan_peak_win32.dll \
725 Then, on the other node :
728 ./TestMasterSlave -l my_driver.so -S none -M 500K -m 0
730 Now messages are being exchanged between master and slave node.
733 \paragraph{Two nodes with PcanLight and Peak dual PCMCIA-CAN adapter}
735 Download the PCAN-Light Zip file for your HW ( URL from download page
739 wget http://www.peak-system.com/files/pccard.zip
741 Extract its content into your MSYS's home (it will create a \char`\"{}
742 Disk\char`\"{} directory):
747 The configure CanFestival3 providing path to the desired PcanLight
751 export PCAN_INCLUDE=~/Disk/PCAN-Light/Api/
752 export PCAN_HEADER=Pcan_pcc.h}
753 export PCAN_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_pcc.lib
754 export PCAN2_HEADER=Pcan_2pcc.h
755 export PCAN2_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_2pcc.lib
758 In order to test, just connect together both CAN ports of the PCMCIA
759 card. Don't forget 120ohms terminator.
762 cp~/Disk/PCAN-Light/Pcan_pcc.dll ~.
763 cp ~/Disk/PCAN-Light/Pcan_2pcc.dll ~.
764 ./examples/TestMasterSlave/TestMasterSlave \
765 -l drivers/can\_peak\_win32/cygcan\_peak\_win32.dll -m 0 -s 1
767 Messages are then exchanged between master and slave node, both inside
768 TestMasterSlave's process.
770 \section{Motorola HCS12}
772 The examples have been tested on a MC9S12DG255 mounted on a Elektronikladen
775 Beware that there are few differences in the MSCAN module of the 68HC12
776 and HCS12 microcontroller. For a HC12, you must adapt the driver that
777 we provide for \ the HCS12.
779 For the difference MSCAN HC12/HCS12, see the Motorola application
788 To do a \canopen node running on a microncontroller Motorola MC9S12DP256,
792 \item The compiler GNU gcc for HC11, HC12, HCS12 : m6811 -elf. \\
793 Download the \textbf{release 3.1} at : \href{http://m68hc11.serveftp.org/m68hc11_pkg_rpm.php}{http://m68hc11.serveftp.org/m68hc11\_pkg\_rpm.php}
794 \item A board with this chip. We are using the T -board from Electronikladen.
795 \item At least about 40 kBytes of program memory.
796 \item A tool to flash the memory. (We are using the high cost Lauterbach
800 \subsection{Running a HCS12 node}
803 \subsubsection{Compiling Canfestival:}
806 ./configure --target=hcs12
810 \subsubsection{Compiling and building an example}
812 Enter in the folder of an HCS12 example,
819 \subsubsection{Flashing the memory :}
821 Use your preferred loader ! If you are using a debugger Lauterbach,
822 you can load the bash file : trace32\_flash\_programmer.cmm. It loads
823 directly the elf file.
826 \subsubsection{Connecting to a serial RS232 console :}
828 Connect the portS(TxD0) of the HCS12 to a console configured at 19200
829 bauds 8N1, via a Max232 chip to adapt the electrical levels. On Linux,
830 you can use minicom. Connecting to a console is useful to read the
831 messages, but not required.
834 \subsubsection{Connecting to the CAN network :}
836 Connect the port CAN0 (pin PM0, PM1) to the network via a CAN controller.
837 On our board, the CAN controller is a PCA82C250 chip.
840 \subsubsection{starting the node :}
842 Press the reset of your HCS12 board.
845 \section{Example and test program:}
847 The {}``examples'' directory contains some test program you can
848 use as example for your own developments.
851 \subsection{TestMasterSlave}
855 **************************************************************
858 * A simple example for PC. It does implement 2 CanOpen *
859 * nodes in the same process. A master and a slave. Both *
860 * communicate together, exchanging periodically NMT, SYNC, *
861 * SDO and PDO. Master configure heartbeat producer time *
862 * at 1000 ms for slave node-id 0x02 by concise DCF. *
865 * ./TestMasterSlave [OPTIONS] *
868 * -l : Can library ["libcanfestival_can_virtual.so"] *
871 * -s : bus name ["0"] *
872 * -S : 1M,500K,250K,125K,100K,50K,20K,10K,none(disable) *
875 * -m : bus name ["1"] *
876 * -M : 1M,500K,250K,125K,100K,50K,20K,10K,none(disable) *
878 **************************************************************
882 Notes aboute use of voncise DCF :
884 In this example, Master configure heartbeat producer time
885 at 1000 ms for slave node -id 0x02 by concise DCF according DS -302
888 Index 0x1F22, sub-index 0x00 of the master OD, correspond
889 to the number of entries. This equal to the maximum possible nodeId
890 (127). Each sub -index points to the Node -ID of the device, to which
891 the configuration belongs.
893 To add more parameters configurations to the slave, the value
894 at sub -index 0x02 must be a binary stream (little -endian) following
900 (UNS32) nb of entries
901 (UNS16) index parameter 1
902 (UNS8) sub -index parameter 1
903 (UNS32) size data parameter 1
904 (DOMAIN) data parameter 1
905 (UNS16) index parameter 2
906 (UNS8) sub -index parameter 2
907 (UNS32) size data parameter 2
908 (DOMAIN) data parameter 2
910 (UNS16) index parameter n
911 (UNS8) sub -index parameter n
912 (UNS32) size data parameter n
913 (DOMAIN) data parameter n
918 So the binary value stream to configure heartbeat producer
923 0100000017100002000000e803
927 The slave node is configured just before the Master entering
928 in Pre\_operational state.
931 \subsection{gene\_SYNC\_HCS12 :}
933 This is a simple \canopen node that only send cyclic SYNC message.
934 It demonstrate implementation on HCS12 based board.
940 \subsection{kerneltest :}
942 Example based on TestMasterSlave slightly modified to suit kernel
943 space requisites. It will do the same as TestMasterSlave but in kernel
944 space sending kernel messages (displayed by dmesg for example). It
945 is designed as external kernel module implemented as character device.
946 There is a shell script called 'insert.sh', which will insert the
947 module and create a new device file /dev/canf\_ktest (used to sending
948 commands to module). To actual sending commands you can use simple
949 console named 'canf\_ktest\_console'. The module is dependent on a
950 another separate module 'canfestival.ko' implementing CanOpen stack
951 which exports requisite functions. Canfestival.ko module is then dependent
952 on CAN card driver module, by default CAN virtual driver will be loaded.
953 After installing modules (make install), all dependencies are solved
954 automatically by kernel. To run the example type:
958 It will insert required modules, start console, and after quitting
959 console it'll remove modules from kernel.
965 \subsection{TestMasterMicroMod }
970 **************************************************************
971 * TestMasterMicroMod *
973 * A simple example for PC. *
974 * A CanOpen master that control a MicroMod module: *
975 * - setup module TPDO 1 transmit type *
976 * - setup module RPDO 1 transmit type *
977 * - setup module hearbeatbeat period *
978 * - disable others TPDOs *
979 * - set state to operational *
980 * - send periodic SYNC *
981 * - send periodic RPDO 1 to Micromod (digital output) *
982 * - listen Micromod's TPDO 1 (digital input) *
983 * - Mapping RPDO 1 bit per bit (digital input) *
986 * ./TestMasterMicroMod [OPTIONS] *
989 * -l : Can library ["libcanfestival_can_virtual.so"] *
992 * -i : Slave Node id format [0x01 , 0x7F] *
995 * -m : bus name ["1"] *
996 * -M : 1M,500K,250K,125K,100K,50K,20K,10K *
998 **************************************************************
1002 \section{Developing a new node}
1004 Using provided examples as a base for your new node is generally a
1005 good idea. You can also use the provided {*}.od files as a base for
1006 your node object dictionary.
1008 Creating a new \canopen node implies to define the Object Dictionary
1009 of this node. For that, developer has to provide a C file. This C
1010 file contains the definition of all dictionary entries, and some kind
1011 of index table that helps the stack to access some entries directly.
1014 \subsection{Using Dictionary Editor GUI}
1016 The Object Dictionary Editor is a WxPython based GUI that is used
1017 to create the C file needed to create a new \canopen node.
1020 \subsubsection{Installation and usage on Linux}
1022 You first have to download and install Gnosis XML modules. This is
1023 automated by a Makefile rule.
1030 Now start the editor.
1033 python objdictedit.py [od files...]
1037 \subsubsection{Installation and usage on Windows}
1039 Install Python (at least version 2.4) and wxPython (at least version
1042 Cygwin users can install Gnosis XML utils the same as Linux use. Just
1050 Others will have to download and install Gnosis XML by hand :
1054 http://freshmeat.net/projects/gnosisxml/
1055 http://www.gnosis.cx/download/
1059 Download CanFestival archive and uncompress it. Use windows file explorer
1060 to go into CanFestival3\textbackslash{}objdicgten, and double -click
1063 \subsubsection{About}
1065 The Object Dictionary editor GUI is a python application that use
1066 the Model-View-Controller design pattern. It depends on WxPython to
1067 display view on any supported platform.
1070 \includegraphics[width=7cm]{Pictures/10000201000001FC000001E5D65E8766}
1074 \subsubsection{Main view}
1076 Top list let you choose dictionary section, bottom left list is the
1077 selected index in that dictionary, and bottom right list are edited
1081 \includegraphics[width=12cm]{Pictures/10000201000003E7000001C7B0296577}
1085 \includegraphics[width=3cm]{Pictures/10000000000000B6000000DF1EDD1E73}
1089 \includegraphics[width=3cm]{Pictures/10000000000000AC000000C9C3F53FA6}
1093 \includegraphics[width=3cm]{Pictures/100000000000006D000000A31EC8CB54}
1097 \includegraphics[width=3cm]{Pictures/10000000000000AA0000006014F74635}
1101 \subsubsection{New node}
1103 Edit your node name and type. Choose your inherited specific profile.
1106 \includegraphics[width=11cm]{Pictures/new_node}
1110 \subsubsection{Node info}
1112 Edit your node name and type.
1115 \includegraphics[width=7cm]{Pictures/node_info}
1119 \subsubsection{Profile editor}
1121 Chose the used profile to edit.
1124 \includegraphics[width=4cm]{Pictures/10000000000000AB000000C88F594413}
1127 Pick up optional chosen profile entries.
1130 \includegraphics[width=11cm]{Pictures/10000201000002DE000001D82D89C224}
1134 \subsubsection{User types}
1136 Use User Types to implement value boundaries, and string length
1139 \includegraphics[width=11cm]{Pictures/10000201000001C40000010766961D7F}
1143 \subsubsection{Mapped variable}
1145 Add your own specific dictionary entries and associated mapped variables.
1148 \includegraphics[width=11cm]{Pictures/10000201000001C4000000DD129D4661}
1152 \subsubsection{Integrated help}
1154 Using F1 key, you can get context sensitive help.
1157 \includegraphics[width=12cm]{Pictures/10000201000002F30000020B23ED7F67}
1160 In order to do that, official 301\_v04000201.pdf file must be placed
1161 into doc/ directory, and xpdf must be present on your system.
1163 F2 key open HTML CanFestival help.
1166 \includegraphics[width=12cm]{Pictures/10000201000003440000025ACC3FD2F1}
1170 \subsection{Generating the object Dictionary}
1172 Once object dictionary has been edited and saved, you have to generate
1173 object dictionary C code for your CanFestival node.
1176 \subsubsection{With GUI}
1178 Menu entry {}``File/Build Dictionary''.
1181 \includegraphics[width=4cm]{Pictures/10000201000000B7000000C66AF89CD5}
1184 Choose C file to create or overwrite. Header file will be also created
1185 with the same prefix as C file.
1188 \subsubsection{With command line}
1191 Usage of objdictgen.py :
1192 python objdictgen.py XMLFilePath CfilePath
1200 \subsection{General}
1203 \subsubsection{Does the code compiles on Windows ?}
1205 Yes, with both Cygwin and Visual Studio C++.
1207 Because \canopen layer is coded with C, put a compilation option
1208 /TC or /TP if you plan to mix C++ files. See the MSDN documentation
1212 \subsubsection{How to fit the library to an other microcontr�ler ?}
1214 First, be sure that you have at least 40K bytes of program memory,
1215 and about 2k of RAM.
1217 You have to create target specific interface to HW resources. Take
1218 model on bundled interfaces provided in drivers/ and create your own
1219 interface. You also have to update Makefile.in files for target specific
1220 cflags and options. Choose {--}target= configure switch to compile
1221 your specific interface.
1223 You are welcome to contribute -back your own interfaces! Other Canfestival
1224 users will use it and provide feedback, tests and enhancements.
1227 \subsubsection{Is CanFestival3 conform to DS301 v.4.02 ?}
1229 Thanks to Philippe Foureys (IUT of Valence), a slave node have been
1230 tested with the National Instrument \canopen Conformance Test. It
1231 passed the test with success.
1233 Some very small unconformity have been found in very unusual situations,
1234 for example in the SDO code response to wrong messages.
1240 \subsubsection{How to use a Peaksystem CAN board ?}
1242 Just install peak driver and then compile and install Canfestival.
1243 Peak driver is detected at compile time.
1246 \subsubsection{How to use an unsupported CAN board ?}
1248 You have to install the specific driver on your system, with necessary
1251 Use can\_peak.c/h or can\_virtual.c/h as an example, and adapt it
1254 Execute configure script and choose --can=mydriver
1262 \item Code was compiled MS VisualStudio 2003.NET and VisualStudio 2005.NET
1263 for WindowsXP \ with ANSI and UNICODE configurations and for WindowsCE
1265 \item Some preliminary testing was done, but not enough to be used in mission
1268 Additional Features:
1271 \item Non -integral integers support implementation UNS24, UNS40, UNS48
1273 \item When enable debug output with DEBUG\_WAR\_CONSOLE\_ON or DEBUG\_ERR\_CONSOLE\_ON,
1274 you can navigate in CanFestival source code by double clicking at
1275 diagnostic lines in VisualStudio.NET 200X Debug Output Window.
1277 Custom size integral types such as INTEGER24, UNS40, INTEGER56 etc.
1278 have been defined as 64 bits integers. You will need to replace sizeof(TYPE)
1279 operators to sizeof\_TYPE definitions in generated code, i.e. replace
1280 sizeof(UNS40) with sizeof\_UNS40.
1286 \subsubsection{Which board are you using ?}
1288 A T -board from elektronikladen with a MC9S12DP256 or MC9S12DG256.
1291 \subsubsection{Does the code compile with an other compiler than GNU gcc ?}
1293 It is known to work with Metrowerks CodeWarrior. Here are some tips
1294 from Philippe Foureys. :
1297 \paragraph{Interrupt functions}
1300 \subparagraph{Code for GCC:
1306 void __attribute__((interrupt))timer3Hdl(void):
1308 void __attribute__((interrupt))timer3Hdl(void){...}
1312 \subparagraph{Code for CodeWarrior
1318 void interrupt timer3Hdl(void);
1320 pragma CODE_SEG__NEAR_SEG_NON_BANKED
1321 void interrupt timer3Hdl(void)
1323 pragma CODE_SEG_DEFAULT\end{verbatim}
1326 \paragraph{Interrupt lock, unlock
1330 \subparagraph{Code for GCC
1337 __asm__ __volatile__("cli");
1341 unsigned short mask;
1342 __asm__ __volatile__("tpa\n\tsei":"=d"(mask));
1347 \subparagraph{Code for CodeWarrior}
1357 unsigned short mask;
1360 tpa:tsei:"=d"(mask);
1366 \paragraph{Initialize function}
1369 \subparagraph{Code for GCC}
1373 void initCanHCS12 (void)
1375 //Init the HCS12 microcontroler for CanOpen
1377 // Init the HCS12 CAN driver
1378 const canBusInit bi0 = {
1379 0, /* no low power */
1380 0, /* no time stamp */
1381 1, /* enable MSCAN */
1382 0, /* clock source : oscillator (In fact, it is not used) */
1383 0, /* no loop back */
1384 0, /* no listen only */
1385 0, /* no low pass filter for wk up */
1386 CAN_Baudrates[CAN_BAUDRATE_250K],
1388 0x00, /* Filter on 16 bits.
1389 See Motorola Block Guide V02.14 fig 4-3 */
1390 0x00, 0xFF, /* filter 0 hight accept all msg */
1391 0x00, 0xFF, /* filter 0 low accept all msg */
1392 0x00, 0xFF, /* filter 1 hight filter all of msg */
1393 0x00, 0xFF, /* filter 1 low filter all of msg */
1394 0x00, 0xFF, /* filter 2 hight filter most of msg */
1395 0x00, 0xFF, /* filter 2 low filter most of msg */
1396 0x00, 0xFF, /* filter 3 hight filter most of msg */
1397 0x00, 0xFF, /* filter 3 low filter most of msg */
1403 \subparagraph{Code for CodeWarrior
1408 void initCanHCS12 (void)
1410 //Init the HCS12 microcontroler for CanOpen
1412 // Init the HCS12 CAN driver
1413 const canBusInit bi0 = {
1414 0, /* no low power */
1415 0, /* no time stamp */
1416 1, /* enable MSCAN */
1417 0, /* clock source : oscillator (In fact, it is not used) */
1418 0, /* no loop back */
1419 0, /* no listen only */
1420 0, /* no low pass filter for wk up */
1430 0x00, /* Filter on 16 bits.
1431 See Motorola Block Guide V02.14 fig 4-3 */
1432 0x00, 0xFF, /* filter 0 hight accept all msg */
1433 0x00, 0xFF, /* filter 0 low accept all msg */
1434 0x00, 0xFF, /* filter 1 hight filter all of msg */
1435 0x00, 0xFF, /* filter 1 low filter all of msg */
1436 0x00, 0xFF, /* filter 2 hight filter most of msg */
1437 0x00, 0xFF, /* filter 2 low filter most of msg */
1438 0x00, 0xFF, /* filter 3 hight filter most of msg */
1439 0x00, 0xFF, /* filter 3 low filter most of msg */
1445 \subsubsection{Does the code works in banked memory ?}
1447 No. Today it seems that the port of gcc is bogged for using the banked
1448 memory. So, unfortunately, we are limited to 48 Kbytes of memory code.
1451 \subsubsection{What GCC version are you using ?}
1453 We are using the stable RPM release 2.2 :
1456 \item GNU Gcc 3.0.4. Build 20030501
1457 \item Newlib 1.10.0 Build 20030421
1458 \item GNU Binutils 2.12.1 Build 20030427
1461 \section{Documentation resources}
1464 \subsection{CIA : Can in Automation }
1466 \href{http://www.can-cia.de/}{http://www.can -cia.de}
1469 \subsection{Resources and training in \canopen
1472 \href{http://www.esacademy.com/}{http://www.esacademy.com}
1475 \subsection{Elektronikladen HCS12 T -board }
1477 \href{http://www.elektronikladen.de/en_hcs12tb.html}{http://www.elektronikladen.de/en\_hcs12tb.html}
1480 \subsection{Gnu gcc compiler for HC12 }
1482 \href{http://m68hc11.serveftp.org/m68hc11_port.php}{http://m68hc11.serveftp.org/m68hc11\_port.php}
1485 \subsection{Motorola documentation on HC12 }
1487 \href{http://www.freescale.com/webapp/sps/site/prod_summary.jsp?code=MC9S12DP256}{http://www.freescale.com/webapp/sps/site/prod\_summary.jsp?code=MC9S12DP256}
1490 \subsection{Lauterbach debugger for HC12 }
1492 \href{http://www.lauterbach.com/}{http://www.lauterbach.com}
1495 \subsection{Python language }
1497 \href{http://www.python.org/}{http://www.python.org}
1502 \section{About the project}
1505 \subsection{Contributors }
1508 \includegraphics[width=10cm]{Pictures/1000020100000258000000832C6FFAB4}
1511 Unit� mixte de recherche INRETS -LCPC
1513 sur les Interractions V�hicule -Infrastructure -Conducteur
1515 14, route de la mini�re
1521 Tel : +33 1 40 43 29 01
1523 \href{http://www.inrets.fr/ur/livic}{http://www.inrets.fr/ur/livic}
1525 \textbf{Contributors :} Francis DUPIN
1535 \includegraphics[width=10cm]{Pictures/100002010000013A0000004A96B0C1FF}
1540 204, rue du Haut du Pin
1542 88470 Saint -Michel sur Meurthe
1546 Tel : +33 3 29 52 95 67
1548 \href{http://www.lolitech.fr/}{http://www.lolitech.fr}
1550 \textbf{Contributors :} Edouard TISSERANT (Original author)
1557 Many thanks to the other contributors for their great work:
1561 David DUMINY (st� A6R)
1566 \subsection{Getting support}
1568 Send your feedback and bug reports to \href{mailto:canfestival-devel@lists.sourceforge.net}{canfestival-devel@lists.sourceforge.net}.
1570 For commercial support, \ training and specific integration and developments,
1571 please ask LOLITECH (see contributors).
1574 \subsection{Contributing}
1576 You are free to contribute your specific interfaces back to the project.
1577 This way, you can hope to get support from CanFestival users community.
1579 Please send your patch to \href{mailto:canfestival-devel@lists.sourceforge.net}{canfestival
1580 -devel@lists.sourceforge.net}.
1582 Feel free to create some new predefined DS -4xx profiles ({*}.prf)
1583 in objdictgen/config, as much as possible respectful to the official
1587 \subsection{License}
1589 All the project is licensed with LGPL. This mean you can link CanFestival
1590 with any code without being obliged to publish it.
1594 #This file is part of CanFestival, a library implementing CanOpen Stack.
1596 #Copyright (C): Edouard TISSERANT, Francis DUPIN and Laurent BESSARD
1598 #See COPYING file for copyrights details.
1600 #This library is free software; you can redistribute it and/or
1601 #modify it under the terms of the GNU Lesser General Public
1602 #License as published by the Free Software Foundation; either
1603 #version 2.1 of the License, or (at your option) any later version.
1605 #This library is distributed in the hope that it will be useful,
1606 #but WITHOUT ANY WARRANTY; without even the implied warranty of
1607 #MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1608 #Lesser General Public License for more details.
1610 #You should have received a copy of the GNU Lesser General Public
1611 #License along with this library; if not, write to the Free Software
1612 #Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA