doc/manual/en/manual.tex

   1 \documentclass[a4paper,12pt]{book}
   2 \usepackage[ascii]{inputenc}
   3 \usepackage[T1]{fontenc}
   4 \usepackage[french,english]{babel}
   5 \usepackage{amsmath,amssymb,amsfonts,textcomp}
   6 \usepackage{color}
   7 \usepackage{calc}
   8 \usepackage{longtable}
   9 \usepackage{hyperref}
  10 \usepackage{graphics}
  11 \usepackage{graphicx}
  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 % Text styles
  22 %\newcommand\textstyleTeletype[1]{\texttt{#1}}
  23 % Outline numbering
  24 \setcounter{secnumdepth}{5}
  25 \renewcommand\thesection{\arabic{section} -}
  26 \renewcommand\thesubsection{\arabic{section}.\arabic{subsection})}
  27 \renewcommand\thesubsubsection{\arabic{section}.\arabic{subsection}.\arabic{subsubsection})}
  28 \renewcommand\theparagraph{\alph{paragraph})}
  29 \renewcommand\thesubparagraph{\roman{subparagraph})}
  30 % List styles
  31 \newcommand\liststyleLi{%
  32 \renewcommand\labelitemi{{--}}
  33 \renewcommand\labelitemii{{--}}
  34 \renewcommand\labelitemiii{{--}}
  35 \renewcommand\labelitemiv{{--}}
  36 }
  37 \newcommand\liststyleLii{%
  38 \renewcommand\labelitemi{{--}}
  39 \renewcommand\labelitemii{{--}}
  40 \renewcommand\labelitemiii{{--}}
  41 \renewcommand\labelitemiv{{--}}
  42 }
  43 \newcommand\liststyleLiii{%
  44 \renewcommand\labelitemi{{--}}
  45 \renewcommand\labelitemii{{--}}
  46 \renewcommand\labelitemiii{{--}}
  47 \renewcommand\labelitemiv{{--}}
  48 }
  49 \newcommand\liststyleLiv{%
  50 \renewcommand\labelitemi{{--}}
  51 \renewcommand\labelitemii{{--}}
  52 \renewcommand\labelitemiii{{--}}
  53 \renewcommand\labelitemiv{{--}}
  54 }
  55 \newcommand\liststyleLv{%
  56 \renewcommand\labelitemi{{--}}
  57 \renewcommand\labelitemii{{--}}
  58 \renewcommand\labelitemiii{{--}}
  59 \renewcommand\labelitemiv{{--}}
  60 }
  61 \newcommand\liststyleLvi{%
  62 \renewcommand\labelitemi{{--}}
  63 \renewcommand\labelitemii{{--}}
  64 \renewcommand\labelitemiii{{--}}
  65 \renewcommand\labelitemiv{{--}}
  66 }
  67 \newcommand\liststyleLvii{%
  68 \renewcommand\labelitemi{{--}}
  69 \renewcommand\labelitemii{{--}}
  70 \renewcommand\labelitemiii{{--}}
  71 \renewcommand\labelitemiv{{--}}
  72 }
  73 \newcommand\liststyleLviii{%
  74 \renewcommand\labelitemi{{--}}
  75 \renewcommand\labelitemii{{--}}
  76 \renewcommand\labelitemiii{{--}}
  77 \renewcommand\labelitemiv{{--}}
  78 }
  79 \newcommand\liststyleLix{%
  80 \renewcommand\labelitemi{{--}}
  81 \renewcommand\labelitemii{{--}}
  82 \renewcommand\labelitemiii{{--}}
  83 \renewcommand\labelitemiv{{--}}
  84 }
  85 \newcommand\liststyleLx{%
  86 \renewcommand\labelitemi{{--}}
  87 \renewcommand\labelitemii{{--}}
  88 \renewcommand\labelitemiii{{--}}
  89 \renewcommand\labelitemiv{{--}}
  90 }
  91 \newcommand\liststyleLxi{%
  92 \renewcommand\labelitemi{{--}}
  93 \renewcommand\labelitemii{{--}}
  94 \renewcommand\labelitemiii{{--}}
  95 \renewcommand\labelitemiv{{--}}
  96 }
  97 \newcommand\liststyleLxii{%
  98 \renewcommand\labelitemi{{--}}
  99 \renewcommand\labelitemii{{--}}
 100 \renewcommand\labelitemiii{{--}}
 101 \renewcommand\labelitemiv{{--}}
 102 }
 103 \newcommand\liststyleLxiii{%
 104 \renewcommand\labelitemi{{\textbullet}}
 105 \renewcommand\labelitemii{{\textbullet}}
 106 \renewcommand\labelitemiii{{\textbullet}}
 107 \renewcommand\labelitemiv{{\textbullet}}
 108 }
 109
 110 \begin{document}
 111
 112 {\centering\sffamily\Huge The CanFestival CANOpen stack manual.}
 113
 114 \renewcommand\contentsname{CanFestival v3.0 Manual}
 115 \setcounter{tocdepth}{2}
 116 \tableofcontents
 117 \section{Introduction}
 118 CanFestival is an OpenSource (LGPL and GPL) CANOpen framework.
 119
 120 \subsection{The CanFestival project}
 121 This project, initiated by Edouard TISSERANT in 2001, as grown thanks to
 122 Francis DUPIN and other contributors.
 123
 124 Today, CanFestival focuses on providing an ANSI{}-C platform independent
 125 CANOpen stack that can be implemented as master or slave nodes on PCs,
 126 Real{}-time IPCs, and Microcontrollers.
 127
 128 CanFestival is a project supported by Lolitech.
 129
 130 \subsection{What is CANopen}
 131 CANopen is a CAN based high level protocol. It defines some protocols to
 132 :
 133
 134 \liststyleLi
 135 \begin{enumerate}
 136 \item Configure a CAN network.
 137 \item Transmit data to a specific node or in broadcast.
 138 \item Administrate the network. For example detecting a not responding
 139 node.
 140 \end{enumerate}
 141 The documentation can be found in the Can in automation website :
 142
 143 \href{http://www.can-cia.de/canopen}{http://www.can{}-cia.de/canopen}
 144
 145 The most important document about CANopen is the normative CiA Draft
 146 Standard 301, version 4.02. You can now download with no cost the
 147 specification in Can in automation website.
 148
 149 To continue reading this document, let us assume that you have read some
 150 papers introducing CANopen.
 151
 152 \section{CanFestival Features}
 153 \subsection{Tools }
 154 The CANopen library is coming with some tools :
 155
 156 \liststyleLii
 157 \begin{enumerate}
 158 \item Object Dictionary editor GUI. WxPython Model{}-View{}-Controler
 159 based GUI, that help a lot in generating object dictionary source code
 160 for each node.
 161 \item A configure script, that let you chose compile time options such
 162 as target CPU/HOST, CAN and TIMER drivers.\newline
 163 This script have not been generated with autoconf, it have been made
 164 keeping micro{}-controller target in mind.
 165 \end{enumerate}
 166 \subsection{Standard conformance}
 167 \paragraph{Multi{}-Platform}
 168 \liststyleLiii
 169 \begin{enumerate}
 170 \item Library source code is C{}-ANSI.
 171 \item Driver and examples coding conventions merely depend on target
 172 specific contributor/compiler.
 173 \item Unix compatible interfaces and examples should compile and run on
 174 any Unix system (tested on GNU/Linux and GNU/FreeBSD).
 175 \end{enumerate}
 176 \paragraph{CanOpen conformance}
 177 {\bfseries\upshape
 178 DS{}-301}
 179
 180 \liststyleLiv
 181 \begin{enumerate}
 182 \item Should conform to DS301. V.4.02 13 february 2002.
 183 \item Master and Slave functionality implemented.
 184 \item Sending SYNC implemented.
 185 \item 1 SDO server per node. (update: more than one possible. To be more
 186 tested)
 187 \item Unlimited SDO client.
 188 \item SDO transmission mode : normal, expedited download and upload.
 189 \item Unlimited PDO receive.
 190 \item Unlimited PDO transmit.
 191 \item Object Data type implemented : 8, 16, 32 bits values, and fixed
 192 length strings.
 193 \item Slave state full implemented.
 194 \item NMT to change slave{\textquotesingle}s state implemented.
 195 \item PDO transmission mode : on request, every reception of 0 to n
 196 SYNC, on event.
 197 \item NMT Heartbeat implemented : A node can be either heartbeat
 198 producer or receiver.
 199 \item NMT NodeGuard implemented : Not fully implemented.
 200 \item TIME (time Stamp) : Not implemented.
 201 \item EMCY (emergency objects) : Not implemented.
 202 \item PDO Mapping bit per bit implemented.
 203 \end{enumerate}
 204 {\bfseries\upshape
 205 DS{}-302}
 206
 207 \liststyleLiv
 208 \begin{enumerate}
 209 \item Concise \space DFC : implemented.
 210 \end{enumerate}
 211 \section{How to start}
 212 \subsection{Host requirements}
 213 What you need on your development workstation.
 214
 215 \subsubsection{Object Dictionary Editor GUI}
 216 \liststyleLv
 217 \begin{enumerate}
 218 \item Python, with
 219 \item wxPyhon modules installed (at least version 2.6.3).
 220 \item Gnosis xml tools. (Optional can also be installed locally to the
 221 project automatically will the help of a Makefile. Please see
 222 \hyperlink{a91UsingDictionaryEditorGUIoutline}{9.1) Using Dictionary
 223 Editor GUI} )
 224 \end{enumerate}
 225 \subsubsection[\space Linux and Unix{}-likes]{\space Linux and Unix{}-likes}
 226 \liststyleLv
 227 \begin{enumerate}
 228 \item Linux, FreeBSD, Cygwin or any Unix environment with GNU toolchain.
 229 \item The GNU C compiler (gcc) or any other ANSI{}-C compiler for your
 230 target platform.
 231 \item Xpdf, and the official 301\_v04000201.pdf file in order to get GUI
 232 context sensitive help. Download the ds301 at\newline
 233 \href{http://www.can-cia.org/downloads/ciaspecifications/?1390}{http://www.can{}-cia.org/downloads/ciaspecifications/?1390}.
 234 \item GNU Make
 235 \item Bash and sed
 236 \end{enumerate}
 237 \subsubsection{Windows (for native win32 target)}
 238 \liststyleLv
 239 \begin{enumerate}
 240 \item Visual Studio Express 2005 or worst.
 241 \item Microsoft platform SDK (requires Genuine Advantage)
 242 \item Cygwin (for configuration only)
 243 \end{enumerate}
 244 \subsection{How to get CanFestival}
 245 Please always use CVS, this is the best way to get the most reactive
 246 support from the developer community :
 247
 248 cvs {}-d:pserver:anonymous@lolitech.dyndns.org:/canfestival
 249 login\newline
 250 (type return, without entering a password)
 251
 252 Then, enter : \newline
 253 cvs {}-z3 {}-d:pserver:anonymous@lolitech.dyndns.org:/canfestival co
 254 {}-P CanFestival{}-3
 255
 256 \section{Understanding Canfestival}
 257 \subsection{CanFestival Project tree layout}
 258 Simplified directory structure.
 259
 260 {\ttfamily\bfseries
 261 ./src ANSI{}-C source of CANOpen stack}
 262
 263 {\ttfamily\bfseries
 264 \space /include Exportables Header files}
 265
 266 {\ttfamily\bfseries
 267 ./drivers Interfaces to specific platforms/HW}
 268
 269 {\ttfamily
 270 ./drivers/unix Linux and Cygwin OS interface}
 271
 272 {\ttfamily
 273 ./drivers/win32 Native Win32 OS interface}
 274
 275 {\ttfamily
 276 ./drivers/timers\_xeno Xenomai timers/threads (Linux only)}
 277
 278 {\ttfamily
 279 ./drivers/timers\_unix Posix timers/threads (Linux, Cygwin)}
 280
 281 {\ttfamily
 282 ./drivers/can\_peak\_linux PeakSystem CAN library interface}
 283
 284 {\ttfamily
 285 ./drivers/can\_peak\_win32 PeakSystem PCAN{}-Light interface}
 286
 287 {\ttfamily
 288 ./drivers/can\_uvccm\_win32 Acacetus{\textquotesingle}s RS232
 289 ``CAN{}-uVCCM'' interface}
 290
 291 {\ttfamily
 292 ./drivers/can\_virtual Fake CAN network (Linux, Cygwin)}
 293
 294 {\ttfamily
 295 ./drivers/hcs12 HCS12 full target interface}
 296
 297 {\ttfamily\bfseries
 298 ./examples Examples}
 299
 300 {\ttfamily
 301 ./examples/TestMasterSlave 2 nodes, NMT SYNC SDO PDO, win32+unix}
 302
 303 {\ttfamily
 304 ./examples/TestMasterMicroMod 1 node, control Peak I/O Module, unix}
 305
 306 {\ttfamily
 307 ./examples/gene\_SYNC\_HCS12 Just send periodic SYNC on HCS12}
 308
 309 {\ttfamily
 310 ./examples/win32test Ask some DS301 infos to a node (\textbf{win32)}}
 311
 312 {\ttfamily\bfseries
 313 ./objdictgen Object Dictionary editor GUI}
 314
 315 {\ttfamily
 316 ./objdictgen/config Pre{}-defined OD profiles}
 317
 318 {\ttfamily
 319 ./objdictgen/examples Some examples/test OD}
 320
 321 {\ttfamily\bfseries
 322 ./doc Project and CanOpen doc}
 323
 324 \subsection{Implement CanFestival in your application}
 325
 326  \begin{center}
 327    \includegraphics[width=12cm]{Pictures/10000201000003F9000002CF880931E7.png}
 328 \end{center}
 329
 330 \bigskip
 331
 332 \subsection{CanFestival CAN interfaces}
 333 Because most CAN controllers and drivers implement FIFOs, CanFestival
 334 consider sending message as a non bloking operation.
 335
 336 In order to prevent reentrent calls to the stack, messages reception is
 337 implemented differently on {\textmu}C and OS.:
 338
 339 \liststyleLvi
 340 \begin{enumerate}
 341 \item {\textmu}C must provide interuption masking for timer and can
 342 receive IT\newline
 343  \begin{center}
 344    \includegraphics[width=12cm]{Pictures/10000201000003CA0000016604E6A5EF.png}
 345 \end{center}
 346 \item OS must provide a receive thread, a timer thread and a mutex. CAN
 347 reception is a bloking operation.\newline
 348 \begin{center}
 349    \includegraphics[width=12cm]{Pictures/10000201000003F9000002CF8B0CDAEA.png}
 350 \end{center}
 351 \end{enumerate}
 352 \subsection{CanFestival events scheduling}
 353 A CanOpen node must be able to take delayed actions.
 354
 355 As exemples, periodic sync emission, heartbeat production or SDO timeout
 356 need to set some alarms that will be called later and do the job.
 357
 358 {\textmu}C generaly do not have enough free timers to handle all the
 359 CanOpen needs directly. Moreover, CanFestival internal data may be
 360 corrupt by reentrant calls.
 361
 362 CanFestival implement a micro{}-scheduler (timer.c). It uses only one
 363 timer to mimic many timers. It manage an alarm table, and call alarms
 364 at desired time.
 365
 366 \begin{center}
 367    \includegraphics[width=12cm]{Pictures/100000000000022C000000DEDAD2140C.png}
 368 \end{center}
 369
 370 Scheduler can handle short clock value ranges limitation found on some
 371 {\textmu}C. As an example, value range for a 16bit clock counter with
 372 4{\textmu}s tick is crossed within 0.26 seconds... Long alarms must be
 373 segmented.
 374
 375 Chronogram illustrate a long alarm (A) and a short periodic alarm (B),
 376 with a A value {\textgreater} clock range {\textgreater} B value.
 377 Values t0...t8 are successive setTimer call parameter values. t1
 378 illustrates an intermediate call to TimeDispatch, caused by a delay
 379 longer than clock range. Because of long alarm segmentation, at the end
 380 of t1, TimeDispatch call will not trig any alarm callback.
 381
 382 \begin{center}
 383    \includegraphics[width=12cm]{Pictures/1000000000000396000000FFC42573DA.png}
 384 \end{center}
 385
 386 \section{Linux Target}
 387 Linux target is default configure target.
 388
 389 \subsection{Linux Compilation and installation}
 390 Call ./configure {--}help to see all available compile time options.
 391
 392 After invoking ./configure with your platform specific switches, just
 393 type make.
 394
 395 {\ttfamily
 396 ./configure [options]}
 397
 398 {\ttfamily
 399 make}
 400
 401 {\ttfamily
 402 make install}
 403
 404 \subsubsection{Standard Linux node}
 405 Configure switch:
 406
 407 {\ttfamily
 408  {}-{}-timers=unix}
 409
 410 To do a CANopen node running on PC{}-Linux, you need :
 411
 412 \liststyleLvii
 413 \begin{enumerate}
 414 \item A working linux distribution
 415 \item One or more Peak system PC CAN interface and the last Peak Linux
 416 driver installed.
 417 \end{enumerate}
 418 \subsubsection{Real{}-Time Linux node}
 419 Configure switch:
 420
 421 {\ttfamily
 422  {}-{}-timers=xeno}
 423
 424 To do a CANopen node running on PC{}-Linux, you need :
 425
 426 \liststyleLviii
 427 \begin{enumerate}
 428 \item A working Linux distribution patched with XENOMAI 2.1 or greater.
 429 \item One or more Peak system PC CAN interface and the last Peak Real
 430 Time Linux driver installed.
 431 \end{enumerate}
 432 \subsubsection{CAN devices}
 433 Curently supported CAN devices and corresponding configure switch:
 434
 435 \paragraph{Peak systems}
 436 Configure switch:
 437
 438 {\ttfamily
 439 {}-{}-can=peak\_linux}
 440
 441 PeakSystems CAN interface is automatically chosen as default CAN
 442 interface if libpcan is present in the system.
 443
 444 Please download driver at
 445 \href{http://www.peak-system.com/linux}{http://www.peak{}-system.com/linux}
 446 and follow instructions in order to install driver on your system.
 447
 448 \paragraph{Socket{}-Can (http://socketcan.berlios.de)}
 449 Configure switch:
 450
 451 {\ttfamily
 452 {}-{}-can=socket}
 453
 454 \paragraph{LinCan}
 455 Configure switch:
 456
 457 {\ttfamily
 458 {}-{}-can=lincan}
 459
 460 \paragraph{Virtual CAN interfaces (for test/debug)}
 461 Configure switch:
 462
 463 {\ttfamily
 464 {}-{}-can=virtual}
 465
 466 Virtual CAN interface use Unix pipes to emulate a virtual CAN network.
 467 Each message issued from a node is repeat to all other nodes. Currently
 468 only works with nodes running in the same process, and does not support
 469 work with Xenomai.
 470
 471 \subsection{Testing your CanFestival installation}
 472 Sample provided in /example/TestMasterSlave is installed into your
 473 system during installation.
 474
 475 {\ttfamily
 476 TestMasterSlave}
 477
 478 Default can driver library is libcanfestival\_can\_virtual.so., which
 479 will simply pass CAN messages through Unix pipes between Master and
 480 Slave.
 481
 482 You may also want to specify different can interface and define some CAN
 483 ports. An other example using Peak{\textquotesingle}s dual PCMCIA
 484 (configure and install with {--}can=peak) :
 485
 486 {\ttfamily
 487 TestMasterSlave {}-l libcanfestival\_can\_peak.so {}-s 40 {}-m 41}
 488
 489 \section{Windows Targets}
 490 CanFestival can be compiled and run on Windows platform. It is possible
 491 to use both Cygwin and win32 native runtime environment.
 492
 493 \subsection{Object Dictionary Editor GUI installation.}
 494 Please refer to
 495 \hyperlink{a821UsingDictionaryEditorGUIoutline}{8.2.1)Using Dictionary
 496 Editor GUI}
 497
 498 \subsection{CYGWIN}
 499 \subsubsection{Requirements}
 500 Cygwin have to be installed with those packages :
 501
 502 \liststyleLix
 503 \begin{enumerate}
 504 \item gcc
 505 \item unzip
 506 \item wget
 507 \item make
 508 \end{enumerate}
 509 Currently, the only supported CAN devices are PeakSystems ones, with
 510 PcanLight driver and library.
 511
 512 Please download driver at
 513 \href{http://www.peak-system.com/themen/download_gb.html}{http://www.peak{}-system.com/themen/download\_gb.html}
 514 \space and follow instructions in order to install driver on your system.
 515
 516 Install Cygwin as required, and the driver for your Peak CAN device.
 517
 518 Open a Cygwin terminal, and follow those instructions:
 519
 520 \subsubsection{Cygwin configuration and compilation}
 521 \paragraph{A single node with PcanLight and Peak CAN{}-USB adapter}
 522 Download the PCAN{}-Light Zip file for your HW ( URL from download page
 523 ):
 524
 525 {\ttfamily
 526 wget http://www.peak{}-system.com/files/usb.zip}
 527
 528 Extract its content into your cygwin home (it will create a ``Disk''
 529 directory):
 530
 531 {\ttfamily
 532 unzip usb.zip}
 533
 534 Configure CanFestival3 providing path to the desired PcanLight
 535 implementation:
 536
 537 {\ttfamily
 538 cd CanFestival{}-3}
 539
 540 {\ttfamily
 541 export PCAN\_INCLUDE=\~{}/Disk/PCAN{}-Light/Api/}
 542
 543 {\ttfamily
 544 export PCAN\_HEADER=Pcan\_usb.h}
 545
 546 {\ttfamily
 547 export PCAN\_LIB=\~{}/Disk/PCAN{}-Light/Lib/Visual{\textbackslash}
 548 C++/Pcan\_usb.lib}
 549
 550 {\ttfamily
 551 ./configure {}-{--}can=peak\_win32}
 552
 553 {\ttfamily
 554 make}
 555
 556 In order to test, you have to use another CanFestival node, connect with
 557 a CAN cable.
 558
 559 {\ttfamily
 560 cp \~{}/Disk/PCAN{}-Light/Pcan\_usb.dll .}
 561
 562 {\ttfamily
 563 ./examples/TestMasterSlave/TestMasterSlave {\textbackslash}}
 564
 565 {\ttfamily
 566   {}-l drivers/can\_peak\_win32/cygcan\_peak\_win32.dll
 567 {\textbackslash}}
 568
 569 {\ttfamily
 570   {}-S 500K {}-M none}
 571
 572 Then, on the other node :
 573
 574 {\ttfamily
 575 ./TestMasterSlave {}-l my\_driver.so {}-S none {}-M 500K}
 576
 577 Now messages are beeing exchanged between master and slave node.
 578
 579 \paragraph{Two nodes with PcanLight and Peak dual PCMCIA{}-CAN adapter}
 580 Download the PCAN{}-Light Zip file for your HW ( URL from download page
 581 ):
 582
 583 {\ttfamily
 584 wget http://www.peak{}-system.com/files/pccard.zip}
 585
 586 Extract its content into your cygwin home (it will create a ``Disk''
 587 directory):
 588
 589 {\ttfamily
 590 unzip pccard.zip}
 591
 592 The configure CanFestival3 providing path to the desired PcanLight
 593 implementation:
 594
 595 {\ttfamily
 596 export PCAN\_INCLUDE=\~{}/Disk/PCAN{}-Light/Api/\newline
 597 export PCAN\_HEADER=Pcan\_pcc.h\newline
 598 export PCAN\_LIB=\~{}/Disk/PCAN{}-Light/Lib/Visual{\textbackslash}
 599 C++/Pcan\_pcc.lib\newline
 600 export PCAN2\_HEADER=Pcan\_2pcc.\newline
 601 export PCAN2\_LIB=\~{}/Disk/PCAN{}-Light/Lib/Visual{\textbackslash}
 602 C++/Pcan\_2pcc.lib}
 603
 604 In order to test, just connect together both CAN ports of the PCMCIA
 605 card. Don{\textquotesingle}t forget 120ohms terminator.
 606
 607 {\ttfamily
 608 cp \~{}/Disk/PCAN{}-Light/Pcan\_pcc.dll .}
 609
 610 {\ttfamily
 611 cp \~{}/Disk/PCAN{}-Light/Pcan\_2pcc.dll .}
 612
 613 {\ttfamily
 614 ./examples/TestMasterSlave/TestMasterSlave {\textbackslash}}
 615
 616 {\ttfamily
 617   {}-l drivers/can\_peak\_win32/cygcan\_peak\_win32.dll}
 618
 619 Messages are then exchanged between master and slave node, both inside
 620 TestMasterSlave{\textquotesingle}s process.
 621
 622 \subsection{Visual Studio C++}
 623 \subsubsection{Requirements}
 624 Minimal Cygwin installation is required at configuration time in order
 625 to create specific header files (config.h and cancfg.h). Once this
 626 files created, cygwin is not necessary any more.
 627
 628 Project and solution files have been created and tested with Visual
 629 Studio Express 2005. Be sure to have installed Microsoft Platform SDK,
 630 as recommended at the end of Visual Studio installation.
 631
 632 \subsubsection{Configuration with cygwin}
 633 Follow instructions given at
 634 \hyperlink{Cygwin configuration and compilation}{Cygwin
 635 configuration and compilation}, but do neither call make nor do tests,
 636 just do configuration steps. This will create headers files accordingly
 637 to your configuration parameters, and the desired CAN hardware.
 638
 639 \subsubsection{Compilation with Visual Studio}
 640 You can either load independents ``*.vcproj'' project files along your
 641 own projects in your own solution or load the provided
 642 ``CanFestival{}-3.vc8.sln'' solution files directly.
 643
 644 Build CanFestival{}-3 project first.
 645
 646 \paragraph{PcanLight and the can\_peak\_win32 project.}
 647 Chosen Pcan\_xxx.lib and eventually Pcan\_2xxx.lib files must be added
 648 to can\_peak\_win32 \space \space project before build of the DLL.
 649
 650 \subsubsection{Testing}
 651 Copy eventually needed dlls (ie : Pcan\_Nxxx.lib) into Release or Debug
 652 directory, and run the test program:
 653
 654 {\ttfamily
 655 TestMasterSlave.exe {}-l can\_peak\_win32.dll}
 656
 657 \subsection{MSYS}
 658
 659
 660 \subsubsection{Requirements}
 661
 662 Download from : http://sourceforge.net/project/showfiles.php?group\_id=2435
 663
 664 \begin{enumerate}
 665 \item MSYS-1.0.10.exe
 666 \item MinGW-5.1.3.exe
 667 \item mingwPORT (which contains wget-1.9.1)
 668 \end{enumerate}
 669 Please download driver at http://www.peak-system.com/themen/download\_gb.html
 670 and follow instructions in order to install driver on your system.
 671 Install MSYS and MingW as required, and the driver for your Peak CAN
 672 device. Open a MSYS terminal, and follow those instructions:\\
 673
 674
 675 \begin{itemize}
 676 \item extract wget-1.9.1-mingwPORT.tar.bz2
 677 \item copy wget.exe in c:\textbackslash{}msys\textbackslash{}1.0\textbackslash{}bin\textbackslash{}
 678 \item start MSYS and check the file /etc/fstab contain the line c:/MinGW
 679 /mingw
 680 \end{itemize}
 681
 682 \subsubsection{MSYS configuration and compilation}
 683
 684 Instructions for compilation are nearly the same as CYGWIN part.
 685
 686
 687 \paragraph{A single node with PcanLight and Peak CAN-USB adapter}
 688
 689 Download the PCAN-Light Zip file for your HW ( URL from download page
 690 ):
 691
 692 \texttt{wget http://www.peak-system.com/files/usb.zip}~\\
 693
 694
 695 Extract its content into your MSYS's home (it will create a \char`\"{}Disk\char`\"{}
 696 directory):
 697
 698 \texttt{unzip usb.zip}~\\
 699
 700
 701 Configure CanFestival3 providing path to the desired PcanLight implementation:
 702
 703 \texttt{cd CanFestival-3}
 704
 705 \texttt{export PCAN\_INCLUDE=\~{ }/Disk/PCAN-Light/Api/}
 706
 707 \texttt{export PCAN\_HEADER=Pcan\_usb.h}
 708
 709 \texttt{export PCAN\_LIB=\~{ }/Disk/PCAN-Light/Lib/Visual\textbackslash{}
 710 C++/Pcan\_usb.lib}
 711
 712 \texttt{./configure -{}-can=peak\_win32}
 713
 714 \texttt{make}~\\
 715
 716
 717 In order to test, you have to use another CanFestival node, connect
 718 with a CAN cable.
 719
 720 \texttt{cp \~{ }/Disk/PCAN-Light/Pcan\_usb.dll .}
 721
 722 \texttt{./examples/TestMasterSlave/TestMasterSlave \textbackslash{}}
 723
 724 \texttt{-l drivers/can\_peak\_win32/cygcan\_peak\_win32.dll \textbackslash{}}
 725
 726 \texttt{-S 500K -M none}~\\
 727
 728
 729 Then, on the other node :
 730
 731 \texttt{./TestMasterSlave -l my\_driver.so -S none -M 500K -m 0}
 732
 733 Now messages are beeing exchanged between master and slave node.
 734
 735
 736 \paragraph{Two nodes with PcanLight and Peak dual PCMCIA-CAN adapter}
 737
 738 Download the PCAN-Light Zip file for your HW ( URL from download page
 739 ):
 740
 741 \texttt{wget http://www.peak-system.com/files/pccard.zip}~\\
 742 \\
 743 Extract its content into your MSYS's home (it will create a \char`\"{}Disk\char`\"{}
 744 directory):
 745
 746 \texttt{unzip pccard.zip}~\\
 747 \\
 748 The configure CanFestival3 providing path to the desired PcanLight
 749 implementation:\\
 750
 751
 752 \texttt{export PCAN\_INCLUDE=\~{ }/Disk/PCAN-Light/Api/}
 753
 754 \texttt{export PCAN\_HEADER=Pcan\_pcc.h}
 755
 756 \texttt{export PCAN\_LIB=\~{ }/Disk/PCAN-Light/Lib/Visual\textbackslash{}
 757 C++/Pcan\_pcc.lib}
 758
 759 \texttt{export PCAN2\_HEADER=Pcan\_2pcc.h}
 760
 761 \texttt{export PCAN2\_LIB=\~{ }/Disk/PCAN-Light/Lib/Visual\textbackslash{}
 762 C++/Pcan\_2pcc.lib}~\\
 763
 764
 765 In order to test, just connect together both CAN ports of the PCMCIA
 766 card. Don't forget 120ohms terminator.
 767
 768 \texttt{cp\~{ }/Disk/PCAN-Light/Pcan\_pcc.dll ~.}
 769
 770 \texttt{cp \~{ }/Disk/PCAN-Light/Pcan\_2pcc.dll ~.}
 771
 772 \texttt{./examples/TestMasterSlave/TestMasterSlave \textbackslash{}}
 773
 774 \texttt{-l drivers/can\_peak\_win32/cygcan\_peak\_win32.dll -m 0 -s
 775 1}~\\
 776
 777
 778 Messages are then exchanged between master and slave node, both inside
 779 TestMasterSlave's process.
 780
 781 \section{Motorola HCS12}
 782 The examples have been tested on a MC9S12DG255 mounted on a
 783 Elektronikladen HCS12 T{}-board.
 784
 785 Beware that there are a few differences in the MSCAN module of the
 786 68HC12 and HCS12 microcontroller. For a HC12, you must adapt the driver
 787 that we provide for \space the HCS12.
 788
 789 For the difference MSCAN HC12/HCS12, see the Motorola application note
 790 AN2011/D.
 791
 792 Configure switch:
 793
 794 {\ttfamily
 795  {}-{}-target=hcs12}
 796
 797 To do a CANopen node running on a microncontroller Motorola MC9S12DP256,
 798 you need :
 799
 800 \liststyleLx
 801 \begin{enumerate}
 802 \item The compiler GNU gcc for HC11, HC12, HCS12 : m6811{}-elf. \newline
 803 Download the \textbf{release 3.1} at :
 804 \space \href{http://m68hc11.serveftp.org/m68hc11_pkg_rpm.php}{http://m68hc11.serveftp.org/m68hc11\_pkg\_rpm.php}
 805
 806 \item A board with this chip. We are using the T{}-board from
 807 Electronikladden.
 808 \item At least about 40 kBytes of program memory.
 809 \item A tool to flash the memory. (We are using the hight cost
 810 Lauterbach debugger).
 811 \end{enumerate}
 812 \subsection{Running a HCS12 node}
 813 \subsubsection{Compiling Canfestival:}
 814 {\ttfamily
 815 ./configure {--}target=hcs12}
 816
 817 \subsubsection{Compiling and building an example}
 818 Enter in the folder of an HCS12 example,
 819
 820 {\ttfamily
 821 make all}
 822
 823 \subsubsection{Flashing the memory :}
 824 Use your prefered loader ! If you are using a debugger Lauterbach, you
 825 can load the bash file : trace32\_flash\_programmer.cmm. It loads
 826 directly the elf file.
 827
 828 \subsubsection{Connecting to a serial RS232 console :}
 829 Connect the portS(TxD0) of the HCS12 to a console configured at 19200
 830 bauds 8N1, via a Max232 chip to adapt the electricals levels. On Linux,
 831 you can use minicom. Connecting to a console is usefull to read the
 832 messages, but not required.
 833
 834 \subsubsection{Connecting to the CAN network :}
 835 Connect the port CAN0 (pin PM0, PM1) to the network via a CAN
 836 controller. On our board, the CAN controler is a PCA82C250 chip.
 837
 838 \subsubsection{starting the node :}
 839 Press the reset of your HCS12 board.
 840
 841 \section{Example and test program:}
 842 The ``examples'' directory contains some test program you can use as
 843 example for your own developments.
 844
 845 \subsection{TestMasterSlave}
 846 {\ttfamily
 847 **************************************************************\space}
 848
 849 {\ttfamily
 850 * \space TestMasterSlave
 851 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
 852
 853 {\ttfamily
 854 *
 855 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
 856
 857 {\ttfamily
 858 * \space A simple example for PC. It does implement 2 CanOpen \space \space \space \space \space *}
 859
 860 {\ttfamily
 861 * \space nodes in the same process. A master and a slave. Both \space \space \space \space *}
 862
 863 {\ttfamily
 864 * \space communicate together, exchanging periodically NMT, SYNC, \space *}
 865
 866 {\ttfamily
 867 * \space SDO and PDO. Master configure heartbeat producer time \space \space \space \space *}
 868
 869 {\ttfamily
 870 * \space at 1000 ms for slave node{}-id 0x02 by concise DCF.
 871 \space \space \space \space \space \space \space \space *}
 872
 873 {\ttfamily
 874 *
 875 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
 876
 877 {\ttfamily
 878 * \space \space Usage:
 879 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
 880
 881 {\ttfamily
 882 * \space \space ./TestMasterSlave \space [OPTIONS]
 883 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
 884
 885 {\ttfamily
 886 *
 887 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
 888
 889 {\ttfamily
 890 * \space \space OPTIONS:
 891 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
 892
 893 {\ttfamily
 894 * \space \space \space \space {}-l : Can library
 895 [{\textquotedbl}libcanfestival\_can\_virtual.so{\textquotedbl}]
 896 \space \space \space \space *}
 897
 898 {\ttfamily
 899 *
 900 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
 901
 902 {\ttfamily
 903 * \space \space \space Slave:
 904 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
 905
 906 {\ttfamily
 907 * \space \space \space \space {}-s : bus name [{\textquotedbl}0{\textquotedbl}]
 908 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
 909
 910 {\ttfamily
 911 * \space \space \space \space {}-S : 1M,500K,250K,125K,100K,50K,20K,10K,none(disable) \space *}
 912
 913 {\ttfamily
 914 *
 915 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
 916
 917 {\ttfamily
 918 * \space \space \space Master:
 919 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
 920
 921 {\ttfamily
 922 * \space \space \space \space {}-m : bus name [{\textquotedbl}1{\textquotedbl}]
 923 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
 924
 925 {\ttfamily
 926 * \space \space \space \space {}-M : 1M,500K,250K,125K,100K,50K,20K,10K,none(disable) \space *}
 927
 928 {\ttfamily
 929 *
 930 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
 931
 932 {\ttfamily
 933 **************************************************************}
 934
 935
 936 \bigskip
 937
 938 {\sffamily
 939 Notes for Concise DCF :}
 940
 941
 942 \bigskip
 943
 944 {\sffamily
 945  In this example, Master configure \space heartbeat producer time at 1000 ms
 946 for slave node{}-id 0x02 by concise DCF according DS{}-302 profile. }
 947
 948 {\sffamily
 949  }
 950
 951 {\sffamily
 952  Index 0x1F22 , sub{}-index 0x00 of the master OD, correspond to the
 953 number of entries. This equal to the maximum possible nodeId (127).
 954 Each sub{}-index points to the Node{}-ID of the device, to which the
 955 configuration belongs. }
 956
 957
 958 \bigskip
 959
 960 {\sffamily
 961  To add more parameters configurations to the slave, the value at
 962 sub{}-index 0x02 must be a binary stream (little{}-endian) following
 963 this structure :\newline
 964 \{
 965 (UNS32) nb of entries\newline
 966 (UNS16) index parameter 1\newline
 967 (UNS8) sub{}-index parameter 1\newline
 968 (UNS32) size data parameter 1\newline
 969 (DOMAIN) data parameter 1\newline
 970 (UNS16) index parameter 2\newline
 971 (UNS8) sub{}-index parameter 2\newline
 972 (UNS32) size data parameter 2\newline
 973 (DOMAIN) data parameter 2\newline
 974 \space \space \space \space \space ....\newline
 975 (UNS16) index parameter n\newline
 976 (UNS8) sub{}-index parameter n\newline
 977 (UNS32) size data parameter n\newline
 978 (DOMAIN) data parameter n\newline
 979 \}
 980 }
 981
 982 {\sffamily
 983  So the binary value stream to configure heartbeat producer time must be
 984 :\newline
 985     0100000017100002000000e803}
 986
 987 {\sffamily
 988 The slave node is configured just before the Master entering in
 989 Pre\_operational state.}
 990
 991 \subsection{gene\_SYNC\_HCS12 :}
 992 This is a simple CanOpen node that only send cyclic SYNC message. It
 993 demonstrate implementation on HCS12 based board.
 994
 995
 996 \bigskip
 997
 998 \subsection{TestMasterMicroMod }
 999 {\ttfamily
1000 **************************************************************}
1001
1002 {\ttfamily
1003 * \space TestMasterMicroMod
1004 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1005
1006 {\ttfamily
1007 *
1008 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1009
1010 {\ttfamily
1011 * \space A simple example for PC.
1012 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1013
1014 {\ttfamily
1015 * \space A CanOpen master that control a MicroMod module:
1016 \space \space \space \space \space \space \space \space \space *}
1017
1018 {\ttfamily
1019 * \space {}- setup module TPDO 1 transmit type
1020 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1021
1022 {\ttfamily
1023 * \space {}- setup module RPDO 1 transmit type
1024 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1025
1026 {\ttfamily
1027 * \space {}- setup module hearbeatbeat period
1028 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1029
1030 {\ttfamily
1031 * \space {}- disable others TPDOs
1032 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1033
1034 {\ttfamily
1035 * \space {}- set state to operational
1036 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1037
1038 {\ttfamily
1039 * \space {}- send periodic SYNC
1040 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1041
1042 {\ttfamily
1043 * \space {}- send periodic RPDO 1 to Micromod (digital output) \space \space \space \space \space \space *}
1044
1045 {\ttfamily
1046 * \space {}- listen Micromod{\textquotesingle}s TPDO 1 (digital input)
1047 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1048
1049 {\ttfamily
1050 * \space {}- Mapping RPDO 1 bit per bit (digital input)
1051 \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1052
1053 {\ttfamily
1054 *
1055 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1056
1057 {\ttfamily
1058 * \space \space Usage:
1059 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1060
1061 {\ttfamily
1062 * \space \space ./TestMasterMicroMod \space [OPTIONS]
1063 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1064
1065 {\ttfamily
1066 *
1067 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1068
1069 {\ttfamily
1070 * \space \space OPTIONS:
1071 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1072
1073 {\ttfamily
1074 * \space \space \space \space {}-l : Can library
1075 [{\textquotedbl}libcanfestival\_can\_virtual.so{\textquotedbl}]
1076 \space \space \space \space *}
1077
1078 {\ttfamily
1079 *
1080 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1081
1082 {\ttfamily
1083 * \space \space \space Slave:
1084 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1085
1086 {\ttfamily
1087 * \space \space \space \space {}-i : Slave Node id format [0x01 , 0x7F]
1088 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1089
1090 {\ttfamily
1091 *
1092 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1093
1094 {\ttfamily
1095 * \space \space \space Master:
1096 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1097
1098 {\ttfamily
1099 * \space \space \space \space {}-m : bus name [{\textquotedbl}1{\textquotedbl}]
1100 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1101
1102 {\ttfamily
1103 * \space \space \space \space {}-M : 1M,500K,250K,125K,100K,50K,20K,10K
1104 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1105
1106 {\ttfamily
1107 *
1108 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space *}
1109
1110 {\ttfamily
1111 **************************************************************}
1112
1113 \section{Developing a new node}
1114 Using provided examples as a base for your new node is generally a good
1115 idea. You can also use the provided *.od files as a base for your node
1116 object dictionary.
1117
1118 Creating a new CanOpen node implies to define the Object Dictionary of
1119 this node. For that, developer have to provide a C file. This C file
1120 contains the definition of all dictionary entries, and some kind of
1121 index table that helps the stack to access some entries directly.
1122
1123 \subsection{Using Dictionary Editor GUI}
1124 The Object Dictionary Editor is a WxPython based GUI that is used to
1125 create the C file needed to create a new CanOpen node.
1126
1127 \subsubsection{Installation and usage on Linux}
1128 You first have to download and install Gnosis XML modules. This is
1129 automated by a Makefile rule.
1130
1131 {\ttfamily
1132 cd objdictgen}
1133
1134 {\ttfamily
1135 make}
1136
1137 Now start the editor.
1138
1139 {\ttfamily
1140 python objdictedit.py [od files...]}
1141
1142 \subsubsection{Installation and usage on Windows}
1143 Install Python (at least version 2.4) and wxPython (at least version
1144 2.6.3.2).
1145
1146 Cygwin users can install Gnosis XML utils the same as Linux use. Just
1147 call make.
1148
1149 {\ttfamily
1150 cd objdictgen}
1151
1152 {\ttfamily
1153 make}
1154
1155 Others will have to download and intall Gnosis XML by hand :
1156
1157 {\ttfamily
1158 Gnosis Utils:}
1159
1160 {\ttfamily
1161 http://freshmeat.net/projects/gnosisxml/}
1162
1163 {\ttfamily
1164 http://www.gnosis.cx/download/Gnosis\_Utils.More/Gnosis\_Utils{}-1.2.1.win32{}-py24.exe}
1165
1166 {\ttfamily
1167 Get latest version.}
1168
1169 Download CanFestival archive and uncompress it. Use windows file
1170 explorer to go into CanFestival3{\textbackslash}objdicgten, and
1171 double{}-click on objdictedit.py.
1172
1173 \subsubsection{About}
1174 The Object Dictionary editor GUI is a python application that use the
1175 Model{}-View{}-Controller design pattern. It depends on WxPython to
1176 display view on any supported platform.
1177
1178  \begin{center}
1179    \includegraphics[width=7cm]{Pictures/10000201000001FC000001E5D65E8766.png}
1180 \end{center}
1181
1182 \subsubsection{Main view}
1183 Top list let you choose dictionary section, bottom left list is the
1184 selected index in that dictionary, and bottom right list are edited
1185 sub{}-indexes.
1186
1187  \begin{center}
1188    \includegraphics[width=12cm]{Pictures/10000201000003E7000001C7B0296577.png}
1189 \end{center}
1190
1191  \begin{center}
1192    \includegraphics[width=3cm]{Pictures/10000000000000B6000000DF1EDD1E73.png}
1193 \end{center}
1194   \begin{center}
1195    \includegraphics[width=3cm]{Pictures/10000000000000AC000000C9C3F53FA6.png}
1196 \end{center}
1197  \begin{center}
1198    \includegraphics[width=3cm]{Pictures/100000000000006D000000A31EC8CB54.png}
1199 \end{center}
1200   \begin{center}
1201    \includegraphics[width=3cm]{Pictures/10000000000000AA0000006014F74635.png}
1202 \end{center}
1203
1204 \subsubsection{New node}
1205 Edit your node name, ID and type. Choose your inherited specific
1206 profile.
1207
1208  \begin{center}
1209    \includegraphics[width=11cm]{Pictures/10000201000001CB0000015F4FC09B68.png}
1210 \end{center}
1211
1212 \subsubsection{Node info}
1213 Edit your node name, ID and type.
1214
1215  \begin{center}
1216    \includegraphics[width=7cm]{Pictures/10000201000001010000011DA724D25C.png}
1217 \end{center}
1218
1219 \subsubsection{Profile editor}
1220 Chose the used profile to edit.\newline
1221  \begin{center}
1222    \includegraphics[width=4cm]{Pictures/10000000000000AB000000C88F594413.png}
1223 \end{center}
1224
1225 Pick up optional chosen profile entries.\newline
1226  \begin{center}
1227    \includegraphics[width=11cm]{Pictures/10000201000002DE000001D82D89C224.png}
1228 \end{center}
1229
1230 \subsubsection{User types}
1231 Use User Types to implement value boundaries, and string lentgth\newline
1232  \begin{center}
1233    \includegraphics[width=11cm]{Pictures/10000201000001C40000010766961D7F.png}
1234 \end{center}
1235
1236 \subsubsection{Mapped variable}
1237 Add your own specific dictionary entries and associated mapped
1238 variables.\newline
1239  \begin{center}
1240    \includegraphics[width=11cm]{Pictures/10000201000001C4000000DD129D4661.png}
1241 \end{center}
1242
1243 \subsubsection{Integrated help}
1244 Using F1 key, you can get context sensitive help.\newline
1245  \begin{center}
1246    \includegraphics[width=12cm]{Pictures/10000201000002F30000020B23ED7F67.png}
1247 \end{center}
1248
1249 In order to do that, official 301\_v04000201.pdf file must be placed
1250 into doc/ directory, and xpdf must be present on your system.
1251
1252 F2 key open HTML CanFestival help.\newline
1253  \begin{center}
1254    \includegraphics[width=12cm]{Pictures/10000201000003440000025ACC3FD2F1.png}
1255 \end{center}
1256
1257 \subsection{Generating the object Dictionary}
1258 Once object dictionary has been edited and saved, you have to generate
1259 object dictionary C code for your CanFestival node.
1260
1261 \subsubsection{With GUI}
1262 Menu entry ``File/Build Dictionary''.
1263
1264  \begin{center}
1265    \includegraphics[width=4cm]{Pictures/10000201000000B7000000C66AF89CD5.png}
1266 \end{center}
1267
1268 Choose C file to create or overwrite. Header file will be also created
1269 with the same prefix as C file.
1270
1271 \subsubsection{With command line}
1272 {\ttfamily
1273 Usage of objdictgen.py :\newline
1274 python objdictgen.py XMLFilePath CfilePath}
1275
1276 \section{FAQ}
1277 \subsection{General}
1278 \subsubsection{Does the code compiles on Windows ?}
1279 Yes, with both Cygwin and Visual Studio C++.
1280
1281 Because CANopen layer is coded with C, put a compilation option /TC or
1282 /TP if you plan to mix C++ files. See the MSDN documentation about
1283 that.
1284
1285 \subsubsection{How to fit the library to an other microcontr\^oler ?}
1286 First, be sure that you have at least 40K bytes of program memory, and
1287 about 2k of RAM.
1288
1289 You have to create target specific interface to HW resources. Take model
1290 on bundled interfaces provided in drivers/ and create your own
1291 interface. You also have to update Makefile.in files for target
1292 specific cflags and options. Chose {--}targer= configure switch to
1293 compile your specific interface.
1294
1295 You are welcome to contribute{}-back your own interfaces ! Other
1296 Canfestival users will use it and provide feedback, tests and
1297 enhancements.
1298
1299 \subsubsection{Is CanFestival3 conform to DS301 v.4.02 ?}
1300 Thanks to Philippe Foureys (IUT of Valence), a slave node have been
1301 tested with the National Instrument CanOpen Conformance Test. It passed
1302 the test with success.
1303
1304 Some very small unconformity have been found in very unusual situations,
1305 for example in the SDO code response to wrong messages.
1306
1307 \subsection{LINUX}
1308 \subsubsection{How to use a Peaksystem CAN board ?}
1309 Just install peak driver and then compile and install Canfestival. Peak
1310 driver is detected at compile time.
1311
1312 \subsubsection{How to use an unsupported CAN board ?}
1313 You have to install the specific driver on your system, with necessary
1314 libs and headers.
1315
1316 Use can\_peak.c/h or can\_virtual.c/h as an example, and adapt it to
1317 your driver API.
1318
1319 Execute configure script and choose {}-{}-can=mydriver
1320
1321 \subsection{Win32}
1322 Compatibility:
1323
1324 \liststyleLxi
1325 \begin{enumerate}
1326 \item Code was compiled MS VisualStudio 2003.NET and VisualStudio
1327 2005.NET for WindowsXP \space with ANSI and UNICODE configurations and for
1328 WindowsCE 5.0.
1329 \item Some preliminary testing was done, but not enough to be used in
1330 mission critical projects.
1331 \end{enumerate}
1332 Additional Features:
1333
1334 \liststyleLxii
1335 \begin{enumerate}
1336 \item Non{}-integral integers support implementation UNS24, UNS40, UNS48
1337 etc.
1338 \item When enable debug output with DEBUG\_WAR\_CONSOLE\_ON or
1339 DEBUG\_ERR\_CONSOLE\_ON, you can navigate in CanFestival source code by
1340 double clicking at diagnostic lines in VisualStudio.NET 200X Debug
1341 Output Window.
1342 \end{enumerate}
1343 Custom size integral types such as INTEGER24, UNS40, INTEGER56 etc. have
1344 been defined as 64 bits integers. You will need to replace sizeof(TYPE)
1345 operators to sizeof\_TYPE definitions in generated code, i.e. replace
1346 sizeof(UNS40) with sizeof\_UNS40.
1347
1348
1349 \bigskip
1350
1351 \subsection{HCS12}
1352 \subsubsection{Which board are you using ?}
1353 A T{}-board from elektronikladen with a MC9S12DP256 or MC9S12DG256.
1354
1355 \subsubsection{Does the code compile with an other compiler than GNU gcc
1356 ?}
1357 It is known to work with Metrowerks CodeWarrior. Here are some tips from
1358 Philippe Foureys. :
1359
1360 \paragraph{Interrupt functions}
1361 \subparagraph{Code for GCC:}
1362 {\ttfamily
1363  // prototype\newline
1364  void \_\_attribute\_\_((interrupt))timer3Hdl(void):\newline
1365  // function\newline
1366  void \_\_attribute\_\_((interrupt))timer3Hdl(void)\{...\}}
1367
1368 \subparagraph{Code for CodeWarrior}
1369 {\ttfamily
1370  // protoype\newline
1371  void interrupt timer3Hdl(void);\newline
1372  // function\newline
1373  pragma CODE\_SEG\_\_NEAR\_SEG\_NON\_BANKED\newline
1374  void interrupt timer3Hdl(void)\newline
1375  \{...\}\newline
1376  pragma CODE\_SEG\_DEFAULT}
1377
1378 \paragraph{Interrupt lock, unlock}
1379 \subparagraph{Code for GCC}
1380 {\ttfamily
1381  void unlock (void)\newline
1382  \{\newline
1383   \space \_\_asm\_\_
1384 \_\_volatile\_\_({\textquotedbl}cli{\textquotedbl});\newline
1385  \}\newline
1386  void lock (void)\newline
1387  \{\newline
1388   \space unsigned short mask;\newline
1389   \space \_\_asm\_\_
1390 \_\_volatile\_\_({\textquotedbl}tpa{\textbackslash}n{\textbackslash}tsei{\textquotedbl}:{\textquotedbl}=d{\textquotedbl}(mask));\newline
1391  \}}
1392
1393 \subparagraph{Code for CodeWarrior}
1394 {\ttfamily
1395 void unlock (void)\newline
1396  \{\newline
1397   \space \_\_asm({\textquotedbl}cli{\textquotedbl});\newline
1398  \}\newline
1399  void lock (void)\newline
1400  \{\newline
1401   \space unsigned short mask;\newline
1402   \space \_\_asm\newline
1403   \{\newline
1404   \space tpa:tsei:{\textquotedbl}=d{\textquotedbl}(mask);\newline
1405   \}\newline
1406  \}}
1407
1408 \paragraph{Initialize function}
1409 \subparagraph{Code for GCC}
1410 {\ttfamily
1411 void initCanHCS12 (void)\newline
1412  \{ \space \newline
1413   \space //Init the HCS12 microcontroler for CanOpen \newline
1414   \space initHCS12();\newline
1415   \space \space // Init the HCS12 \space CAN driver\newline
1416   \space const canBusInit bi0 = \{\newline
1417   \space \space \space 0, \space \space \space /* no low power \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space */
1418 \newline
1419   \space \space \space 0, \space \space \space /* no time stamp
1420 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space */\newline
1421   \space \space \space 1, \space \space \space /* enable MSCAN
1422 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space */\newline
1423   \space \space \space 0, \space \space \space /* clock source : oscillator (In fact, it is not used)
1424 \space \space */\newline
1425   \space \space \space 0, \space \space \space /* no loop back
1426 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space */\newline
1427   \space \space \space 0, \space \space \space /* no listen only
1428 \space \space \space \space \space \space \space \space \space \space \space \space \space \space */\newline
1429   \space \space \space 0, \space \space \space /* no low pass filter for wk up */\newline
1430   \space CAN\_Baudrates[CAN\_BAUDRATE\_250K],\newline
1431   \space \space \space \{\newline
1432   \space \space \space \space \space 0x00, \space \space \space /* Filter on 16 bits.\newline
1433   \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space See Motorola Block Guide V02.14 fig
1434 4{}-3 */\newline
1435   \space \space \space \space \space 0x00, 0xFF, /* filter 0 hight accept all msg
1436 \space \space \space \space \space */\newline
1437   \space \space \space \space \space 0x00, 0xFF, /* filter 0 low accept all msg
1438 \space \space \space \space \space \space \space */\newline
1439   \space \space \space \space \space 0x00, 0xFF, /* filter 1 hight filter all of \space msg
1440 \space */\newline
1441   \space \space \space \space \space 0x00, 0xFF, /* filter 1 low filter all of \space msg
1442 \space \space \space */\newline
1443   \space \space \space \space \space 0x00, 0xFF, /* filter 2 hight filter most of \space msg
1444 */\newline
1445   \space \space \space \space \space 0x00, 0xFF, /* filter 2 low filter most of \space msg
1446 \space \space */\newline
1447   \space \space \space \space \space 0x00, 0xFF, /* filter 3 hight filter most of \space msg
1448 */\newline
1449   \space \space \space \space \space 0x00, 0xFF, /* filter 3 low filter most of \space msg
1450 \space \space */\newline
1451   \space \space \space \}\newline
1452   \space \};}
1453
1454 \subparagraph{Code for CodeWarrior}
1455 {\ttfamily
1456 void initCanHCS12 (void)\newline
1457  \{ \space \newline
1458   \space //Init the HCS12 microcontroler for CanOpen \newline
1459   \space initHCS12();\newline
1460   \space \space // Init the HCS12 \space CAN driver\newline
1461   \space const canBusInit bi0 = \{\newline
1462   \space \space \space 0, \space \space \space /* no low power \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space */
1463 \newline
1464   \space \space \space 0, \space \space \space /* no time stamp
1465 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space */\newline
1466   \space \space \space 1, \space \space \space /* enable MSCAN
1467 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space */\newline
1468   \space \space \space 0, \space \space \space /* clock source : oscillator (In fact, it is not used)
1469 \space \space */\newline
1470   \space \space \space 0, \space \space \space /* no loop back
1471 \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space */\newline
1472   \space \space \space 0, \space \space \space /* no listen only
1473 \space \space \space \space \space \space \space \space \space \space \space \space \space \space */\newline
1474   \space \space \space 0, \space \space \space /* no low pass filter for wk up */\newline
1475   \space \space \space \{\newline
1476   \space \space \space \space 1, /* clksrc */\newline
1477   \space \space \space \space 3, /* brp \space \space \space */\newline
1478   \space \space \space \space 0, /* sjw \space \space \space */\newline
1479   \space \space \space \space 0, /* samp \space \space */\newline
1480   \space \space \space \space 1, /* tseg2 \space */\newline
1481   \space \space \space \space 12,/* tseg1 \space */\newline
1482   \space \space \space \},\newline
1483   \space \space \space \{\newline
1484   \space \space \space \space \space 0x00, \space \space \space /* Filter on 16 bits.\newline
1485   \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space \space See Motorola Block Guide V02.14 fig
1486 4{}-3 */\newline
1487   \space \space \space \space \space 0x00, 0xFF, /* filter 0 hight accept all msg
1488 \space \space \space \space \space */\newline
1489   \space \space \space \space \space 0x00, 0xFF, /* filter 0 low accept all msg
1490 \space \space \space \space \space \space \space */\newline
1491   \space \space \space \space \space 0x00, 0xFF, /* filter 1 hight filter all of \space msg
1492 \space */\newline
1493   \space \space \space \space \space 0x00, 0xFF, /* filter 1 low filter all of \space msg
1494 \space \space \space */\newline
1495   \space \space \space \space \space 0x00, 0xFF, /* filter 2 hight filter most of \space msg
1496 */\newline
1497   \space \space \space \space \space 0x00, 0xFF, /* filter 2 low filter most of \space msg
1498 \space \space */\newline
1499   \space \space \space \space \space 0x00, 0xFF, /* filter 3 hight filter most of \space msg
1500 */\newline
1501   \space \space \space \space \space 0x00, 0xFF, /* filter 3 low filter most of \space msg
1502 \space \space */\newline
1503   \space \space \space \}\newline
1504   \space \};}
1505
1506 \subsubsection{Does the code works in banked memory ?}
1507 No. Today it seems that the port of gcc is bogged for using the banked
1508 memory. So, unfortunately, we are limited to 48 Kbytes of memory code.
1509
1510 \subsubsection{What GCC version are you using ?}
1511 We are using the stable RPM release 2.2 :
1512
1513 \liststyleLxiii
1514 \begin{enumerate}
1515 \item GNU Gcc 3.0.4. Build 20030501
1516 \item Newlib 1.10.0 Build 20030421
1517 \item GNU Binutils 2.12.1 Build 20030427
1518 \end{enumerate}
1519 \section{Documentation resources\newline}
1520 \paragraph{CIA : Can in Automation\newline}
1521 Many documentation on CANopen.\newline
1522 \href{http://www.can-cia.de/}{http://www.can{}-cia.de}
1523
1524 \paragraph{Resources and training in CANopen\newline}
1525 \href{http://www.esacademy.com/}{http://www.esacademy.com}
1526
1527 \paragraph{Elektronikladen HCS12 T{}-board\newline}
1528 \href{http://www.elektronikladen.de/en_hcs12tb.html}{http://www.elektronikladen.de/en\_hcs12tb.html}
1529
1530 \paragraph{Gnu gcc compiler for HC12\newline}
1531 \href{http://m68hc11.serveftp.org/m68hc11_port.php}{http://m68hc11.serveftp.org/m68hc11\_port.php}
1532
1533 \paragraph{Motorola documentation on HC12\newline}
1534 \href{http://www.freescale.com/webapp/sps/site/prod_summary.jsp?code=MC9S12DP256}{http://www.freescale.com/webapp/sps/site/prod\_summary.jsp?code=MC9S12DP256}
1535
1536 \paragraph{Lauterbach debugger for HC12\newline}
1537 \href{http://www.lauterbach.com/}{http://www.lauterbach.com}
1538
1539 \paragraph{Python language\newline}
1540 \href{http://www.python.org/}{http://www.python.org}
1541
1542 \clearpage\section{About the project}
1543 \subsection{Contributors }
1544  \begin{center}
1545    \includegraphics[width=10cm]{Pictures/1000020100000258000000832C6FFAB4.png}
1546 \end{center}
1547
1548 Unit\'e mixte de recherche INRETS{}-LCPC
1549
1550 sur les Interractions V\'ehicule{}-Infrastructure{}-Conducteur
1551
1552 14, route de la mini\`ere
1553
1554 78000 Versailles
1555
1556 FRANCE
1557
1558 Tel : +33 1 40 43 29 01
1559
1560 \href{http://www.inrets.fr/ur/livic}{http://www.inrets.fr/ur/livic}
1561
1562 \textbf{Contributors :} Francis DUPIN
1563
1564    Camille BOSSARD
1565
1566    Laurent ROMIEUX
1567
1568
1569 \bigskip
1570
1571  \begin{center}
1572    \includegraphics[width=10cm]{Pictures/100002010000013A0000004A96B0C1FF.png}
1573 \end{center}
1574
1575 LOLITECH
1576
1577 204, rue du Haut du Pin
1578
1579 88470 Saint{}-Michel sur Meurthe
1580
1581 FRANCE
1582
1583 Tel : +33 3 29 52 95 67
1584
1585 \href{http://www.lolitech.fr/}{http://www.lolitech.fr}
1586
1587 {\bfseries
1588 Contributors : \textmd{Edouard TISSERANT (Original author)}}
1589
1590 {\mdseries
1591    Laurent BESSARD}
1592
1593
1594 \bigskip
1595
1596 Many thanks to the other contributors for their great work:
1597
1598 \textmd{   }Raphael ZULLIGER
1599
1600 \textmd{   }David DUMINY (st\'e A6R)
1601
1602 \textmd{   }Zakaria BELAMRI
1603
1604 \subsection{Getting support}
1605 Send your feedback and bug reports to
1606 \href{mailto:canfestival-devel@lists.sourceforge.net}{canfestival{}-devel@lists.sourceforge.net}.
1607
1608 For commercial support, \space training and specific integration and
1609 developments, please ask LOLITECH (see contributors).
1610
1611 \subsection{Contributing}
1612 You are free to contribute your specific interfaces back to the project.
1613 This way, you can hope to get support from CanFestival users community.
1614
1615 Please send your patch to
1616 \href{mailto:canfestival-devel@lists.sourceforge.net}{canfestival{}-devel@lists.sourceforge.net}.
1617
1618 Feel free to create some new predefined DS{}-4xx profiles (*.prf) in
1619 objdictgen/config, as much as possible respectful to the official
1620 specifications.
1621
1622 \subsection{License}
1623 All the project is licensed with LGPL. This mean you can link
1624 CanFestival with any code without being obliged to publish it.
1625
1626 {\ttfamily
1627 \#This file is part of CanFestival, a library implementing CanOpen
1628 Stack. \newline
1629 \# \newline
1630 \#Copyright (C): Edouard TISSERANT, Francis DUPIN and Laurent BESSARD
1631 \newline
1632 \# \newline
1633 \#See COPYING file for copyrights details. \newline
1634 \# \newline
1635 \#This library is free software; you can redistribute it and/or \newline
1636 \#modify it under the terms of the GNU Lesser General Public \newline
1637 \#License as published by the Free Software Foundation; either \newline
1638 \#version 2.1 of the License, or (at your option) any later version.
1639 \newline
1640 \# \newline
1641 \#This library is distributed in the hope that it will be useful,
1642 \newline
1643 \#but WITHOUT ANY WARRANTY; without even the implied warranty of
1644 \newline
1645 \#MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. \space See the GNU
1646 \newline
1647 \#Lesser General Public License for more details. \newline
1648 \# \newline
1649 \#You should have received a copy of the GNU Lesser General Public
1650 \newline
1651 \#License along with this library; if not, write to the Free Software
1652 \newline
1653 \#Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA
1654 \space 02111{}-1307 \space USA }
1655
1656
1657 \bigskip
1658
1659 \end{document}