From ad230e1ba3c223abf19f7576a465c0927cf17300 Mon Sep 17 00:00:00 2001
From: Florian Pose <fp@igh-essen.com>
Date: Thu, 24 Jul 2008 08:11:07 +0000
Subject: [PATCH] Command-line help in the docs.
---
documentation/Makefile | 34 +++++++++--
documentation/ethercat_doc.tex | 100 ++++++++++++++++++++++++++-------
2 files changed, 107 insertions(+), 27 deletions(-)
diff --git a/documentation/Makefile b/documentation/Makefile
index 3d9106b5..1cc39d35 100644
--- a/documentation/Makefile
+++ b/documentation/Makefile
@@ -10,16 +10,38 @@ FILE := ethercat_doc
LATEX_OPTIONS := -file-line-error-style
-#------------------------------------------------------------------------------
+COMMANDS := \
+ alias \
+ config \
+ data \
+ debug \
+ domains \
+ master \
+ pdos \
+ sdos \
+ download \
+ upload \
+ slaves \
+ sii_read \
+ sii_write \
+ states \
+ xml
+
+EXT_PREFIX := external/ethercat_
+EXT_FILES := $(addprefix $(EXT_PREFIX),$(COMMANDS))
+ETHERCAT_CMD := ../tool/ethercat
+ETHERCAT_HELP := $(ETHERCAT_CMD) -h
-first: pdf
+#------------------------------------------------------------------------------
-all: dvi pdf
+all: pdf
-dvi:
- latex $(LATEX_OPTIONS) \\nonstopmode\\input{$(FILE).tex}
+$(EXT_FILES): $(ETHERCAT_CMD)
+ @mkdir -pv external
+ @echo Creating $@...
+ $(shell $(subst $(EXT_PREFIX),$(ETHERCAT_HELP) ,$@) > $@)
-pdf:
+pdf: $(EXT_FILES)
pdflatex $(LATEX_OPTIONS) $(FILE)
index:
diff --git a/documentation/ethercat_doc.tex b/documentation/ethercat_doc.tex
index 891367be..0e720805 100644
--- a/documentation/ethercat_doc.tex
+++ b/documentation/ethercat_doc.tex
@@ -301,7 +301,8 @@ EtherCAT functionality (see section~\ref{sec:ecrt}).
\end{itemize}
-\item User space command-line-tool ``ethercat``.
+\item User space command-line-tool ``ethercat`` (see
+section~\ref{sec:ethercat})
\begin{itemize}
@@ -2692,36 +2693,77 @@ master.
%------------------------------------------------------------------------------
-\subsection{Listing the bus}
+\subsection{Setting alias addresses}
-Slave information can be gathered with the subcommand \lstinline+slaves+:
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_alias}
-\begin{lstlisting}
-$ `\textbf{ethercat slaves}`
-0 0:0 PREOP + EK1100 Ethernet Kopplerklemme (2A E-Bus)
-1 5555:0 PREOP + EL3162 2K. Ana. Eingang 0-10V
-2 5555:1 PREOP + EL4102 2K. Ana. Ausgang 0-10V
-3 5555:2 PREOP + EL2004 4K. Dig. Ausgang 24V, 0,5A
-\end{lstlisting}
+%------------------------------------------------------------------------------
-Every slave found is displayed as one text row. The columns have the following
-meanings:
+\subsection{Displaying the bus configuration}
-\begin{enumerate}
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_config}
-\item Ring position in the bus.
+%------------------------------------------------------------------------------
-\item Alias and position (see section~\ref{sec:addr}).
+\subsection{Displaying process data}
-\item Application-layer state.
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_data}
-\item Error flag: \lstinline!+! means that the slave is ok, \lstinline+E+
-means that an error has occurred during scanning or configuration.
+%------------------------------------------------------------------------------
-\item The slave's name, as it appears in the ``general'' SII category. If no
-name is found, the slave's vendor ID and product code are listed.
+\subsection{Setting a master's debug level}
-\end{enumerate}
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_debug}
+
+%------------------------------------------------------------------------------
+
+\subsection{Configured domains}
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_domains}
+
+%------------------------------------------------------------------------------
+
+\subsection{Master and Ethernet device information}
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_master}
+
+%------------------------------------------------------------------------------
+
+\subsection{Showing slaves' sync managers, Pdos and Pdo entries}
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_pdos}
+
+%------------------------------------------------------------------------------
+
+\subsection{Displaying the Sdo dictionary}
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sdos}
+
+%------------------------------------------------------------------------------
+
+\subsection{Sdo access}
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_download}
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_upload}
+
+%------------------------------------------------------------------------------
+
+\subsection{Displaying slaves on the bus}
+
+Slave information can be gathered with the subcommand \lstinline+slaves+:
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_slaves}
+
+Below is a typical output:
+
+\begin{lstlisting}
+$ `\textbf{ethercat slaves}`
+0 0:0 PREOP + EK1100 Ethernet Kopplerklemme (2A E-Bus)
+1 5555:0 PREOP + EL3162 2K. Ana. Eingang 0-10V
+2 5555:1 PREOP + EL4102 2K. Ana. Ausgang 0-10V
+3 5555:2 PREOP + EL2004 4K. Dig. Ausgang 24V, 0,5A
+\end{lstlisting}
%------------------------------------------------------------------------------
@@ -2746,6 +2788,8 @@ space.
\end{itemize}
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sii_read}
+
Reading out SII data is as easy as other commands. Though the data are in
binary format, analysis is easier with a tool like \textit{hexdump}:
@@ -2766,6 +2810,8 @@ $ `\textbf{ethercat sii\_read --slave 3 > sii-of-slave3.bin}`
To download SII contents to a slave, writing access to the master's character
device is necessary (see section~\ref{sec:cdev}).
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_sii_write}
+
\begin{lstlisting}
# `\textbf{ethercat sii\_write --slave 3 sii-of-slave3.bin}`
\end{lstlisting}
@@ -2775,6 +2821,18 @@ write operation may take a few seconds.
%------------------------------------------------------------------------------
+\subsection{Requesting application-layer states}
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_states}
+
+%------------------------------------------------------------------------------
+
+\subsection{Generating slave description XML}
+
+\lstinputlisting[basicstyle=\ttfamily\footnotesize]{external/ethercat_xml}
+
+%------------------------------------------------------------------------------
+
\section{System Integration}
\label{sec:system}
--
GitLab