manual.tex

CANopen 协议栈源码 ,实现基本的CANopen 协议

\documentclass[12pt,english,a4paper]{book}
\usepackage[T1]{fontenc}
\usepackage[latin9]{inputenc}
\usepackage{graphicx}
\usepackage{amsfonts}
\usepackage{textcomp}
\usepackage{color}
\usepackage{calc}
\usepackage{longtable}
\usepackage{hyperref}
\usepackage{graphics}
\DeclareGraphicsExtensions{.jpg}
\DeclareGraphicsExtensions{.png}
\hypersetup{colorlinks=true, linkcolor=blue, filecolor=blue, pagecolor=blue, urlcolor=blue}

%%%%\%%%%%%%% titre, auteurs, date, etc...%%%%%%%%%%%%%%%%%%
\title{\Huge The CanFestival CANOpen stack manual}
\author{Edouard TISSERANT}
\date{\today}

\setcounter{secnumdepth}{5}
\renewcommand\thesection{\arabic{section} -}
\renewcommand\thesubsection{\arabic{section}.\arabic{subsection})}
\renewcommand\thesubsubsection{\arabic{section}.\arabic{subsection}.\arabic{subsubsection})}
\renewcommand\theparagraph{\alph{paragraph})}
\renewcommand\thesubparagraph{\roman{subparagraph})}

\newcommand{\canopen}{CANopen }

\begin{document}
{\centering\textsf{\huge The CanFestival \canopen stack manual.}}

\renewcommand{\contentsname}{CanFestival v3.0 Manual}
\setcounter{tocdepth}{2} \tableofcontents{}

\clearpage{}

\section{Introduction}

CanFestival is an OpenSource (LGPL and GPL) \canopen framework.

\subsection{The CanFestival project}

This project, initiated by Edouard TISSERANT in 2001, has grown thanks
to Francis DUPIN and other contributors.

Today, CanFestival focuses on providing an ANSI-C platform independent
\canopen stack that can be implemented as master or slave nodes on
PCs, Real-time IPCs, and Microcontrollers.

CanFestival is a project supported by Lolitech.


\subsection{What is \canopen}

CANopen is a CAN based high level protocol. It defines some protocols
to :

\begin{enumerate}
\item Configure a CAN network. 
\item Transmit data to a specific node or in broadcast. 
\item Administrate the network. For example detecting a not responding node. 
\end{enumerate}
The documentation can be found on the CAN in Automation website :

\href{http://www.can-cia.de/canopen}{http://www.can-cia.de/canopen}

The most important document about \canopen is the normative CiA Draft
Standard 301, version 4.02. You can now download the specification
from the CAN in Automation website at no cost.

To continue reading this document, let us assume that you have read
some papers introducing \canopen .


\section{CanFestival Features}


\subsection{Tools }

The \canopen library is coming with some tools :

\begin{enumerate}
\item Object Dictionary editor GUI. WxPython Model-View-Controler based
GUI, that helps a lot in generating object dictionary source code for
each node. 
\item A configure script, that let you chose compile time options such as
target CPU/HOST, CAN and TIMER drivers.\\
 This script has not been generated with autoconf, it has been made
keeping micro-controller target in mind. 
\end{enumerate}

\subsection{Multi-Platform}

\begin{enumerate}
\item Library source code is C-ANSI. 
\item Driver and examples coding conventions merely depend on target specific
contributor/compiler. 
\item Unix compatible interfaces and examples should compile and run on
any Unix system (tested on GNU/Linux and GNU/FreeBSD). 
\end{enumerate}

\subsection{\canopen standard conformance}

\subsubsection{DS-301}

Supported features should conform to DS301. V.4.02 13 february 2002. 

\begin{enumerate}
\item NMT master and slave
\item Heartbeat consumer and producer
\item NodeGuard slave reponder and basic master without tracking
\item SYNC service
\item SDO multiples client and server, segmented and expedited
\item PDO : TPDO and RPDO, with respect to transmission type
\item PDO mapping from/to OD variables bit per bit. 
\item EMCY : Send and receive and keeps track of emergency objects
\item Data types : 8 to 64 bits values, fixed length strings.
\end{enumerate}

\subsubsection{DS-302}

Only concise DFC is supported.

\subsubsection{DS-305}

LSS services are fully supported although they have to be enabled at compile time. Additionally, FastScan LSS service is also optionally enabled. 

\section{How to start}

\subsection{Host requirements}

What you need on your development workstation.

\subsubsection{Object Dictionary Editor GUI}

\begin{enumerate}
\item Python, with 
\item wxPython modules installed (at least version 2.6.3).
\item Gnosis xml tools. (Optional can also be installed locally to the project
automatically with the help of a Makefile. Please see {}``Using Dictionary
Editor GUI'' ) 
\end{enumerate}

\subsubsection{Linux and Unix-likes}

\begin{enumerate}
\item Linux, FreeBSD, Cygwin or any Unix environment with GNU toolchain. 
\item The GNU C compiler (gcc) or any other ANSI-C compiler for your target
platform. 
\item Xpdf, and the official 301\_v04000201.pdf file in order to get GUI
context sensitive help. 
\item GNU Make 
\item Bash and sed 
\end{enumerate}

\subsubsection{Windows (for native win32 target)}

\begin{enumerate}
\item Visual Studio Express 2005 or worst.
\item Microsoft platform SDK (requires Genuine Advantage)
\item Cygwin (for configuration only)
\item MinGW/MSYS
\end{enumerate}

\subsection{How to get CanFestival}

Please always use CVS, this is the best way to get the most reactive
support from the developer community :


\begin{verbatim}
	cvs -d:pserver:[e-mail]:/canfestival login
\end{verbatim}

(type return, without entering a password)

Then, enter :

\begin{verbatim}
	cvs -z3 -d:pserver:[e-mail]:/canfestival co -P CanFestival-3
\end{verbatim}



\section{Understanding Canfestival}

\subsection{CanFestival Project tree layout}
Simplified directory structure.
\begin{verbatim}
./src ANSI-C source of \canopen stack
./include Exportables Header files
./drivers Interfaces to specific platforms/HW
./drivers/unix Linux and Cygwin OS interface
./drivers/win32 Native Win32 OS interface
./drivers/timers_xeno Xenomai timers/threads (Linux only)
./drivers/timers_rtai Rtai timers/threads (Linux only)
./drivers/timers_kernel Linux kernel timer/threads
./drivers/timers_unix Posix timers/threads (Linux, Cygwin)
./drivers/can_virtual_kernel Fake CAN network (kernel space)
./drivers/can_serial Serial point to point and PTY hub (*nix only)
./drivers/can_peak_linux PeakSystem CAN library interface
./drivers/can_peak_win32 PeakSystem PCAN-Light interface
./drivers/can_uvccm_win32 Acacetus's RS232 CAN-uVCCM interface
./drivers/can_virtual Fake CAN network (Linux, Cygwin)
./drivers/can_vcom VScom VSCAN interface
./drivers/hcs12 HCS12 full target interface
./examples Examples
./examples/TestMasterSlave 2 nodes, NMT SYNC SDO PDO, win32+unix
./examples/TestMasterSlaveLSS 3 nodes, NMT SYNC SDO PDO LSS, win32+unix
./examples/TestMasterMicroMod 1 node, control Peak I/O Module, unix
./examples/gene_SYNC_HCS12 Just send periodic SYNC on HCS12
./examples/win32test Ask some DS301 infos to a node (win32)
./objdictgen Object Dictionary editor GUI
./objdictgen/config Pre-defined OD profiles
./objdictgen/examples Some examples/test OD
./doc Documentation source
\end{verbatim}



\subsection{Implement CanFestival in your application}

\begin{center}
\includegraphics[width=12cm]{Pictures/10000201000003F9000002CF880931E7} 
\par\end{center}

\bigskip{}



\subsection{CanFestival CAN interfaces}

Because most CAN controllers and drivers implement FIFOs, CanFestival
consider sending message as a non blocking operation.

In order to prevent reentrant calls to the stack, messages reception
is implemented differently on {\textmu}C and OS.:

\begin{enumerate}
\item {\textmu}C must provide interruption masking, mutually excluding timer and CAN receive interrupts.\\



\begin{center}
\includegraphics[width=12cm]{Pictures/10000201000003CA0000016604E6A5EF} 
\par\end{center}

\item OS must provide a receive thread, a timer thread and a mutex. CAN
reception should be a blocking operation.\\



\begin{center}
\includegraphics[width=12cm]{Pictures/10000201000003F9000002CF8B0CDAEA} 
\par\end{center}

\end{enumerate}

\subsection{CanFestival event scheduling}

A \canopen node must be able to take delayed actions.

For instance, periodic sync emission, heartbeat production or SDO timeout
need to set some alarms that will be called later and do the job.

{\textmu}C generally do not have enough free timers to handle all
the \canopen needs directly. Moreover, CanFestival internal data
may be corrupt by reentrant calls.

CanFestival implement a micro -scheduler (timer.c). It uses only one
timer to mimic many timers. It manage an alarm table, and call alarms
at desired time.

\begin{center}
\includegraphics[width=12cm]{Pictures/100000000000022C000000DEDAD2140C} 
\par\end{center}

Scheduler can handle short clock value ranges limitation found on
some {\textmu}C. As an example, value range for a 16bit clock counter
with 4{\textmu}s tick is crossed within 0.26 seconds... Long alarms
must be segmented.

Chronogram illustrate a long alarm (A) and a short periodic alarm
(B), with a A value {\textgreater} clock range {\textgreater}
B value. Values t0...t8 are successive setTimer call parameter values.
t1 illustrates an intermediate call to TimeDispatch, caused by a delay
longer than clock range. Because of long alarm segmentation, at the
end of t1, TimeDispatch call will not trig any alarm callback.

\begin{center}
\includegraphics[width=12cm]{Pictures/1000000000000396000000FFC42573DA} 
\par\end{center}


\section{Linux Target}

Linux target is default configure target.


\subsection{Linux Compilation and installation}

Call ./configure -- help to see all available compile time options.

After invoking ./configure with your platform specific switches, just
type make.



\begin{verbatim}
	./configure [options]
	make
	make install
\end{verbatim}




\subsubsection{Standard Linux node}


\begin{verbatim}
	./configure --timers=unix
\end{verbatim}


To do a \canopen node running on PC -Linux, you need :

\begin{enumerate}
\item A working linux distribution 
\item One or more Peak system PC CAN interface and the last Peak Linux driver
installed. 
\end{enumerate}

\subsubsection{Real -Time Linux node}

With Xenomai :
\begin{verbatim}
	./configure --timers=xeno
\end{verbatim}
With Rtai :
\begin{verbatim}
	./configure --timers=rtai
\end{verbatim}

To do a \canopen node running on PC -Linux, you need :

\begin{enumerate}
\item A working Linux distribution patched with XENOMAI (2.1 or greater) or RTAI (3.6). 
\item One or more Peak system PC CAN interface and the last Peak Real Time
Linux driver installed. 
\end{enumerate}

\subsubsection{Linux kernel node}

To do a CANopen node running on PC-Linux in kernel space, you need:


\begin{enumerate}
\item A working Linux distribution with pre-built 2.6.x.x kernel sources
\item A CAN card driver compatible with CanFestival
\end{enumerate}


\subsubsection{CAN devices}
Currently supported CAN devices and corresponding configure switch:

\paragraph{Peak systems}
\begin{verbatim}
	./configure --can=peak_linux
\end{verbatim}
PeakSystems CAN interface is automatically chosen as default CAN interface
if libpcan is present in the system.

Please download driver at \href{http://www.peak-system.com/linux}{http://www.peak
-system.com/linux} and follow instructions in order to install driver
on your system.

\paragraph{Socket-Can (http://socketcan.berlios.de)}
\begin{verbatim}
	./configure --can=socket
\end{verbatim}

\paragraph{Serial}
\begin{verbatim}
	./configure --can=serial
\end{verbatim}
The CAN serial driver implements a 1:1 serial connection between 2 CAN devices.
For example, you can connect 2 CANFestival applications via a NULL modem cable.

Also with this driver comes a software hub, for up to 16 CANFestival apps to 
be connected on a single PC, with an optional connection to another CAN driver.
Note that only the serial driver is supported at this time.  The hub uses ptys 
(pseudo ttys) available on a *nix like system.