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

\subsubsection{DS-305}

   126

   127

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

   128

   129

\section{How to start}

   130

   131

\subsection{Host requirements}

   132

   133

What you need on your development workstation.

   134

   135

\subsubsection{Object Dictionary Editor GUI}

   136

   137

\begin{enumerate}

   138

\item Python, with 

   139

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

   140

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

   141

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

   142

Editor GUI'' ) 

   143

\end{enumerate}

   144

   145

\subsubsection{Linux and Unix-likes}

   146

   147

\begin{enumerate}

   148

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

   149

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

   150

platform. 

   151

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

   152

context sensitive help. 

   153

\item GNU Make 

   154

\item Bash and sed 

   155

\end{enumerate}

   156

   157

\subsubsection{Windows (for native win32 target)}

   158

   159

\begin{enumerate}

   160

\item Visual Studio Express 2005 or worst.

   161

\item Microsoft platform SDK (requires Genuine Advantage)

   162

\item Cygwin (for configuration only)

   163

\item MinGW/MSYS

   164

\end{enumerate}

   165

   166

\subsection{How to get CanFestival}

   167

   168

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

   169

support from the developer community :

   170

   171

   172

\begin{verbatim}

   173

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

   174

\end{verbatim}

   175

   176

(type return, without entering a password)

   177

   178

Then, enter :

   179

   180

\begin{verbatim}

   181

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

   182

\end{verbatim}

   183

   184

   185

   186

\section{Understanding Canfestival}

   187

   188

\subsection{CanFestival Project tree layout}

   189

Simplified directory structure.

   190

\begin{verbatim}

   191

./src ANSI-C source of \canopen stack

   192

./include Exportables Header files

   193

./drivers Interfaces to specific platforms/HW

   194

./drivers/unix Linux and Cygwin OS interface

   195

./drivers/win32 Native Win32 OS interface

   196

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

   197

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

   198

./drivers/timers_kernel Linux kernel timer/threads

   199

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

   200

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

   201

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

   202

./drivers/can_peak_linux PeakSystem CAN library interface

   203

./drivers/can_peak_win32 PeakSystem PCAN-Light interface

   204

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

   205

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

   206

./drivers/can_vcom VScom VSCAN interface

   207

./drivers/hcs12 HCS12 full target interface

   208

./examples Examples

   209

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

   210

./examples/TestMasterSlaveLSS 3 nodes, NMT SYNC SDO PDO LSS, win32+unix

   211

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

   212

./examples/gene_SYNC_HCS12 Just send periodic SYNC on HCS12

   213

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

   214

./objdictgen Object Dictionary editor GUI

   215

./objdictgen/config Pre-defined OD profiles

   216

./objdictgen/examples Some examples/test OD

   217

./doc Documentation source

   218

\end{verbatim}

   219

   220

   221

   222

\subsection{Implement CanFestival in your application}

   223

   224

\begin{center}

   225

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

   226

\par\end{center}

   227

   228

\bigskip{}

   229

   230

   231

   232

\subsection{CanFestival CAN interfaces}

   233

   234

Because most CAN controllers and drivers implement FIFOs, CanFestival

   235

consider sending message as a non blocking operation.

   236

   237

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

   238

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

   239

   240

\begin{enumerate}

   241

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

   242

   243

   244

   245

\begin{center}

   246

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

   247

\par\end{center}

   248

   249

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

   250

reception should be a blocking operation.\\

   251

   252

   253

   254

\begin{center}

   255

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

   256

\par\end{center}

   257

   258

\end{enumerate}

   259

   260

\subsection{CanFestival event scheduling}

   261

   262

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

   263

   264

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

   265

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

   266

   267

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

   268

the \canopen needs directly. Moreover, CanFestival internal data

   269

may be corrupt by reentrant calls.

   270

   271

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

   272

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

   273

at desired time.

   274

   275

\begin{center}

   276

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

   277

\par\end{center}

   278

   279

Scheduler can handle short clock value ranges limitation found on

   280

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

   281

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

   282

must be segmented.

   283

   284

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

   285

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

   286

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

   287

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

   288

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

   289

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

   290

   291

\begin{center}

   292

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

   293

\par\end{center}

   294

   295

   296

\section{Linux Target}

   297

   298

Linux target is default configure target.

   299

   300

   301

\subsection{Linux Compilation and installation}

   302

   303

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

   304

   305

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

   306

type make.

   307

   308

   309

   310

\begin{verbatim}

   311

	./configure [options]

   312

	make

   313

	make install

   314

\end{verbatim}

   315

   316

   317

   318

   319

\subsubsection{Standard Linux node}

   320

   321

   322

\begin{verbatim}

   323

	./configure --timers=unix

   324

\end{verbatim}

   325

   326

   327

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

   328

   329

\begin{enumerate}

   330

\item A working linux distribution 

   331

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

   332

installed. 

   333

\end{enumerate}

   334

   335

\subsubsection{Real -Time Linux node}

   336

   337

With Xenomai :

   338

\begin{verbatim}

   339

	./configure --timers=xeno

   340

\end{verbatim}

   341

With Rtai :

   342

\begin{verbatim}

   343

	./configure --timers=rtai

   344

\end{verbatim}

   345

   346

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

   347

   348

\begin{enumerate}

   349

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

   350

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

   351

Linux driver installed. 

   352

\end{enumerate}

   353

   354

\subsubsection{Linux kernel node}

   355

   356

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

   357

   358

   359

\begin{enumerate}

   360

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

   361

\item A CAN card driver compatible with CanFestival

   362

\end{enumerate}

   363

   364

   365

\subsubsection{CAN devices}

   366

Currently supported CAN devices and corresponding configure switch:

   367

   368

\paragraph{Peak systems}

   369

\begin{verbatim}

   370

	./configure --can=peak_linux

   371

\end{verbatim}

   372

PeakSystems CAN interface is automatically chosen as default CAN interface

   373

if libpcan is present in the system.

   374

   375

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

   376

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

   377

on your system.

   378

   379

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

   380

\begin{verbatim}

   381

	./configure --can=socket

   382

\end{verbatim}

   383

   384

\paragraph{Serial}

   385

\begin{verbatim}

   386

	./configure --can=serial

   387

\end{verbatim}

   388

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

   389

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

   390

   391

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

   392

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

   393

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

   394

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

   395

   396

\paragraph{LinCan}

   397

\begin{verbatim}

   398

	./configure --can=lincan

   399

\end{verbatim}

   400

   401

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

   402

\begin{verbatim}

   403

	./configure --can=virtual

   404

		or, for kernel space:

   405

	./configure --can=kernel_virtual

   406

\end{verbatim}

   407

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

   408

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

   409

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

   410

work with Xenomai or RTAI.

   411

   412

\paragraph{VScom}

   413

\begin{verbatim}

   414

	./configure --can=vscom

   415

\end{verbatim}

   416

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

   417

   418

\subsubsection{LSS services}

   419

Canfestival optionally supports LSS services but they must be enabled.

   420

\begin{verbatim}

   421

	./configure --enable-lss

   422

\end{verbatim}

   423

   424

Additionally, the FastScan LSS service can also be enabled.

   425

\begin{verbatim}

   426

	./configure --enable-lss --enable-lss-fs

   427

\end{verbatim}

   428

   429

\subsection{Testing your CanFestival installation}

   430

   431

\subsubsection{User space}

   432

   433

Sample provided in /example/TestMasterSlave is installed into your

   434

system during installation.

   435

   436

   437

\begin{verbatim}

   438

	TestMasterSlave

   439

\end{verbatim}

   440

   441

   442

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

   443

will simply pass CAN messages through Unix pipes between Master and

   444

Slave.

   445

   446

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

   447

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

   448

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

   449

   450

   451

\begin{verbatim}

   452

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

   453

\end{verbatim}

   454

   455

If the LSS services are enabled the sample provided in /example/TestMasterSlaveLSS will be also installed. It behaves the same as TestMasterSlave except that there are 2 slave nodes without a valid nodeID so the the initializations is done via  the LSS services. If FastScan optional service is enabled the example will use it. 

   456

   457

\subsubsection{Kernel space}

   458

   459

   460

\begin{verbatim}

   461

	example/kerneltest

   462

\end{verbatim}

   463

   464

   465

It's based on TestMasterSlave example

   466

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

   467

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

   468

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

   469

which is used to start/stop sending data.

   470

   471

   472

\section{Windows Targets}

   473

   474

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

   475

to use both Cygwin and win32 native runtime environment.

   476

   477

\subsection{Object Dictionary Editor GUI installation.}

   478

   479

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

   480

Dictionary Editor GUI}

   481

   482

\subsection{CYGWIN}

   483

   484

\subsubsection{Requirements}

   485

   486

Cygwin have to be installed with those packages :

   487

   488

\begin{enumerate}

   489

\item gcc 

   490

\item unzip 

   491

\item wget