diff --git a/FEATURES b/FEATURES.md similarity index 76% rename from FEATURES rename to FEATURES.md index 7d84f12a..f7c7ae8c 100644 --- a/FEATURES +++ b/FEATURES.md @@ -1,20 +1,14 @@ -------------------------------------------------------------------------------- - This is the FEATURES file of the IgH EtherCAT Master. -$Id$ - vim: spelllang=en spell -------------------------------------------------------------------------------- +# General Features -General Features: - -* EtherCAT master implementation conforming to IEC/PAS 62407. +- EtherCAT master implementation conforming to IEC/PAS 62407. - Runs as kernel module for Linux 2.6. - Multiple masters possible on one machine. -* Native EtherCAT-capable versions of standard Linux drivers for wide-spread +- Native EtherCAT-capable versions of standard Linux drivers for wide-spread Ethernet devices, as well as a generic driver for all chips supported by the Linux kernel. - Interrupt-less operation of Ethernet devices when using native drivers. @@ -25,12 +19,12 @@ General Features: - For any other hardware, the generic driver can be used. It uses the lower layers of the Linux network stack. -* Supports any realtime environment through independent architecture. +- Supports any realtime environment through independent architecture. - RTAI, Xenomai, RT-Preempt, etc. - RTDM Interface for userspace realtime enviroments - Operation possible without any realtime extension at all. -* Common API for Realtime-Applications in kernel- and userspace. +- Common API for Realtime-Applications in kernel- and userspace. - Requesting and releasing masters. - Dynamic slave configuration, even for slaves that are offline. - Detailed configuration of the slaves' PDOs and SDOs. @@ -42,37 +36,37 @@ General Features: - Similar userspace implementation of the kernel API via a C-library. - Avoidance of unnecessary copy operations for process data. -* Separating slave groups through domains. +- Separating slave groups through domains. - Handling of multiple slave groups with different sampling rates. - Automatic calculation of process data mapping, FMMU- and sync manager configuration within the domains. - Process data exchange can be monitored via a per-domain mechanism. -* Master finite state machine (FSM). +- Master finite state machine (FSM). - The same state machine runs both in idle mode and in realtime operation. - Bus monitoring: Slave states are read cyclically. Automatic scanning of the bus after a topology change. - Automatic configuration of slaves, if a application-layer state change is requested. -* Implementation of the "CANopen over EtherCAT" (CoE) mailbox protocol. +- Implementation of the "CANopen over EtherCAT" (CoE) mailbox protocol. - Configuration of CoE-capable slaves. - SDO information service (dictionary listing). - SDO transfers both via the application interface and the command-line tool. -* Implementation of the "Ethernet over EtherCAT" (EoE) mailbox protocol. +- Implementation of the "Ethernet over EtherCAT" (EoE) mailbox protocol. - Virtual network interface for any EoE-capable slave. - Both a switched and a routed EoE network architecture is natively supported and configurable with standard tools. -* Implementation of the "Vendor-specific over EtherCAT" (VoE) mailbox protocol. +- Implementation of the "Vendor-specific over EtherCAT" (VoE) mailbox protocol. - Communication with vendor-specific mailbox protocols via the API. -* Implementation of the "File Access over EtherCAT" (FoE) mailbox protocol. +- Implementation of the "File Access over EtherCAT" (FoE) mailbox protocol. - Loading and storing files via the command-line tool. - Updating a slave's firmware can be done easily. -* Userspace command-line tool 'ethercat'. +- Userspace command-line tool 'ethercat'. - Detailed information about master, slaves, domains and bus configuration. - Setting the master's debug level. - Reading/Writing alias addresses. @@ -85,11 +79,9 @@ General Features: - Controlling application-layer states. - Generation of slave description XML from existing slaves. -* Seamless integration in any GNU/Linux distribution. +- Seamless integration in any GNU/Linux distribution. - "Linux Standard Base"-compatible init script for master control. - Master and Ethernet device configuration via sysconfig file. -* Virtual read-only network interface for debugging and traffic monitoring +- Virtual read-only network interface for debugging and traffic monitoring purposes (using Wireshark, etc.). No additional hardware necessary. - -------------------------------------------------------------------------------- diff --git a/INSTALL b/INSTALL deleted file mode 100644 index d211cedb..00000000 --- a/INSTALL +++ /dev/null @@ -1,53 +0,0 @@ -------------------------------------------------------------------------------- - -This is the INSTALL file of the IgH EtherCAT Master. - -$Id$ - -vim: set spelllang=en spell tw=78 - -------------------------------------------------------------------------------- - -Building and installing -======================= - -The complete build and installation procedure is described in the respective -section of the documentation available from http://etherlab.org/en/ethercat. - -------------------------------------------------------------------------------- - -For the impatient: The procedure mainly consists of calling - -$ ./bootstrap # to create the configure script, if downloaded from the repo - -$ ./configure -$ make all modules - -... and as root: - -# make modules_install install -# depmod - -... and linking the init script and copying the sysconfig file from $PREFIX/etc -to the appropriate locations and customizing the sysconfig file. - -# ln -s ${PREFIX}/etc/init.d/ethercat /etc/init.d/ethercat -# cp ${PREFIX}/etc/sysconfig/ethercat /etc/sysconfig/ethercat -# vi /etc/sysconfig/ethercat - -Make sure, that the 'udev' package is installed, to automatically create the -EtherCAT character devices. The character devices will be created with mode -0660 and group root by default. If you want to give normal users reading -access, create a udev rule like this: - -# echo KERNEL==\"EtherCAT[0-9]*\", MODE=\"0664\" > /etc/udev/rules.d/99-EtherCAT.rules - -Now you can start the EtherCAT master: - -# /etc/init.d/ethercat start - -Have a look at the examples/ subdirectory for some application examples. - -Have fun! - -------------------------------------------------------------------------------- diff --git a/INSTALL.md b/INSTALL.md new file mode 100644 index 00000000..33029117 --- /dev/null +++ b/INSTALL.md @@ -0,0 +1,59 @@ +This is the INSTALL file of the IgH EtherCAT Master. + +vim: set spelllang=en spell tw=78 + +# Building and installing + +The complete build and installation procedure is described in the respective +section of the +[https://gitlab.com/etherlab.org/ethercat/-/jobs/artifacts/stable-1.5/raw/pdf/ethercat_doc.pdf?job=pdf](documentation). + +--- + +For the impatient: The procedure mainly consists of calling + +```bash +./bootstrap # to create the configure script, if downloaded from the repo + +./configure +make all modules +``` + +... and as root: + +```bash +make modules_install install +depmod +``` + +... and linking the init script and copying the sysconfig file from $PREFIX/etc +to the appropriate locations and customizing the sysconfig file. + +```bash +ln -s ${PREFIX}/etc/init.d/ethercat /etc/init.d/ethercat +cp ${PREFIX}/etc/sysconfig/ethercat /etc/sysconfig/ethercat +vi /etc/sysconfig/ethercat +``` + +Make sure, that the 'udev' package is installed, to automatically create the +EtherCAT character devices. The character devices will be created with mode +0660 and group root by default. If you want to give normal users reading +access, create a udev rule like this: + +```bash +echo KERNEL==\"EtherCAT[0-9]*\", MODE=\"0664\" > /etc/udev/rules.d/99-EtherCAT.rules +``` + +Now you can start the EtherCAT master: + +```bash +/etc/init.d/ethercat start +``` + +Have a look at the examples/ subdirectory for some application examples. + +--- + +Have fun! + +--- diff --git a/README b/README.md similarity index 54% rename from README rename to README.md index 49c3d145..c622374f 100644 --- a/README +++ b/README.md @@ -1,28 +1,21 @@ ------------------------------------------------------------------------------- - This is the README file of the IgH EtherCAT Master. vim: spelllang=en spell tw=78 ------------------------------------------------------------------------------- - Contents: -1) General Information -2) Requirements -3) Building and installing -4) Realtime & Tuning -5) License -6) Coding Style +- general-information +- requirements +- building-and-installing +- realtime-and-tuning +- license +- coding-style ------------------------------------------------------------------------------- +# General Information -1) General Information -====================== +This is an open-source EtherCAT master implementation for Linux 2.6 or newer. -This is an open-source EtherCAT master implementation for Linux 2.6. - -See the FEATURES file for a list of features. For more information, see -http://etherlab.org/en/ethercat. +See the (Features file)[FEATURES] for a list of features. For more +information, see http://etherlab.org/en/ethercat. or contact @@ -32,32 +25,54 @@ Nordsternstraße 66 D-45329 Essen http://igh.de ------------------------------------------------------------------------------- +# Documentation -2) Requirements -=============== +## Handbook -1) Software requirements +The PDF documentation is generated via LaTeX and can be build with the +following steps: -Configured sources for the Linux 2.6 kernel are required to build the EtherCAT -master. +```bash +cd documentation +make +``` -2) Hardware requirements +The PDF is automatically generated automatically in GitLab and can be +downloaded +[https://gitlab.com/etherlab.org/ethercat/-/jobs/artifacts/stable-1.5/raw/pdf/ethercat_doc.pdf?job=pdf](from +here). + +## Dogygen + +To generate the Doxygen documentation, the following commands can be used. +Therefore, the configure script must have run (see the [install +file](INSTALL.md)). + +```bash +git submodule update --init +make doc +``` + +An up-to-date Doxygen output can be found on +[https://docs.etherlab.org/ethercat/1.5/doxygen/index.html](docs.etherlab.org). + +# Requirements + +## Software requirements + +Configured sources for the Linux 2.6 (or newer) kernel are required to build +the EtherCAT master. + +## Hardware requirements A table of supported hardware can be found at http://etherlab.org/en/ethercat/hardware.php. ------------------------------------------------------------------------------- +# Building and installing -3) Building and installing -========================== +See the [install file](INSTALL.md). -See the INSTALL file. - ------------------------------------------------------------------------------- - -4) Realtime & Tuning -==================== +# Realtime and Tuning Realtime patches for the Linux kernel are supported, but not required. The realtime processing has to be done by the calling module (see API @@ -65,12 +80,9 @@ documentation). The EtherCAT master code itself is passive (except for the idle mode and EoE). To avoid frame timeouts, deactivating DMA access for hard drives is -recommended (hdparm -d0 ). +recommended (`hdparm -d0 `). ------------------------------------------------------------------------------- - -5) License -========== +# License Copyright (C) 2006-2023 Florian Pose, Ingenieurgemeinschaft IgH @@ -95,11 +107,7 @@ The license mentioned above concerns the source code only. Using the EtherCAT technology and brand is only permitted in compliance with the industrial property and similar rights of Beckhoff Automation GmbH. ------------------------------------------------------------------------------- +# Coding Style -6) Coding Style -=============== - -Developers shall use the coding style rules in the CodingStyle.txt file. - ------------------------------------------------------------------------------- +Developers shall use the coding style rules in the [coding style +file](CodingStyle.txt).