
etisserant@393: \documentclass[12pt,english,a4paper]{book}
nico@208: \usepackage[T1]{fontenc}
etisserant@393: \usepackage[latin9]{inputenc}
etisserant@393: \usepackage{graphicx}
etisserant@393: \usepackage{amsfonts}
etisserant@393: \usepackage{textcomp}
nico@208: \usepackage{color}
nico@208: \usepackage{calc}
nico@208: \usepackage{longtable}
nico@208: \usepackage{hyperref}
nico@208: \usepackage{graphics}
nico@208: \DeclareGraphicsExtensions{.jpg}
nico@208: \DeclareGraphicsExtensions{.png}
nico@208: \hypersetup{colorlinks=true, linkcolor=blue, filecolor=blue, pagecolor=blue, urlcolor=blue}
nico@208: 
nico@208: %%%%\%%%%%%%% titre, auteurs, date, etc...%%%%%%%%%%%%%%%%%%
etisserant@249: \title{\Huge The CanFestival CANOpen stack manual}
nico@208: \author{Edouard TISSERANT}
nico@208: \date{\today}
nico@208: 
etisserant@394: \setcounter{secnumdepth}{5}
etisserant@394: \renewcommand\thesection{\arabic{section} -}
etisserant@394: \renewcommand\thesubsection{\arabic{section}.\arabic{subsection})}
etisserant@394: \renewcommand\thesubsubsection{\arabic{section}.\arabic{subsection}.\arabic{subsubsection})}
etisserant@394: \renewcommand\theparagraph{\alph{paragraph})}
etisserant@394: \renewcommand\thesubparagraph{\roman{subparagraph})}
etisserant@394: 
etisserant@393: \newcommand{\canopen}{CANopen }
etisserant@392: 
nico@208: \begin{document}
etisserant@393: {\centering\textsf{\huge The CanFestival \canopen stack manual.}}
etisserant@393: 
etisserant@393: \renewcommand{\contentsname}{CanFestival v3.0 Manual}
etisserant@393: \setcounter{tocdepth}{2} \tableofcontents{}
etisserant@393: 
etisserant@393: \clearpage{}
etisserant@393: 
nico@208: \section{Introduction}
etisserant@393: 
etisserant@393: CanFestival is an OpenSource (LGPL and GPL) \canopen framework.
nico@208: 
nico@208: \subsection{The CanFestival project}
etisserant@393: 
etisserant@393: This project, initiated by Edouard TISSERANT in 2001, has grown thanks
etisserant@393: to Francis DUPIN and other contributors.
etisserant@393: 
etisserant@393: Today, CanFestival focuses on providing an ANSI-C platform independent
etisserant@393: \canopen stack that can be implemented as master or slave nodes on
etisserant@393: PCs, Real-time IPCs, and Microcontrollers.
nico@208: 
nico@208: CanFestival is a project supported by Lolitech.
nico@208: 
etisserant@393: 
etisserant@393: \subsection{What is \canopen}
etisserant@393: 
etisserant@393: CANopen is a CAN based high level protocol. It defines some protocols
etisserant@393: to :
etisserant@393: 
nico@208: \begin{enumerate}
etisserant@393: \item Configure a CAN network. 
etisserant@393: \item Transmit data to a specific node or in broadcast. 
etisserant@393: \item Administrate the network. For example detecting a not responding node. 
nico@208: \end{enumerate}
etisserant@392: The documentation can be found on the CAN in Automation website :
nico@208: 
etisserant@393: \href{http://www.can-cia.de/canopen}{http://www.can-cia.de/canopen}
etisserant@393: 
etisserant@393: The most important document about \canopen is the normative CiA Draft
etisserant@393: Standard 301, version 4.02. You can now download the specification
etisserant@393: from the CAN in Automation website at no cost.
etisserant@393: 
etisserant@393: To continue reading this document, let us assume that you have read
etisserant@393: some papers introducing \canopen .
etisserant@393: 
nico@208: 
nico@208: \section{CanFestival Features}
etisserant@393: 
etisserant@393: 
nico@208: \subsection{Tools }
etisserant@393: 
etisserant@393: The \canopen library is coming with some tools :
etisserant@393: 
nico@208: \begin{enumerate}
etisserant@393: \item Object Dictionary editor GUI. WxPython Model-View-Controler based
etisserant@394: GUI, that helps a lot in generating object dictionary source code for
etisserant@393: each node. 
etisserant@393: \item A configure script, that let you chose compile time options such as
etisserant@393: target CPU/HOST, CAN and TIMER drivers.\\
etisserant@393:  This script has not been generated with autoconf, it has been made
etisserant@393: keeping micro-controller target in mind. 
nico@208: \end{enumerate}
etisserant@393: 
etisserant@394: \subsection{Multi-Platform}
etisserant@393: 
nico@208: \begin{enumerate}
etisserant@393: \item Library source code is C-ANSI. 
etisserant@393: \item Driver and examples coding conventions merely depend on target specific
etisserant@393: contributor/compiler. 
nico@208: \item Unix compatible interfaces and examples should compile and run on
etisserant@393: any Unix system (tested on GNU/Linux and GNU/FreeBSD). 
nico@208: \end{enumerate}
etisserant@393: 
etisserant@394: \subsection{\canopen standard conformance}
etisserant@394: 
etisserant@394: \subsubsection{DS-301}
etisserant@394: 
etisserant@394: Supported features should conform to DS301. V.4.02 13 february 2002. 
etisserant@393: 
nico@208: \begin{enumerate}
etisserant@394: \item NMT master and slave
etisserant@394: \item Heartbeat consumer and producer
etisserant@394: \item NodeGuard slave reponder and basic master without tracking
etisserant@394: \item SYNC service
etisserant@394: \item SDO multiples client and server, segmented and expedited
etisserant@394: \item PDO : TPDO and RPDO, with respect to transmission type
etisserant@394: \item PDO mapping from/to OD variables bit per bit. 
etisserant@394: \item EMCY : Send and receive and keeps track of emergency objects
etisserant@394: \item Data types : 8 to 64 bits values, fixed length strings.
nico@208: \end{enumerate}
etisserant@393: 
etisserant@394: \subsubsection{DS-302}
etisserant@394: 
etisserant@394: Only concise DFC is supported.
etisserant@393: 
nico@208: \section{How to start}
etisserant@393: 
nico@208: \subsection{Host requirements}
etisserant@393: 
nico@208: What you need on your development workstation.
nico@208: 
nico@208: \subsubsection{Object Dictionary Editor GUI}
etisserant@393: 
nico@208: \begin{enumerate}
nico@208: \item Python, with 
etisserant@394: \item wxPython modules installed (at least version 2.6.3).
etisserant@393: \item Gnosis xml tools. (Optional can also be installed locally to the project
etisserant@393: automatically with the help of a Makefile. Please see {}``Using Dictionary
etisserant@393: Editor GUI'' ) 
nico@208: \end{enumerate}
etisserant@393: 
etisserant@393: \subsubsection{Linux and Unix-likes}
etisserant@393: 
nico@208: \begin{enumerate}
etisserant@393: \item Linux, FreeBSD, Cygwin or any Unix environment with GNU toolchain. 
etisserant@393: \item The GNU C compiler (gcc) or any other ANSI-C compiler for your target
etisserant@393: platform. 
nico@208: \item Xpdf, and the official 301\_v04000201.pdf file in order to get GUI
etisserant@393: context sensitive help. 
etisserant@393: \item GNU Make 
etisserant@393: \item Bash and sed 
nico@208: \end{enumerate}
etisserant@393: 
nico@208: \subsubsection{Windows (for native win32 target)}
etisserant@393: 
nico@208: \begin{enumerate}
greg@464: \item Visual Studio Express 2005 or worst.
greg@464: \item Microsoft platform SDK (requires Genuine Advantage)
greg@464: \item Cygwin (for configuration only)
greg@464: \item MinGW/MSYS
nico@208: \end{enumerate}
etisserant@393: 
nico@208: \subsection{How to get CanFestival}
etisserant@393: 
nico@208: Please always use CVS, this is the best way to get the most reactive
nico@208: support from the developer community :
nico@208: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	cvs -d:pserver:anonymous@lolitech.dyndns.org:/canfestival login
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@394: (type return, without entering a password)
etisserant@394: 
etisserant@394: Then, enter :
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	cvs -z3 -d:pserver:anonymous@lolitech.dyndns.org:/canfestival co -P CanFestival-3
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@393: 
nico@208: 
nico@208: \section{Understanding Canfestival}
etisserant@393: 
nico@208: \subsection{CanFestival Project tree layout}
nico@208: Simplified directory structure.
etisserant@394: \begin{verbatim}
etisserant@394: ./src ANSI-C source of \canopen stack
etisserant@394: ./include Exportables Header files
etisserant@394: ./drivers Interfaces to specific platforms/HW
etisserant@394: ./drivers/unix Linux and Cygwin OS interface
etisserant@394: ./drivers/win32 Native Win32 OS interface
etisserant@394: ./drivers/timers_xeno Xenomai timers/threads (Linux only)
greg@454: ./drivers/timers_rtai Rtai timers/threads (Linux only)
etisserant@394: ./drivers/timers_kernel Linux kernel timer/threads
etisserant@394: ./drivers/timers_unix Posix timers/threads (Linux, Cygwin)
etisserant@394: ./drivers/can_virtual_kernel Fake CAN network (kernel space)
etisserant@448: ./drivers/can_serial Serial point to point and PTY hub (*nix only)
etisserant@394: ./drivers/can_peak_linux PeakSystem CAN library interface
etisserant@394: ./drivers/can_peak_win32 PeakSystem PCAN-Light interface
etisserant@394: ./drivers/can_uvccm_win32 Acacetus's RS232 CAN-uVCCM interface
etisserant@394: ./drivers/can_virtual Fake CAN network (Linux, Cygwin)
greg@464: ./drivers/can_vcom VScom VSCAN interface
etisserant@394: ./drivers/hcs12 HCS12 full target interface
etisserant@394: ./examples Examples
etisserant@394: ./examples/TestMasterSlave 2 nodes, NMT SYNC SDO PDO, win32+unix
etisserant@394: ./examples/TestMasterMicroMod 1 node, control Peak I/O Module, unix
etisserant@394: ./examples/gene_SYNC_HCS12 Just send periodic SYNC on HCS12
etisserant@394: ./examples/win32test Ask some DS301 infos to a node (win32)
etisserant@394: ./objdictgen Object Dictionary editor GUI
etisserant@394: ./objdictgen/config Pre-defined OD profiles
etisserant@394: ./objdictgen/examples Some examples/test OD
etisserant@394: ./doc Documentation source
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@393: 
nico@208: 
nico@208: \subsection{Implement CanFestival in your application}
etisserant@393: 
etisserant@393: \begin{center}
etisserant@393: \includegraphics[width=12cm]{Pictures/10000201000003F9000002CF880931E7} 
etisserant@393: \par\end{center}
etisserant@393: 
etisserant@393: \bigskip{}
etisserant@393: 
etisserant@393: 
nico@208: 
nico@208: \subsection{CanFestival CAN interfaces}
etisserant@393: 
nico@208: Because most CAN controllers and drivers implement FIFOs, CanFestival
etisserant@394: consider sending message as a non blocking operation.
nico@208: 
greg@464: In order to prevent reentrant calls to the stack, messages reception
etisserant@393: is implemented differently on {\textmu}C and OS.:
etisserant@393: 
nico@208: \begin{enumerate}
etisserant@394: \item {\textmu}C must provide interruption masking, mutually excluding timer and CAN receive interrupts.\\
etisserant@393: 
etisserant@393: 
etisserant@393: 
etisserant@393: \begin{center}
etisserant@393: \includegraphics[width=12cm]{Pictures/10000201000003CA0000016604E6A5EF} 
etisserant@393: \par\end{center}
etisserant@393: 
nico@208: \item OS must provide a receive thread, a timer thread and a mutex. CAN
greg@464: reception should be a blocking operation.\\
etisserant@393: 
etisserant@393: 
etisserant@393: 
etisserant@393: \begin{center}
etisserant@393: \includegraphics[width=12cm]{Pictures/10000201000003F9000002CF8B0CDAEA} 
etisserant@393: \par\end{center}
etisserant@393: 
nico@208: \end{enumerate}
etisserant@393: 
etisserant@394: \subsection{CanFestival event scheduling}
etisserant@393: 
etisserant@393: A \canopen node must be able to take delayed actions.
nico@208: 
etisserant@394: For instance, periodic sync emission, heartbeat production or SDO timeout
nico@208: need to set some alarms that will be called later and do the job.
nico@208: 
etisserant@394: {\textmu}C generally do not have enough free timers to handle all
etisserant@393: the \canopen needs directly. Moreover, CanFestival internal data
etisserant@393: may be corrupt by reentrant calls.
etisserant@393: 
etisserant@393: CanFestival implement a micro -scheduler (timer.c). It uses only one
nico@208: timer to mimic many timers. It manage an alarm table, and call alarms
nico@208: at desired time.
nico@208: 
nico@208: \begin{center}
etisserant@393: \includegraphics[width=12cm]{Pictures/100000000000022C000000DEDAD2140C} 
etisserant@393: \par\end{center}
etisserant@393: 
etisserant@393: Scheduler can handle short clock value ranges limitation found on
etisserant@393: some {\textmu}C. As an example, value range for a 16bit clock counter
etisserant@393: with 4{\textmu}s tick is crossed within 0.26 seconds... Long alarms
etisserant@393: must be segmented.
etisserant@393: 
etisserant@393: Chronogram illustrate a long alarm (A) and a short periodic alarm
etisserant@393: (B), with a A value {\textgreater} clock range {\textgreater}
etisserant@393: B value. Values t0...t8 are successive setTimer call parameter values.
etisserant@393: t1 illustrates an intermediate call to TimeDispatch, caused by a delay
etisserant@393: longer than clock range. Because of long alarm segmentation, at the
etisserant@393: end of t1, TimeDispatch call will not trig any alarm callback.
etisserant@393: 
etisserant@393: \begin{center}
etisserant@393: \includegraphics[width=12cm]{Pictures/1000000000000396000000FFC42573DA} 
etisserant@393: \par\end{center}
etisserant@393: 
nico@208: 
nico@208: \section{Linux Target}
etisserant@393: 
nico@208: Linux target is default configure target.
nico@208: 
etisserant@393: 
nico@208: \subsection{Linux Compilation and installation}
etisserant@393: 
etisserant@393: Call ./configure -- help to see all available compile time options.
nico@208: 
nico@208: After invoking ./configure with your platform specific switches, just
nico@208: type make.
nico@208: 
etisserant@394: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	./configure [options]
etisserant@394: 	make
etisserant@394: 	make install
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@394: 
etisserant@393: 
nico@208: 
nico@208: \subsubsection{Standard Linux node}
etisserant@393: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	./configure --timers=unix
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@393: 
etisserant@393: To do a \canopen node running on PC -Linux, you need :
etisserant@393: 
nico@208: \begin{enumerate}
etisserant@393: \item A working linux distribution 
etisserant@393: \item One or more Peak system PC CAN interface and the last Peak Linux driver
etisserant@393: installed. 
nico@208: \end{enumerate}
etisserant@393: 
etisserant@393: \subsubsection{Real -Time Linux node}
etisserant@393: 
greg@454: With Xenomai :
etisserant@394: \begin{verbatim}
etisserant@394: 	./configure --timers=xeno
etisserant@394: \end{verbatim}
greg@454: With Rtai :
greg@454: \begin{verbatim}
greg@454: 	./configure --timers=rtai
greg@454: \end{verbatim}
etisserant@393: 
etisserant@393: To do a \canopen node running on PC -Linux, you need :
etisserant@393: 
nico@208: \begin{enumerate}
greg@454: \item A working Linux distribution patched with XENOMAI (2.1 or greater) or RTAI (3.6). 
etisserant@393: \item One or more Peak system PC CAN interface and the last Peak Real Time
etisserant@393: Linux driver installed. 
nico@208: \end{enumerate}
etisserant@391: 
etisserant@391: \subsubsection{Linux kernel node}
etisserant@393: 
etisserant@391: To do a CANopen node running on PC-Linux in kernel space, you need:
etisserant@391: 
etisserant@393: 
etisserant@394: \begin{enumerate}
etisserant@394: \item A working Linux distribution with pre-built 2.6.x.x kernel sources
etisserant@394: \item A CAN card driver compatible with CanFestival
etisserant@394: \end{enumerate}
etisserant@391: 
etisserant@393: 
nico@208: \subsubsection{CAN devices}
etisserant@394: Currently supported CAN devices and corresponding configure switch:
nico@208: 
nico@208: \paragraph{Peak systems}
etisserant@394: \begin{verbatim}
etisserant@394: 	./configure --can=peak_linux
etisserant@394: \end{verbatim}
etisserant@393: PeakSystems CAN interface is automatically chosen as default CAN interface
etisserant@393: if libpcan is present in the system.
etisserant@393: 
etisserant@393: Please download driver at \href{http://www.peak-system.com/linux}{http://www.peak
etisserant@393: -system.com/linux} and follow instructions in order to install driver
etisserant@393: on your system.
etisserant@393: 
greg@464: \paragraph{Socket-Can (http://socketcan.berlios.de)}
etisserant@394: \begin{verbatim}
etisserant@394: 	./configure --can=socket
etisserant@394: \end{verbatim}
etisserant@393: 
etisserant@448: \paragraph{Serial}
etisserant@448: \begin{verbatim}
etisserant@448: 	./configure --can=serial
etisserant@448: \end{verbatim}
etisserant@448: The CAN serial driver implements a 1:1 serial connection between 2 CAN devices.
etisserant@448: For example, you can connect 2 CANFestival applications via a NULL modem cable.
etisserant@448: 
etisserant@448: Also with this driver comes a software hub, for up to 16 CANFestival apps to 
etisserant@448: be connected on a single PC, with an optional connection to another CAN driver.
etisserant@448: Note that only the serial driver is supported at this time.  The hub uses ptys 
etisserant@448: (pseudo ttys) available on a *nix like system.
etisserant@448: 
nico@208: \paragraph{LinCan}
etisserant@394: \begin{verbatim}
etisserant@394: 	./configure --can=lincan
etisserant@394: \end{verbatim}
etisserant@393: 
nico@208: \paragraph{Virtual CAN interfaces (for test/debug)}
etisserant@394: \begin{verbatim}
etisserant@394: 	./configure --can=virtual
etisserant@394: 		or, for kernel space:
etisserant@394: 	./configure --can=kernel_virtual
etisserant@394: \end{verbatim}
nico@208: Virtual CAN interface use Unix pipes to emulate a virtual CAN network.
nico@208: Each message issued from a node is repeat to all other nodes. Currently
nico@208: only works with nodes running in the same process, and does not support
greg@464: work with Xenomai or RTAI.
greg@464: 
greg@464: \paragraph{VScom}
greg@464: \begin{verbatim}
greg@464: 	./configure --can=vscom
greg@464: \end{verbatim}
greg@464: 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.
nico@208: \subsection{Testing your CanFestival installation}
etisserant@393: 
etisserant@394: \subsection{User space}
etisserant@394: 
nico@208: Sample provided in /example/TestMasterSlave is installed into your
nico@208: system during installation.
nico@208: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	TestMasterSlave
etisserant@394: \end{verbatim}
etisserant@394: 
nico@208: 
etisserant@392: Default CAN driver library is libcanfestival\_can\_virtual.so., which
nico@208: will simply pass CAN messages through Unix pipes between Master and
etisserant@393: Slave.
etisserant@393: 
etisserant@393: You may also want to specify different can interface and define some
etisserant@393: CAN ports. Another example using Peak{\textquotesingle}s dual PCMCIA
etisserant@393: (configure and install with --can=peak) :
etisserant@393: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	TestMasterSlave -l libcanfestival_can_peak.so -s 40 -m 41
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@394: 
etisserant@394: \subsection{Kernel space}
etisserant@394: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	example/kerneltest
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@394: 
etisserant@394: It's based on TestMasterSlave example
etisserant@393: and has the same functionality. Uses virtual can driver as default
etisserant@394: too. After successful installation you can insert the module by typing:
etisserant@393: modprobe canf\_ktest Module control is done by simple console 'canf\_ktest\_console'
etisserant@393: which is used to start/stop sending data.
etisserant@393: 
etisserant@391: 
nico@208: \section{Windows Targets}
etisserant@393: 
nico@208: CanFestival can be compiled and run on Windows platform. It is possible
nico@208: to use both Cygwin and win32 native runtime environment.
nico@208: 
nico@208: \subsection{Object Dictionary Editor GUI installation.}
etisserant@393: 
etisserant@393: Please refer to \hyperlink{a821UsingDictionaryEditorGUIoutline}{8.2.1)Using
etisserant@393: Dictionary Editor GUI}
etisserant@393: 
nico@208: \subsection{CYGWIN}
etisserant@393: 
nico@208: \subsubsection{Requirements}
etisserant@393: 
nico@208: Cygwin have to be installed with those packages :
nico@208: 
nico@208: \begin{enumerate}
etisserant@393: \item gcc 
etisserant@393: \item unzip 
etisserant@393: \item wget 
etisserant@393: \item make 
nico@208: \end{enumerate}
nico@208: Currently, the only supported CAN devices are PeakSystems ones, with
etisserant@393: PcanLight driver and library.
etisserant@393: 
etisserant@393: Please download driver at \href{http://www.peak-system.com/themen/download_gb.html}{http://www.peak
etisserant@393: -system.com/themen/download\_gb.html} \ and follow instructions
etisserant@393: in order to install driver on your system.
nico@208: 
nico@208: Install Cygwin as required, and the driver for your Peak CAN device.
nico@208: 
nico@208: Open a Cygwin terminal, and follow those instructions:
nico@208: 
etisserant@393: 
nico@208: \subsubsection{Cygwin configuration and compilation}
etisserant@393: 
etisserant@393: 
etisserant@393: \paragraph{A single node with PcanLight and Peak CAN -USB adapter}
etisserant@393: 
etisserant@394: Download the PCAN-Light Zip file for your HW ( URL from download
etisserant@393: page ):
etisserant@393: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	wget http://www.peak -system.com/files/usb.zip
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@393: 
etisserant@393: Extract its content into your cygwin home (it will create a {}``Disk''
nico@208: directory):
nico@208: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	unzip usb.zip
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@393: 
etisserant@393: Configure CanFestival3 providing path to the desired PcanLight implementation:
etisserant@393: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	cd CanFestival -3
etisserant@394: 	export PCAN_INCLUDE=~/Disk/PCAN-Light/Api/
etisserant@394: 	export PCAN_HEADER=Pcan_usb.h
etisserant@394: 	export PCAN_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_usb.lib
etisserant@394: 	./configure --can=peak_win32
etisserant@394: 	make
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@393: 
etisserant@393: In order to test, you have to use another CanFestival node, connect
etisserant@393: with a CAN cable.
etisserant@393: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	cp ~/Disk/PCAN-Light/Pcan_usb.dll .
etisserant@394: 	./examples/TestMasterSlave/TestMasterSlave \
etisserant@394: 	-l drivers/can\_peak\_win32/cygcan\_peak\_win32.dll \
etisserant@394: 	-S 500K -M none
etisserant@394: \end{verbatim}
etisserant@394: 
nico@208: 
nico@208: Then, on the other node :
nico@208: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	./TestMasterSlave -l my_driver.so -S none -M 500K
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@394: 
etisserant@394: Now messages are being exchanged between master and slave node.
etisserant@393: 
etisserant@393: \paragraph{Two nodes with PcanLight and Peak dual PCMCIA -CAN adapter}
etisserant@393: 
etisserant@394: Download the PCAN-Light Zip file for your HW ( URL from download
etisserant@393: page ):
etisserant@393: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	wget http://www.peak-system.com/files/pccard.zip
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@393: 
etisserant@393: Extract its content into your cygwin home (it will create a {}``Disk''
nico@208: directory):
nico@208: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	unzip pccard.zip
etisserant@394: \end{verbatim}
etisserant@394: 
nico@208: 
nico@208: The configure CanFestival3 providing path to the desired PcanLight
nico@208: implementation:
nico@208: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	export PCAN_INCLUDE=~/Disk/PCAN-Light/Api/
etisserant@394: 	export PCAN_HEADER=Pcan_pcc.h
etisserant@394: 	export PCAN_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_pcc.lib
etisserant@394: 	export PCAN2_HEADER=Pcan_2pcc.h
etisserant@394: 	export PCAN2_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_2pcc.lib
etisserant@394: \end{verbatim}
etisserant@394: 
nico@208: 
nico@208: In order to test, just connect together both CAN ports of the PCMCIA
nico@208: card. Don{\textquotesingle}t forget 120ohms terminator.
nico@208: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	cp ~/Disk/PCAN-Light/Pcan_pcc.dll .
etisserant@394: 	cp ~/Disk/PCAN-Light/Pcan_2pcc.dll .
etisserant@394: 	./examples/TestMasterSlave/TestMasterSlave \
etisserant@394: 	   -l drivers/can_peak_win32/cygcan_peak_win32.dll
etisserant@394: \end{verbatim}
etisserant@394: 
nico@208: 
nico@208: Messages are then exchanged between master and slave node, both inside
nico@208: TestMasterSlave{\textquotesingle}s process.
nico@208: 
nico@208: \subsection{Visual Studio C++}
etisserant@393: 
nico@208: \subsubsection{Requirements}
etisserant@393: 
nico@208: Minimal Cygwin installation is required at configuration time in order
nico@208: to create specific header files (config.h and cancfg.h). Once this
nico@208: files created, cygwin is not necessary any more.
nico@208: 
nico@208: Project and solution files have been created and tested with Visual
etisserant@393: Studio Express 2005. Be sure to have installed Microsoft Platform
etisserant@393: SDK, as recommended at the end of Visual Studio installation.
etisserant@393: 
nico@208: 
nico@208: \subsubsection{Configuration with cygwin}
etisserant@393: 
etisserant@393: Follow instructions given at \hyperlink{Cygwin configuration and compilation}{Cygwin
nico@208: configuration and compilation}, but do neither call make nor do tests,
nico@208: just do configuration steps. This will create headers files accordingly
nico@208: to your configuration parameters, and the desired CAN hardware.
nico@208: 
etisserant@393: 
nico@208: \subsubsection{Compilation with Visual Studio}
etisserant@393: 
etisserant@394: You can either load independent {}``{*}.vcproj'' project files
etisserant@393: along your own projects in your own solution or load the provided
etisserant@393: {}``CanFestival -3.vc8.sln'' solution files directly.
etisserant@393: 
etisserant@393: Build CanFestival -3 project first.
etisserant@393: 
nico@208: 
nico@208: \paragraph{PcanLight and the can\_peak\_win32 project.}
etisserant@393: 
nico@208: Chosen Pcan\_xxx.lib and eventually Pcan\_2xxx.lib files must be added
etisserant@393: to can\_peak\_win32 \ \ project before build of the DLL.
etisserant@393: 
nico@208: 
nico@208: \subsubsection{Testing}
etisserant@393: 
etisserant@393: Copy eventually needed dlls (ie : Pcan\_Nxxx.lib) into Release or
etisserant@393: Debug directory, and run the test program:
etisserant@393: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	TestMasterSlave.exe -l can_peak_win32.dll
etisserant@394: \end{verbatim}
etisserant@393: 
nico@208: 
greg@282: \subsection{MSYS}
greg@282: 
greg@282: 
greg@282: \subsubsection{Requirements}
greg@282: 
greg@282: Download from : http://sourceforge.net/project/showfiles.php?group\_id=2435
greg@282: 
greg@282: \begin{enumerate}
etisserant@393: \item MSYS-1.0.10.exe 
etisserant@393: \item MinGW-5.1.3.exe 
etisserant@393: \item mingwPORT (which contains wget-1.9.1) 
greg@282: \end{enumerate}
greg@282: Please download driver at http://www.peak-system.com/themen/download\_gb.html
greg@282: and follow instructions in order to install driver on your system.
greg@282: Install MSYS and MingW as required, and the driver for your Peak CAN
greg@282: device. Open a MSYS terminal, and follow those instructions:\\
greg@282: 
greg@282: 
greg@282: \begin{itemize}
etisserant@393: \item extract wget-1.9.1-mingwPORT.tar.bz2 
etisserant@393: \item copy wget.exe in c:\textbackslash{} msys\textbackslash{} 1.0\textbackslash{}
etisserant@393: bin\textbackslash{} 
greg@282: \item start MSYS and check the file /etc/fstab contain the line c:/MinGW
etisserant@393: /mingw 
greg@282: \end{itemize}
greg@282: 
greg@282: \subsubsection{MSYS configuration and compilation}
greg@282: 
etisserant@393: Instructions for compilation are nearly the same as CYGWIN part.
greg@282: 
greg@282: 
greg@282: \paragraph{A single node with PcanLight and Peak CAN-USB adapter}
greg@282: 
greg@282: Download the PCAN-Light Zip file for your HW ( URL from download page
greg@282: ):
greg@282: 
etisserant@394: \begin{verbatim}
etisserant@394: 	wget http://www.peak-system.com/files/usb.zip
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@393: Extract its content into your MSYS's home (it will create a \char`\"{}
etisserant@393: Disk\char`\"{} directory):
etisserant@393: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	unzip usb.zip
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@394: 
greg@282: Configure CanFestival3 providing path to the desired PcanLight implementation:
greg@282: 
etisserant@394: \begin{verbatim}
etisserant@394: 	cd CanFestival-3
etisserant@394: 	export PCAN_INCLUDE=~/Disk/PCAN-Light/Api/
etisserant@394: 	export PCAN_HEADER=Pcan_usb.h
etisserant@394: 	export PCAN_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_usb.lib
etisserant@394: 	./configure --can=peak_win32
etisserant@394: 	make
etisserant@394: \end{verbatim}
etisserant@394: 
greg@282: In order to test, you have to use another CanFestival node, connect
greg@282: with a CAN cable.
greg@282: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	cp ~/Disk/PCAN-Light/Pcan_usb.dll .
etisserant@394: 	./examples/TestMasterSlave/TestMasterSlave \
etisserant@394: 	  -l drivers/can_peak_win32/cygcan_peak_win32.dll \
etisserant@394: 	  -S 500K -M none
etisserant@394: \end{verbatim}
etisserant@394: 
greg@282: Then, on the other node :
greg@282: 
etisserant@394: \begin{verbatim}
etisserant@394: 	./TestMasterSlave -l my_driver.so -S none -M 500K -m 0
etisserant@394: \end{verbatim}
etisserant@394: Now messages are being exchanged between master and slave node.
greg@282: 
greg@282: 
greg@282: \paragraph{Two nodes with PcanLight and Peak dual PCMCIA-CAN adapter}
greg@282: 
greg@282: Download the PCAN-Light Zip file for your HW ( URL from download page
greg@282: ):
greg@282: 
etisserant@394: \begin{verbatim}
etisserant@394: 	wget http://www.peak-system.com/files/pccard.zip
etisserant@394: \end{verbatim}
etisserant@393: Extract its content into your MSYS's home (it will create a \char`\"{}
etisserant@393: Disk\char`\"{} directory):
etisserant@393: 
etisserant@394: \begin{verbatim}
etisserant@394: 	unzip pccard.zip
etisserant@394: \end{verbatim}
greg@282: The configure CanFestival3 providing path to the desired PcanLight
etisserant@393: implementation:
etisserant@393: 
etisserant@394: \begin{verbatim}
etisserant@394: 	export PCAN_INCLUDE=~/Disk/PCAN-Light/Api/
etisserant@394: 	export PCAN_HEADER=Pcan_pcc.h}
etisserant@394: 	export PCAN_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_pcc.lib
etisserant@394: 	export PCAN2_HEADER=Pcan_2pcc.h
etisserant@394: 	export PCAN2_LIB=~/Disk/PCAN-Light/Lib/Visual\ C++/Pcan_2pcc.lib
etisserant@394: \end{verbatim}
etisserant@394: 
greg@282: In order to test, just connect together both CAN ports of the PCMCIA
greg@282: card. Don't forget 120ohms terminator.
greg@282: 
etisserant@394: \begin{verbatim}
etisserant@394: 	cp~/Disk/PCAN-Light/Pcan_pcc.dll ~.
etisserant@394: 	cp ~/Disk/PCAN-Light/Pcan_2pcc.dll ~.
etisserant@394: 	./examples/TestMasterSlave/TestMasterSlave \
etisserant@394: 		-l drivers/can\_peak\_win32/cygcan\_peak\_win32.dll -m 0 -s 1
etisserant@394: \end{verbatim}
greg@282: Messages are then exchanged between master and slave node, both inside
greg@282: TestMasterSlave's process.
greg@282: 
nico@208: \section{Motorola HCS12}
etisserant@393: 
etisserant@393: The examples have been tested on a MC9S12DG255 mounted on a Elektronikladen
etisserant@393: HCS12 T -board.
etisserant@393: 
etisserant@393: Beware that there are few differences in the MSCAN module of the 68HC12
etisserant@393: and HCS12 microcontroller. For a HC12, you must adapt the driver that
etisserant@393: we provide for \ the HCS12.
etisserant@393: 
etisserant@393: For the difference MSCAN HC12/HCS12, see the Motorola application
etisserant@393: note AN2011/D.
nico@208: 
nico@208: Configure switch:
nico@208: 
etisserant@394: \begin{verbatim}
etisserant@394: 	--target=hcs12
etisserant@394: \end{verbatim}
etisserant@393: 
etisserant@393: To do a \canopen node running on a microncontroller Motorola MC9S12DP256,
nico@208: you need :
nico@208: 
nico@208: \begin{enumerate}
etisserant@393: \item The compiler GNU gcc for HC11, HC12, HCS12 : m6811 -elf. \\
etisserant@393:  Download the \textbf{release 3.1} at : \href{http://m68hc11.serveftp.org/m68hc11_pkg_rpm.php}{http://m68hc11.serveftp.org/m68hc11\_pkg\_rpm.php} 
etisserant@394: \item A board with this chip. We are using the T -board from Electronikladen. 
etisserant@393: \item At least about 40 kBytes of program memory. 
etisserant@394: \item A tool to flash the memory. (We are using the high cost Lauterbach
etisserant@393: debugger). 
nico@208: \end{enumerate}
etisserant@393: 
nico@208: \subsection{Running a HCS12 node}
etisserant@393: 
etisserant@393: 
nico@208: \subsubsection{Compiling Canfestival:}
etisserant@393: 
etisserant@394: \begin{verbatim}
etisserant@394: 	./configure --target=hcs12
etisserant@394: \end{verbatim}
etisserant@393: 
nico@208: 
nico@208: \subsubsection{Compiling and building an example}
etisserant@393: 
etisserant@393: Enter in the folder of an HCS12 example,
etisserant@393: 
etisserant@394: \begin{verbatim}
etisserant@394: 	make all
etisserant@394: \end{verbatim}
etisserant@393: 
nico@208: 
nico@208: \subsubsection{Flashing the memory :}
etisserant@393: 
etisserant@394: Use your preferred loader ! If you are using a debugger Lauterbach,
etisserant@393: you can load the bash file : trace32\_flash\_programmer.cmm. It loads
nico@208: directly the elf file.
nico@208: 
etisserant@393: 
nico@208: \subsubsection{Connecting to a serial RS232 console :}
etisserant@393: 
nico@208: Connect the portS(TxD0) of the HCS12 to a console configured at 19200
etisserant@394: bauds 8N1, via a Max232 chip to adapt the electrical levels. On Linux,
etisserant@394: you can use minicom. Connecting to a console is useful to read the
nico@208: messages, but not required.
nico@208: 
etisserant@393: 
nico@208: \subsubsection{Connecting to the CAN network :}
etisserant@393: 
etisserant@393: Connect the port CAN0 (pin PM0, PM1) to the network via a CAN controller.
etisserant@394: On our board, the CAN controller is a PCA82C250 chip.
etisserant@393: 
nico@208: 
nico@208: \subsubsection{starting the node :}
etisserant@393: 
nico@208: Press the reset of your HCS12 board.
nico@208: 
etisserant@393: 
nico@208: \section{Example and test program:}
etisserant@393: 
etisserant@393: The {}``examples'' directory contains some test program you can
etisserant@393: use as example for your own developments.
etisserant@393: 
nico@208: 
nico@208: \subsection{TestMasterSlave}
etisserant@393: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394:   **************************************************************
etisserant@394:   *  TestMasterSlave                                           *
etisserant@394:   *                                                            *
etisserant@394:   *  A simple example for PC. It does implement 2 CanOpen      *
etisserant@394:   *  nodes in the same process. A master and a slave. Both     *
etisserant@394:   *  communicate together, exchanging periodically NMT, SYNC,  *
etisserant@394:   *  SDO and PDO. Master configure heartbeat producer time     *
etisserant@394:   *  at 1000 ms for slave node-id 0x02 by concise DCF.         *                                  
etisserant@394:   *                                                            *
etisserant@394:   *   Usage:                                                   *
etisserant@394:   *   ./TestMasterSlave  [OPTIONS]                             *
etisserant@394:   *                                                            *
etisserant@394:   *   OPTIONS:                                                 *
etisserant@394:   *     -l : Can library ["libcanfestival_can_virtual.so"]     *
etisserant@394:   *                                                            *
etisserant@394:   *    Slave:                                                  *
etisserant@394:   *     -s : bus name ["0"]                                    *
etisserant@394:   *     -S : 1M,500K,250K,125K,100K,50K,20K,10K,none(disable)  *
etisserant@394:   *                                                            *
etisserant@394:   *    Master:                                                 *
etisserant@394:   *     -m : bus name ["1"]                                    *
etisserant@394:   *     -M : 1M,500K,250K,125K,100K,50K,20K,10K,none(disable)  *
etisserant@394:   *                                                            *
etisserant@394:   **************************************************************
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@394: 
etisserant@394: Notes aboute use of voncise DCF :
etisserant@394: 
etisserant@394: In this example, Master configure heartbeat producer time
etisserant@393: at 1000 ms for slave node -id 0x02 by concise DCF according DS -302
etisserant@394: profile.
etisserant@394: 
etisserant@394: Index 0x1F22, sub-index 0x00 of the master OD, correspond
etisserant@393: to the number of entries. This equal to the maximum possible nodeId
etisserant@393: (127). Each sub -index points to the Node -ID of the device, to which
etisserant@394: the configuration belongs.
etisserant@394: 
etisserant@394: To add more parameters configurations to the slave, the value
etisserant@393: at sub -index 0x02 must be a binary stream (little -endian) following
etisserant@394: this structure :
etisserant@394: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 
etisserant@394: 	 (UNS32) nb of entries
etisserant@394: 	 (UNS16) index parameter 1
etisserant@394: 	 (UNS8) sub -index parameter 1
etisserant@394: 	 (UNS32) size data parameter 1
etisserant@394: 	 (DOMAIN) data parameter 1
etisserant@394: 	 (UNS16) index parameter 2
etisserant@394: 	 (UNS8) sub -index parameter 2
etisserant@394: 	 (UNS32) size data parameter 2
etisserant@394: 	 (DOMAIN) data parameter 2
etisserant@394: 	      ....
etisserant@394: 	 (UNS16) index parameter n
etisserant@394: 	 (UNS8) sub -index parameter n
etisserant@394: 	 (UNS32) size data parameter n
etisserant@394: 	 (DOMAIN) data parameter n
etisserant@394: 	 
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@394: 
etisserant@394: So the binary value stream to configure heartbeat producer
etisserant@394: time must be :
etisserant@394: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	0100000017100002000000e803
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@394: 
etisserant@394: The slave node is configured just before the Master entering
etisserant@394: in Pre\_operational state.
etisserant@393: 
nico@208: 
nico@208: \subsection{gene\_SYNC\_HCS12 :}
etisserant@393: 
etisserant@393: This is a simple \canopen node that only send cyclic SYNC message.
etisserant@393: It demonstrate implementation on HCS12 based board.
etisserant@393: 
etisserant@393: \bigskip{}
etisserant@393: 
etisserant@393: 
etisserant@393: 
etisserant@391: \subsection{kerneltest :}
etisserant@391: 
etisserant@393: Example based on TestMasterSlave slightly modified to suit kernel
etisserant@393: space requisites. It will do the same as TestMasterSlave but in kernel
etisserant@393: space sending kernel messages (displayed by dmesg for example). It
etisserant@393: is designed as external kernel module implemented as character device.
etisserant@393: There is a shell script called 'insert.sh', which will insert the
etisserant@393: module and create a new device file /dev/canf\_ktest (used to sending
etisserant@393: commands to module). To actual sending commands you can use simple
etisserant@393: console named 'canf\_ktest\_console'. The module is dependent on a
etisserant@393: another separate module 'canfestival.ko' implementing CanOpen stack
etisserant@393: which exports requisite functions. Canfestival.ko module is then dependent
etisserant@393: on CAN card driver module, by default CAN virtual driver will be loaded.
etisserant@393: After installing modules (make install), all dependencies are solved
etisserant@394: automatically by kernel. To run the example type: 
etisserant@394: \begin{verbatim}
etisserant@394: 	sh run.sh
etisserant@394: \end{verbatim}
etisserant@393: It will insert required modules, start console, and after quitting
etisserant@393: console it'll remove modules from kernel.
etisserant@393: 
etisserant@393: \bigskip{}
etisserant@393: 
etisserant@393: 
nico@208: 
nico@208: \subsection{TestMasterMicroMod }
etisserant@393: 
etisserant@394: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394:   **************************************************************
etisserant@394:   *  TestMasterMicroMod                                        *
etisserant@394:   *                                                            *
etisserant@394:   *  A simple example for PC.                                  *
etisserant@394:   *  A CanOpen master that control a MicroMod module:          *
etisserant@394:   *  - setup module TPDO 1 transmit type                       *
etisserant@394:   *  - setup module RPDO 1 transmit type                       *
etisserant@394:   *  - setup module hearbeatbeat period                        *
etisserant@394:   *  - disable others TPDOs                                    *
etisserant@394:   *  - set state to operational                                *
etisserant@394:   *  - send periodic SYNC                                      *
etisserant@394:   *  - send periodic RPDO 1 to Micromod (digital output)       *
etisserant@394:   *  - listen Micromod's TPDO 1 (digital input)                *
etisserant@394:   *  - Mapping RPDO 1 bit per bit (digital input)              *
etisserant@394:   *                                                            *
etisserant@394:   *   Usage:                                                   *
etisserant@394:   *   ./TestMasterMicroMod  [OPTIONS]                          *
etisserant@394:   *                                                            *
etisserant@394:   *   OPTIONS:                                                 *
etisserant@394:   *     -l : Can library ["libcanfestival_can_virtual.so"]     *
etisserant@394:   *                                                            *
etisserant@394:   *    Slave:                                                  *
etisserant@394:   *     -i : Slave Node id format [0x01 , 0x7F]                *
etisserant@394:   *                                                            *
etisserant@394:   *    Master:                                                 *
etisserant@394:   *     -m : bus name ["1"]                                    *
etisserant@394:   *     -M : 1M,500K,250K,125K,100K,50K,20K,10K                *
etisserant@394:   *                                                            *
etisserant@394:   **************************************************************
etisserant@394: \end{verbatim}
etisserant@393: 
nico@208: 
nico@208: \section{Developing a new node}
etisserant@393: 
etisserant@393: Using provided examples as a base for your new node is generally a
etisserant@393: good idea. You can also use the provided {*}.od files as a base for
etisserant@393: your node object dictionary.
etisserant@393: 
etisserant@393: Creating a new \canopen node implies to define the Object Dictionary
etisserant@393: of this node. For that, developer has to provide a C file. This C
etisserant@393: file contains the definition of all dictionary entries, and some kind
etisserant@393: of index table that helps the stack to access some entries directly.
etisserant@393: 
nico@208: 
nico@208: \subsection{Using Dictionary Editor GUI}
etisserant@393: 
etisserant@393: The Object Dictionary Editor is a WxPython based GUI that is used
etisserant@393: to create the C file needed to create a new \canopen node.
etisserant@393: 
nico@208: 
nico@208: \subsubsection{Installation and usage on Linux}
etisserant@393: 
nico@208: You first have to download and install Gnosis XML modules. This is
nico@208: automated by a Makefile rule.
nico@208: 
etisserant@394: \begin{verbatim}
etisserant@394: 	cd objdictgen 
etisserant@394: 	make
etisserant@394: \end{verbatim}
nico@208: 
nico@208: Now start the editor.
nico@208: 
etisserant@394: \begin{verbatim}
etisserant@394: 	python objdictedit.py [od files...]
etisserant@394: \end{verbatim}
etisserant@393: 
nico@208: 
nico@208: \subsubsection{Installation and usage on Windows}
etisserant@393: 
nico@208: Install Python (at least version 2.4) and wxPython (at least version
nico@208: 2.6.3.2).
nico@208: 
nico@208: Cygwin users can install Gnosis XML utils the same as Linux use. Just
nico@208: call make.
nico@208: 
etisserant@394: \begin{verbatim}
etisserant@394: 	cd objdictgen
etisserant@394: 	make
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@394: Others will have to download and install Gnosis XML by hand :
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	Gnosis Utils:
etisserant@394: 	http://freshmeat.net/projects/gnosisxml/
etisserant@394: 	http://www.gnosis.cx/download/
etisserant@394: 	Get latest version.
etisserant@394: \end{verbatim}
etisserant@393: 
etisserant@393: Download CanFestival archive and uncompress it. Use windows file explorer
etisserant@393: to go into CanFestival3\textbackslash{}objdicgten, and double -click
etisserant@393: on objdictedit.py.
etisserant@393: 
nico@208: \subsubsection{About}
etisserant@393: 
etisserant@393: The Object Dictionary editor GUI is a python application that use
etisserant@393: the Model-View-Controller design pattern. It depends on WxPython to
nico@208: display view on any supported platform.
nico@208: 
etisserant@393: \begin{center}
etisserant@393: \includegraphics[width=7cm]{Pictures/10000201000001FC000001E5D65E8766} 
etisserant@393: \par\end{center}
etisserant@393: 
nico@208: 
nico@208: \subsubsection{Main view}
etisserant@393: 
nico@208: Top list let you choose dictionary section, bottom left list is the
nico@208: selected index in that dictionary, and bottom right list are edited
etisserant@393: sub -indexes.
etisserant@393: 
etisserant@393: \begin{center}
etisserant@393: \includegraphics[width=12cm]{Pictures/10000201000003E7000001C7B0296577} 
etisserant@393: \par\end{center}
etisserant@393: 
etisserant@393: \begin{center}
etisserant@393: \includegraphics[width=3cm]{Pictures/10000000000000B6000000DF1EDD1E73} 
etisserant@393: \par\end{center}
etisserant@393: 
etisserant@393: \begin{center}
etisserant@393: \includegraphics[width=3cm]{Pictures/10000000000000AC000000C9C3F53FA6} 
etisserant@393: \par\end{center}
etisserant@393: 
etisserant@393: \begin{center}
etisserant@393: \includegraphics[width=3cm]{Pictures/100000000000006D000000A31EC8CB54} 
etisserant@393: \par\end{center}
etisserant@393: 
etisserant@393: \begin{center}
etisserant@393: \includegraphics[width=3cm]{Pictures/10000000000000AA0000006014F74635} 
etisserant@393: \par\end{center}
etisserant@393: 
nico@208: 
nico@208: \subsubsection{New node}
etisserant@393: 
etisserant@440: Edit your node name and type. Choose your inherited specific profile.
etisserant@440: 
etisserant@440: \begin{center}
etisserant@440: \includegraphics[width=11cm]{Pictures/new_node} 
etisserant@393: \par\end{center}
etisserant@393: 
nico@208: 
nico@208: \subsubsection{Node info}
etisserant@393: 
etisserant@440: Edit your node name and type.
etisserant@440: 
etisserant@440: \begin{center}
etisserant@440: \includegraphics[width=7cm]{Pictures/node_info} 
etisserant@393: \par\end{center}
etisserant@393: 
nico@208: 
nico@208: \subsubsection{Profile editor}
etisserant@393: 
etisserant@393: Chose the used profile to edit.
etisserant@393: 
etisserant@393: \begin{center}
etisserant@393: \includegraphics[width=4cm]{Pictures/10000000000000AB000000C88F594413} 
etisserant@393: \par\end{center}
etisserant@393: 
etisserant@393: Pick up optional chosen profile entries.
etisserant@393: 
etisserant@393: \begin{center}
etisserant@393: \includegraphics[width=11cm]{Pictures/10000201000002DE000001D82D89C224} 
etisserant@393: \par\end{center}
etisserant@393: 
nico@208: 
nico@208: \subsubsection{User types}
etisserant@393: 
etisserant@394: Use User Types to implement value boundaries, and string length
etisserant@393: 
etisserant@393: \begin{center}
etisserant@393: \includegraphics[width=11cm]{Pictures/10000201000001C40000010766961D7F} 
etisserant@393: \par\end{center}
etisserant@393: 
nico@208: 
nico@208: \subsubsection{Mapped variable}
etisserant@393: 
etisserant@393: Add your own specific dictionary entries and associated mapped variables.
etisserant@393: 
etisserant@393: \begin{center}
etisserant@393: \includegraphics[width=11cm]{Pictures/10000201000001C4000000DD129D4661} 
etisserant@393: \par\end{center}
etisserant@393: 
nico@208: 
nico@208: \subsubsection{Integrated help}
etisserant@393: 
etisserant@393: Using F1 key, you can get context sensitive help.
etisserant@393: 
etisserant@393: \begin{center}
etisserant@393: \includegraphics[width=12cm]{Pictures/10000201000002F30000020B23ED7F67} 
etisserant@393: \par\end{center}
nico@208: 
nico@208: In order to do that, official 301\_v04000201.pdf file must be placed
nico@208: into doc/ directory, and xpdf must be present on your system.
nico@208: 
etisserant@393: F2 key open HTML CanFestival help.
etisserant@393: 
etisserant@393: \begin{center}
etisserant@393: \includegraphics[width=12cm]{Pictures/10000201000003440000025ACC3FD2F1} 
etisserant@393: \par\end{center}
etisserant@393: 
nico@208: 
nico@208: \subsection{Generating the object Dictionary}
etisserant@393: 
nico@208: Once object dictionary has been edited and saved, you have to generate
nico@208: object dictionary C code for your CanFestival node.
nico@208: 
etisserant@393: 
nico@208: \subsubsection{With GUI}
etisserant@393: 
etisserant@393: Menu entry {}``File/Build Dictionary''.
etisserant@393: 
etisserant@393: \begin{center}
etisserant@393: \includegraphics[width=4cm]{Pictures/10000201000000B7000000C66AF89CD5} 
etisserant@393: \par\end{center}
nico@208: 
nico@208: Choose C file to create or overwrite. Header file will be also created
nico@208: with the same prefix as C file.
nico@208: 
etisserant@393: 
nico@208: \subsubsection{With command line}
etisserant@393: 
etisserant@394: \begin{verbatim}
etisserant@394: 	Usage of objdictgen.py :
etisserant@394: 	python objdictgen.py XMLFilePath CfilePath
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@393: 
nico@208: 
nico@208: \section{FAQ}
etisserant@393: 
etisserant@393: 
nico@208: \subsection{General}
etisserant@393: 
etisserant@393: 
nico@208: \subsubsection{Does the code compiles on Windows ?}
etisserant@393: 
etisserant@393: Yes, with both Cygwin and Visual Studio C++. 
etisserant@393: 
etisserant@393: Because \canopen layer is coded with C, put a compilation option
etisserant@393: /TC or /TP if you plan to mix C++ files. See the MSDN documentation
etisserant@393: about that.
etisserant@393: 
etisserant@393: 
etisserant@448: \subsubsection{How to fit the library to an other microcontr�ler ?}
etisserant@393: 
etisserant@393: First, be sure that you have at least 40K bytes of program memory,
etisserant@393: and about 2k of RAM.
etisserant@393: 
etisserant@393: You have to create target specific interface to HW resources. Take
etisserant@393: model on bundled interfaces provided in drivers/ and create your own
etisserant@393: interface. You also have to update Makefile.in files for target specific
etisserant@393: cflags and options. Choose {--}target= configure switch to compile
etisserant@393: your specific interface.
etisserant@393: 
etisserant@393: You are welcome to contribute -back your own interfaces! Other Canfestival
etisserant@393: users will use it and provide feedback, tests and enhancements.
etisserant@393: 
nico@208: 
nico@208: \subsubsection{Is CanFestival3 conform to DS301 v.4.02 ?}
etisserant@393: 
nico@208: Thanks to Philippe Foureys (IUT of Valence), a slave node have been
etisserant@393: tested with the National Instrument \canopen Conformance Test. It
etisserant@393: passed the test with success.
nico@208: 
nico@208: Some very small unconformity have been found in very unusual situations,
nico@208: for example in the SDO code response to wrong messages.
nico@208: 
etisserant@393: 
nico@208: \subsection{LINUX}
etisserant@393: 
etisserant@393: 
nico@208: \subsubsection{How to use a Peaksystem CAN board ?}
etisserant@393: 
etisserant@393: Just install peak driver and then compile and install Canfestival.
etisserant@393: Peak driver is detected at compile time.
etisserant@393: 
nico@208: 
nico@208: \subsubsection{How to use an unsupported CAN board ?}
etisserant@393: 
nico@208: You have to install the specific driver on your system, with necessary
etisserant@393: libs and headers.
etisserant@393: 
etisserant@393: Use can\_peak.c/h or can\_virtual.c/h as an example, and adapt it
etisserant@393: to your driver API.
etisserant@393: 
etisserant@393: Execute configure script and choose --can=mydriver
etisserant@393: 
nico@208: 
nico@208: \subsection{Win32}
etisserant@393: 
nico@208: Compatibility:
nico@208: 
nico@208: \begin{enumerate}
etisserant@393: \item Code was compiled MS VisualStudio 2003.NET and VisualStudio 2005.NET
etisserant@393: for WindowsXP \ with ANSI and UNICODE configurations and for WindowsCE
etisserant@393: 5.0. 
etisserant@393: \item Some preliminary testing was done, but not enough to be used in mission
etisserant@393: critical projects. 
nico@208: \end{enumerate}
nico@208: Additional Features:
nico@208: 
nico@208: \begin{enumerate}
etisserant@393: \item Non -integral integers support implementation UNS24, UNS40, UNS48
etisserant@393: etc. 
etisserant@393: \item When enable debug output with DEBUG\_WAR\_CONSOLE\_ON or DEBUG\_ERR\_CONSOLE\_ON,
etisserant@393: you can navigate in CanFestival source code by double clicking at
etisserant@393: diagnostic lines in VisualStudio.NET 200X Debug Output Window. 
nico@208: \end{enumerate}
etisserant@393: Custom size integral types such as INTEGER24, UNS40, INTEGER56 etc.
etisserant@393: have been defined as 64 bits integers. You will need to replace sizeof(TYPE)
nico@208: operators to sizeof\_TYPE definitions in generated code, i.e. replace
nico@208: sizeof(UNS40) with sizeof\_UNS40.
nico@208: 
nico@208: 
nico@208: \subsection{HCS12}
etisserant@393: 
etisserant@393: 
nico@208: \subsubsection{Which board are you using ?}
etisserant@393: 
etisserant@393: A T -board from elektronikladen with a MC9S12DP256 or MC9S12DG256.
etisserant@393: 
etisserant@393: 
etisserant@393: \subsubsection{Does the code compile with an other compiler than GNU gcc ?}
etisserant@393: 
etisserant@393: It is known to work with Metrowerks CodeWarrior. Here are some tips
etisserant@393: from Philippe Foureys. :
etisserant@393: 
nico@208: 
nico@208: \paragraph{Interrupt functions}
etisserant@393: 
etisserant@393: 
etisserant@394: \subparagraph{Code for GCC:
etisserant@394: }
etisserant@394: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	// prototype
etisserant@394: 	void __attribute__((interrupt))timer3Hdl(void):
etisserant@394: 	// function
etisserant@394: 	void __attribute__((interrupt))timer3Hdl(void){...}
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@394: 	
etisserant@394: \subparagraph{Code for CodeWarrior
etisserant@394: }
etisserant@394: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: 	// protoype
etisserant@394: 	void interrupt timer3Hdl(void);
etisserant@394: 	// function
etisserant@394: 	pragma CODE_SEG__NEAR_SEG_NON_BANKED
etisserant@394: 	void interrupt timer3Hdl(void)
etisserant@394: 	{...}
etisserant@394: 	pragma CODE_SEG_DEFAULT\end{verbatim}
etisserant@394: 
etisserant@394: 
etisserant@394: \paragraph{Interrupt lock, unlock
etisserant@394: }
etisserant@394: 
etisserant@394: 
etisserant@394: \subparagraph{Code for GCC
etisserant@394: }
etisserant@394: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394:  void unlock (void)
etisserant@394:  {
etisserant@394:    __asm__ __volatile__("cli");
etisserant@394:  }
etisserant@394:  void lock (void)
etisserant@394:  {
etisserant@394:    unsigned short mask;
etisserant@394:    __asm__ __volatile__("tpa\n\tsei":"=d"(mask));
etisserant@394:  }
etisserant@394: \end{verbatim}
etisserant@393: 
nico@208: 
nico@208: \subparagraph{Code for CodeWarrior}
etisserant@393: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: void unlock (void)
etisserant@394: 	{
etisserant@394: 	  __asm("cli");
etisserant@394: 	}
etisserant@394: 	void lock (void)
etisserant@394: 	{
etisserant@394: 	  unsigned short mask;
etisserant@394: 	  __asm
etisserant@394: 	 {
etisserant@394: 	  tpa:tsei:"=d"(mask);
etisserant@394: 	 }
etisserant@394: 	}
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@394: 
etisserant@394: \paragraph{Initialize function}
etisserant@393: 
etisserant@393: 
nico@208: \subparagraph{Code for GCC}
etisserant@393: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: void initCanHCS12 (void)
etisserant@394: {  
etisserant@394:   //Init the HCS12 microcontroler for CanOpen 
etisserant@394:   initHCS12();
etisserant@394:    // Init the HCS12  CAN driver
etisserant@394:   const canBusInit bi0 = {
etisserant@394:     0,    /* no low power                 */ 
etisserant@394:     0,    /* no time stamp                */
etisserant@394:     1,    /* enable MSCAN                 */
etisserant@394:     0,    /* clock source : oscillator (In fact, it is not used)   */
etisserant@394:     0,    /* no loop back                 */
etisserant@394:     0,    /* no listen only               */
etisserant@394:     0,    /* no low pass filter for wk up */
etisserant@394:   CAN_Baudrates[CAN_BAUDRATE_250K],
etisserant@394:     {
etisserant@394:       0x00,    /* Filter on 16 bits.
etisserant@394:                   See Motorola Block Guide V02.14 fig 4-3 */
etisserant@394:       0x00, 0xFF, /* filter 0 hight accept all msg      */
etisserant@394:       0x00, 0xFF, /* filter 0 low accept all msg        */
etisserant@394:       0x00, 0xFF, /* filter 1 hight filter all of  msg  */
etisserant@394:       0x00, 0xFF, /* filter 1 low filter all of  msg    */
etisserant@394:       0x00, 0xFF, /* filter 2 hight filter most of  msg */
etisserant@394:       0x00, 0xFF, /* filter 2 low filter most of  msg   */
etisserant@394:       0x00, 0xFF, /* filter 3 hight filter most of  msg */
etisserant@394:       0x00, 0xFF, /* filter 3 low filter most of  msg   */
etisserant@394:     }
etisserant@394: };
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@394: 
etisserant@394: \subparagraph{Code for CodeWarrior
etisserant@394: }
etisserant@394: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: void initCanHCS12 (void)
etisserant@394: {  
etisserant@394:   //Init the HCS12 microcontroler for CanOpen 
etisserant@394:   initHCS12();
etisserant@394:    // Init the HCS12  CAN driver
etisserant@394:   const canBusInit bi0 = {
etisserant@394:     0,    /* no low power                 */ 
etisserant@394:     0,    /* no time stamp                */
etisserant@394:     1,    /* enable MSCAN                 */
etisserant@394:     0,    /* clock source : oscillator (In fact, it is not used)   */
etisserant@394:     0,    /* no loop back                 */
etisserant@394:     0,    /* no listen only               */
etisserant@394:     0,    /* no low pass filter for wk up */
etisserant@394:     {
etisserant@394:      1, /* clksrc */
etisserant@394:      3, /* brp    */
etisserant@394:      0, /* sjw    */
etisserant@394:      0, /* samp   */
etisserant@394:      1, /* tseg2  */
etisserant@394:      12,/* tseg1  */
etisserant@394:     },
etisserant@394:     {
etisserant@394:       0x00,    /* Filter on 16 bits.
etisserant@394:                  See Motorola Block Guide V02.14 fig 4-3 */
etisserant@394:       0x00, 0xFF, /* filter 0 hight accept all msg      */
etisserant@394:       0x00, 0xFF, /* filter 0 low accept all msg        */
etisserant@394:       0x00, 0xFF, /* filter 1 hight filter all of  msg  */
etisserant@394:       0x00, 0xFF, /* filter 1 low filter all of  msg    */
etisserant@394:       0x00, 0xFF, /* filter 2 hight filter most of  msg */
etisserant@394:       0x00, 0xFF, /* filter 2 low filter most of  msg   */
etisserant@394:       0x00, 0xFF, /* filter 3 hight filter most of  msg */
etisserant@394:       0x00, 0xFF, /* filter 3 low filter most of  msg   */
etisserant@394:     }
etisserant@394: };
etisserant@394: \end{verbatim}
etisserant@393: 
nico@208: 
nico@208: \subsubsection{Does the code works in banked memory ?}
etisserant@393: 
nico@208: No. Today it seems that the port of gcc is bogged for using the banked
nico@208: memory. So, unfortunately, we are limited to 48 Kbytes of memory code.
nico@208: 
etisserant@393: 
nico@208: \subsubsection{What GCC version are you using ?}
etisserant@393: 
nico@208: We are using the stable RPM release 2.2 :
nico@208: 
nico@208: \begin{enumerate}
etisserant@393: \item GNU Gcc 3.0.4. Build 20030501 
etisserant@393: \item Newlib 1.10.0 Build 20030421 
etisserant@393: \item GNU Binutils 2.12.1 Build 20030427 
nico@208: \end{enumerate}
etisserant@393: 
etisserant@393: \section{Documentation resources}
etisserant@393: 
etisserant@393: 
etisserant@394: \subsection{CIA : Can in Automation }
etisserant@393: 
etisserant@393: \href{http://www.can-cia.de/}{http://www.can -cia.de}
etisserant@393: 
etisserant@393: 
etisserant@394: \subsection{Resources and training in \canopen 
etisserant@394: }
etisserant@393: 
nico@208: \href{http://www.esacademy.com/}{http://www.esacademy.com}
nico@208: 
etisserant@393: 
etisserant@394: \subsection{Elektronikladen HCS12 T -board }
etisserant@393: 
nico@208: \href{http://www.elektronikladen.de/en_hcs12tb.html}{http://www.elektronikladen.de/en\_hcs12tb.html}
nico@208: 
etisserant@393: 
etisserant@394: \subsection{Gnu gcc compiler for HC12 }
etisserant@393: 
nico@208: \href{http://m68hc11.serveftp.org/m68hc11_port.php}{http://m68hc11.serveftp.org/m68hc11\_port.php}
nico@208: 
etisserant@393: 
etisserant@394: \subsection{Motorola documentation on HC12 }
etisserant@393: 
nico@208: \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}
nico@208: 
etisserant@393: 
etisserant@394: \subsection{Lauterbach debugger for HC12 }
etisserant@393: 
nico@208: \href{http://www.lauterbach.com/}{http://www.lauterbach.com}
nico@208: 
etisserant@393: 
etisserant@394: \subsection{Python language }
etisserant@393: 
nico@208: \href{http://www.python.org/}{http://www.python.org}
nico@208: 
etisserant@393: \clearpage{}
etisserant@393: 
etisserant@393: 
etisserant@393: \section{About the project}
etisserant@393: 
etisserant@393: 
nico@208: \subsection{Contributors }
etisserant@393: 
etisserant@393: \begin{center}
etisserant@393: \includegraphics[width=10cm]{Pictures/1000020100000258000000832C6FFAB4} 
etisserant@393: \par\end{center}
etisserant@393: 
etisserant@448: Unit� mixte de recherche INRETS -LCPC
etisserant@448: 
etisserant@448: sur les Interractions V�hicule -Infrastructure -Conducteur
etisserant@448: 
etisserant@448: 14, route de la mini�re
nico@208: 
nico@208: 78000 Versailles
nico@208: 
nico@208: FRANCE
nico@208: 
nico@208: Tel : +33 1 40 43 29 01
nico@208: 
nico@208: \href{http://www.inrets.fr/ur/livic}{http://www.inrets.fr/ur/livic}
nico@208: 
nico@208: \textbf{Contributors :} Francis DUPIN
nico@208: 
etisserant@393: Camille BOSSARD
etisserant@393: 
etisserant@393: Laurent ROMIEUX
etisserant@393: 
etisserant@393: \bigskip{}
etisserant@393: 
etisserant@393: 
etisserant@393: \begin{center}
etisserant@393: \includegraphics[width=10cm]{Pictures/100002010000013A0000004A96B0C1FF} 
etisserant@393: \par\end{center}
nico@208: 
nico@208: LOLITECH
nico@208: 
nico@208: 204, rue du Haut du Pin
nico@208: 
etisserant@393: 88470 Saint -Michel sur Meurthe
nico@208: 
nico@208: FRANCE
nico@208: 
nico@208: Tel : +33 3 29 52 95 67
nico@208: 
nico@208: \href{http://www.lolitech.fr/}{http://www.lolitech.fr}
nico@208: 
etisserant@393: \textbf{Contributors :} Edouard TISSERANT (Original author)
etisserant@393: 
etisserant@393: Laurent BESSARD
etisserant@393: 
etisserant@393: \bigskip{}
etisserant@393: 
nico@208: 
nico@208: Many thanks to the other contributors for their great work:
nico@208: 
etisserant@393: Raphael ZULLIGER
etisserant@393: 
etisserant@448: David DUMINY (st� A6R)
etisserant@393: 
etisserant@393: Zakaria BELAMRI
etisserant@393: 
nico@208: 
nico@208: \subsection{Getting support}
etisserant@393: 
etisserant@393: Send your feedback and bug reports to \href{mailto:canfestival-devel@lists.sourceforge.net}{canfestival-devel@lists.sourceforge.net}.
etisserant@393: 
etisserant@393: For commercial support, \ training and specific integration and developments,
etisserant@393: please ask LOLITECH (see contributors).
etisserant@393: 
nico@208: 
nico@208: \subsection{Contributing}
etisserant@393: 
nico@208: You are free to contribute your specific interfaces back to the project.
nico@208: This way, you can hope to get support from CanFestival users community.
nico@208: 
etisserant@393: Please send your patch to \href{mailto:canfestival-devel@lists.sourceforge.net}{canfestival
etisserant@393: -devel@lists.sourceforge.net}.
etisserant@393: 
etisserant@393: Feel free to create some new predefined DS -4xx profiles ({*}.prf)
etisserant@393: in objdictgen/config, as much as possible respectful to the official
nico@208: specifications.
nico@208: 
etisserant@393: 
nico@208: \subsection{License}
etisserant@393: 
etisserant@393: All the project is licensed with LGPL. This mean you can link CanFestival
etisserant@393: with any code without being obliged to publish it.
etisserant@393: 
etisserant@394: 
etisserant@394: \begin{verbatim}
etisserant@394: #This file is part of CanFestival, a library implementing CanOpen Stack. 
etisserant@394: # 
etisserant@394: #Copyright (C): Edouard TISSERANT, Francis DUPIN and Laurent BESSARD 
etisserant@394: # 
etisserant@394: #See COPYING file for copyrights details. 
etisserant@394: # 
etisserant@394: #This library is free software; you can redistribute it and/or 
etisserant@394: #modify it under the terms of the GNU Lesser General Public 
etisserant@394: #License as published by the Free Software Foundation; either 
etisserant@394: #version 2.1 of the License, or (at your option) any later version. 
etisserant@394: # 
etisserant@394: #This library is distributed in the hope that it will be useful, 
etisserant@394: #but WITHOUT ANY WARRANTY; without even the implied warranty of 
etisserant@394: #MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the GNU 
etisserant@394: #Lesser General Public License for more details. 
etisserant@394: # 
etisserant@394: #You should have received a copy of the GNU Lesser General Public 
etisserant@394: #License along with this library; if not, write to the Free Software 
etisserant@394: #Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA  02111-1307  USA 
etisserant@394: \end{verbatim}
etisserant@394: 
etisserant@394: 
nico@208: \end{document}




