1

\documentclass[12pt,english,a4paper]{book}

     2

\usepackage[T1]{fontenc}

     3

\usepackage[latin9]{inputenc}

     4

\usepackage{graphicx}

     5

\usepackage{amsfonts}

     6

\usepackage{textcomp}

     7

\usepackage{color}

     8

\usepackage{calc}

     9

\usepackage{longtable}

    10

\usepackage{hyperref}

    11

\usepackage{graphics}

    12

\DeclareGraphicsExtensions{.jpg}

    13

\DeclareGraphicsExtensions{.png}

    14

\hypersetup{colorlinks=true, linkcolor=blue, filecolor=blue, pagecolor=blue, urlcolor=blue}

    15

    16

%%%%\%%%%%%%% titre, auteurs, date, etc...%%%%%%%%%%%%%%%%%%

    17

\title{\Huge The CanFestival CANOpen stack manual}

    18

\author{Edouard TISSERANT}

    19

\date{\today}

    20

    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})}

    27

    28

\newcommand{\canopen}{CANopen }

    29

    30

\begin{document}

    31

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

    32

    33

\renewcommand{\contentsname}{CanFestival v3.0 Manual}

    34

\setcounter{tocdepth}{2} \tableofcontents{}

    35

    36

\clearpage{}

    37

    38

\section{Introduction}

    39

    40

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

    41

    42

\subsection{The CanFestival project}

    43

    44

This project, initiated by Edouard TISSERANT in 2001, has grown thanks

    45

to Francis DUPIN and other contributors.

    46

    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.

    50

    51

CanFestival is a project supported by Lolitech.

    52

    53

    54

\subsection{What is \canopen}

    55

    56

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

    57

to :

    58

    59

\begin{enumerate}

    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. 

    63

\end{enumerate}

    64

The documentation can be found on the CAN in Automation website :

    65

    66

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

    67

    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.

    71

    72

To continue reading this document, let us assume that you have read

    73

some papers introducing \canopen .

    74

    75

    76

\section{CanFestival Features}

    77

    78

    79

\subsection{Tools }

    80

    81

The \canopen library is coming with some tools :

    82

    83

\begin{enumerate}

    84

\item Object Dictionary editor GUI. WxPython Model-View-Controler based

    85

GUI, that helps a lot in generating object dictionary source code for

    86

each node. 

    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. 

    91

\end{enumerate}

    92

    93

\subsection{Multi-Platform}

    94

    95

\begin{enumerate}

    96

\item Library source code is C-ANSI. 

    97

\item Driver and examples coding conventions merely depend on target specific

    98

contributor/compiler. 

    99

\item Unix compatible interfaces and examples should compile and run on

   100

any Unix system (tested on GNU/Linux and GNU/FreeBSD). 

   101

\end{enumerate}

   102

   103

\subsection{\canopen standard conformance}

   104

   105

\subsubsection{DS-301}

   106

   107

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

   108

   109

\begin{enumerate}

   110

\item NMT master and slave

   111

\item Heartbeat consumer and producer

   112

\item NodeGuard slave reponder and basic master without tracking

   113

\item SYNC service

   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.

   119

\end{enumerate}

   120

   121

\subsubsection{DS-302}

   122

   123

Only concise DFC is supported.

   124

   125

\section{How to start}

   126

   127

\subsection{Host requirements}

   128

   129

What you need on your development workstation.

   130

   131

\subsubsection{Object Dictionary Editor GUI}

   132

   133

\begin{enumerate}

   134

\item Python, with 

   135

\item wxPython modules installed (at least version 2.6.3).

   136

\item Gnosis xml tools. (Optional can also be installed locally to the project

   137

automatically with the help of a Makefile. Please see {}``Using Dictionary

   138

Editor GUI'' ) 

   139

\end{enumerate}

   140

   141

\subsubsection{Linux and Unix-likes}

   142

   143

\begin{enumerate}

   144

\item Linux, FreeBSD, Cygwin or any Unix environment with GNU toolchain. 

   145

\item The GNU C compiler (gcc) or any other ANSI-C compiler for your target

   146

platform. 

   147

\item Xpdf, and the official 301\_v04000201.pdf file in order to get GUI

   148

context sensitive help. 

   149

\item GNU Make 

   150

\item Bash and sed 

   151

\end{enumerate}

   152

   153

\subsubsection{Windows (for native win32 target)}

   154

   155

\begin{enumerate}

   156

\item Visual Studio Express 2005 or worst. 

   157

\item Microsoft platform SDK (requires Genuine Advantage) 

   158

\item Cygwin (for configuration only) 

   159

\end{enumerate}

   160

   161

\subsection{How to get CanFestival}

   162

   163

Please always use CVS, this is the best way to get the most reactive

   164

support from the developer community :

   165

   166

   167

\begin{verbatim}

   168

	cvs -d:pserver:anonymous@lolitech.dyndns.org:/canfestival login

   169

\end{verbatim}

   170

   171

(type return, without entering a password)

   172

   173

Then, enter :

   174

   175

\begin{verbatim}

   176

	cvs -z3 -d:pserver:anonymous@lolitech.dyndns.org:/canfestival co -P CanFestival-3

   177

\end{verbatim}

   178

   179

   180

   181

\section{Understanding Canfestival}

   182

   183

\subsection{CanFestival Project tree layout}

   184

   185

Simplified directory structure.

   186

   187

\begin{verbatim}

   188

./src ANSI-C source of \canopen stack

   189

./include Exportables Header files

   190

./drivers Interfaces to specific platforms/HW

   191

./drivers/unix Linux and Cygwin OS interface

   192

./drivers/win32 Native Win32 OS interface

   193

./drivers/timers_xeno Xenomai timers/threads (Linux only)

   194

./drivers/timers_kernel Linux kernel timer/threads

   195

./drivers/timers_unix Posix timers/threads (Linux, Cygwin)

   196

./drivers/can_virtual_kernel Fake CAN network (kernel space)

   197

./drivers/can_peak_linux PeakSystem CAN library interface

   198

./drivers/can_peak_win32 PeakSystem PCAN-Light interface

   199

./drivers/can_uvccm_win32 Acacetus's RS232 CAN-uVCCM interface

   200

./drivers/can_virtual Fake CAN network (Linux, Cygwin)

   201

./drivers/hcs12 HCS12 full target interface

   202

./examples Examples

   203

./examples/TestMasterSlave 2 nodes, NMT SYNC SDO PDO, win32+unix

   204

./examples/TestMasterMicroMod 1 node, control Peak I/O Module, unix

   205

./examples/gene_SYNC_HCS12 Just send periodic SYNC on HCS12

   206

./examples/win32test Ask some DS301 infos to a node (win32)

   207

./objdictgen Object Dictionary editor GUI

   208

./objdictgen/config Pre-defined OD profiles

   209

./objdictgen/examples Some examples/test OD

   210

./doc Documentation source

   211

\end{verbatim}

   212

   213

   214

   215

\subsection{Implement CanFestival in your application}

   216

   217

\begin{center}

   218

\includegraphics[width=12cm]{Pictures/10000201000003F9000002CF880931E7} 

   219

\par\end{center}

   220

   221

\bigskip{}

   222

   223

   224

   225

\subsection{CanFestival CAN interfaces}

   226

   227

Because most CAN controllers and drivers implement FIFOs, CanFestival

   228

consider sending message as a non blocking operation.

   229

   230

In order to prevent reentrent calls to the stack, messages reception

   231

is implemented differently on {\textmu}C and OS.:

   232

   233

\begin{enumerate}

   234

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

   235

   236

   237

   238

\begin{center}

   239

\includegraphics[width=12cm]{Pictures/10000201000003CA0000016604E6A5EF} 

   240

\par\end{center}

   241

   242

\item OS must provide a receive thread, a timer thread and a mutex. CAN

   243

reception should be a bloking operation.\\

   244

   245

   246

   247

\begin{center}

   248

\includegraphics[width=12cm]{Pictures/10000201000003F9000002CF8B0CDAEA} 

   249

\par\end{center}

   250

   251

\end{enumerate}

   252

   253

\subsection{CanFestival event scheduling}

   254

   255

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

   256

   257

For instance, periodic sync emission, heartbeat production or SDO timeout

   258

need to set some alarms that will be called later and do the job.

   259

   260

{\textmu}C generally do not have enough free timers to handle all

   261

the \canopen needs directly. Moreover, CanFestival internal data

   262

may be corrupt by reentrant calls.

   263

   264

CanFestival implement a micro -scheduler (timer.c). It uses only one

   265

timer to mimic many timers. It manage an alarm table, and call alarms

   266

at desired time.

   267

   268

\begin{center}

   269

\includegraphics[width=12cm]{Pictures/100000000000022C000000DEDAD2140C} 

   270

\par\end{center}

   271

   272

Scheduler can handle short clock value ranges limitation found on

   273

some {\textmu}C. As an example, value range for a 16bit clock counter

   274

with 4{\textmu}s tick is crossed within 0.26 seconds... Long alarms

   275

must be segmented.

   276

   277

Chronogram illustrate a long alarm (A) and a short periodic alarm

   278

(B), with a A value {\textgreater} clock range {\textgreater}

   279

B value. Values t0...t8 are successive setTimer call parameter values.

   280

t1 illustrates an intermediate call to TimeDispatch, caused by a delay

   281

longer than clock range. Because of long alarm segmentation, at the

   282

end of t1, TimeDispatch call will not trig any alarm callback.

   283

   284

\begin{center}

   285

\includegraphics[width=12cm]{Pictures/1000000000000396000000FFC42573DA} 

   286

\par\end{center}

   287

   288

   289

\section{Linux Target}

   290

   291

Linux target is default configure target.

   292

   293

   294

\subsection{Linux Compilation and installation}

   295

   296

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

   297

   298

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

   299

type make.

   300

   301

   302

   303

\begin{verbatim}

   304

	./configure [options]

   305

	make

   306

	make install

   307

\end{verbatim}

   308

   309

   310

   311

   312

\subsubsection{Standard Linux node}

   313

   314

   315

\begin{verbatim}

   316

	./configure --timers=unix

   317

\end{verbatim}

   318

   319

   320

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

   321

   322

\begin{enumerate}

   323

\item A working linux distribution 

   324

\item One or more Peak system PC CAN interface and the last Peak Linux driver

   325

installed. 

   326

\end{enumerate}

   327

   328

\subsubsection{Real -Time Linux node}

   329

   330

   331

\begin{verbatim}

   332

	./configure --timers=xeno

   333

\end{verbatim}

   334

   335

   336

   337

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

   338

   339

\begin{enumerate}

   340

\item A working Linux distribution patched with XENOMAI 2.1 or greater. 

   341

\item One or more Peak system PC CAN interface and the last Peak Real Time

   342

Linux driver installed. 

   343

\end{enumerate}

   344

   345

\subsubsection{Linux kernel node}

   346

   347

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

   348

   349

   350

\begin{enumerate}

   351

\item A working Linux distribution with pre-built 2.6.x.x kernel sources

   352

\item A CAN card driver compatible with CanFestival

   353

\end{enumerate}

   354

   355

   356

\subsubsection{CAN devices}

   357

   358

Currently supported CAN devices and corresponding configure switch:

   359

   360

   361

\paragraph{Peak systems}

   362

   363

   364

\begin{verbatim}

   365

	./configure --can=peak_linux

   366

\end{verbatim}

   367

   368

   369

PeakSystems CAN interface is automatically chosen as default CAN interface

   370

if libpcan is present in the system.

   371

   372

Please download driver at \href{http://www.peak-system.com/linux}{http://www.peak

   373

-system.com/linux} and follow instructions in order to install driver

   374

on your system.

   375

   376

   377

\paragraph{Socket -Can (http://socketcan.berlios.de)}

   378

   379

   380

\begin{verbatim}

   381

	./configure --can=socket

   382

\end{verbatim}

   383

   384

   385

\paragraph{LinCan}

   386

   387

   388

\begin{verbatim}

   389

	./configure --can=lincan

   390

\end{verbatim}

   391

   392

   393

\paragraph{Virtual CAN interfaces (for test/debug)}

   394

   395

   396

\begin{verbatim}

   397

	./configure --can=virtual

   398

		or, for kernel space:

   399

	./configure --can=kernel_virtual

   400

\end{verbatim}

   401

   402

   403

Virtual CAN interface use Unix pipes to emulate a virtual CAN network.

   404

Each message issued from a node is repeat to all other nodes. Currently

   405

only works with nodes running in the same process, and does not support

   406

work with Xenomai.

   407

   408

   409

\subsection{Testing your CanFestival installation}

   410

   411

\subsection{User space}

   412

   413

Sample provided in /example/TestMasterSlave is installed into your

   414

system during installation.

   415

   416

   417

\begin{verbatim}

   418

	TestMasterSlave

   419

\end{verbatim}

   420

   421

   422

Default CAN driver library is libcanfestival\_can\_virtual.so., which

   423

will simply pass CAN messages through Unix pipes between Master and

   424

Slave.

   425

   426

You may also want to specify different can interface and define some

   427

CAN ports. Another example using Peak{\textquotesingle}s dual PCMCIA

   428

(configure and install with --can=peak) :

   429

   430

   431

\begin{verbatim}

   432

	TestMasterSlave -l libcanfestival_can_peak.so -s 40 -m 41

   433

\end{verbatim}

   434

   435

   436

\subsection{Kernel space}

   437

   438

   439

\begin{verbatim}

   440

	example/kerneltest

   441

\end{verbatim}

   442

   443

   444

It's based on TestMasterSlave example

   445

and has the same functionality. Uses virtual can driver as default

   446

too. After successful installation you can insert the module by typing:

   447

modprobe canf\_ktest Module control is done by simple console 'canf\_ktest\_console'

   448

which is used to start/stop sending data.

   449

   450

   451

\section{Windows Targets}

   452

   453

CanFestival can be compiled and run on Windows platform. It is possible

   454

to use both Cygwin and win32 native runtime environment.

   455

   456

\subsection{Object Dictionary Editor GUI installation.}

   457

   458

Please refer to \hyperlink{a821UsingDictionaryEditorGUIoutline}{8.2.1)Using

   459

Dictionary Editor GUI}

   460

   461

\subsection{CYGWIN}

   462

   463

\subsubsection{Requirements}

   464

   465

Cygwin have to be installed with those packages :

   466

   467

\begin{enumerate}

   468

\item gcc 

   469

\item unzip 

   470

\item wget 

   471

\item make 

   472

\end{enumerate}

   473

Currently, the only supported CAN devices are PeakSystems ones, with

   474

PcanLight driver and library.

   475

   476

Please download driver at \href{http://www.peak-system.com/themen/download_gb.html}{http://www.peak

   477

-system.com/themen/download\_gb.html} \ and follow instructions

   478

in order to install driver on your system.

   479

   480

Install Cygwin as required, and the driver for your Peak CAN device.

   481

   482

Open a Cygwin terminal, and follow those instructions:

   483

   484

   485

\subsubsection{Cygwin configuration and compilation}

   486

   487

   488

\paragraph{A single node with PcanLight and Peak CAN -USB adapter}

   489

   490

Download the PCAN-Light Zip file for your HW ( URL from download

   491

page ):

   492