documentation/ethercat_doc.tex
changeset 1094 eb0258e53236
parent 1087 f1417824cee5
child 1095 a3ca9a8a223e
equal deleted inserted replaced
1093:f34cc6fa4a73 1094:eb0258e53236
   604 
   604 
   605 \chapter{Application Interface}
   605 \chapter{Application Interface}
   606 \label{sec:ecrt}
   606 \label{sec:ecrt}
   607 \index{Application interface}
   607 \index{Application interface}
   608 
   608 
   609 %------------------------------------------------------------------------------
   609 The application interface provides functions and data structures for
   610 
   610 applications to access and use an EtherCAT master. The complete documentation
   611 \section{The Realtime Interface} % FIXME move information to ecrt.h, reference
   611 of the interface is included as Doxygen~\cite{doxygen} comments in the header
   612 \label{sec:ecrt}
   612 file \textit{include/ecrt.h}. You can either directly view the file comments
   613 \index{Realtime interface}
   613 or generate an HTML documentation as described in section~\ref{sec:gendoc}.
   614 
   614 
   615 The realtime interface provides functions and data structures for applications
   615 The following sections cover a general description of the application
   616 to access and use an EtherCAT master.
   616 interface.
   617 
   617 
   618 % \paragraph{Master Phases}
   618 Every application should use the master in two steps:
   619 % 
   619 
   620 % Every application should use the master in three phases:
   620 \begin{description}
   621 % 
   621 
   622 % \begin{enumerate}
   622 \item[Configuration] The master is requested and the configuration is applied.
   623 % \item \textit{Startup} - The master is requested and the bus is
   623 Domains are created Slaves are configured and Pdo entries are registered (see
   624 %   validated. Domains are created and Pdos are registered. Slave
   624 section~\ref{sec:masterconfig}).
   625 %   configurations are applied.
   625 
   626 % \item \textit{Operation} - Cyclic code is run, process data is
   626 \item[Operation] Cyclic code is run, process data is exchanged (see
   627 %   exchanged and the master state machine is executed.
   627 section~\ref{sec:cyclic}).
   628 % \item \textit{Shutdown} - Cyclic code is stopped and the master
   628 
   629 %   is released.
   629 \end{description}
   630 % \end{enumerate}
   630 
   631 
   631 %------------------------------------------------------------------------------
   632 \subsubsection{Master Requesting and Releasing}
   632 
   633 
   633 \section{Master Configuration}
   634 Before an application can access an EtherCAT master provided by the
   634 \label{sec:masterconfig}
   635 master module, it has to reserve one for exclusive use. After use, it
   635 
   636 has to release the requested master and make it available for other
   636 \ldots
   637 modules. This is done with the following functions:
   637 
   638 
   638 \begin{figure}[htbp]
   639 \begin{lstlisting}[gobble=2,language=C]
   639   \centering
   640   ec_master_t *ecrt_request_master(unsigned int master_index);
   640   \includegraphics[width=.8\textwidth]{images/app-config}
   641   void ecrt_release_master(ec_master_t *master);
   641   \caption{Master configuration structures}
   642 \end{lstlisting}
   642   \label{fig:app-config}
   643 
   643 \end{figure}
   644 The \textit{ecrt\_request\_master()} function has to be the first function a
   644 
   645 module has to call, when using EtherCAT. The function takes the index of the
   645 %------------------------------------------------------------------------------
   646 master as its argument. The first master has index 0, the $n$th master has
   646 
   647 index $n - 1$. The number of existent masters has to be specified when loading
   647 \section{Cyclic Operation}
   648 the master module (see section~\ref{sec:mastermod}). The function tries to
   648 \label{sec:cyclic}
   649 reserve the specified master and scans for slaves. It returns a pointer to the
   649 
   650 reserved master object upon success, or \textit{NULL} if an error occurred.
   650 \ldots
   651 
   651 % FIXME PDOS endianess
   652 The \textit{ecrt\_release\_master()} function releases a reserved
   652 
   653 master after use. It takes the pointer to the master object returned
   653 
   654 by \textit{ecrt\_request\_master()} as its argument and can never
   654 %------------------------------------------------------------------------------
   655 fail.
   655 
   656 
   656 \section{Concurrent Master Access} % FIXME
   657 \subsubsection{Master Methods}
       
   658 \label{sec:ecrt-master}
       
   659 
       
   660 \paragraph{Domain Creation}
       
   661 
       
   662 For process data exchange, at least one process data domain is needed
       
   663 (see section~\ref{sec:processdata}).
       
   664 
       
   665 \begin{lstlisting}[gobble=2,language=C]
       
   666   ec_domain_t *ecrt_master_create_domain(ec_master_t *master);
       
   667 \end{lstlisting}
       
   668 
       
   669 The \textit{ecrt\_master\_create\_domain()} method creates a new
       
   670 process data domain and returns a pointer to the new domain object.
       
   671 This object can be used for registering process data objects and
       
   672 exchange process data in cyclic operation. On failure, the function
       
   673 returns \textit{NULL}.
       
   674 
       
   675 \paragraph{Slave Handlers}
       
   676 
       
   677 To access a certain slave, there is a method to get a slave handler:
       
   678 
       
   679 \begin{lstlisting}[gobble=2,language=C]
       
   680   ec_slave_t *ecrt_master_get_slave(const ec_master_t *,
       
   681                                     const char *);
       
   682 \end{lstlisting}
       
   683 
       
   684 The \textit{ecrt\_master\_get\_slave()} method returns a pointer to a
       
   685 certain slave object, specified by its ASCII address (see
       
   686 section~\ref{sec:addr}). If the address is invalid, \textit{NULL} is
       
   687 returned.
       
   688 
       
   689 \paragraph{Master Activation}
       
   690 
       
   691 When all domains are created, and all process data objects are
       
   692 registered, the master can be activated:
       
   693 
       
   694 \begin{lstlisting}[gobble=2,language=C]
       
   695   int ecrt_master_activate(ec_master_t *master);
       
   696   void ecrt_master_deactivate(ec_master_t *master);
       
   697 \end{lstlisting}
       
   698 
       
   699 By calling the \textit{ecrt\_master\_activate()} method, all slaves
       
   700 are configured according to the prior method calls and are brought
       
   701 into OP state. In this case, the method has a return value of 0.
       
   702 Otherwise (wrong configuration or bus failure) the method returns
       
   703 non-zero.
       
   704 
       
   705 The \textit{ecrt\_master\_deactivate()} method is the counterpart to
       
   706 the activate call: It brings all slaves back into INIT state again.
       
   707 This method should be called prior to
       
   708 \textit{ecrt\_\-master\_\-release()}.
       
   709 
       
   710 \paragraph{Locking Callbacks}
       
   711 
       
   712 For concurrent master access, the application has to provide a locking
       
   713 mechanism (see section~\ref{sec:concurr}):
       
   714 
       
   715 \begin{lstlisting}[gobble=2,language=C]
       
   716   void ecrt_master_callbacks(ec_master_t *master,
       
   717                              int (*request_cb)(void *),
       
   718                              void (*release_cb)(void *),
       
   719                              void *cb_data);
       
   720 \end{lstlisting}
       
   721 
       
   722 The ``request lock'' and ``release lock'' callbacks can be set with
       
   723 the \textit{ecrt\_master\_call\-backs()} method. It takes two function
       
   724 pointers and a data value as additional arguments. The arbitrary data
       
   725 value will be passed as argument on every callback. Asynchronous
       
   726 master access (like EoE processing) is only possible if these
       
   727 callbacks have been set.
       
   728 
       
   729 \paragraph{Preparation of Cyclic Data Exchange}
       
   730 
       
   731 Cyclic operation mostly consists of the three steps input, processing and
       
   732 output. In EtherCAT terms this would mean: Receive datagrams, evaluate process
       
   733 data and send datagrams. The first cycle differs from this principle, because
       
   734 no datagrams have been sent yet, so there is nothing to receive. To avoid
       
   735 having a case differentiation (in terms of an \textit{if} clause), the
       
   736 following method exists:
       
   737 
       
   738 \begin{lstlisting}[gobble=2,language=C]
       
   739   void ecrt_master_prepare(ec_master_t *master);
       
   740 \end{lstlisting}
       
   741 
       
   742 As a last thing before cyclic operation, a call to the
       
   743 \textit{ecrt\_master\_prepare()} method should be issued. It makes all
       
   744 process data domains queue their datagrams and issues a send command,
       
   745 so that the first receive call in cyclic operation will not fail.
       
   746 
       
   747 \paragraph{Frame Sending and Receiving}
       
   748 
       
   749 To send all queued datagrams and to later receive the sent datagrams
       
   750 there are two methods:
       
   751 
       
   752 \begin{lstlisting}[gobble=2,language=C]
       
   753   void ecrt_master_send(ec_master_t *master);
       
   754   void ecrt_master_receive(ec_master_t *master);
       
   755 \end{lstlisting}
       
   756 
       
   757 The \textit{ecrt\_master\_send()} method takes all datagrams, that
       
   758 have been queued for transmission, packs them into frames, and passes
       
   759 them to the network device for sending.
       
   760 
       
   761 The \textit{ecrt\_master\_receive()} queries the network device for
       
   762 received frames (by calling the ISR\index{ISR}), extracts received
       
   763 datagrams and dispatches the results to the datagram objects in the
       
   764 queue. Received datagrams, and the ones that timed out, will be
       
   765 marked, and then dequeued.
       
   766 
       
   767 \paragraph{Running the Operation State Machine}
       
   768 
       
   769 The master's operation state machine (see section~\ref{sec:fsm-op})
       
   770 monitors the bus in cyclic operation and reconfigures slaves, if
       
   771 necessary. Therefore, the following method should be called
       
   772 cyclically:
       
   773 
       
   774 \begin{lstlisting}[gobble=2,language=C]
       
   775   void ecrt_master_run(ec_master_t *master);
       
   776 \end{lstlisting}
       
   777 
       
   778 The \textit{ecrt\_master\_run()} method executes the master's
       
   779 operation state machine step by step. It returns after processing one
       
   780 state and queuing a datagram. Calling this function is not mandatory,
       
   781 but highly recommended.
       
   782 
       
   783 \paragraph{Master Monitoring}
       
   784 
       
   785 It is also highly recommended to evaluate the master's error state. In
       
   786 this way it is possible to notice lost network links, failed bus
       
   787 segments, and other issues:
       
   788 
       
   789 \begin{lstlisting}[gobble=2,language=C]
       
   790   int ecrt_master_state(const ec_master_t *master);
       
   791 \end{lstlisting}
       
   792 
       
   793 The \textit{ecrt\_master\_state()} method returns the master's error
       
   794 state. The following states are defined as part of the realtime
       
   795 interface:
       
   796 
       
   797 \begin{description}
       
   798 \item[EC\_MASTER\_OK] means, that no error has occurred.
       
   799 \item[EC\_MASTER\_LINK\_ERROR] means, that the network link is
       
   800   currently down.
       
   801 \item[EC\_MASTER\_BUS\_ERROR] means, that one or more slaves do not
       
   802   respond.
       
   803 \end{description}
       
   804 
       
   805 \subsubsection{Domain Methods}
       
   806 \label{sec:ecrt-domain}
       
   807 
       
   808 \paragraph{Pdo Registration}
       
   809 
       
   810 To access data of a slave's Pdo in cyclic operation, it is necessary
       
   811 to make it part of a process data domain:
       
   812 
       
   813 \begin{lstlisting}[gobble=2,language=C]
       
   814   ec_slave_t *ecrt_domain_register_pdo(ec_domain_t *domain,
       
   815                                        const char *address,
       
   816                                        uint32_t vendor_id,
       
   817                                        uint32_t product_code,
       
   818                                        const char *pdo_name
       
   819                                        void **data_ptr);
       
   820   int ecrt_domain_register_pdo_list(ec_domain_t *domain,
       
   821                                     const ec_pdo_reg_t *pdos);
       
   822 \end{lstlisting}
       
   823 
       
   824 The \textit{ecrt\_domain\_register\_pdo()} method registers a certain
       
   825 Pdo as part of the domain and takes the address of the process data
       
   826 pointer. This pointer will be set on master activation and then can be
       
   827 parameter to the \textit{EC\_READ\_*} and \textit{EC\_WRITE\_*} macros
       
   828 described below.
       
   829 
       
   830 A perhaps easier way to register multiple Pdos at the same time is to
       
   831 fill an array of \textit{ec\_pdo\_reg\_t} and hand it to the
       
   832 \textit{ecrt\_domain\_register\_pdo\_list()} method. Attention: This
       
   833 array has to be terminated by an empty structure (\textit{\{\}})!
       
   834 
       
   835 \paragraph{Evaluating Domain Data}
       
   836 
       
   837 To evaluate domain data, the following method has to be used:
       
   838 
       
   839 \begin{lstlisting}[gobble=2,language=C]
       
   840   void ecrt_domain_process(ec_domain_t *domain);
       
   841 \end{lstlisting}
       
   842 
       
   843 The \textit{ecrt\_domain\_process()} method sets the domains state and
       
   844 re-queues its datagram for sending.
       
   845 
       
   846 \paragraph{Domain State}
       
   847 
       
   848 Similar to the master state, a domain has an own error state:
       
   849 
       
   850 \begin{lstlisting}[gobble=2,language=C]
       
   851   int ecrt_domain_state(const ec_domain_t *domain);
       
   852 \end{lstlisting}
       
   853 
       
   854 The \textit{ecrt\_domain\_state()} method returns the domain's error state. It
       
   855 is non-zero if \textbf{not} all process data values could be exchanged, and
       
   856 zero otherwise.
       
   857 
       
   858 \subsubsection{Slave Methods}
       
   859 \label{sec:ecrt-slave}
       
   860 
       
   861 \paragraph{Sdo Configuration}
       
   862 
       
   863 To configure slave Sdos, the function interface below can be used:
       
   864 
       
   865 \begin{lstlisting}[gobble=2,language=C]
       
   866   int ecrt_slave_conf_sdo8(ec_slave_t *slave,
       
   867                            uint16_t sdo_index,
       
   868                            uint8_t sdo_subindex,
       
   869                            uint8_t value);
       
   870   int ecrt_slave_conf_sdo16(ec_slave_t *slave,
       
   871                             uint16_t sdo_index,
       
   872                             uint8_t sdo_subindex,
       
   873                             uint16_t value);
       
   874   int ecrt_slave_conf_sdo32(ec_slave_t *slave,
       
   875                             uint16_t sdo_index,
       
   876                             uint8_t sdo_subindex,
       
   877                             uint32_t value);
       
   878 \end{lstlisting}
       
   879 
       
   880 The \textit{ecrt\_slave\_conf\_sdo*()} methods prepare the configuration of a
       
   881 certain Sdo. The index and subindex of the Sdo, and the value have to be
       
   882 specified. The configuration is done each time, the slave is reconfigured. The
       
   883 methods only differ in the Sdo's data type. If the configuration could be
       
   884 prepared, zero is returned. If an error occurred, non-zero is returned.
       
   885 
       
   886 \paragraph{Variable-sized Pdos}
       
   887 
       
   888 For specifying the size of variable-sized Pdos, the following method
       
   889 can be used:
       
   890 
       
   891 \begin{lstlisting}[gobble=2,language=C]
       
   892   int ecrt_slave_pdo_size(ec_slave_t *slave,
       
   893                           const char *pdo_name,
       
   894                           size_t size);
       
   895 \end{lstlisting}
       
   896 
       
   897 The \textit{ecrt\_slave\_pdo\_size()} method takes the name of the Pdo
       
   898 and the size. It returns zero on success, otherwise non-zero.
       
   899 
       
   900 \subsubsection{Process Data Access}
       
   901 \label{sec:macros}
       
   902 
       
   903 The endianess of the process data could differ from that of the CPU.
       
   904 Therefore, process data access has to be done by the macros below,
       
   905 that are also provided by the realtime interface:
       
   906 
       
   907 \begin{lstlisting}[gobble=2,language=C]
       
   908   #define EC_READ_BIT(DATA, POS)
       
   909   #define EC_WRITE_BIT(DATA, POS, VAL)
       
   910 
       
   911   #define EC_READ_U8(DATA)
       
   912   #define EC_READ_S8(DATA)
       
   913   #define EC_READ_U16(DATA)
       
   914   #define EC_READ_S16(DATA)
       
   915   #define EC_READ_U32(DATA)
       
   916   #define EC_READ_S32(DATA)
       
   917 
       
   918   #define EC_WRITE_U8(DATA, VAL)
       
   919   #define EC_WRITE_S8(DATA, VAL)
       
   920   #define EC_WRITE_U16(DATA, VAL)
       
   921   #define EC_WRITE_S16(DATA, VAL)
       
   922   #define EC_WRITE_U32(DATA, VAL)
       
   923   #define EC_WRITE_S32(DATA, VAL)
       
   924 \end{lstlisting}
       
   925 
       
   926 There are macros for bitwise access (\textit{EC\_READ\_BIT()},
       
   927 \textit{EC\_WRITE\_BIT()}), and byte-wise access (\textit{EC\_READ\_*()},
       
   928 \textit{EC\_WRITE\_*()}). The byte-wise macros carry the data type in their
       
   929 name. Example: \textit{EC\_WRITE\_S16()} writes a 16 bit signed value to
       
   930 EtherCAT data. The \textit{DATA} parameter is supposed to be a process data
       
   931 pointer, as provided at Pdo registration.
       
   932 
       
   933 The macros use the kernel's endianess conversion macros, that are
       
   934 preprocessed to empty macros in case of equal endianess. This is the
       
   935 definition for the \textit{EC\_\-READ\_\-U16()} macro:
       
   936 
       
   937 \begin{lstlisting}[gobble=2,language=C]
       
   938   #define EC_READ_U16(DATA) \
       
   939           ((uint16_t) le16_to_cpup((void *) (DATA)))
       
   940 \end{lstlisting}
       
   941 
       
   942 The \textit{le16\_to\_cpup()} macro converts a little-endian, 16 bit
       
   943 value to the CPU's architecture and takes a pointer to the input value
       
   944 as its argument. If the CPU's architecture is little-endian, too (for
       
   945 example on X86 and compatible), nothing has to be converted. In this
       
   946 case, the macro is replaced with an empty macro by the preprocessor
       
   947 and so there is no unneeded function call or case differentiation in
       
   948 the code.
       
   949 
       
   950 For keeping it portable, it is highly recommended to make use of these
       
   951 macros.
       
   952 
       
   953 %------------------------------------------------------------------------------
       
   954 
       
   955 \subsection{Slave Addressing}
       
   956 \label{sec:addr}
       
   957 \index{Slave!Addressing}
       
   958 
       
   959 The master offers the several slave addressing schemes (for Pdo
       
   960 registration or configuration) via the realtime interface. For this
       
   961 reason, slave addresses are ASCII\nomenclature{ASCII}{American
       
   962   Standard Code for Information Interchange}-coded and passed as a
       
   963 string. The addressing schemes are independent of the EtherCAT
       
   964 protocol and represent an additional feature of the master.
       
   965 
       
   966 Below, the allowed addressing schemes are described. The descriptions
       
   967 are followed by a regular expression formally defining the addressing
       
   968 scheme, and one or more examples.
       
   969 
       
   970 \begin{description}
       
   971 
       
   972 \item[Position Addressing] This is the normal addressing scheme, where each
       
   973 slave is addressed by its ring position. The first slave has address 0, and the
       
   974 $n$th slave has address $n - 1$. This addressing scheme is useful for small
       
   975 buses that have a fixed number of slaves.
       
   976 
       
   977 RegEx: \texttt{[0-9]+} --- Example: \texttt{"42"}
       
   978 
       
   979 \item[Advanced Position Addressing] Bus couplers segment the bus into
       
   980 (physical) blocks. Though the logical ring positions keep being the same, it is
       
   981 easier to address a slave with its block number and the relative position
       
   982 inside the block. This addressing is done by passing the (zero-based) index of
       
   983 the bus coupler (not the coupler's ring position), followed by a colon and the
       
   984 relative position of the actual slave starting at the bus coupler.
       
   985 
       
   986 RegEx: \texttt{[0-9]+:[0-9]+} --- Examples: \texttt{"0:42"}, \texttt{"2:7"}
       
   987 
       
   988 \item[Alias Addressing] Each slave can have a ``secondary slave address'' or
       
   989 ``alias address''\footnote{Information about how to set the alias can be found
       
   990 in section~\ref{sec:eepromaccess}} stored in its E$^2$PROM.  The alias is
       
   991 evaluated by the master and can be used to address the slave, which is useful
       
   992 when a clearly defined slave has to be addressed and the ring position is not
       
   993 known or can change over time. This scheme is used by starting the address
       
   994 string with a mesh (\#) followed by the alias address.  The latter can also be
       
   995 provided as hexadecimal value, prefixed with \textit{0x}.
       
   996 
       
   997 RegEx: \texttt{\#(0x[0-9A-F]+|[0-9]+)} --- Examples: \texttt{"\#6622"},
       
   998 \texttt{"\#0xBEEF"}
       
   999 
       
  1000 \item[Advanced Alias Addressing] This is a mixture of the ``Alias Addressing''
       
  1001 and ``Advanced Position Addressing'' schemes. A certain slave is addressed by
       
  1002 specifying its relative position after an aliased slave. This is very useful,
       
  1003 if a complete block of slaves can vary its position in the bus. The bus coupler
       
  1004 preceding the block should get an alias. The block slaves can then be addressed
       
  1005 by specifying this alias and their position inside the block. This scheme is
       
  1006 used by starting the address string with a mesh (\#) followed by the alias
       
  1007 address (which can be hexadecimal), then a colon and the relative position of
       
  1008 the slave to address.
       
  1009 
       
  1010 RegEx: \texttt{\#(0x[0-9A-F]+|[0-9]+):[0-9]+} --- Examples:
       
  1011 \texttt{"\#0xBEEF:7"}, \texttt{"\#6:2"}
       
  1012 
       
  1013 \end{description}
       
  1014 
       
  1015 In anticipation of section~\ref{sec:ecrt}, the functions accepting
       
  1016 these address strings are \textit{ecrt\_\-master\_\-get\_slave()},
       
  1017 \textit{ecrt\_domain\_register\_pdo()} and
       
  1018 \textit{ecrt\_domain\_register\_pdo\_list()} (the latter through the
       
  1019 \textit{ec\_pdo\_reg\_t} structure).
       
  1020 
       
  1021 %------------------------------------------------------------------------------
       
  1022 
       
  1023 \subsection{Concurrent Master Access}
       
  1024 \label{sec:concurr}
   657 \label{sec:concurr}
  1025 \index{Concurrency}
   658 \index{Concurrency}
  1026 
   659 
  1027 In some cases, one master is used by several instances, for example when an
   660 In some cases, one master is used by several instances, for example when an
  1028 application does cyclic process data exchange, and there are EoE-capable slaves
   661 application does cyclic process data exchange, and there are EoE-capable slaves
  3378 
  3011 
  3379 \chapter{Installation}
  3012 \chapter{Installation}
  3380 \label{sec:installation}
  3013 \label{sec:installation}
  3381 \index{Master!Installation}
  3014 \index{Master!Installation}
  3382 
  3015 
  3383 The current EtherCAT master code is available at~\cite{etherlab} or
  3016 \section{Building the software}
  3384 can be obtained from the EtherLab\textsuperscript{\textregistered} CD.
  3017 
  3385 The \textit{tar.bz2} file has to be unpacked with the commands below
  3018 The current EtherCAT master code is available at~\cite{etherlab} or can be
  3386 (or similar):
  3019 obtained from the EtherLab CD. The \textit{tar.bz2} file has to be unpacked
       
  3020 with the commands below (or similar):
  3387 
  3021 
  3388 \begin{lstlisting}[gobble=2]
  3022 \begin{lstlisting}[gobble=2]
  3389   `\$` `\textbf{tar xjf ethercat-\masterversion.tar.bz2}`
  3023   `\$` `\textbf{tar xjf ethercat-\masterversion.tar.bz2}`
  3390   `\$` `\textbf{cd ethercat-\masterversion/}`
  3024   `\$` `\textbf{cd ethercat-\masterversion/}`
  3391 \end{lstlisting}
  3025 \end{lstlisting}
  3458 
  3092 
  3459 \end{description}
  3093 \end{description}
  3460 
  3094 
  3461 \end{table}
  3095 \end{table}
  3462 
  3096 
       
  3097 \section{Building the documentation}
       
  3098 \label{sec:gendoc}
       
  3099 
       
  3100 The source code is documented using Doxygen~\cite{doxygen}. To build the HTML
       
  3101 documentation, you must have the Doxygen software installed. The below command
       
  3102 will generate the documents in the subdirecory \textit{doxygen-output}:
       
  3103 
       
  3104 \begin{lstlisting}
       
  3105 $ `\textbf{make doc}`
       
  3106 \end{lstlisting}
       
  3107 
       
  3108 To view them, point your browser to \textit{doxygen-output/html/index.html}.
       
  3109 
       
  3110 \section{Installation}
       
  3111 
  3463 The below commands have to be entered as \textit{root}: The first one
  3112 The below commands have to be entered as \textit{root}: The first one
  3464 will install the kernel modules to the kernel's modules directory. The
  3113 will install the kernel modules to the kernel's modules directory. The
  3465 second one will install EtherCAT headers, the init script, the
  3114 second one will install EtherCAT headers, the init script, the
  3466 sysconfig file and the user space tools to the prefix path.
  3115 sysconfig file and the user space tools to the prefix path.
  3467 
  3116 
  3468 \begin{lstlisting}[gobble=2]
  3117 \begin{lstlisting}
  3469   # `\textbf{make modules\_install}`
  3118 # `\textbf{make modules\_install}`
  3470   # `\textbf{make install}`
  3119 # `\textbf{make install}`
  3471 \end{lstlisting}
  3120 \end{lstlisting}
  3472 
  3121 
  3473 If the target kernel's modules directory is not under
  3122 If the target kernel's modules directory is not under
  3474 \textit{/lib/modules}, a different destination directory can be
  3123 \textit{/lib/modules}, a different destination directory can be
  3475 specified with the \textit{DESTDIR} make variable. For example:
  3124 specified with the \textit{DESTDIR} make variable. For example:
  3476 
  3125 
  3477 \begin{lstlisting}[gobble=2]
  3126 \begin{lstlisting}
  3478   # `\textbf{make DESTDIR=/vol/nfs/root modules\_install}`
  3127 # `\textbf{make DESTDIR=/vol/nfs/root modules\_install}`
  3479 \end{lstlisting}
  3128 \end{lstlisting}
  3480 
  3129 
  3481 This command will install the compiled kernel modules to
  3130 This command will install the compiled kernel modules to
  3482 \textit{/vol/nfs/root/lib/modules}, prepended by the kernel release.
  3131 \textit{/vol/nfs/root/lib/modules}, prepended by the kernel release.
  3483 
  3132 
  3486 recommended for manual (un-)loading.} (see section~\ref{sec:system}), the init
  3135 recommended for manual (un-)loading.} (see section~\ref{sec:system}), the init
  3487 script and the sysconfig file have to be copied (or linked) to the appropriate
  3136 script and the sysconfig file have to be copied (or linked) to the appropriate
  3488 locations. The below example is suitable for SUSE Linux. It may vary for other
  3137 locations. The below example is suitable for SUSE Linux. It may vary for other
  3489 distributions.
  3138 distributions.
  3490 
  3139 
  3491 \begin{lstlisting}[gobble=2]
  3140 \begin{lstlisting}
  3492   # `\textbf{cd /opt/etherlab}`
  3141 # `\textbf{cd /opt/etherlab}`
  3493   # `\textbf{cp etc/sysconfig/ethercat /etc/sysconfig/}`
  3142 # `\textbf{cp etc/sysconfig/ethercat /etc/sysconfig/}`
  3494   # `\textbf{ln -s etc/init.d/ethercat /etc/init.d/}`
  3143 # `\textbf{ln -s etc/init.d/ethercat /etc/init.d/}`
  3495   # `\textbf{insserv ethercat}`
  3144 # `\textbf{insserv ethercat}`
  3496 \end{lstlisting}
  3145 \end{lstlisting}
  3497 
  3146 
  3498 Now the sysconfig file \texttt{/etc/sysconfig/ethercat} (see
  3147 Now the sysconfig file \texttt{/etc/sysconfig/ethercat} (see
  3499 section~\ref{sec:sysconfig}) has to be customized. The minimal customization
  3148 section~\ref{sec:sysconfig}) has to be customized. The minimal customization
  3500 is to set the \lstinline+MASTER0_DEVICE+ variable to the MAC address of the
  3149 is to set the \lstinline+MASTER0_DEVICE+ variable to the MAC address of the
  3503 \lstinline+DEVICE_MODULES+ variable.
  3152 \lstinline+DEVICE_MODULES+ variable.
  3504 
  3153 
  3505 After the basic configuration is done, the master can be started with
  3154 After the basic configuration is done, the master can be started with
  3506 the below command:
  3155 the below command:
  3507 
  3156 
  3508 \begin{lstlisting}[gobble=2]
  3157 \begin{lstlisting}
  3509   # `\textbf{/etc/init.d/ethercat start}`
  3158 # `\textbf{/etc/init.d/ethercat start}`
  3510 \end{lstlisting}
  3159 \end{lstlisting}
  3511 
  3160 
  3512 The operation of the master can be observed by looking at the
  3161 The operation of the master can be observed by looking at the
  3513 Syslog\index{Syslog} messages, which should look like the ones below.  If
  3162 Syslog\index{Syslog} messages, which should look like the ones below.  If
  3514 EtherCAT slaves are connected to the master's EtherCAT device, the activity
  3163 EtherCAT slaves are connected to the master's EtherCAT device, the activity
  4167 \end{description}
  3816 \end{description}
  4168 
  3817 
  4169 %------------------------------------------------------------------------------
  3818 %------------------------------------------------------------------------------
  4170 
  3819 
  4171 \begin{thebibliography}{99}
  3820 \begin{thebibliography}{99}
  4172 \bibitem{etherlab} Ingenieurgemeinschaft IgH: EtherLab -- Open Source
  3821 
  4173   Toolkit for rapid realtime code generation under Linux with
  3822 \bibitem{etherlab} Ingenieurgemeinschaft IgH: EtherLab -- Open Source Toolkit
  4174   Simulink/RTW and EtherCAT technology. URL: http://etherlab.org,
  3823 for rapid realtime code generation under Linux with Simulink/RTW and EtherCAT
  4175   July~31, 2006.
  3824 technology. \url{http://etherlab.org/en}, 2008.
       
  3825 
  4176 \bibitem{dlspec} IEC 61158-4-12: Data-link Protocol Specification.
  3826 \bibitem{dlspec} IEC 61158-4-12: Data-link Protocol Specification.
  4177   International Electrotechnical Comission (IEC), 2005.
  3827 International Electrotechnical Comission (IEC), 2005.
  4178 \bibitem{alspec} IEC 61158-6-12: Application Layer Protocol
  3828 
  4179   Specification. International Electrotechnical Comission (IEC), 2005.
  3829 \bibitem{alspec} IEC 61158-6-12: Application Layer Protocol Specification.
  4180 \bibitem{gpl} GNU General Public License, Version 2. URL:
  3830 International Electrotechnical Comission (IEC), 2005.
  4181   http://www.gnu.org/licenses/gpl.txt. August~9, 2006.
  3831 
  4182 \bibitem{lsb} Linux Standard Base. URL:
  3832 \bibitem{gpl} GNU General Public License, Version 2.
  4183   http://www.freestandards.org/en/LSB. August~9, 2006.
  3833 \url{http://www.gnu.org/licenses/gpl.txt}. August~9, 2006.
  4184 \bibitem{wireshark} Wireshark. URL: http://www.wireshark.org.
  3834 
  4185   August~9, 2006.
  3835 \bibitem{lsb} Linux Standard Base.
  4186 \bibitem{automata} {\it Hopcroft, J.~E. / Ullman, J.~D.}: Introduction
  3836 \url{http://www.linuxfoundation.org/en/LSB}.  August~9, 2006.
  4187   to Automata Theory, Languages and Computation. Adison-Wesley,
  3837 
  4188   Reading, Mass.~1979.
  3838 \bibitem{wireshark} Wireshark. \url{http://www.wireshark.org}. 2008.
       
  3839 
       
  3840 \bibitem{automata} {\it Hopcroft, J.~E. / Ullman, J.~D.}: Introduction to
       
  3841 Automata Theory, Languages and Computation. Adison-Wesley, Reading,
       
  3842 Mass.~1979.
       
  3843 
  4189 \bibitem{fsmmis} {\it Wagner, F. / Wolstenholme, P.}: State machine
  3844 \bibitem{fsmmis} {\it Wagner, F. / Wolstenholme, P.}: State machine
  4190   misunderstandings. In: IEE journal ``Computing and Control
  3845 misunderstandings. In: IEE journal ``Computing and Control Engineering'',
  4191   Engineering'', 2004.
  3846 2004.
  4192 \bibitem{rtai} RTAI. The RealTime Application Interface for Linux from
  3847 
  4193   DIAPM. URL: http://www.rtai.org, 2006.
  3848 \bibitem{rtai} RTAI. The RealTime Application Interface for Linux from DIAPM.
       
  3849 \url{http://www.rtai.org}, 2006.
       
  3850 
       
  3851 \bibitem{doxygen} Doxygen. Source code documentation generator tool.
       
  3852 \url{http://www.stack.nl/~dimitri/doxygen}, 2008.
       
  3853 
  4194 \end{thebibliography}
  3854 \end{thebibliography}
  4195 
  3855 
  4196 \printnomenclature
  3856 \printnomenclature
  4197 \addcontentsline{toc}{chapter}{\nomname}
  3857 \addcontentsline{toc}{chapter}{\nomname}
  4198 \markleft{\nomname}
  3858 \markleft{\nomname}