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

\item MinGW/MSYS

   160

\end{enumerate}

   161

   162

\subsection{How to get CanFestival}

   163

   164

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

   165

support from the developer community :

   166

   167

   168

\begin{verbatim}

   169

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

   170

\end{verbatim}

   171

   172

(type return, without entering a password)

   173

   174

Then, enter :

   175

   176

\begin{verbatim}

   177

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

   178

\end{verbatim}

   179

   180

   181

   182

\section{Understanding Canfestival}

   183

   184

\subsection{CanFestival Project tree layout}

   185

Simplified directory structure.

   186

\begin{verbatim}

   187

./src ANSI-C source of \canopen stack

   188

./include Exportables Header files

   189

./drivers Interfaces to specific platforms/HW

   190

./drivers/unix Linux and Cygwin OS interface

   191

./drivers/win32 Native Win32 OS interface

   192

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

   193

./drivers/timers_rtai Rtai timers/threads (Linux only)

   194

./drivers/timers_kernel Linux kernel timer/threads

   195

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

   196

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

   197

./drivers/can_serial Serial point to point and PTY hub (*nix only)

   198

./drivers/can_peak_linux PeakSystem CAN library interface

   199

./drivers/can_peak_win32 PeakSystem PCAN-Light interface

   200

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

   201

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

   202

./drivers/can_vcom VScom VSCAN interface

   203

./drivers/hcs12 HCS12 full target interface

   204

./examples Examples

   205

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

   206

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

   207

./examples/gene_SYNC_HCS12 Just send periodic SYNC on HCS12

   208

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

   209

./objdictgen Object Dictionary editor GUI

   210

./objdictgen/config Pre-defined OD profiles

   211

./objdictgen/examples Some examples/test OD

   212

./doc Documentation source

   213

\end{verbatim}

   214

   215

   216

   217

\subsection{Implement CanFestival in your application}

   218

   219

\begin{center}

   220

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

   221

\par\end{center}

   222

   223

\bigskip{}

   224

   225

   226

   227

\subsection{CanFestival CAN interfaces}

   228

   229

Because most CAN controllers and drivers implement FIFOs, CanFestival

   230

consider sending message as a non blocking operation.

   231

   232

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

   233

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

   234

   235

\begin{enumerate}

   236

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

   237

   238

   239

   240

\begin{center}

   241

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

   242

\par\end{center}

   243

   244

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

   245

reception should be a blocking operation.\\

   246

   247

   248

   249

\begin{center}

   250

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

   251

\par\end{center}

   252

   253

\end{enumerate}

   254

   255

\subsection{CanFestival event scheduling}

   256

   257

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

   258

   259

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

   260

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

   261

   262

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

   263

the \canopen needs directly. Moreover, CanFestival internal data

   264

may be corrupt by reentrant calls.

   265

   266

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

   267

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

   268

at desired time.

   269

   270

\begin{center}

   271

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

   272

\par\end{center}

   273

   274

Scheduler can handle short clock value ranges limitation found on

   275

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

   276

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

   277

must be segmented.

   278

   279

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

   280

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

   281

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

   282

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

   283

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

   284

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

   285

   286

\begin{center}

   287

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

   288

\par\end{center}

   289

   290

   291

\section{Linux Target}

   292

   293

Linux target is default configure target.

   294

   295

   296

\subsection{Linux Compilation and installation}

   297

   298

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

   299

   300

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

   301

type make.

   302

   303

   304

   305

\begin{verbatim}

   306

	./configure [options]

   307

	make

   308

	make install

   309

\end{verbatim}

   310

   311

   312

   313

   314

\subsubsection{Standard Linux node}

   315

   316

   317

\begin{verbatim}

   318

	./configure --timers=unix

   319

\end{verbatim}

   320

   321

   322

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

   323

   324

\begin{enumerate}

   325

\item A working linux distribution 

   326

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

   327

installed. 

   328

\end{enumerate}

   329

   330

\subsubsection{Real -Time Linux node}

   331

   332

With Xenomai :

   333

\begin{verbatim}

   334

	./configure --timers=xeno

   335

\end{verbatim}

   336

With Rtai :

   337

\begin{verbatim}

   338

	./configure --timers=rtai

   339

\end{verbatim}

   340

   341

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

   342

   343

\begin{enumerate}

   344

\item A working Linux distribution patched with XENOMAI (2.1 or greater) or RTAI (3.6). 

   345

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

   346

Linux driver installed. 

   347

\end{enumerate}

   348

   349

\subsubsection{Linux kernel node}

   350

   351

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

   352

   353

   354

\begin{enumerate}

   355

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

   356

\item A CAN card driver compatible with CanFestival

   357

\end{enumerate}

   358

   359

   360

\subsubsection{CAN devices}

   361

Currently supported CAN devices and corresponding configure switch:

   362

   363

\paragraph{Peak systems}

   364

\begin{verbatim}

   365

	./configure --can=peak_linux

   366

\end{verbatim}

   367

PeakSystems CAN interface is automatically chosen as default CAN interface

   368

if libpcan is present in the system.

   369

   370

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

   371

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

   372

on your system.

   373

   374

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

   375

\begin{verbatim}

   376

	./configure --can=socket

   377

\end{verbatim}

   378

   379

\paragraph{Serial}

   380

\begin{verbatim}

   381

	./configure --can=serial

   382

\end{verbatim}

   383

The CAN serial driver implements a 1:1 serial connection between 2 CAN devices.

   384

For example, you can connect 2 CANFestival applications via a NULL modem cable.

   385

   386

Also with this driver comes a software hub, for up to 16 CANFestival apps to 

   387

be connected on a single PC, with an optional connection to another CAN driver.

   388

Note that only the serial driver is supported at this time.  The hub uses ptys 

   389

(pseudo ttys) available on a *nix like system.

   390

   391

\paragraph{LinCan}

   392

\begin{verbatim}

   393

	./configure --can=lincan

   394

\end{verbatim}

   395

   396

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

   397

\begin{verbatim}

   398

	./configure --can=virtual

   399

		or, for kernel space:

   400

	./configure --can=kernel_virtual

   401

\end{verbatim}

   402

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

   403

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

   404

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

   405

work with Xenomai or RTAI.

   406

   407

\paragraph{VScom}

   408

\begin{verbatim}

   409

	./configure --can=vscom

   410

\end{verbatim}

   411

The VSCAN API archive will be automatically downloaded and decompressed (unzip required). See \href{http://www.vscom.de/1_1_05.htm}{www.vscom.de} for available adapters.

   412

\subsection{Testing your CanFestival installation}

   413

   414

\subsection{User space}

   415

   416

Sample provided in /example/TestMasterSlave is installed into your

   417

system during installation.

   418

   419

   420

\begin{verbatim}

   421

	TestMasterSlave

   422

\end{verbatim}

   423

   424

   425

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

   426

will simply pass CAN messages through Unix pipes between Master and

   427

Slave.

   428

   429

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

   430

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

   431

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

   432

   433

   434

\begin{verbatim}

   435

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

   436

\end{verbatim}

   437

   438

   439

\subsection{Kernel space}

   440

   441

   442

\begin{verbatim}

   443

	example/kerneltest

   444

\end{verbatim}

   445

   446

   447

It's based on TestMasterSlave example

   448

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

   449

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

   450

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

   451

which is used to start/stop sending data.

   452

   453

   454

\section{Windows Targets}

   455

   456

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

   457

to use both Cygwin and win32 native runtime environment.

   458

   459

\subsection{Object Dictionary Editor GUI installation.}

   460

   461

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

   462

Dictionary Editor GUI}

   463

   464

\subsection{CYGWIN}

   465

   466

\subsubsection{Requirements}

   467

   468

Cygwin have to be installed with those packages :

   469

   470

\begin{enumerate}

   471

\item gcc 

   472

\item unzip 

   473

\item wget 

   474

\item make 

   475

\end{enumerate}

   476

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

   477

PcanLight driver and library.

   478

   479

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

   480

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

   481

in order to install driver on your system.

   482

   483

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

   484

   485

Open a Cygwin terminal, and follow those instructions:

   486

   487

   488

\subsubsection{Cygwin configuration and compilation}

   489

   490

   491

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

   492