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 \subsubsection{DS-305}
127 LSS services are fully supported although they have to be enabled at compile time. Additionally, FastScan LSS service is also optionally enabled.
129 \section{How to start}
131 \subsection{Host requirements}
133 What you need on your development workstation.
135 \subsubsection{Object Dictionary Editor GUI}
139 \item wxPython modules installed (at least version 2.6.3).
140 \item Gnosis xml tools. (Optional can also be installed locally to the project
141 automatically with the help of a Makefile. Please see {}``Using Dictionary
145 \subsubsection{Linux and Unix-likes}
148 \item Linux, FreeBSD, Cygwin or any Unix environment with GNU toolchain.
149 \item The GNU C compiler (gcc) or any other ANSI-C compiler for your target
151 \item Xpdf, and the official 301\_v04000201.pdf file in order to get GUI
152 context sensitive help.
157 \subsubsection{Windows (for native win32 target)}
160 \item Visual Studio Express 2005 or worst.
161 \item Microsoft platform SDK (requires Genuine Advantage)
162 \item Cygwin (for configuration only)
166 \subsection{How to get CanFestival}
168 Please always use CVS, this is the best way to get the most reactive
169 support from the developer community :
173 cvs -d:pserver:anonymous@lolitech.dyndns.org:/canfestival login
176 (type return, without entering a password)
181 cvs -z3 -d:pserver:anonymous@lolitech.dyndns.org:/canfestival co -P CanFestival-3
186 \section{Understanding Canfestival}
188 \subsection{CanFestival Project tree layout}
189 Simplified directory structure.
191 ./src ANSI-C source of \canopen stack
192 ./include Exportables Header files
193 ./drivers Interfaces to specific platforms/HW
194 ./drivers/unix Linux and Cygwin OS interface
195 ./drivers/win32 Native Win32 OS interface
196 ./drivers/timers_xeno Xenomai timers/threads (Linux only)
197 ./drivers/timers_rtai Rtai timers/threads (Linux only)
198 ./drivers/timers_kernel Linux kernel timer/threads
199 ./drivers/timers_unix Posix timers/threads (Linux, Cygwin)
200 ./drivers/can_virtual_kernel Fake CAN network (kernel space)
201 ./drivers/can_serial Serial point to point and PTY hub (*nix only)
202 ./drivers/can_peak_linux PeakSystem CAN library interface
203 ./drivers/can_peak_win32 PeakSystem PCAN-Light interface
204 ./drivers/can_uvccm_win32 Acacetus's RS232 CAN-uVCCM interface
205 ./drivers/can_virtual Fake CAN network (Linux, Cygwin)
206 ./drivers/can_vcom VScom VSCAN interface
207 ./drivers/hcs12 HCS12 full target interface
209 ./examples/TestMasterSlave 2 nodes, NMT SYNC SDO PDO, win32+unix
210 ./examples/TestMasterSlaveLSS 3 nodes, NMT SYNC SDO PDO LSS, win32+unix
211 ./examples/TestMasterMicroMod 1 node, control Peak I/O Module, unix
212 ./examples/gene_SYNC_HCS12 Just send periodic SYNC on HCS12
213 ./examples/win32test Ask some DS301 infos to a node (win32)
214 ./objdictgen Object Dictionary editor GUI
215 ./objdictgen/config Pre-defined OD profiles
216 ./objdictgen/examples Some examples/test OD
217 ./doc Documentation source
222 \subsection{Implement CanFestival in your application}
225 \includegraphics[width=12cm]{Pictures/10000201000003F9000002CF880931E7}
232 \subsection{CanFestival CAN interfaces}
234 Because most CAN controllers and drivers implement FIFOs, CanFestival
235 consider sending message as a non blocking operation.
237 In order to prevent reentrant calls to the stack, messages reception
238 is implemented differently on {\textmu}C and OS.:
241 \item {\textmu}C must provide interruption masking, mutually excluding timer and CAN receive interrupts.\\
246 \includegraphics[width=12cm]{Pictures/10000201000003CA0000016604E6A5EF}
249 \item OS must provide a receive thread, a timer thread and a mutex. CAN
250 reception should be a blocking operation.\\
255 \includegraphics[width=12cm]{Pictures/10000201000003F9000002CF8B0CDAEA}
260 \subsection{CanFestival event scheduling}
262 A \canopen node must be able to take delayed actions.
264 For instance, periodic sync emission, heartbeat production or SDO timeout
265 need to set some alarms that will be called later and do the job.
267 {\textmu}C generally do not have enough free timers to handle all
268 the \canopen needs directly. Moreover, CanFestival internal data
269 may be corrupt by reentrant calls.
271 CanFestival implement a micro -scheduler (timer.c). It uses only one
272 timer to mimic many timers. It manage an alarm table, and call alarms
276 \includegraphics[width=12cm]{Pictures/100000000000022C000000DEDAD2140C}
279 Scheduler can handle short clock value ranges limitation found on
280 some {\textmu}C. As an example, value range for a 16bit clock counter
281 with 4{\textmu}s tick is crossed within 0.26 seconds... Long alarms
284 Chronogram illustrate a long alarm (A) and a short periodic alarm
285 (B), with a A value {\textgreater} clock range {\textgreater}
286 B value. Values t0...t8 are successive setTimer call parameter values.
287 t1 illustrates an intermediate call to TimeDispatch, caused by a delay
288 longer than clock range. Because of long alarm segmentation, at the
289 end of t1, TimeDispatch call will not trig any alarm callback.
292 \includegraphics[width=12cm]{Pictures/1000000000000396000000FFC42573DA}
296 \section{Linux Target}
298 Linux target is default configure target.
301 \subsection{Linux Compilation and installation}
303 Call ./configure -- help to see all available compile time options.
305 After invoking ./configure with your platform specific switches, just
311 ./configure [options]
319 \subsubsection{Standard Linux node}
323 ./configure --timers=unix
327 To do a \canopen node running on PC -Linux, you need :
330 \item A working linux distribution
331 \item One or more Peak system PC CAN interface and the last Peak Linux driver
335 \subsubsection{Real -Time Linux node}
339 ./configure --timers=xeno
343 ./configure --timers=rtai
346 To do a \canopen node running on PC -Linux, you need :
349 \item A working Linux distribution patched with XENOMAI (2.1 or greater) or RTAI (3.6).
350 \item One or more Peak system PC CAN interface and the last Peak Real Time
351 Linux driver installed.
354 \subsubsection{Linux kernel node}
356 To do a CANopen node running on PC-Linux in kernel space, you need:
360 \item A working Linux distribution with pre-built 2.6.x.x kernel sources
361 \item A CAN card driver compatible with CanFestival
365 \subsubsection{CAN devices}
366 Currently supported CAN devices and corresponding configure switch:
368 \paragraph{Peak systems}
370 ./configure --can=peak_linux
372 PeakSystems CAN interface is automatically chosen as default CAN interface
373 if libpcan is present in the system.
375 Please download driver at \href{http://www.peak-system.com/linux}{http://www.peak
376 -system.com/linux} and follow instructions in order to install driver
379 \paragraph{Socket-Can (http://socketcan.berlios.de)}
381 ./configure --can=socket
386 ./configure --can=serial
388 The CAN serial driver implements a 1:1 serial connection between 2 CAN devices.
389 For example, you can connect 2 CANFestival applications via a NULL modem cable.
391 Also with this driver comes a software hub, for up to 16 CANFestival apps to
392 be connected on a single PC, with an optional connection to another CAN driver.
393 Note that only the serial driver is supported at this time. The hub uses ptys
394 (pseudo ttys) available on a *nix like system.
398 ./configure --can=lincan
401 \paragraph{Virtual CAN interfaces (for test/debug)}
403 ./configure --can=virtual
404 or, for kernel space:
405 ./configure --can=kernel_virtual
407 Virtual CAN interface use Unix pipes to emulate a virtual CAN network.
408 Each message issued from a node is repeat to all other nodes. Currently
409 only works with nodes running in the same process, and does not support
410 work with Xenomai or RTAI.
414 ./configure --can=vscom
416 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.
418 \subsubsection{LSS services}
419 Canfestival optionally supports LSS services but they must be enabled.
421 ./configure --enable-lss
424 Additionally, the FastScan LSS service can also be enabled.
426 ./configure --enable-lss --enable-lss-fs
429 \subsection{Testing your CanFestival installation}
431 \subsubsection{User space}
433 Sample provided in /example/TestMasterSlave is installed into your
434 system during installation.
442 Default CAN driver library is libcanfestival\_can\_virtual.so., which
443 will simply pass CAN messages through Unix pipes between Master and
446 You may also want to specify different can interface and define some
447 CAN ports. Another example using Peak{\textquotesingle}s dual PCMCIA
448 (configure and install with --can=peak) :
452 TestMasterSlave -l libcanfestival_can_peak.so -s 40 -m 41
455 If the LSS services are enabled the sample provided in /example/TestMasterSlaveLSS will be also installed. It behaves the same as TestMasterSlave except that there are 2 slave nodes without a valid nodeID so the the initializations is done via the LSS services. If FastScan optional service is enabled the example will use it.
457 \subsubsection{Kernel space}
465 It's based on TestMasterSlave example
466 and has the same functionality. Uses virtual can driver as default
467 too. After successful installation you can insert the module by typing:
468 modprobe canf\_ktest Module control is done by simple console 'canf\_ktest\_console'
469 which is used to start/stop sending data.
472 \section{Windows Targets}
474 CanFestival can be compiled and run on Windows platform. It is possible
475 to use both Cygwin and win32 native runtime environment.
477 \subsection{Object Dictionary Editor GUI installation.}
479 Please refer to \hyperlink{a821UsingDictionaryEditorGUIoutline}{8.2.1)Using
480 Dictionary Editor GUI}
484 \subsubsection{Requirements}
486 Cygwin have to be installed with those packages :
494 Currently, the only supported CAN devices are PeakSystems ones, with
495 PcanLight driver and library.
497 Please download driver at \href{http://www.peak-system.com/themen/download_gb.html}{http://www.peak
498 -system.com/themen/download\_gb.html} \ and follow instructions
499 in order to install driver on your system.
501 Install Cygwin as required, and the driver for your Peak CAN device.
503 Open a Cygwin terminal, and follow those instructions:
506 \subsubsection{Cygwin configuration and compilation}
509 \paragraph{A single node with PcanLight and Peak CAN -USB adapter}
511 Download the PCAN-Light Zip file for your HW ( URL from download
516 wget http://www.peak -system.com/files/usb.zip
520 Extract its content into your cygwin home (it will create a {}``Disk''
529 Configure CanFestival3 providing path to the desired PcanLight implementation:
534 export PCAN_INCLUDE=~/Disk/PCAN-Light/Api/
535 export PCAN_HEADER=Pcan_usb.h
536 export PCAN_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_usb.lib
537 ./configure --can=peak_win32
542 In order to test, you have to use another CanFestival node, connect
547 cp ~/Disk/PCAN-Light/Pcan_usb.dll .
548 ./examples/TestMasterSlave/TestMasterSlave \
549 -l drivers/can\_peak\_win32/cygcan\_peak\_win32.dll \
554 Then, on the other node :
558 ./TestMasterSlave -l my_driver.so -S none -M 500K
562 Now messages are being exchanged between master and slave node.
564 \paragraph{Two nodes with PcanLight and Peak dual PCMCIA -CAN adapter}
566 Download the PCAN-Light Zip file for your HW ( URL from download
571 wget http://www.peak-system.com/files/pccard.zip
575 Extract its content into your cygwin home (it will create a {}``Disk''
584 The configure CanFestival3 providing path to the desired PcanLight
589 export PCAN_INCLUDE=~/Disk/PCAN-Light/Api/
590 export PCAN_HEADER=Pcan_pcc.h
591 export PCAN_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_pcc.lib
592 export PCAN2_HEADER=Pcan_2pcc.h
593 export PCAN2_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_2pcc.lib
597 In order to test, just connect together both CAN ports of the PCMCIA
598 card. Don{\textquotesingle}t forget 120ohms terminator.
602 cp ~/Disk/PCAN-Light/Pcan_pcc.dll .
603 cp ~/Disk/PCAN-Light/Pcan_2pcc.dll .
604 ./examples/TestMasterSlave/TestMasterSlave \
605 -l drivers/can_peak_win32/cygcan_peak_win32.dll
609 Messages are then exchanged between master and slave node, both inside
610 TestMasterSlave{\textquotesingle}s process.
612 \subsection{Visual Studio C++}
614 \subsubsection{Requirements}
616 Minimal Cygwin installation is required at configuration time in order
617 to create specific header files (config.h and cancfg.h). Once this
618 files created, cygwin is not necessary any more.
620 Project and solution files have been created and tested with Visual
621 Studio Express 2005. Be sure to have installed Microsoft Platform
622 SDK, as recommended at the end of Visual Studio installation.
625 \subsubsection{Configuration with cygwin}
627 Follow instructions given at \hyperlink{Cygwin configuration and compilation}{Cygwin
628 configuration and compilation}, but do neither call make nor do tests,
629 just do configuration steps. This will create headers files accordingly
630 to your configuration parameters, and the desired CAN hardware.
633 \subsubsection{Compilation with Visual Studio}
635 You can either load independent {}``{*}.vcproj'' project files
636 along your own projects in your own solution or load the provided
637 {}``CanFestival -3.vc8.sln'' solution files directly.
639 Build CanFestival -3 project first.
642 \paragraph{PcanLight and the can\_peak\_win32 project.}
644 Chosen Pcan\_xxx.lib and eventually Pcan\_2xxx.lib files must be added
645 to can\_peak\_win32 \ \ project before build of the DLL.
648 \subsubsection{Testing}
650 Copy eventually needed dlls (ie : Pcan\_Nxxx.lib) into Release or
651 Debug directory, and run the test program:
655 TestMasterSlave.exe -l can_peak_win32.dll
662 \subsubsection{Requirements}
664 Download from : http://sourceforge.net/project/showfiles.php?group\_id=2435
667 \item MSYS-1.0.10.exe
668 \item MinGW-5.1.3.exe
669 \item mingwPORT (which contains wget-1.9.1)
671 Please download driver at http://www.peak-system.com/themen/download\_gb.html
672 and follow instructions in order to install driver on your system.
673 Install MSYS and MingW as required, and the driver for your Peak CAN
674 device. Open a MSYS terminal, and follow those instructions:\\
678 \item extract wget-1.9.1-mingwPORT.tar.bz2
679 \item copy wget.exe in c:\textbackslash{} msys\textbackslash{} 1.0\textbackslash{}
681 \item start MSYS and check the file /etc/fstab contain the line c:/MinGW
685 \subsubsection{MSYS configuration and compilation}
687 Instructions for compilation are nearly the same as CYGWIN part.
690 \paragraph{A single node with PcanLight and Peak CAN-USB adapter}
692 Download the PCAN-Light Zip file for your HW ( URL from download page
696 wget http://www.peak-system.com/files/usb.zip
699 Extract its content into your MSYS's home (it will create a \char`\"{}
700 Disk\char`\"{} directory):
708 Configure CanFestival3 providing path to the desired PcanLight implementation:
712 export PCAN_INCLUDE=~/Disk/PCAN-Light/Api/
713 export PCAN_HEADER=Pcan_usb.h
714 export PCAN_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_usb.lib
715 ./configure --can=peak_win32
719 In order to test, you have to use another CanFestival node, connect
724 cp ~/Disk/PCAN-Light/Pcan_usb.dll .
725 ./examples/TestMasterSlave/TestMasterSlave \
726 -l drivers/can_peak_win32/cygcan_peak_win32.dll \
730 Then, on the other node :
733 ./TestMasterSlave -l my_driver.so -S none -M 500K -m 0
735 Now messages are being exchanged between master and slave node.
738 \paragraph{Two nodes with PcanLight and Peak dual PCMCIA-CAN adapter}
740 Download the PCAN-Light Zip file for your HW ( URL from download page
744 wget http://www.peak-system.com/files/pccard.zip
746 Extract its content into your MSYS's home (it will create a \char`\"{}
747 Disk\char`\"{} directory):
752 The configure CanFestival3 providing path to the desired PcanLight
756 export PCAN_INCLUDE=~/Disk/PCAN-Light/Api/
757 export PCAN_HEADER=Pcan_pcc.h}
758 export PCAN_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_pcc.lib
759 export PCAN2_HEADER=Pcan_2pcc.h
760 export PCAN2_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_2pcc.lib
763 In order to test, just connect together both CAN ports of the PCMCIA
764 card. Don't forget 120ohms terminator.
767 cp~/Disk/PCAN-Light/Pcan_pcc.dll ~.
768 cp ~/Disk/PCAN-Light/Pcan_2pcc.dll ~.
769 ./examples/TestMasterSlave/TestMasterSlave \
770 -l drivers/can\_peak\_win32/cygcan\_peak\_win32.dll -m 0 -s 1
772 Messages are then exchanged between master and slave node, both inside
773 TestMasterSlave's process.
775 \section{Motorola HCS12}
777 The examples have been tested on a MC9S12DG255 mounted on a Elektronikladen
780 Beware that there are few differences in the MSCAN module of the 68HC12
781 and HCS12 microcontroller. For a HC12, you must adapt the driver that
782 we provide for \ the HCS12.
784 For the difference MSCAN HC12/HCS12, see the Motorola application
793 To do a \canopen node running on a microncontroller Motorola MC9S12DP256,
797 \item The compiler GNU gcc for HC11, HC12, HCS12 : m6811 -elf. \\
798 Download the \textbf{release 3.1} at : \href{http://m68hc11.serveftp.org/m68hc11_pkg_rpm.php}{http://m68hc11.serveftp.org/m68hc11\_pkg\_rpm.php}
799 \item A board with this chip. We are using the T -board from Electronikladen.
800 \item At least about 40 kBytes of program memory.
801 \item A tool to flash the memory. (We are using the high cost Lauterbach
805 \subsection{Running a HCS12 node}
808 \subsubsection{Compiling Canfestival:}
811 ./configure --target=hcs12
815 \subsubsection{Compiling and building an example}
817 Enter in the folder of an HCS12 example,
824 \subsubsection{Flashing the memory :}
826 Use your preferred loader ! If you are using a debugger Lauterbach,
827 you can load the bash file : trace32\_flash\_programmer.cmm. It loads
828 directly the elf file.
831 \subsubsection{Connecting to a serial RS232 console :}
833 Connect the portS(TxD0) of the HCS12 to a console configured at 19200
834 bauds 8N1, via a Max232 chip to adapt the electrical levels. On Linux,
835 you can use minicom. Connecting to a console is useful to read the
836 messages, but not required.
839 \subsubsection{Connecting to the CAN network :}
841 Connect the port CAN0 (pin PM0, PM1) to the network via a CAN controller.
842 On our board, the CAN controller is a PCA82C250 chip.
845 \subsubsection{starting the node :}
847 Press the reset of your HCS12 board.
850 \section{Example and test program:}
852 The {}``examples'' directory contains some test program you can
853 use as example for your own developments.
856 \subsection{TestMasterSlave}
860 **************************************************************
863 * A simple example for PC. It does implement 2 CanOpen *
864 * nodes in the same process. A master and a slave. Both *
865 * communicate together, exchanging periodically NMT, SYNC, *
866 * SDO and PDO. Master configure heartbeat producer time *
867 * at 1000 ms for slave node-id 0x02 by concise DCF. *
870 * ./TestMasterSlave [OPTIONS] *
873 * -l : Can library ["libcanfestival_can_virtual.so"] *
876 * -s : bus name ["0"] *
877 * -S : 1M,500K,250K,125K,100K,50K,20K,10K,none(disable) *
880 * -m : bus name ["1"] *
881 * -M : 1M,500K,250K,125K,100K,50K,20K,10K,none(disable) *
883 **************************************************************
887 Notes aboute use of voncise DCF :
889 In this example, Master configure heartbeat producer time
890 at 1000 ms for slave node -id 0x02 by concise DCF according DS -302
893 Index 0x1F22, sub-index 0x00 of the master OD, correspond
894 to the number of entries. This equal to the maximum possible nodeId
895 (127). Each sub -index points to the Node -ID of the device, to which
896 the configuration belongs.
898 To add more parameters configurations to the slave, the value
899 at sub -index 0x02 must be a binary stream (little -endian) following
905 (UNS32) nb of entries
906 (UNS16) index parameter 1
907 (UNS8) sub -index parameter 1
908 (UNS32) size data parameter 1
909 (DOMAIN) data parameter 1
910 (UNS16) index parameter 2
911 (UNS8) sub -index parameter 2
912 (UNS32) size data parameter 2
913 (DOMAIN) data parameter 2
915 (UNS16) index parameter n
916 (UNS8) sub -index parameter n
917 (UNS32) size data parameter n
918 (DOMAIN) data parameter n
923 So the binary value stream to configure heartbeat producer
928 0100000017100002000000e803
932 The slave node is configured just before the Master entering
933 in Pre\_operational state.
936 \subsection{gene\_SYNC\_HCS12 :}
938 This is a simple \canopen node that only send cyclic SYNC message.
939 It demonstrate implementation on HCS12 based board.
945 \subsection{kerneltest :}
947 Example based on TestMasterSlave slightly modified to suit kernel
948 space requisites. It will do the same as TestMasterSlave but in kernel
949 space sending kernel messages (displayed by dmesg for example). It
950 is designed as external kernel module implemented as character device.
951 There is a shell script called 'insert.sh', which will insert the
952 module and create a new device file /dev/canf\_ktest (used to sending
953 commands to module). To actual sending commands you can use simple
954 console named 'canf\_ktest\_console'. The module is dependent on a
955 another separate module 'canfestival.ko' implementing CanOpen stack
956 which exports requisite functions. Canfestival.ko module is then dependent
957 on CAN card driver module, by default CAN virtual driver will be loaded.
958 After installing modules (make install), all dependencies are solved
959 automatically by kernel. To run the example type:
963 It will insert required modules, start console, and after quitting
964 console it'll remove modules from kernel.
970 \subsection{TestMasterMicroMod }
975 **************************************************************
976 * TestMasterMicroMod *
978 * A simple example for PC. *
979 * A CanOpen master that control a MicroMod module: *
980 * - setup module TPDO 1 transmit type *
981 * - setup module RPDO 1 transmit type *
982 * - setup module hearbeatbeat period *
983 * - disable others TPDOs *
984 * - set state to operational *
985 * - send periodic SYNC *
986 * - send periodic RPDO 1 to Micromod (digital output) *
987 * - listen Micromod's TPDO 1 (digital input) *
988 * - Mapping RPDO 1 bit per bit (digital input) *
991 * ./TestMasterMicroMod [OPTIONS] *
994 * -l : Can library ["libcanfestival_can_virtual.so"] *
997 * -i : Slave Node id format [0x01 , 0x7F] *
1000 * -m : bus name ["1"] *
1001 * -M : 1M,500K,250K,125K,100K,50K,20K,10K *
1003 **************************************************************
1006 \subsection{TestMasterSlaveLSS}
1010 **************************************************************
1011 * TestMasterSlaveLSS *
1013 * A LSS example for PC. It does implement 3 CanOpen *
1014 * nodes in the same process. A master and 2 slaves. All *
1015 * communicate together, exchanging periodically NMT, SYNC, *
1016 * SDO and PDO. Master configure heartbeat producer time *
1017 * at 1000 ms for the slaves by concise DCF. *
1020 * ./TestMasterSlaveLSS [OPTIONS] *
1023 * -l : Can library ["libcanfestival_can_virtual.so"] *
1026 * -a : bus name ["0"] *
1027 * -A : 1M,500K,250K,125K,100K,50K,20K,10K,none(disable) *
1030 * -b : bus name ["1"] *
1031 * -B : 1M,500K,250K,125K,100K,50K,20K,10K,none(disable) *
1034 * -m : bus name ["2"] *
1035 * -M : 1M,500K,250K,125K,100K,50K,20K,10K,none(disable) *
1037 **************************************************************
1040 The function used to request LSS services is \textit{configNetworkNode}. It works similar to \textit{writeNetworkDict} and its model is the following:
1042 UNS8 configNetworkNode (CO_Data* d, UNS8 command, void *dat1, void* dat2,
1043 LSSCallback_t Callback)
1046 \subsection{FastScan}
1047 FastScan is a special LSS service that allow the dynamically identification of the slave nodes even if they do not have a valid nodeID. This identification is based on the LSS address, composed by vendor ID, product code, revision number and serial number (refer to the DS305 for more information). The LSS address can be partially known or fully unknown. To represent this fact in Canfestival, we use the structure \textit{lss\_fs\_transfer\_t}. The parameter \textit{FS\_LSS\_ID} is an array of four elements which represents the four elements of the LSS address. The other parameter, \textit{FS\_BitChecked}, is also an array and it represents how many bits of each LSS address element are UNKNOWN. The next example is taken from \textit{TestMasterSlaveLSS}, where only the last two digits (8 bits) of vendor ID and product code are unknown and revision number and serial number are totally unknown.
1050 lss_fs_transfer_t lss_fs;
1051 /* The VendorID and ProductCode are partialy known, */
1052 /* except the last two digits (8 bits). */
1053 lss_fs.FS_LSS_ID[0]=Vendor_ID;
1054 lss_fs.FS_BitChecked[0]=8;
1055 lss_fs.FS_LSS_ID[1]=Product_Code;
1056 lss_fs.FS_BitChecked[1]=8;
1057 /* serialNumber and RevisionNumber are unknown, */
1058 /* i.e. the 8 digits (32bits) are unknown. */
1059 lss_fs.FS_BitChecked[2]=32;
1060 lss_fs.FS_BitChecked[3]=32;
1061 res=configNetworkNode(&d,LSS_IDENT_FASTSCAN,&lss_fs,0,CheckLSSAndContinue);
1064 \section{Developing a new node}
1066 Using provided examples as a base for your new node is generally a
1067 good idea. You can also use the provided {*}.od files as a base for
1068 your node object dictionary.
1070 Creating a new \canopen node implies to define the Object Dictionary
1071 of this node. For that, developer has to provide a C file. This C
1072 file contains the definition of all dictionary entries, and some kind
1073 of index table that helps the stack to access some entries directly.
1076 \subsection{Using Dictionary Editor GUI}
1078 The Object Dictionary Editor is a WxPython based GUI that is used
1079 to create the C file needed to create a new \canopen node.
1082 \subsubsection{Installation and usage on Linux}
1084 You first have to download and install Gnosis XML modules. This is
1085 automated by a Makefile rule.
1092 Now start the editor.
1095 python objdictedit.py [od files...]
1099 \subsubsection{Installation and usage on Windows}
1101 Install Python (at least version 2.4) and wxPython (at least version
1104 Cygwin users can install Gnosis XML utils the same as Linux use. Just
1112 Others will have to download and install Gnosis XML by hand :
1116 http://freshmeat.net/projects/gnosisxml/
1117 http://www.gnosis.cx/download/
1121 Download CanFestival archive and uncompress it. Use windows file explorer
1122 to go into CanFestival3\textbackslash{}objdicgten, and double -click
1125 \subsubsection{About}
1127 The Object Dictionary editor GUI is a python application that use
1128 the Model-View-Controller design pattern. It depends on WxPython to
1129 display view on any supported platform.
1132 \includegraphics[width=7cm]{Pictures/10000201000001FC000001E5D65E8766}
1136 \subsubsection{Main view}
1138 Top list let you choose dictionary section, bottom left list is the
1139 selected index in that dictionary, and bottom right list are edited
1143 \includegraphics[width=12cm]{Pictures/10000201000003E7000001C7B0296577}
1147 \includegraphics[width=3cm]{Pictures/10000000000000B6000000DF1EDD1E73}
1151 \includegraphics[width=3cm]{Pictures/10000000000000AC000000C9C3F53FA6}
1155 \includegraphics[width=3cm]{Pictures/100000000000006D000000A31EC8CB54}
1159 \includegraphics[width=3cm]{Pictures/10000000000000AA0000006014F74635}
1163 \subsubsection{New node}
1165 Edit your node name and type. Choose your inherited specific profile.
1168 \includegraphics[width=11cm]{Pictures/new_node}
1172 \subsubsection{Node info}
1174 Edit your node name and type.
1177 \includegraphics[width=7cm]{Pictures/node_info}
1181 \subsubsection{Profile editor}
1183 Chose the used profile to edit.
1186 \includegraphics[width=4cm]{Pictures/10000000000000AB000000C88F594413}
1189 Pick up optional chosen profile entries.
1192 \includegraphics[width=11cm]{Pictures/10000201000002DE000001D82D89C224}
1196 \subsubsection{User types}
1198 Use User Types to implement value boundaries, and string length
1201 \includegraphics[width=11cm]{Pictures/10000201000001C40000010766961D7F}
1205 \subsubsection{Mapped variable}
1207 Add your own specific dictionary entries and associated mapped variables.
1210 \includegraphics[width=11cm]{Pictures/10000201000001C4000000DD129D4661}
1214 \subsubsection{Integrated help}
1216 Using F1 key, you can get context sensitive help.
1219 \includegraphics[width=12cm]{Pictures/10000201000002F30000020B23ED7F67}
1222 In order to do that, official 301\_v04000201.pdf file must be placed
1223 into doc/ directory, and xpdf must be present on your system.
1225 F2 key open HTML CanFestival help.
1228 \includegraphics[width=12cm]{Pictures/10000201000003440000025ACC3FD2F1}
1232 \subsection{Generating the object Dictionary}
1234 Once object dictionary has been edited and saved, you have to generate
1235 object dictionary C code for your CanFestival node.
1238 \subsubsection{With GUI}
1240 Menu entry {}``File/Build Dictionary''.
1243 \includegraphics[width=4cm]{Pictures/10000201000000B7000000C66AF89CD5}
1246 Choose C file to create or overwrite. Header file will be also created
1247 with the same prefix as C file.
1250 \subsubsection{With command line}
1253 Usage of objdictgen.py :
1254 python objdictgen.py XMLFilePath CfilePath
1262 \subsection{General}
1265 \subsubsection{Does the code compiles on Windows ?}
1267 Yes, with both Cygwin and Visual Studio C++.
1269 Because \canopen layer is coded with C, put a compilation option
1270 /TC or /TP if you plan to mix C++ files. See the MSDN documentation
1274 \subsubsection{How to fit the library to an other microcontr�ler ?}
1276 First, be sure that you have at least 40K bytes of program memory,
1277 and about 2k of RAM.
1279 You have to create target specific interface to HW resources. Take
1280 model on bundled interfaces provided in drivers/ and create your own
1281 interface. You also have to update Makefile.in files for target specific
1282 cflags and options. Choose {--}target= configure switch to compile
1283 your specific interface.
1285 You are welcome to contribute -back your own interfaces! Other Canfestival
1286 users will use it and provide feedback, tests and enhancements.
1289 \subsubsection{Is CanFestival3 conform to DS301 v.4.02 ?}
1291 Thanks to Philippe Foureys (IUT of Valence), a slave node have been
1292 tested with the National Instrument \canopen Conformance Test. It
1293 passed the test with success.
1295 Some very small unconformity have been found in very unusual situations,
1296 for example in the SDO code response to wrong messages.
1302 \subsubsection{How to use a Peaksystem CAN board ?}
1304 Just install peak driver and then compile and install Canfestival.
1305 Peak driver is detected at compile time.
1308 \subsubsection{How to use an unsupported CAN board ?}
1310 You have to install the specific driver on your system, with necessary
1313 Use can\_peak.c/h or can\_virtual.c/h as an example, and adapt it
1316 Execute configure script and choose --can=mydriver
1324 \item Code was compiled MS VisualStudio 2003.NET and VisualStudio 2005.NET
1325 for WindowsXP \ with ANSI and UNICODE configurations and for WindowsCE
1327 \item Some preliminary testing was done, but not enough to be used in mission
1330 Additional Features:
1333 \item Non -integral integers support implementation UNS24, UNS40, UNS48
1335 \item When enable debug output with DEBUG\_WAR\_CONSOLE\_ON or DEBUG\_ERR\_CONSOLE\_ON,
1336 you can navigate in CanFestival source code by double clicking at
1337 diagnostic lines in VisualStudio.NET 200X Debug Output Window.
1339 Custom size integral types such as INTEGER24, UNS40, INTEGER56 etc.
1340 have been defined as 64 bits integers. You will need to replace sizeof(TYPE)
1341 operators to sizeof\_TYPE definitions in generated code, i.e. replace
1342 sizeof(UNS40) with sizeof\_UNS40.
1348 \subsubsection{Which board are you using ?}
1350 A T -board from elektronikladen with a MC9S12DP256 or MC9S12DG256.
1353 \subsubsection{Does the code compile with an other compiler than GNU gcc ?}
1355 It is known to work with Metrowerks CodeWarrior. Here are some tips
1356 from Philippe Foureys. :
1359 \paragraph{Interrupt functions}
1362 \subparagraph{Code for GCC:
1368 void __attribute__((interrupt))timer3Hdl(void):
1370 void __attribute__((interrupt))timer3Hdl(void){...}
1374 \subparagraph{Code for CodeWarrior
1380 void interrupt timer3Hdl(void);
1382 pragma CODE_SEG__NEAR_SEG_NON_BANKED
1383 void interrupt timer3Hdl(void)
1385 pragma CODE_SEG_DEFAULT\end{verbatim}
1388 \paragraph{Interrupt lock, unlock
1392 \subparagraph{Code for GCC
1399 __asm__ __volatile__("cli");
1403 unsigned short mask;
1404 __asm__ __volatile__("tpa\n\tsei":"=d"(mask));
1409 \subparagraph{Code for CodeWarrior}
1419 unsigned short mask;
1422 tpa:tsei:"=d"(mask);
1428 \paragraph{Initialize function}
1431 \subparagraph{Code for GCC}
1435 void initCanHCS12 (void)
1437 //Init the HCS12 microcontroler for CanOpen
1439 // Init the HCS12 CAN driver
1440 const canBusInit bi0 = {
1441 0, /* no low power */
1442 0, /* no time stamp */
1443 1, /* enable MSCAN */
1444 0, /* clock source : oscillator (In fact, it is not used) */
1445 0, /* no loop back */
1446 0, /* no listen only */
1447 0, /* no low pass filter for wk up */
1448 CAN_Baudrates[CAN_BAUDRATE_250K],
1450 0x00, /* Filter on 16 bits.
1451 See Motorola Block Guide V02.14 fig 4-3 */
1452 0x00, 0xFF, /* filter 0 hight accept all msg */
1453 0x00, 0xFF, /* filter 0 low accept all msg */
1454 0x00, 0xFF, /* filter 1 hight filter all of msg */
1455 0x00, 0xFF, /* filter 1 low filter all of msg */
1456 0x00, 0xFF, /* filter 2 hight filter most of msg */
1457 0x00, 0xFF, /* filter 2 low filter most of msg */
1458 0x00, 0xFF, /* filter 3 hight filter most of msg */
1459 0x00, 0xFF, /* filter 3 low filter most of msg */
1465 \subparagraph{Code for CodeWarrior
1470 void initCanHCS12 (void)
1472 //Init the HCS12 microcontroler for CanOpen
1474 // Init the HCS12 CAN driver
1475 const canBusInit bi0 = {
1476 0, /* no low power */
1477 0, /* no time stamp */
1478 1, /* enable MSCAN */
1479 0, /* clock source : oscillator (In fact, it is not used) */
1480 0, /* no loop back */
1481 0, /* no listen only */
1482 0, /* no low pass filter for wk up */
1492 0x00, /* Filter on 16 bits.
1493 See Motorola Block Guide V02.14 fig 4-3 */
1494 0x00, 0xFF, /* filter 0 hight accept all msg */
1495 0x00, 0xFF, /* filter 0 low accept all msg */
1496 0x00, 0xFF, /* filter 1 hight filter all of msg */
1497 0x00, 0xFF, /* filter 1 low filter all of msg */
1498 0x00, 0xFF, /* filter 2 hight filter most of msg */
1499 0x00, 0xFF, /* filter 2 low filter most of msg */
1500 0x00, 0xFF, /* filter 3 hight filter most of msg */
1501 0x00, 0xFF, /* filter 3 low filter most of msg */
1507 \subsubsection{Does the code works in banked memory ?}
1509 No. Today it seems that the port of gcc is bogged for using the banked
1510 memory. So, unfortunately, we are limited to 48 Kbytes of memory code.
1513 \subsubsection{What GCC version are you using ?}
1515 We are using the stable RPM release 2.2 :
1518 \item GNU Gcc 3.0.4. Build 20030501
1519 \item Newlib 1.10.0 Build 20030421
1520 \item GNU Binutils 2.12.1 Build 20030427
1523 \section{Documentation resources}
1526 \subsection{CIA : Can in Automation }
1528 \href{http://www.can-cia.de/}{http://www.can -cia.de}
1531 \subsection{Resources and training in \canopen
1534 \href{http://www.esacademy.com/}{http://www.esacademy.com}
1537 \subsection{Elektronikladen HCS12 T -board }
1539 \href{http://www.elektronikladen.de/en_hcs12tb.html}{http://www.elektronikladen.de/en\_hcs12tb.html}
1542 \subsection{Gnu gcc compiler for HC12 }
1544 \href{http://m68hc11.serveftp.org/m68hc11_port.php}{http://m68hc11.serveftp.org/m68hc11\_port.php}
1547 \subsection{Motorola documentation on HC12 }
1549 \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}
1552 \subsection{Lauterbach debugger for HC12 }
1554 \href{http://www.lauterbach.com/}{http://www.lauterbach.com}
1557 \subsection{Python language }
1559 \href{http://www.python.org/}{http://www.python.org}
1564 \section{About the project}
1567 \subsection{Contributors }
1570 \includegraphics[width=10cm]{Pictures/1000020100000258000000832C6FFAB4}
1573 Unit� mixte de recherche INRETS -LCPC
1575 sur les Interractions V�hicule -Infrastructure -Conducteur
1577 14, route de la mini�re
1583 Tel : +33 1 40 43 29 01
1585 \href{http://www.inrets.fr/ur/livic}{http://www.inrets.fr/ur/livic}
1587 \textbf{Contributors :} Francis DUPIN
1597 \includegraphics[width=10cm]{Pictures/100002010000013A0000004A96B0C1FF}
1602 204, rue du Haut du Pin
1604 88470 Saint -Michel sur Meurthe
1608 Tel : +33 3 29 52 95 67
1610 \href{http://www.lolitech.fr/}{http://www.lolitech.fr}
1612 \textbf{Contributors :} Edouard TISSERANT (Original author)
1619 Many thanks to the other contributors for their great work:
1623 David DUMINY (st� A6R)
1628 \subsection{Getting support}
1630 Send your feedback and bug reports to \href{mailto:canfestival-devel@lists.sourceforge.net}{canfestival-devel@lists.sourceforge.net}.
1632 For commercial support, \ training and specific integration and developments,
1633 please ask LOLITECH (see contributors).
1636 \subsection{Contributing}
1638 You are free to contribute your specific interfaces back to the project.
1639 This way, you can hope to get support from CanFestival users community.
1641 Please send your patch to \href{mailto:canfestival-devel@lists.sourceforge.net}{canfestival
1642 -devel@lists.sourceforge.net}.
1644 Feel free to create some new predefined DS -4xx profiles ({*}.prf)
1645 in objdictgen/config, as much as possible respectful to the official
1649 \subsection{License}
1651 All the project is licensed with LGPL. This mean you can link CanFestival
1652 with any code without being obliged to publish it.
1656 #This file is part of CanFestival, a library implementing CanOpen Stack.
1658 #Copyright (C): Edouard TISSERANT, Francis DUPIN and Laurent BESSARD
1660 #See COPYING file for copyrights details.
1662 #This library is free software; you can redistribute it and/or
1663 #modify it under the terms of the GNU Lesser General Public
1664 #License as published by the Free Software Foundation; either
1665 #version 2.1 of the License, or (at your option) any later version.
1667 #This library is distributed in the hope that it will be useful,
1668 #but WITHOUT ANY WARRANTY; without even the implied warranty of
1669 #MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
1670 #Lesser General Public License for more details.
1672 #You should have received a copy of the GNU Lesser General Public
1673 #License along with this library; if not, write to the Free Software
1674 #Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA