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

    52

\subsection{What is \canopen}

    53

    54

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

    55

to :

    56

    57

\begin{enumerate}

    58

\item Configure a CAN network. 

    59

\item Transmit data to a specific node or in broadcast. 

    60

\item Administrate the network. For example detecting a not responding node. 

    61

\end{enumerate}

    62

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

    63

    64

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

    65

    66

The most important document about \canopen is the normative CiA Draft

    67

Standard 301, version 4.02. You can now download the specification

    68

from the CAN in Automation website at no cost.

    69

    70

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

    71

some papers introducing \canopen .

    72

    73

    74

\section{CanFestival Features}

    75

    76

    77

\subsection{Tools }

    78

    79

The \canopen library is coming with some tools :

    80

    81

\begin{enumerate}

    82

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

    83

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

    84

each node. 

    85

\item A configure script, that let you chose compile time options such as

    86

target CPU/HOST, CAN and TIMER drivers.\\

    87

 This script has not been generated with autoconf, it has been made

    88

keeping micro-controller target in mind. 

    89

\end{enumerate}

    90

    91

\subsection{Multi-Platform}

    92

    93

\begin{enumerate}

    94

\item Library source code is C-ANSI. 

    95

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

    96

contributor/compiler. 

    97

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

    98

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

    99

\end{enumerate}

   100

   101

\subsection{\canopen standard conformance}

   102

   103

\subsubsection{DS-301}

   104

   105

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

   106

   107

\begin{enumerate}

   108

\item NMT master and slave

   109

\item Heartbeat consumer and producer

   110

\item NodeGuard slave reponder and basic master without tracking

   111

\item SYNC service

   112

\item SDO multiples client and server, segmented and expedited

   113

\item PDO : TPDO and RPDO, with respect to transmission type

   114

\item PDO mapping from/to OD variables bit per bit. 

   115

\item EMCY : Send and receive and keeps track of emergency objects

   116

\item Data types : 8 to 64 bits values, fixed length strings.

   117

\end{enumerate}

   118

   119

\subsubsection{DS-302}

   120

   121

Only concise DFC is supported.

   122

   123

\subsubsection{DS-305}

   124

   125

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

   126

   127

\section{How to start}

   128

   129

\subsection{Host requirements}

   130

   131

What you need on your development workstation.

   132

   133

\subsubsection{Object Dictionary Editor GUI}

   134

   135

\begin{enumerate}

   136

\item Python, with 

   137

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

   138

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

   139

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

   140

Editor GUI'' ) 

   141

\end{enumerate}

   142

   143

\subsubsection{Linux and Unix-likes}

   144

   145

\begin{enumerate}

   146

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

   147

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

   148

platform. 

   149

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

   150

context sensitive help. 

   151

\item GNU Make 

   152

\item Bash and sed 

   153

\end{enumerate}

   154

   155

\subsubsection{Windows (for native win32 target)}

   156

   157

\begin{enumerate}

   158

\item Visual Studio Express 2005 or worst.

   159

\item Microsoft platform SDK (requires Genuine Advantage)

   160

\item Cygwin (for configuration only)

   161

\item MinGW/MSYS

   162

\end{enumerate}

   163

   164

\section{Understanding Canfestival}

   165

   166

\subsection{CanFestival Project tree layout}

   167

Simplified directory structure.

   168

\begin{verbatim}

   169

./src ANSI-C source of \canopen stack

   170

./include Exportables Header files

   171

./drivers Interfaces to specific platforms/HW

   172

./drivers/unix Linux and Cygwin OS interface

   173

./drivers/win32 Native Win32 OS interface

   174

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

   175

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

   176

./drivers/timers_kernel Linux kernel timer/threads

   177

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

   178

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

   179

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

   180

./drivers/can_peak_linux PeakSystem CAN library interface

   181

./drivers/can_peak_win32 PeakSystem PCAN-Light interface

   182

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

   183

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

   184

./drivers/can_vcom VScom VSCAN interface

   185

./drivers/hcs12 HCS12 full target interface

   186

./examples Examples

   187

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

   188

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

   189

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

   190

./examples/gene_SYNC_HCS12 Just send periodic SYNC on HCS12

   191

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

   192

./objdictgen Object Dictionary editor GUI

   193

./objdictgen/config Pre-defined OD profiles

   194

./objdictgen/examples Some examples/test OD

   195

./doc Documentation source

   196

\end{verbatim}

   197

   198

   199

   200

\subsection{Implement CanFestival in your application}

   201

   202

\begin{center}

   203

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

   204

\par\end{center}

   205

   206

\bigskip{}

   207

   208

   209

   210

\subsection{CanFestival CAN interfaces}

   211

   212

Because most CAN controllers and drivers implement FIFOs, CanFestival

   213

consider sending message as a non blocking operation.

   214

   215

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

   216

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

   217

   218

\begin{enumerate}

   219

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

   220

   221

   222

   223

\begin{center}

   224

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

   225

\par\end{center}

   226

   227

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

   228

reception should be a blocking operation.\\

   229

   230

   231

   232

\begin{center}

   233

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

   234

\par\end{center}

   235

   236

\end{enumerate}

   237

   238

\subsection{CanFestival event scheduling}

   239

   240

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

   241

   242

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

   243

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

   244

   245

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

   246

the \canopen needs directly. Moreover, CanFestival internal data

   247

may be corrupt by reentrant calls.

   248

   249

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

   250

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

   251

at desired time.

   252

   253

\begin{center}

   254

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

   255

\par\end{center}

   256

   257

Scheduler can handle short clock value ranges limitation found on

   258

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

   259

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

   260

must be segmented.

   261

   262

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

   263

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

   264

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

   265

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

   266

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

   267

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

   268

   269

\begin{center}

   270

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

   271

\par\end{center}

   272

   273

   274

\section{Linux Target}

   275

   276

Linux target is default configure target.

   277

   278

   279

\subsection{Linux Compilation and installation}

   280

   281

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

   282

   283

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

   284

type make.

   285

   286

   287

   288

\begin{verbatim}

   289

	./configure [options]

   290

	make

   291

	make install

   292

\end{verbatim}

   293

   294

   295

   296

   297

\subsubsection{Standard Linux node}

   298

   299

   300

\begin{verbatim}

   301

	./configure --timers=unix

   302

\end{verbatim}

   303

   304

   305

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

   306

   307

\begin{enumerate}

   308

\item A working linux distribution 

   309

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

   310

installed. 

   311

\end{enumerate}

   312

   313

\subsubsection{Real -Time Linux node}

   314

   315

With Xenomai :

   316

\begin{verbatim}

   317

	./configure --timers=xeno

   318

\end{verbatim}

   319

With Rtai :

   320

\begin{verbatim}

   321

	./configure --timers=rtai

   322

\end{verbatim}

   323

   324

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

   325

   326

\begin{enumerate}

   327

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

   328

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

   329

Linux driver installed. 

   330

\end{enumerate}

   331

   332

\subsubsection{Linux kernel node}

   333

   334

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

   335

   336

   337

\begin{enumerate}

   338

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

   339

\item A CAN card driver compatible with CanFestival

   340

\end{enumerate}

   341

   342

   343

\subsubsection{CAN devices}

   344

Currently supported CAN devices and corresponding configure switch:

   345

   346

\paragraph{Peak systems}

   347

\begin{verbatim}

   348

	./configure --can=peak_linux

   349

\end{verbatim}

   350

PeakSystems CAN interface is automatically chosen as default CAN interface

   351

if libpcan is present in the system.

   352

   353

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

   354

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

   355

on your system.

   356

   357

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

   358

\begin{verbatim}

   359

	./configure --can=socket

   360

\end{verbatim}

   361

   362

\paragraph{Serial}

   363

\begin{verbatim}

   364

	./configure --can=serial

   365

\end{verbatim}

   366

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

   367

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

   368

   369

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

   370

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

   371

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

   372

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

   373

   374

\paragraph{LinCan}

   375

\begin{verbatim}

   376

	./configure --can=lincan

   377

\end{verbatim}

   378

   379

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

   380

\begin{verbatim}

   381

	./configure --can=virtual

   382

		or, for kernel space:

   383

	./configure --can=kernel_virtual

   384

\end{verbatim}

   385

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

   386

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

   387

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

   388

work with Xenomai or RTAI.

   389

   390

\paragraph{VScom}

   391

\begin{verbatim}

   392

	./configure --can=vscom

   393

\end{verbatim}

   394

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.

   395

   396

\subsubsection{LSS services}

   397

Canfestival optionally supports LSS services but they must be enabled.

   398

\begin{verbatim}

   399

	./configure --enable-lss

   400

\end{verbatim}

   401

   402

Additionally, the FastScan LSS service can also be enabled.

   403

\begin{verbatim}

   404

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

   405

\end{verbatim}

   406

   407

\subsection{Testing your CanFestival installation}

   408

   409

\subsubsection{User space}

   410

   411

Sample provided in /example/TestMasterSlave is installed into your

   412

system during installation.

   413

   414

   415

\begin{verbatim}

   416

	TestMasterSlave

   417

\end{verbatim}

   418

   419

   420

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

   421

will simply pass CAN messages through Unix pipes between Master and

   422

Slave.

   423

   424

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

   425

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

   426

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

   427

   428

   429

\begin{verbatim}

   430

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

   431

\end{verbatim}

   432

   433

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. 

   434

   435

\subsubsection{Kernel space}

   436

   437

   438

\begin{verbatim}

   439

	example/kerneltest

   440

\end{verbatim}

   441

   442

   443

It's based on TestMasterSlave example

   444

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

   445

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

   446

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

   447

which is used to start/stop sending data.

   448

   449

   450

\section{Windows Targets}

   451

   452

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

   453

to use both Cygwin and win32 native runtime environment.

   454

   455

\subsection{Object Dictionary Editor GUI installation.}

   456

   457

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

   458

Dictionary Editor GUI}

   459

   460

\subsection{CYGWIN}

   461

   462

\subsubsection{Requirements}

   463

   464

Cygwin have to be installed with those packages :

   465

   466

\begin{enumerate}

   467

\item gcc 

   468

\item unzip 

   469

\item wget 

   470

\item make 

   471

\end{enumerate}

   472

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

   473

PcanLight driver and library.

   474

   475

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

   476

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

   477

in order to install driver on your system.

   478

   479

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

   480

   481

Open a Cygwin terminal, and follow those instructions:

   482

   483

   484

\subsubsection{Cygwin configuration and compilation}

   485

   486

   487

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

   488

   489

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

   490

page ):

   491