1

%------------------------------------------------------------------------------

     2

%

     3

%  IgH EtherCAT Master Documentation

     4

%

     5

%  $Id$

     6

%

     7

%  vi: spell spelllang=en

     8

% 

     9

%------------------------------------------------------------------------------

    10

    11

%

    12

%   Conventions

    13

% The IgH EtherCAT Master

    14

%   Feature Summary

    15

%   License

    16

% Architecture

    17

%   Phases

    18

%   Behavior (Scanning) TODO

    19

% Application Interface

    20

%   Interface version

    21

%   Master Requesting and Releasing

    22

%   Master Locking

    23

%   Slave configuration

    24

%   Configuring Pdo assignment and mapping

    25

%   Domains (memory)

    26

%   Pdo entry registration

    27

%   Sdo configuration

    28

%   Sdo access

    29

%   Cyclic operation

    30

% Ethernet Devices

    31

%   Device Interface

    32

%   Device Modules

    33

%   Network Driver Basics

    34

%   EtherCAT Network Drivers

    35

%   Device Selection

    36

%   The Device Interface

    37

%   Patching Network Drivers

    38

% The Master's State Machines

    39

%   Master

    40

%   Slave scanning

    41

%     SII

    42

%     Pdo assign/mapping

    43

%   Slave configuration

    44

%     State change

    45

%     Pdo assign/mapping

    46

%   CoE upload/download/information

    47

% Mailbox Protocol Implementations

    48

%     Ethernet-over-EtherCAT (EoE)

    49

%     CANopen-over-EtherCAT (CoE)

    50

% User Space

    51

%     The ethercat command

    52

%     System Integration

    53

%         The EtherCAT Init Script

    54

%         The EtherCAT Sysconfig File

    55

%     Monitoring and Debugging

    56

% Installation

    57

% Example applications

    58

% Bibliography

    59

% Glossary

    60

%

    61

    62

\documentclass[a4paper,12pt,BCOR6mm,bibtotoc,idxtotoc]{scrbook}

    63

    64

\usepackage[latin1]{inputenc}

    65

\usepackage[automark,headsepline]{scrpage2}

    66

\usepackage{graphicx}

    67

\usepackage{makeidx}

    68

\usepackage[refpage]{nomencl}

    69

\usepackage{listings}

    70

\usepackage{svn}

    71

\usepackage{textcomp}

    72

\usepackage{url}

    73

\usepackage{SIunits}

    74

\usepackage[pdfpagelabels,plainpages=false]{hyperref}

    75

    76

\setlength{\parskip}{0.8ex plus 0.8ex minus 0.5ex}

    77

\setlength{\parindent}{0mm}

    78

    79

\setcounter{secnumdepth}{\subsubsectionlevel}

    80

    81

\DeclareFontShape{OT1}{cmtt}{bx}{n}

    82

{

    83

  <5><6><7><8><9><10><10.95><12><14.4><17.28><20.74><24.88>cmttb10

    84

}{}

    85

    86

\lstset{basicstyle=\ttfamily\small,numberstyle=\tiny,aboveskip=4mm,

    87

  belowskip=2mm,escapechar=`}

    88

\renewcommand\lstlistlistingname{List of Listings}

    89

    90

% Workaround for lstlistoflistings bug

    91

\makeatletter% --> De-TeX-FAQ

    92

\renewcommand*{\lstlistoflistings}{%

    93

  \begingroup

    94

    \if@twocolumn

    95

      \@restonecoltrue\onecolumn

    96

    \else

    97

      \@restonecolfalse

    98

    \fi

    99

    \lol@heading

   100

    \setlength{\parskip}{\z@}%

   101

    \setlength{\parindent}{\z@}%

   102

    \setlength{\parfillskip}{\z@ \@plus 1fil}%

   103

    \@starttoc{lol}%

   104

    \if@restonecol\twocolumn\fi

   105

  \endgroup

   106

}

   107

\makeatother% --> \makeatletter

   108

   109

\renewcommand\nomname{Glossary}

   110

   111

\newcommand{\IgH}{\raisebox{-0.7667ex}

   112

  {\includegraphics[height=2.2ex]{images/ighsign}}}

   113

   114

\SVN $Date$

   115

\SVN $Revision$

   116

   117

\newcommand{\masterversion}{1.4.0}

   118

\newcommand{\linenum}[1]{\normalfont\textcircled{\tiny #1}}

   119

   120

\makeindex

   121

\makenomenclature

   122

   123

%------------------------------------------------------------------------------

   124

   125

\begin{document}

   126

   127

\pagenumbering{roman}

   128

\pagestyle{empty}

   129

   130

\begin{titlepage}

   131

  \begin{center}

   132

    \rule{\textwidth}{1.5mm}

   133

   134

    {\Huge\bf IgH \includegraphics[height=2.4ex]{images/ethercat}

   135

      Master \masterversion\\[1ex]

   136

      Documentation}

   137

   138

    \vspace{1ex}

   139

    \rule{\textwidth}{1.5mm}

   140

   141

    \vspace{\fill}

   142

    {\Large Florian Pose, \url{fp@igh-essen.com}\\[1ex]

   143

      Ingenieurgemeinschaft \IgH}

   144

   145

    \vspace{\fill}

   146

    {\Large Essen, \SVNDate\\[1ex]

   147

      Revision \SVNRevision}

   148

  \end{center}

   149

\end{titlepage}

   150

   151

%------------------------------------------------------------------------------

   152

   153

\tableofcontents

   154

\listoftables

   155

\listoffigures

   156

\lstlistoflistings

   157

   158

%------------------------------------------------------------------------------

   159

   160

\newpage

   161

\pagestyle{scrheadings}

   162

   163

\section*{Conventions}

   164

\addcontentsline{toc}{section}{Conventions}

   165

\markleft{Conventions}

   166

   167

The following typographic conventions are used:

   168

   169

\begin{itemize}

   170

   171

\item \textit{Italic face} is used for newly introduced terms and file names.

   172

   173

\item \texttt{Typewriter face} is used for code examples and command line

   174

output.

   175

   176

\item \texttt{\textbf{Bold typewriter face}} is used for user input in command

   177

lines.

   178

   179

\end{itemize}

   180

   181

Data values and addresses are usually specified as hexadecimal values. These

   182

are marked in the \textit{C} programming language style with the prefix

   183

\lstinline+0x+ (example: \lstinline+0x88A4+). Unless otherwise noted, address

   184

values are specified as byte addresses.

   185

   186

Function names are always printed with parentheses, but without

   187

parameters. So, if a function \lstinline+ecrt_request_master()+ has

   188

empty parentheses, this shall not imply that it has no parameters.

   189

   190

If shell commands have to be entered, this is marked by a dollar prompt:

   191

   192

\begin{lstlisting}

   193

$

   194

\end{lstlisting}

   195

   196

Further, if a shell command has to be entered as the superuser, the

   197

prompt is a mesh:

   198

   199

\begin{lstlisting}

   200

#

   201

\end{lstlisting}

   202

   203

%------------------------------------------------------------------------------

   204

   205

\chapter{The IgH EtherCAT Master}

   206

\label{chapter:master}

   207

\pagenumbering{arabic}

   208

   209

This chapter covers some general information about the EtherCAT master.

   210

   211

%------------------------------------------------------------------------------

   212

   213

\section{Feature Summary}

   214

\label{sec:summary}

   215

\index{Master!Features}

   216

   217

The list below gives a short summary of the master features.

   218

   219

\begin{itemize}

   220

   221

\item Designed as a kernel module for Linux 2.6.

   222

   223

\item Implemented according to IEC 61158-12 \cite{dlspec} \cite{alspec}.

   224

   225

\item Comes with EtherCAT-capable drivers for several common Ethernet devices.

   226

   227

  \begin{itemize}

   228

   229

  \item The Ethernet hardware is operated without interrupts.

   230

   231

  \item Drivers for additional Ethernet hardware can easily be implemented

   232

  using the common device interface (see section~\ref{sec:ecdev}) provided by

   233

  the master module.

   234

   235

  \end{itemize}

   236

   237

\item The master module supports multiple EtherCAT masters running in

   238

parallel.

   239

   240

\item The master code supports any Linux realtime extension through its

   241

independent architecture.

   242

   243

  \begin{itemize}

   244

   245

  \item RTAI\nomenclature{RTAI}{Realtime Application Interface},

   246

  ADEOS\nomenclature{ADEOS}{Adaptive Domain Environment for Operating

   247

  Systems}, etc.

   248

   249

  \item It runs well even without realtime extensions.

   250

   251

  \end{itemize}

   252

   253

\item Common ``realtime interface'' for applications, that want to use

   254

EtherCAT functionality (see section~\ref{sec:ecrt}).

   255

   256

\item \textit{Domains} are introduced, to allow grouping of process

   257

  data transfers with different slave groups and task periods.

   258

   259

  \begin{itemize}

   260

   261

  \item Handling of multiple domains with different task periods.

   262

   263

  \item Automatic calculation of process data mapping, FMMU and sync manager

   264

  configuration within each domain.

   265

   266

  \end{itemize}

   267

   268

\item Communication through several finite state machines.

   269

   270

  \begin{itemize}

   271

   272

  \item Automatic bus scanning after topology changes.

   273

   274

  \item Bus monitoring during operation.

   275

   276

  \item Automatic reconfiguration of slaves (for example after power failure)

   277

  during operation.

   278

   279

  \end{itemize}

   280

   281

\item CANopen-over-EtherCAT (CoE)

   282

   283

  \begin{itemize}

   284

   285

  \item Sdo upload, download and information service.

   286

   287

  \item Slave configuration via Sdos.

   288

   289

  \item Sdo access from user-space and from the application.

   290

   291

  \end{itemize}

   292

   293

\item Ethernet-over-EtherCAT (EoE)

   294

   295

  \begin{itemize}

   296

   297

  \item Transparent use of EoE slaves via virtual network interfaces.

   298

   299

  \item Natively supports either a switched or a routed EoE network

   300

  architecture.

   301

   302

  \end{itemize}

   303

   304

\item User space command-line-tool ``ethercat``.

   305

   306

  \begin{itemize}

   307

   308

  \item Showing the current bus with slaves, Pdos and Sdos.

   309

  \item Showing the bus configuration.

   310

  \item Showing domains and process data.

   311

  \item Setting the master's debug level.

   312

  \item Writing alias addresses.

   313

  \item Sdo uploading/downloading.

   314

  \item Reading/writing a slave's SII.

   315

  \item Setting slave states.

   316

  \item Generate slave description XML.

   317

   318

  \end{itemize}

   319

   320

\item Seamless system integration though LSB\nomenclature{LSB}{Linux

   321

    Standard Base} compliance.

   322

   323

  \begin{itemize}

   324

   325

  \item Master and network device configuration via sysconfig files.

   326

   327

  \item Init script for master control.

   328

   329

  \end{itemize}

   330

   331

\item Virtual read-only network interface for monitoring and debugging

   332

  purposes.

   333

   334

\end{itemize}

   335

   336

%------------------------------------------------------------------------------

   337

   338

\section{License}

   339

\label{sec:license}

   340

   341

The master code is released under the terms and conditions of the GNU

   342

General Public License\index{GPL} \cite{gpl} (version 2). Other

   343

developers, that want to use EtherCAT with Linux systems, are invited

   344

to use the master code or even participate on development.

   345

   346

%------------------------------------------------------------------------------

   347

   348

\chapter{Architecture}

   349

\label{sec:arch}

   350

\index{Master!Architecture}

   351

   352

The EtherCAT master is integrated into the Linux 2.6 kernel. This was

   353

an early design decision, which has been made for several reasons:

   354

   355

\begin{itemize}

   356

   357

\item Kernel code has significantly better realtime characteristics, i.~e.

   358

less latency than user space code. It was foreseeable, that a fieldbus master

   359

has a lot of cyclic work to do. Cyclic work is usually triggered by timer

   360

interrupts inside the kernel. The execution delay of a function that processes

   361

timer interrupts is less, when it resides in kernel space, because there is no

   362

need of time-consuming context switches to a user space process.

   363

   364

\item It was also foreseeable, that the master code has to directly

   365

communicate with the Ethernet hardware. This has to be done in the kernel

   366

anyway (through network device drivers), which is one more reason for the

   367

master code being in kernel space.

   368

   369

\end{itemize}

   370

   371

Figure~\ref{fig:arch} gives a general overview of the master architecture.

   372

   373

\begin{figure}[htbp]

   374

  \centering

   375

  \includegraphics[width=.9\textwidth]{images/architecture}

   376

  \caption{Master architecture}

   377

  \label{fig:arch}

   378

\end{figure}

   379

   380

\paragraph{Master Module}

   381

\index{Master module}

   382

   383

Kernel module containing one or more EtherCAT master instances (see

   384

section~\ref{sec:mastermod}), the ``Device Interface'' (see

   385

section~\ref{sec:ecdev}) and the ``Realtime Interface'' (see

   386

section~\ref{sec:ecrt}).

   387

   388

\paragraph{Device Modules}

   389

\index{Device modules}

   390

   391

EtherCAT-capable Ethernet device driver modules\index{Device modules}, that

   392

offer their devices to the EtherCAT master via the device interface (see

   393

section~\ref{sec:ecdev}). These modified network drivers can handle network

   394

devices used for EtherCAT operation and ``normal'' Ethernet devices in

   395

parallel. A master can accept a certain device and then is able to send and

   396

receive EtherCAT frames. Ethernet devices declined by the master module are

   397

connected to the kernel's network stack as usual.

   398

   399

\paragraph{Application Modules}

   400

\index{Application module}

   401

   402

Kernel modules, that use the EtherCAT master (usually for cyclic exchange of

   403

process data with EtherCAT slaves). These modules are not part of the EtherCAT

   404

master code\footnote{Although there are some examples provided in the

   405

\textit{examples} directory, see chapter~\ref{chapter:examples}}, but have to

   406

be generated or written by the user. An application module can ``request'' a

   407

master through the realtime interface (see section~\ref{sec:ecrt}). If this

   408

succeeds, the module has the control over the master: It can provide a bus

   409

configuration and exchange process data.

   410

   411

%------------------------------------------------------------------------------

   412

   413

\section{Phases}

   414

\index{Master phases}

   415

   416

The EtherCAT master runs through several phases (see fig.~\ref{fig:phases}):

   417

   418

\begin{figure}[htbp]

   419

  \centering

   420

  \includegraphics[width=.9\textwidth]{images/phases}

   421

  \caption{Master phases and transitions}

   422

  \label{fig:phases}

   423

\end{figure}

   424

\begin{description}

   425

   426

\item[Orphaned phase]\index{Orphaned phase} This mode takes effect, when the

   427

master still waits for its Ethernet device to connect. No bus communication is

   428

possible until then.

   429

   430

\item[Idle phase]\index{Idle phase} takes effect when the master has accepted

   431

an Ethernet device, but is not requested by any application yet. The master

   432

runs its state machine (see section~\ref{sec:fsm-master}), that automatically

   433

scans the bus for slaves and executes pending operations from the user space

   434

interface (for example Sdo access). The command-line tool can be used to access

   435

the bus, but there is no process data exchange because of the missing bus

   436

configuration.

   437

   438

\item[Operation phase]\index{Operation phase} The master is requested by an

   439

application that can provide a bus configuration and exchange process data.

   440

   441

\end{description}

   442

   443

%------------------------------------------------------------------------------

   444

   445

\section{General behavior} % FIXME

   446

\index{Master behavior}

   447

   448

\ldots

   449

   450

%------------------------------------------------------------------------------

   451

   452

\section{Master Module}

   453

\label{sec:mastermodule}

   454

\index{Master module}

   455

   456

The EtherCAT master kernel module \textit{ec\_master} can contain multiple

   457

master instances. Each master waits for a certain Ethernet device identified

   458

by its MAC address\index{MAC address}. These addresses have to be specified on

   459

module loading via the \textit{main\_devices} module parameter. The number of

   460

master instances to initialize is taken from the number of MAC addresses

   461

given.

   462

   463

The below command loads the master module with a single master instance that

   464

waits for the Ethernet device with the MAC address

   465

\lstinline+00:0E:0C:DA:A2:20+. The master will be accessible via index $0$.

   466

   467

\begin{lstlisting}

   468

# `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20}`

   469

\end{lstlisting}

   470

   471

MAC addresses for multiple masters have to be separated by commas:

   472

   473

\begin{lstlisting}

   474

# `\textbf{modprobe ec\_master main\_devices=00:0E:0C:DA:A2:20,00:e0:81:71:d5:1c}`

   475

\end{lstlisting}

   476

   477

The two masters can be addressed by their indices 0 and 1 respectively (see

   478

figure~\ref{fig:masters}). The master index is needed for the

   479

\lstinline+ecrt_master_request()+ function of the realtime interface (see

   480

section~\ref{sec:ecrt}) and the \lstinline+--master+ option of the

   481

\textit{ethercat} command-line tool (see section~\ref{sec:ethercat}), which

   482

defaults to $0$.

   483

   484

\begin{figure}[htbp]

   485

  \centering

   486

  \includegraphics[width=.5\textwidth]{images/masters}

   487

  \caption{Multiple masters in one module}

   488

  \label{fig:masters}

   489

\end{figure}

   490

   491

\paragraph{Init script}

   492

\index{Init script}

   493

   494

Most probably you won't want to load the master module and the Ethernet driver

   495

modules manually, but start the master as a service. See

   496

section~\ref{sec:system} on how to do this.

   497

   498

\paragraph{Syslog}

   499

   500

The master module outputs information about it's state and events to the