bkinnightskytw
/
ethercat
mirror of https://gitlab.com/bkinnightskytw/ethercat.git
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

Re-formatted README, INSTALL and FEATURES to markdown.

This commit is contained in:
Florian Pose 2023-01-30 10:36:21 +01:00
parent 6f9509214d
commit d8045fe122
4 changed files with 126 additions and 120 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

36
FEATURES → FEATURES.md
View File

@ -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.
-------------------------------------------------------------------------------

53
INSTALL
View File

@ -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!
-------------------------------------------------------------------------------

59
INSTALL.md Normal file
View File

@ -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!
---

98
README → README.md
View File

@ -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 <DEV>).
recommended (`hdparm -d0 <DEV>`).
------------------------------------------------------------------------------
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).