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)
162 \subsection{How to get CanFestival}
164 Please always use CVS, this is the best way to get the most reactive
165 support from the developer community :
169 cvs -d:pserver:anonymous@lolitech.dyndns.org:/canfestival login
172 (type return, without entering a password)
177 cvs -z3 -d:pserver:anonymous@lolitech.dyndns.org:/canfestival co -P CanFestival-3
182 \section{Understanding Canfestival}
184 \subsection{CanFestival Project tree layout}
185 Simplified directory structure.
187 ./src ANSI-C source of \canopen stack
188 ./include Exportables Header files
189 ./drivers Interfaces to specific platforms/HW
190 ./drivers/unix Linux and Cygwin OS interface
191 ./drivers/win32 Native Win32 OS interface
192 ./drivers/timers_xeno Xenomai timers/threads (Linux only)
193 ./drivers/timers_rtai Rtai 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/can_vcom VScom VSCAN interface
203 ./drivers/hcs12 HCS12 full target interface
205 ./examples/TestMasterSlave 2 nodes, NMT SYNC SDO PDO, win32+unix
206 ./examples/TestMasterMicroMod 1 node, control Peak I/O Module, unix
207 ./examples/gene_SYNC_HCS12 Just send periodic SYNC on HCS12
208 ./examples/win32test Ask some DS301 infos to a node (win32)
209 ./objdictgen Object Dictionary editor GUI
210 ./objdictgen/config Pre-defined OD profiles
211 ./objdictgen/examples Some examples/test OD
212 ./doc Documentation source
217 \subsection{Implement CanFestival in your application}
220 \includegraphics[width=12cm]{Pictures/10000201000003F9000002CF880931E7}
227 \subsection{CanFestival CAN interfaces}
229 Because most CAN controllers and drivers implement FIFOs, CanFestival
230 consider sending message as a non blocking operation.
232 In order to prevent reentrant calls to the stack, messages reception
233 is implemented differently on {\textmu}C and OS.:
236 \item {\textmu}C must provide interruption masking, mutually excluding timer and CAN receive interrupts.\\
241 \includegraphics[width=12cm]{Pictures/10000201000003CA0000016604E6A5EF}
244 \item OS must provide a receive thread, a timer thread and a mutex. CAN
245 reception should be a blocking operation.\\
250 \includegraphics[width=12cm]{Pictures/10000201000003F9000002CF8B0CDAEA}
255 \subsection{CanFestival event scheduling}
257 A \canopen node must be able to take delayed actions.
259 For instance, periodic sync emission, heartbeat production or SDO timeout
260 need to set some alarms that will be called later and do the job.
262 {\textmu}C generally do not have enough free timers to handle all
263 the \canopen needs directly. Moreover, CanFestival internal data
264 may be corrupt by reentrant calls.
266 CanFestival implement a micro -scheduler (timer.c). It uses only one
267 timer to mimic many timers. It manage an alarm table, and call alarms
271 \includegraphics[width=12cm]{Pictures/100000000000022C000000DEDAD2140C}
274 Scheduler can handle short clock value ranges limitation found on
275 some {\textmu}C. As an example, value range for a 16bit clock counter
276 with 4{\textmu}s tick is crossed within 0.26 seconds... Long alarms
279 Chronogram illustrate a long alarm (A) and a short periodic alarm
280 (B), with a A value {\textgreater} clock range {\textgreater}
281 B value. Values t0...t8 are successive setTimer call parameter values.
282 t1 illustrates an intermediate call to TimeDispatch, caused by a delay
283 longer than clock range. Because of long alarm segmentation, at the
284 end of t1, TimeDispatch call will not trig any alarm callback.
287 \includegraphics[width=12cm]{Pictures/1000000000000396000000FFC42573DA}
291 \section{Linux Target}
293 Linux target is default configure target.
296 \subsection{Linux Compilation and installation}
298 Call ./configure -- help to see all available compile time options.
300 After invoking ./configure with your platform specific switches, just
306 ./configure [options]
314 \subsubsection{Standard Linux node}
318 ./configure --timers=unix
322 To do a \canopen node running on PC -Linux, you need :
325 \item A working linux distribution
326 \item One or more Peak system PC CAN interface and the last Peak Linux driver
330 \subsubsection{Real -Time Linux node}
334 ./configure --timers=xeno
338 ./configure --timers=rtai
341 To do a \canopen node running on PC -Linux, you need :
344 \item A working Linux distribution patched with XENOMAI (2.1 or greater) or RTAI (3.6).
345 \item One or more Peak system PC CAN interface and the last Peak Real Time
346 Linux driver installed.
349 \subsubsection{Linux kernel node}
351 To do a CANopen node running on PC-Linux in kernel space, you need:
355 \item A working Linux distribution with pre-built 2.6.x.x kernel sources
356 \item A CAN card driver compatible with CanFestival
360 \subsubsection{CAN devices}
361 Currently supported CAN devices and corresponding configure switch:
363 \paragraph{Peak systems}
365 ./configure --can=peak_linux
367 PeakSystems CAN interface is automatically chosen as default CAN interface
368 if libpcan is present in the system.
370 Please download driver at \href{http://www.peak-system.com/linux}{http://www.peak
371 -system.com/linux} and follow instructions in order to install driver
374 \paragraph{Socket-Can (http://socketcan.berlios.de)}
376 ./configure --can=socket
381 ./configure --can=serial
383 The CAN serial driver implements a 1:1 serial connection between 2 CAN devices.
384 For example, you can connect 2 CANFestival applications via a NULL modem cable.
386 Also with this driver comes a software hub, for up to 16 CANFestival apps to
387 be connected on a single PC, with an optional connection to another CAN driver.
388 Note that only the serial driver is supported at this time. The hub uses ptys
389 (pseudo ttys) available on a *nix like system.
393 ./configure --can=lincan
396 \paragraph{Virtual CAN interfaces (for test/debug)}
398 ./configure --can=virtual
399 or, for kernel space:
400 ./configure --can=kernel_virtual
402 Virtual CAN interface use Unix pipes to emulate a virtual CAN network.
403 Each message issued from a node is repeat to all other nodes. Currently
404 only works with nodes running in the same process, and does not support
405 work with Xenomai or RTAI.
409 ./configure --can=vscom
411 The VSCAN API archive will be automatically downloaded and decompressed (unzip required). See \href{http://www.vscom.de/1_1_05.htm}{www.vscom.de} for available adapters.
412 \subsection{Testing your CanFestival installation}
414 \subsection{User space}
416 Sample provided in /example/TestMasterSlave is installed into your
417 system during installation.
425 Default CAN driver library is libcanfestival\_can\_virtual.so., which
426 will simply pass CAN messages through Unix pipes between Master and
429 You may also want to specify different can interface and define some
430 CAN ports. Another example using Peak{\textquotesingle}s dual PCMCIA
431 (configure and install with --can=peak) :
435 TestMasterSlave -l libcanfestival_can_peak.so -s 40 -m 41
439 \subsection{Kernel space}
447 It's based on TestMasterSlave example
448 and has the same functionality. Uses virtual can driver as default
449 too. After successful installation you can insert the module by typing:
450 modprobe canf\_ktest Module control is done by simple console 'canf\_ktest\_console'
451 which is used to start/stop sending data.
454 \section{Windows Targets}
456 CanFestival can be compiled and run on Windows platform. It is possible
457 to use both Cygwin and win32 native runtime environment.
459 \subsection{Object Dictionary Editor GUI installation.}
461 Please refer to \hyperlink{a821UsingDictionaryEditorGUIoutline}{8.2.1)Using
462 Dictionary Editor GUI}
466 \subsubsection{Requirements}
468 Cygwin have to be installed with those packages :
476 Currently, the only supported CAN devices are PeakSystems ones, with
477 PcanLight driver and library.
479 Please download driver at \href{http://www.peak-system.com/themen/download_gb.html}{http://www.peak
480 -system.com/themen/download\_gb.html} \ and follow instructions
481 in order to install driver on your system.
483 Install Cygwin as required, and the driver for your Peak CAN device.
485 Open a Cygwin terminal, and follow those instructions:
488 \subsubsection{Cygwin configuration and compilation}
491 \paragraph{A single node with PcanLight and Peak CAN -USB adapter}
493 Download the PCAN-Light Zip file for your HW ( URL from download
498 wget http://www.peak -system.com/files/usb.zip
502 Extract its content into your cygwin home (it will create a {}``Disk''
511 Configure CanFestival3 providing path to the desired PcanLight implementation:
516 export PCAN_INCLUDE=~/Disk/PCAN-Light/Api/
517 export PCAN_HEADER=Pcan_usb.h
518 export PCAN_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_usb.lib
519 ./configure --can=peak_win32
524 In order to test, you have to use another CanFestival node, connect
529 cp ~/Disk/PCAN-Light/Pcan_usb.dll .
530 ./examples/TestMasterSlave/TestMasterSlave \
531 -l drivers/can\_peak\_win32/cygcan\_peak\_win32.dll \
536 Then, on the other node :
540 ./TestMasterSlave -l my_driver.so -S none -M 500K
544 Now messages are being exchanged between master and slave node.
546 \paragraph{Two nodes with PcanLight and Peak dual PCMCIA -CAN adapter}
548 Download the PCAN-Light Zip file for your HW ( URL from download
553 wget http://www.peak-system.com/files/pccard.zip
557 Extract its content into your cygwin home (it will create a {}``Disk''
566 The configure CanFestival3 providing path to the desired PcanLight
571 export PCAN_INCLUDE=~/Disk/PCAN-Light/Api/
572 export PCAN_HEADER=Pcan_pcc.h
573 export PCAN_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_pcc.lib
574 export PCAN2_HEADER=Pcan_2pcc.h
575 export PCAN2_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_2pcc.lib
579 In order to test, just connect together both CAN ports of the PCMCIA
580 card. Don{\textquotesingle}t forget 120ohms terminator.
584 cp ~/Disk/PCAN-Light/Pcan_pcc.dll .
585 cp ~/Disk/PCAN-Light/Pcan_2pcc.dll .
586 ./examples/TestMasterSlave/TestMasterSlave \
587 -l drivers/can_peak_win32/cygcan_peak_win32.dll
591 Messages are then exchanged between master and slave node, both inside
592 TestMasterSlave{\textquotesingle}s process.
594 \subsection{Visual Studio C++}
596 \subsubsection{Requirements}
598 Minimal Cygwin installation is required at configuration time in order
599 to create specific header files (config.h and cancfg.h). Once this
600 files created, cygwin is not necessary any more.
602 Project and solution files have been created and tested with Visual
603 Studio Express 2005. Be sure to have installed Microsoft Platform
604 SDK, as recommended at the end of Visual Studio installation.
607 \subsubsection{Configuration with cygwin}
609 Follow instructions given at \hyperlink{Cygwin configuration and compilation}{Cygwin
610 configuration and compilation}, but do neither call make nor do tests,
611 just do configuration steps. This will create headers files accordingly
612 to your configuration parameters, and the desired CAN hardware.
615 \subsubsection{Compilation with Visual Studio}
617 You can either load independent {}``{*}.vcproj'' project files
618 along your own projects in your own solution or load the provided
619 {}``CanFestival -3.vc8.sln'' solution files directly.
621 Build CanFestival -3 project first.
624 \paragraph{PcanLight and the can\_peak\_win32 project.}
626 Chosen Pcan\_xxx.lib and eventually Pcan\_2xxx.lib files must be added
627 to can\_peak\_win32 \ \ project before build of the DLL.
630 \subsubsection{Testing}
632 Copy eventually needed dlls (ie : Pcan\_Nxxx.lib) into Release or
633 Debug directory, and run the test program:
637 TestMasterSlave.exe -l can_peak_win32.dll
644 \subsubsection{Requirements}
646 Download from : http://sourceforge.net/project/showfiles.php?group\_id=2435
649 \item MSYS-1.0.10.exe
650 \item MinGW-5.1.3.exe
651 \item mingwPORT (which contains wget-1.9.1)
653 Please download driver at http://www.peak-system.com/themen/download\_gb.html
654 and follow instructions in order to install driver on your system.
655 Install MSYS and MingW as required, and the driver for your Peak CAN
656 device. Open a MSYS terminal, and follow those instructions:\\
660 \item extract wget-1.9.1-mingwPORT.tar.bz2
661 \item copy wget.exe in c:\textbackslash{} msys\textbackslash{} 1.0\textbackslash{}
663 \item start MSYS and check the file /etc/fstab contain the line c:/MinGW
667 \subsubsection{MSYS configuration and compilation}
669 Instructions for compilation are nearly the same as CYGWIN part.
672 \paragraph{A single node with PcanLight and Peak CAN-USB adapter}
674 Download the PCAN-Light Zip file for your HW ( URL from download page
678 wget http://www.peak-system.com/files/usb.zip
681 Extract its content into your MSYS's home (it will create a \char`\"{}
682 Disk\char`\"{} directory):
690 Configure CanFestival3 providing path to the desired PcanLight implementation:
694 export PCAN_INCLUDE=~/Disk/PCAN-Light/Api/
695 export PCAN_HEADER=Pcan_usb.h
696 export PCAN_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_usb.lib
697 ./configure --can=peak_win32
701 In order to test, you have to use another CanFestival node, connect
706 cp ~/Disk/PCAN-Light/Pcan_usb.dll .
707 ./examples/TestMasterSlave/TestMasterSlave \
708 -l drivers/can_peak_win32/cygcan_peak_win32.dll \
712 Then, on the other node :
715 ./TestMasterSlave -l my_driver.so -S none -M 500K -m 0
717 Now messages are being exchanged between master and slave node.
720 \paragraph{Two nodes with PcanLight and Peak dual PCMCIA-CAN adapter}
722 Download the PCAN-Light Zip file for your HW ( URL from download page
726 wget http://www.peak-system.com/files/pccard.zip
728 Extract its content into your MSYS's home (it will create a \char`\"{}
729 Disk\char`\"{} directory):
734 The configure CanFestival3 providing path to the desired PcanLight
738 export PCAN_INCLUDE=~/Disk/PCAN-Light/Api/
739 export PCAN_HEADER=Pcan_pcc.h}
740 export PCAN_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_pcc.lib
741 export PCAN2_HEADER=Pcan_2pcc.h
742 export PCAN2_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_2pcc.lib
745 In order to test, just connect together both CAN ports of the PCMCIA
746 card. Don't forget 120ohms terminator.
749 cp~/Disk/PCAN-Light/Pcan_pcc.dll ~.
750 cp ~/Disk/PCAN-Light/Pcan_2pcc.dll ~.
751 ./examples/TestMasterSlave/TestMasterSlave \
752 -l drivers/can\_peak\_win32/cygcan\_peak\_win32.dll -m 0 -s 1
754 Messages are then exchanged between master and slave node, both inside
755 TestMasterSlave's process.
757 \section{Motorola HCS12}
759 The examples have been tested on a MC9S12DG255 mounted on a Elektronikladen
762 Beware that there are few differences in the MSCAN module of the 68HC12
763 and HCS12 microcontroller. For a HC12, you must adapt the driver that
764 we provide for \ the HCS12.
766 For the difference MSCAN HC12/HCS12, see the Motorola application
775 To do a \canopen node running on a microncontroller Motorola MC9S12DP256,
779 \item The compiler GNU gcc for HC11, HC12, HCS12 : m6811 -elf. \\
780 Download the \textbf{release 3.1} at : \href{http://m68hc11.serveftp.org/m68hc11_pkg_rpm.php}{http://m68hc11.serveftp.org/m68hc11\_pkg\_rpm.php}
781 \item A board with this chip. We are using the T -board from Electronikladen.
782 \item At least about 40 kBytes of program memory.
783 \item A tool to flash the memory. (We are using the high cost Lauterbach
787 \subsection{Running a HCS12 node}
790 \subsubsection{Compiling Canfestival:}
793 ./configure --target=hcs12
797 \subsubsection{Compiling and building an example}
799 Enter in the folder of an HCS12 example,
806 \subsubsection{Flashing the memory :}
808 Use your preferred loader ! If you are using a debugger Lauterbach,
809 you can load the bash file : trace32\_flash\_programmer.cmm. It loads
810 directly the elf file.
813 \subsubsection{Connecting to a serial RS232 console :}
815 Connect the portS(TxD0) of the HCS12 to a console configured at 19200
816 bauds 8N1, via a Max232 chip to adapt the electrical levels. On Linux,
817 you can use minicom. Connecting to a console is useful to read the
818 messages, but not required.
821 \subsubsection{Connecting to the CAN network :}
823 Connect the port CAN0 (pin PM0, PM1) to the network via a CAN controller.
824 On our board, the CAN controller is a PCA82C250 chip.
827 \subsubsection{starting the node :}
829 Press the reset of your HCS12 board.
832 \section{Example and test program:}
834 The {}``examples'' directory contains some test program you can
835 use as example for your own developments.
838 \subsection{TestMasterSlave}
842 **************************************************************
845 * A simple example for PC. It does implement 2 CanOpen *
846 * nodes in the same process. A master and a slave. Both *
847 * communicate together, exchanging periodically NMT, SYNC, *
848 * SDO and PDO. Master configure heartbeat producer time *
849 * at 1000 ms for slave node-id 0x02 by concise DCF. *
852 * ./TestMasterSlave [OPTIONS] *
855 * -l : Can library ["libcanfestival_can_virtual.so"] *
858 * -s : bus name ["0"] *
859 * -S : 1M,500K,250K,125K,100K,50K,20K,10K,none(disable) *
862 * -m : bus name ["1"] *
863 * -M : 1M,500K,250K,125K,100K,50K,20K,10K,none(disable) *
865 **************************************************************
869 Notes aboute use of voncise DCF :
871 In this example, Master configure heartbeat producer time
872 at 1000 ms for slave node -id 0x02 by concise DCF according DS -302
875 Index 0x1F22, sub-index 0x00 of the master OD, correspond
876 to the number of entries. This equal to the maximum possible nodeId
877 (127). Each sub -index points to the Node -ID of the device, to which
878 the configuration belongs.
880 To add more parameters configurations to the slave, the value
881 at sub -index 0x02 must be a binary stream (little -endian) following
887 (UNS32) nb of entries
888 (UNS16) index parameter 1
889 (UNS8) sub -index parameter 1
890 (UNS32) size data parameter 1
891 (DOMAIN) data parameter 1
892 (UNS16) index parameter 2
893 (UNS8) sub -index parameter 2
894 (UNS32) size data parameter 2
895 (DOMAIN) data parameter 2
897 (UNS16) index parameter n
898 (UNS8) sub -index parameter n
899 (UNS32) size data parameter n
900 (DOMAIN) data parameter n
905 So the binary value stream to configure heartbeat producer
910 0100000017100002000000e803
914 The slave node is configured just before the Master entering
915 in Pre\_operational state.
918 \subsection{gene\_SYNC\_HCS12 :}
920 This is a simple \canopen node that only send cyclic SYNC message.
921 It demonstrate implementation on HCS12 based board.
927 \subsection{kerneltest :}
929 Example based on TestMasterSlave slightly modified to suit kernel
930 space requisites. It will do the same as TestMasterSlave but in kernel
931 space sending kernel messages (displayed by dmesg for example). It
932 is designed as external kernel module implemented as character device.
933 There is a shell script called 'insert.sh', which will insert the
934 module and create a new device file /dev/canf\_ktest (used to sending
935 commands to module). To actual sending commands you can use simple
936 console named 'canf\_ktest\_console'. The module is dependent on a
937 another separate module 'canfestival.ko' implementing CanOpen stack
938 which exports requisite functions. Canfestival.ko module is then dependent
939 on CAN card driver module, by default CAN virtual driver will be loaded.
940 After installing modules (make install), all dependencies are solved
941 automatically by kernel. To run the example type:
945 It will insert required modules, start console, and after quitting
946 console it'll remove modules from kernel.
952 \subsection{TestMasterMicroMod }
957 **************************************************************
958 * TestMasterMicroMod *
960 * A simple example for PC. *
961 * A CanOpen master that control a MicroMod module: *
962 * - setup module TPDO 1 transmit type *
963 * - setup module RPDO 1 transmit type *
964 * - setup module hearbeatbeat period *
965 * - disable others TPDOs *
966 * - set state to operational *
967 * - send periodic SYNC *
968 * - send periodic RPDO 1 to Micromod (digital output) *
969 * - listen Micromod's TPDO 1 (digital input) *
970 * - Mapping RPDO 1 bit per bit (digital input) *
973 * ./TestMasterMicroMod [OPTIONS] *
976 * -l : Can library ["libcanfestival_can_virtual.so"] *
979 * -i : Slave Node id format [0x01 , 0x7F] *
982 * -m : bus name ["1"] *
983 * -M : 1M,500K,250K,125K,100K,50K,20K,10K *
985 **************************************************************
989 \section{Developing a new node}
991 Using provided examples as a base for your new node is generally a
992 good idea. You can also use the provided {*}.od files as a base for
993 your node object dictionary.
995 Creating a new \canopen node implies to define the Object Dictionary
996 of this node. For that, developer has to provide a C file. This C
997 file contains the definition of all dictionary entries, and some kind
998 of index table that helps the stack to access some entries directly.
1001 \subsection{Using Dictionary Editor GUI}
1003 The Object Dictionary Editor is a WxPython based GUI that is used
1004 to create the C file needed to create a new \canopen node.
1007 \subsubsection{Installation and usage on Linux}
1009 You first have to download and install Gnosis XML modules. This is
1010 automated by a Makefile rule.
1017 Now start the editor.
1020 python objdictedit.py [od files...]
1024 \subsubsection{Installation and usage on Windows}
1026 Install Python (at least version 2.4) and wxPython (at least version
1029 Cygwin users can install Gnosis XML utils the same as Linux use. Just
1037 Others will have to download and install Gnosis XML by hand :
1041 http://freshmeat.net/projects/gnosisxml/
1042 http://www.gnosis.cx/download/
1046 Download CanFestival archive and uncompress it. Use windows file explorer
1047 to go into CanFestival3\textbackslash{}objdicgten, and double -click
1050 \subsubsection{About}
1052 The Object Dictionary editor GUI is a python application that use
1053 the Model-View-Controller design pattern. It depends on WxPython to
1054 display view on any supported platform.
1057 \includegraphics[width=7cm]{Pictures/10000201000001FC000001E5D65E8766}
1061 \subsubsection{Main view}
1063 Top list let you choose dictionary section, bottom left list is the
1064 selected index in that dictionary, and bottom right list are edited
1068 \includegraphics[width=12cm]{Pictures/10000201000003E7000001C7B0296577}
1072 \includegraphics[width=3cm]{Pictures/10000000000000B6000000DF1EDD1E73}
1076 \includegraphics[width=3cm]{Pictures/10000000000000AC000000C9C3F53FA6}
1080 \includegraphics[width=3cm]{Pictures/100000000000006D000000A31EC8CB54}
1084 \includegraphics[width=3cm]{Pictures/10000000000000AA0000006014F74635}
1088 \subsubsection{New node}
1090 Edit your node name and type. Choose your inherited specific profile.
1093 \includegraphics[width=11cm]{Pictures/new_node}
1097 \subsubsection{Node info}
1099 Edit your node name and type.
1102 \includegraphics[width=7cm]{Pictures/node_info}
1106 \subsubsection{Profile editor}
1108 Chose the used profile to edit.
1111 \includegraphics[width=4cm]{Pictures/10000000000000AB000000C88F594413}
1114 Pick up optional chosen profile entries.
1117 \includegraphics[width=11cm]{Pictures/10000201000002DE000001D82D89C224}
1121 \subsubsection{User types}
1123 Use User Types to implement value boundaries, and string length
1126 \includegraphics[width=11cm]{Pictures/10000201000001C40000010766961D7F}
1130 \subsubsection{Mapped variable}
1132 Add your own specific dictionary entries and associated mapped variables.
1135 \includegraphics[width=11cm]{Pictures/10000201000001C4000000DD129D4661}
1139 \subsubsection{Integrated help}
1141 Using F1 key, you can get context sensitive help.
1144 \includegraphics[width=12cm]{Pictures/10000201000002F30000020B23ED7F67}
1147 In order to do that, official 301\_v04000201.pdf file must be placed
1148 into doc/ directory, and xpdf must be present on your system.
1150 F2 key open HTML CanFestival help.
1153 \includegraphics[width=12cm]{Pictures/10000201000003440000025ACC3FD2F1}
1157 \subsection{Generating the object Dictionary}
1159 Once object dictionary has been edited and saved, you have to generate
1160 object dictionary C code for your CanFestival node.
1163 \subsubsection{With GUI}
1165 Menu entry {}``File/Build Dictionary''.
1168 \includegraphics[width=4cm]{Pictures/10000201000000B7000000C66AF89CD5}
1171 Choose C file to create or overwrite. Header file will be also created
1172 with the same prefix as C file.
1175 \subsubsection{With command line}
1178 Usage of objdictgen.py :
1179 python objdictgen.py XMLFilePath CfilePath
1187 \subsection{General}
1190 \subsubsection{Does the code compiles on Windows ?}
1192 Yes, with both Cygwin and Visual Studio C++.
1194 Because \canopen layer is coded with C, put a compilation option
1195 /TC or /TP if you plan to mix C++ files. See the MSDN documentation
1199 \subsubsection{How to fit the library to an other microcontr�ler ?}
1201 First, be sure that you have at least 40K bytes of program memory,
1202 and about 2k of RAM.
1204 You have to create target specific interface to HW resources. Take
1205 model on bundled interfaces provided in drivers/ and create your own
1206 interface. You also have to update Makefile.in files for target specific
1207 cflags and options. Choose {--}target= configure switch to compile
1208 your specific interface.
1210 You are welcome to contribute -back your own interfaces! Other Canfestival
1211 users will use it and provide feedback, tests and enhancements.
1214 \subsubsection{Is CanFestival3 conform to DS301 v.4.02 ?}
1216 Thanks to Philippe Foureys (IUT of Valence), a slave node have been
1217 tested with the National Instrument \canopen Conformance Test. It
1218 passed the test with success.
1220 Some very small unconformity have been found in very unusual situations,
1221 for example in the SDO code response to wrong messages.
1227 \subsubsection{How to use a Peaksystem CAN board ?}
1229 Just install peak driver and then compile and install Canfestival.
1230 Peak driver is detected at compile time.
1233 \subsubsection{How to use an unsupported CAN board ?}
1235 You have to install the specific driver on your system, with necessary
1238 Use can\_peak.c/h or can\_virtual.c/h as an example, and adapt it
1241 Execute configure script and choose --can=mydriver
1249 \item Code was compiled MS VisualStudio 2003.NET and VisualStudio 2005.NET
1250 for WindowsXP \ with ANSI and UNICODE configurations and for WindowsCE
1252 \item Some preliminary testing was done, but not enough to be used in mission
1255 Additional Features:
1258 \item Non -integral integers support implementation UNS24, UNS40, UNS48
1260 \item When enable debug output with DEBUG\_WAR\_CONSOLE\_ON or DEBUG\_ERR\_CONSOLE\_ON,
1261 you can navigate in CanFestival source code by double clicking at
1262 diagnostic lines in VisualStudio.NET 200X Debug Output Window.
1264 Custom size integral types such as INTEGER24, UNS40, INTEGER56 etc.
1265 have been defined as 64 bits integers. You will need to replace sizeof(TYPE)
1266 operators to sizeof\_TYPE definitions in generated code, i.e. replace
1267 sizeof(UNS40) with sizeof\_UNS40.
1273 \subsubsection{Which board are you using ?}
1275 A T -board from elektronikladen with a MC9S12DP256 or MC9S12DG256.
1278 \subsubsection{Does the code compile with an other compiler than GNU gcc ?}
1280 It is known to work with Metrowerks CodeWarrior. Here are some tips
1281 from Philippe Foureys. :
1284 \paragraph{Interrupt functions}
1287 \subparagraph{Code for GCC:
1293 void __attribute__((interrupt))timer3Hdl(void):
1295 void __attribute__((interrupt))timer3Hdl(void){...}
1299 \subparagraph{Code for CodeWarrior
1305 void interrupt timer3Hdl(void);
1307 pragma CODE_SEG__NEAR_SEG_NON_BANKED
1308 void interrupt timer3Hdl(void)
1310 pragma CODE_SEG_DEFAULT\end{verbatim}
1313 \paragraph{Interrupt lock, unlock
1317 \subparagraph{Code for GCC
1324 __asm__ __volatile__("cli");
1328 unsigned short mask;
1329 __asm__ __volatile__("tpa\n\tsei":"=d"(mask));
1334 \subparagraph{Code for CodeWarrior}
1344 unsigned short mask;
1347 tpa:tsei:"=d"(mask);
1353 \paragraph{Initialize function}
1356 \subparagraph{Code for GCC}
1360 void initCanHCS12 (void)
1362 //Init the HCS12 microcontroler for CanOpen
1364 // Init the HCS12 CAN driver
1365 const canBusInit bi0 = {
1366 0, /* no low power */
1367 0, /* no time stamp */
1368 1, /* enable MSCAN */
1369 0, /* clock source : oscillator (In fact, it is not used) */
1370 0, /* no loop back */
1371 0, /* no listen only */
1372 0, /* no low pass filter for wk up */
1373 CAN_Baudrates[CAN_BAUDRATE_250K],
1375 0x00, /* Filter on 16 bits.
1376 See Motorola Block Guide V02.14 fig 4-3 */
1377 0x00, 0xFF, /* filter 0 hight accept all msg */
1378 0x00, 0xFF, /* filter 0 low accept all msg */
1379 0x00, 0xFF, /* filter 1 hight filter all of msg */
1380 0x00, 0xFF, /* filter 1 low filter all of msg */
1381 0x00, 0xFF, /* filter 2 hight filter most of msg */
1382 0x00, 0xFF, /* filter 2 low filter most of msg */
1383 0x00, 0xFF, /* filter 3 hight filter most of msg */
1384 0x00, 0xFF, /* filter 3 low filter most of msg */
1390 \subparagraph{Code for CodeWarrior
1395 void initCanHCS12 (void)
1397 //Init the HCS12 microcontroler for CanOpen
1399 // Init the HCS12 CAN driver
1400 const canBusInit bi0 = {
1401 0, /* no low power */
1402 0, /* no time stamp */
1403 1, /* enable MSCAN */
1404 0, /* clock source : oscillator (In fact, it is not used) */
1405 0, /* no loop back */
1406 0, /* no listen only */
1407 0, /* no low pass filter for wk up */
1417 0x00, /* Filter on 16 bits.
1418 See Motorola Block Guide V02.14 fig 4-3 */
1419 0x00, 0xFF, /* filter 0 hight accept all msg */
1420 0x00, 0xFF, /* filter 0 low accept all msg */
1421 0x00, 0xFF, /* filter 1 hight filter all of msg */
1422 0x00, 0xFF, /* filter 1 low filter all of msg */
1423 0x00, 0xFF, /* filter 2 hight filter most of msg */
1424 0x00, 0xFF, /* filter 2 low filter most of msg */
1425 0x00, 0xFF, /* filter 3 hight filter most of msg */
1426 0x00, 0xFF, /* filter 3 low filter most of msg */
1432 \subsubsection{Does the code works in banked memory ?}
1434 No. Today it seems that the port of gcc is bogged for using the banked
1435 memory. So, unfortunately, we are limited to 48 Kbytes of memory code.
1438 \subsubsection{What GCC version are you using ?}
1440 We are using the stable RPM release 2.2 :
1443 \item GNU Gcc 3.0.4. Build 20030501
1444 \item Newlib 1.10.0 Build 20030421
1445 \item GNU Binutils 2.12.1 Build 20030427
1448 \section{Documentation resources}
1451 \subsection{CIA : Can in Automation }
1453 \href{http://www.can-cia.de/}{http://www.can -cia.de}
1456 \subsection{Resources and training in \canopen
1459 \href{http://www.esacademy.com/}{http://www.esacademy.com}
1462 \subsection{Elektronikladen HCS12 T -board }
1464 \href{http://www.elektronikladen.de/en_hcs12tb.html}{http://www.elektronikladen.de/en\_hcs12tb.html}
1467 \subsection{Gnu gcc compiler for HC12 }
1469 \href{http://m68hc11.serveftp.org/m68hc11_port.php}{http://m68hc11.serveftp.org/m68hc11\_port.php}
1472 \subsection{Motorola documentation on HC12 }
1474 \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}
1477 \subsection{Lauterbach debugger for HC12 }
1479 \href{http://www.lauterbach.com/}{http://www.lauterbach.com}
1482 \subsection{Python language }
1484 \href{http://www.python.org/}{http://www.python.org}
1489 \section{About the project}
1492 \subsection{Contributors }
1495 \includegraphics[width=10cm]{Pictures/1000020100000258000000832C6FFAB4}
1498 Unit� mixte de recherche INRETS -LCPC
1500 sur les Interractions V�hicule -Infrastructure -Conducteur
1502 14, route de la mini�re
1508 Tel : +33 1 40 43 29 01
1510 \href{http://www.inrets.fr/ur/livic}{http://www.inrets.fr/ur/livic}
1512 \textbf{Contributors :} Francis DUPIN
1522 \includegraphics[width=10cm]{Pictures/100002010000013A0000004A96B0C1FF}
1527 204, rue du Haut du Pin
1529 88470 Saint -Michel sur Meurthe
1533 Tel : +33 3 29 52 95 67
1535 \href{http://www.lolitech.fr/}{http://www.lolitech.fr}
1537 \textbf{Contributors :} Edouard TISSERANT (Original author)
1544 Many thanks to the other contributors for their great work:
1548 David DUMINY (st� A6R)
1553 \subsection{Getting support}
1555 Send your feedback and bug reports to \href{mailto:canfestival-devel@lists.sourceforge.net}{canfestival-devel@lists.sourceforge.net}.
1557 For commercial support, \ training and specific integration and developments,
1558 please ask LOLITECH (see contributors).
1561 \subsection{Contributing}
1563 You are free to contribute your specific interfaces back to the project.
1564 This way, you can hope to get support from CanFestival users community.
1566 Please send your patch to \href{mailto:canfestival-devel@lists.sourceforge.net}{canfestival
1567 -devel@lists.sourceforge.net}.
1569 Feel free to create some new predefined DS -4xx profiles ({*}.prf)
1570 in objdictgen/config, as much as possible respectful to the official
1574 \subsection{License}
1576 All the project is licensed with LGPL. This mean you can link CanFestival
1577 with any code without being obliged to publish it.
1581 #This file is part of CanFestival, a library implementing CanOpen Stack.
1583 #Copyright (C): Edouard TISSERANT, Francis DUPIN and Laurent BESSARD
1585 #See COPYING file for copyrights details.
1587 #This library is free software; you can redistribute it and/or
1588 #modify it under the terms of the GNU Lesser General Public
1589 #License as published by the Free Software Foundation; either
1590 #version 2.1 of the License, or (at your option) any later version.
1592 #This library is distributed in the hope that it will be useful,
1593 #but WITHOUT ANY WARRANTY; without even the implied warranty of
1594 #MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1595 #Lesser General Public License for more details.
1597 #You should have received a copy of the GNU Lesser General Public
1598 #License along with this library; if not, write to the Free Software
1599 #Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA