Mirrors_Framework/ethercat
1
0
Fork 0
mirror of https://gitlab.com/etherlab.org/ethercat.git synced 2026-08-17 08:41:43 +08:00
Code Issues Actions Packages Projects Releases Wiki Activity

Followed markdownlint guidelines and fixed broken links.

Browse Source
This commit is contained in:
Florian Pose
2026-07-14 18:54:39 +02:00
parent c4b4ac405f
commit a27db36a33
8 changed files with 79 additions and 85 deletions
Download Patch File Download Diff File Expand all files Collapse all files
CONTRIBUTING.md
+18 -28
View File
@@ -13,12 +13,12 @@ forward to your contributions. 🎉
> And if you like the project, but just don't have time to contribute, that's
> fine. There are other easy ways to support the project and show your
> appreciation, which we would also be very happy about:
>
> - Star the project
> - Write something about it in the social media
> - Refer this project in your project's readme
> - Mention the project at local meetups and tell your friends/colleagues
<!-- omit in toc -->
## Table of Contents
@@ -26,12 +26,7 @@ forward to your contributions. 🎉
- [I Want To Contribute](#i-want-to-contribute)
- [Reporting Bugs](#reporting-bugs)
- [Suggesting Enhancements](#suggesting-enhancements)
- [Your First Code Contribution](#your-first-code-contribution)
- [Improving The Documentation](#improving-the-documentation)
- [Styleguides](#styleguides)
- [Commit Messages](#commit-messages)
- [Join The Project Team](#join-the-project-team)
## I Have a Question
@@ -39,9 +34,9 @@ forward to your contributions. 🎉
> [Documentation](https://docs.etherlab.org).
Before you ask a question, it is best to search for existing
[Issues](https://gitlab.com/etherlab.org/ethercat/issues) and in the [mailing
list archives](https://lists.etherlab.org/mailman/listinfo) for posts that
might help you.
[Issues](https://gitlab.com/etherlab.org/ethercat/-/work_items) and in the
[mailing list archives](https://lists.etherlab.org/mailman/listinfo) for posts
that might help you.
In case you have found a suitable issue and still need clarification, you can
write your question in this issue. It is also advisable to search the internet
@@ -52,8 +47,8 @@ recommend the following:
- If it is a question about getting a certain device to work, please ask you
question on our [mailing lists](https://lists.etherlab.org/mailman/listinfo).
- If f you think the problem lies in the master itself, open an
[Issue](https://gitlab.com/etherlab.org/ethercat/issues/new).
- If you think the problem lies in the master itself, open an
[Issue](https://gitlab.com/etherlab.org/ethercat/-/work_items/new?type=Issue).
- Provide as much context as you can about what you're running into.
- Provide project and platform versions: EtherCAT master version, Linux Kernel
version, the Linux distribution and the used Ethernet driver (generic,
@@ -61,15 +56,14 @@ recommend the following:
We will then take care of the issue as soon as possible.
## I Want To Contribute
> ### Legal Notice <!-- omit in toc -->
>
> When contributing to this project, you must agree that you have authored 100%
> of the content, that you have the necessary rights to the content and that
> the content you contribute may be provided under the project licence.
### Reporting Bugs
<!-- omit in toc -->
@@ -89,17 +83,16 @@ possible.
- To see if other users have experienced (and potentially already solved) the
same issue you are having, check if there is not already a bug report
existing for your bug or error in the
[bug tracker](https://gitlab.com/etherlab.org/ethercat/issues?q=label%3Abug).
[bug tracker](https://gitlab.com/etherlab.org/ethercat/-/work_items).
- Also make sure to search the internet to see if
users outside of the GitLab community have discussed the issue.
- Collect information about the bug:
- Stack trace (Traceback)
- OS, Platform and Version (Linux Kernel, Distribution, x86, ARM, ...)
- OS, Platform and Version (Linux Kernel, Distribution, x86, ARM, ...)
- The Ethernet driver use are using (generic, 8139too, ccat, ...)
- Can you reliably reproduce the issue? And can you also reproduce it with
older versions?
<!-- omit in toc -->
#### How Do I Submit a Good Bug Report?
@@ -110,9 +103,10 @@ possible.
We use GitLab issues to track bugs and errors. If you run into an issue with
the project:
- Open an [Issue](https://gitlab.com/etherlab.org/ethercat/issues/new). (Since
we can't be sure at this point whether it is a bug or not, we ask you not to
talk about a bug yet and not to label the issue.)
- Open an
[Issue](https://gitlab.com/etherlab.org/ethercat/-/work_items/new?type=Issue).
(Since we can't be sure at this point whether it is a bug or not, we ask you
not to talk about a bug yet and not to label the issue.)
- Explain the behavior you would expect and the actual behavior.
- Please provide as much context as possible and describe the *reproduction
steps* that someone else can follow to recreate the issue on their own. This
@@ -124,7 +118,6 @@ Once it's filed:
- The project team will label the issue accordingly.
### Suggesting Enhancements
This section guides you through submitting an enhancement suggestion for IgH
@@ -132,16 +125,15 @@ EtherCAT Master, **including completely new features and minor improvements to
existing functionality**. Following these guidelines will help maintainers and
the community to understand your suggestion and find related suggestions.
<!-- omit in toc -->
#### Before Submitting an Enhancement
- Make sure that you are using the latest version.
- Read the [documentation](https://docs.etherlab.org) carefully and find out if
the functionality is already covered, maybe by an individual configuration.
- Perform a [search](https://gitlab.com/etherlab.org/ethercat/issues) to see if
the enhancement has already been suggested. If it has, add a comment to the
existing issue instead of opening a new one.
- Perform a [search](https://gitlab.com/etherlab.org/ethercat/-/work_items) to
see if the enhancement has already been suggested. If it has, add a comment
to the existing issue instead of opening a new one.
- Find out whether your idea fits with the scope and aims of the project. It's
up to you to make a strong case to convince the project's developers of the
merits of this feature. Keep in mind that we want features that will be
@@ -149,12 +141,11 @@ the community to understand your suggestion and find related suggestions.
just targeting a minority of users, consider writing an add-on/plugin
library.
<!-- omit in toc -->
#### How Do I Submit a Good Enhancement Suggestion?
Enhancement suggestions are tracked as
[GitLab issues](https://gitlab.com/etherlab.org/ethercat/issues).
[GitLab issues](https://gitlab.com/etherlab.org/ethercat/-/work_items).
- Use a **clear and descriptive title** for the issue to identify the
suggestion.
@@ -170,12 +161,11 @@ Enhancement suggestions are tracked as
users. You may also want to point out the other projects that solved it
better and which could serve as inspiration.
## Styleguides
There is a [coding style document](CodingStyle.md) next to this guide.
<!-- omit in toc -->
## Attribution
This guide is based on the [contributing.md](https://contributing.md/generator)!
CodingStyle.md
+7 -5
View File
@@ -1,15 +1,15 @@
vim: spelllang=en tw=78
# Coding Style
This is a short introduction to the coding style that shall be used. The below
rules are applicable for all C source files, except the Ethernet drivers, for
which the Linux Kernel coding style shall be used to minimize the
differences).
# Line length
## Line length
- Lines shall not exceed 78 characters.
# Whitespace
## Whitespace
- Indentation shall be done using 4 space characters
@@ -21,7 +21,7 @@ differences).
- Binary operators (`=`, `==`, `~=`, `|`, `||`, etc.) shall be enclosed by 2 spaces
(except `.` and `->`).
# Placing braces
## Placing braces
- Braces shall be placed in the following way (K&R style):
@@ -40,7 +40,7 @@ int function(...)
}
```
# Defines and Macros
## Defines and Macros
- Defines and macros shall be named in CAPITAL letters. If a macro contains
multiple statements, they should be enclosed by a 'do {} while (0)' loop.
@@ -54,3 +54,5 @@ int function(...)
statement(B); \
} while (0)
```
vim: spelllang=en tw=78
FEATURES.md
+4 -4
View File
@@ -1,9 +1,7 @@
This is the FEATURES file of the IgH EtherCAT Master.
vim: spelllang=en spell
# General Features
This is the FEATURES.md file of the IgH EtherCAT Master.
- EtherCAT master implementation conforming to IEC/PAS 62407.
- Runs as kernel module for Linux 2.6.
- Multiple masters possible on one machine.
@@ -85,3 +83,5 @@ vim: spelllang=en spell
- Virtual read-only network interface for debugging and traffic monitoring
purposes (using Wireshark, etc.). No additional hardware necessary.
vim: spelllang=en spell
INSTALL.md
+5 -5
View File
@@ -1,12 +1,10 @@
This is the INSTALL file of the IgH EtherCAT Master.
vim: set spelllang=en spell tw=78
# Building and installing
This is the INSTALL.md file of the IgH EtherCAT Master.
The complete build and installation procedure is described in the respective
section of the
[documentation](https://gitlab.com/etherlab.org/ethercat/-/jobs/artifacts/stable-1.5/raw/pdf/ethercat_doc.pdf?job=pdf).
[documentation](https://gitlab.com/etherlab.org/ethercat/-/jobs/artifacts/stable-1.6/raw/pdf/ethercat_doc.pdf?job=pdf).
---
@@ -57,3 +55,5 @@ examples.
Have fun!
---
vim: set spelllang=en spell tw=78
README.md
+21 -21
View File
@@ -1,15 +1,15 @@
This is the README file of the IgH EtherCAT Master.
Contents:
# The IgH EtherCAT Master
[[_TOC_]]
# General Information
## General Information
This is the README.md file of the IgH EtherCAT Master.
This is an open-source EtherCAT master implementation for Linux 2.6 or newer.
See the [features file](FEATURES.md) for a list of features. For more
information, see https://etherlab.org/ethercat.
information, see [etherlab.org/ethercat](https://etherlab.org/ethercat).
or contact
@@ -18,12 +18,12 @@ Dipl.-Ing. (FH) Florian Pose <fp@igh.de>
Ingenieurgemeinschaft IgH
Nordsternstraße 66
D-45329 Essen
http://igh.de
[igh.de](http://igh.de)
>>>
# Documentation
## Documentation
## Handbook
### Handbook
The PDF documentation is generated via LaTeX and can be build with the
following steps:
@@ -36,7 +36,7 @@ make
The PDF is automatically held up-to-date and can be [downloaded from
GitLab](https://gitlab.com/etherlab.org/ethercat/-/jobs/artifacts/stable-1.5/raw/pdf/ethercat_doc.pdf?job=pdf).
## Doxygen
### Doxygen
To generate the Doxygen documentation, the following commands can be used.
Therefore, the configure script must have run (see the [install
@@ -50,30 +50,30 @@ make doc
An up-to-date Doxygen output can be found on
[docs.etherlab.org](https://docs.etherlab.org/ethercat/1.6/doxygen/index.html).
# Requirements
## Requirements
## Software requirements
### Software requirements
Configured sources for the Linux 2.6 (or newer) kernel are required to build
the EtherCAT master.
## Hardware requirements
### Hardware requirements
A table of supported hardware can be found at:
https://docs.etherlab.org/ethercat/1.6/doxygen/devicedrivers.html
A table of supported hardware can be found at
[docs.etherlab.org](https://docs.etherlab.org/ethercat/1.6/doxygen/devicedrivers.html).
# Building and installing
## Building and installing
See the [install file](INSTALL.md).
# Dry-run and Field Simulation
## Dry-run and Field Simulation
A limited set of the userspace API is available in `libfakeethercat`,
a library which can be used to run an userspace application
without an EtherCAT master or with emulated EtherCAT slaves.
Please find some details [here](fake_lib/README.md).
Please find some details in the [Fakelib README](fake_lib/README.md).
# Realtime and 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
@@ -83,7 +83,7 @@ idle mode and EoE).
To avoid frame timeouts, deactivating DMA access for hard drives is
recommended (`hdparm -d0 <DEV>`).
# License
## License
Copyright (C) 2006-2023 Florian Pose, Ingenieurgemeinschaft IgH
@@ -102,11 +102,11 @@ You should have received a copy of the GNU General Public License along with
the IgH EtherCAT Master; if not, write to the Free Software Foundation, Inc.,
51 Franklin St, Fifth Floor, Boston, MA 02110-1301 USA
# I have a question / I want to contribute
## I have a question / I want to contribute
Please see the [contributiong document](CONTRIBUTING.md).
# Coding Style
## Coding Style
Developers shall use the coding style rules in the [coding style
file](CodingStyle.md).
devices/device_drivers_template.md
+5 -2
View File
@@ -1,18 +1,21 @@
Device Drivers {#devicedrivers}
==============
This table contains a list of all available native drivers,
depending on the kernel version.
This table contains a list of all available native drivers, depending on the
kernel version.
The `generic` and the `ccat` driver are independent of the kernel version.
To find out which native driver is required for your network card,
you can use `lspci -vv` or look in `/sys`:
```sh
admin@ipc:~> ls -l /sys/class/net/eth5/device/driver
lrwxrwxrwx 1 root root 0 6. Nov 15:35 /sys/class/net/eth5/device/driver -> ../../../../bus/pci/drivers/e1000
```
or
```sh
admin@ipc:~> basename $(readlink /sys/class/net/eth5/device/driver)
e1000
fake_lib/README.md
+13 -13
View File
@@ -1,5 +1,4 @@
FakeEtherCAT Library {#libfakeethercat}
====================
# FakeEtherCAT Library {#libfakeethercat}
Libfakeethercat is a userspace library which has the same API as the EtherCAT
master interface library libethercat. Libfakeethercat can be used to spin up
@@ -14,11 +13,11 @@ references), most function calls will just do nothing and return no error.
However, some methods have a bit of logic implemented to simulate a working
master. This is what is possible:
- Creating master and domain instances
- Activating master, `send()` and `receive()`.
- Processing and queuing domains
- Configuring PDOs
- Configuring SDOs using `ecrt_slave_config_sdo*()`
- Creating master and domain instances
- Activating master, `send()` and `receive()`.
- Processing and queuing domains
- Configuring PDOs
- Configuring SDOs using `ecrt_slave_config_sdo*()`
The SDO config does not do anything, but when activating the master the SDO
config will be dumped into a JSON file.
@@ -29,8 +28,8 @@ bus works without errors. So currently, a bus error cannot be simulated.
## How to build
[RtIPC](https://gitlab.com/etherlab.org/rtipc) is needed. Simply pass
`--enable-fakeuserlib` to your `./configure` call and the library will be
built for you.
`--enable-fakeuserlib` to your `./configure` call and the library will be built
for you.
## How to set up dry run mode
@@ -67,6 +66,7 @@ export FAKE_EC_HOMEDIR=/tmp/FakeEtherCAT
rm -rf $FAKE_EC_HOMEDIR
mkdir -p $FAKE_EC_HOMEDIR
```
For each master instance, one subdirectory named by the master id is created.
### Spin up your application
@@ -123,7 +123,7 @@ simulator.
## Environment variables
- FAKE_EC_HOMEDIR: Directory for RtIPC bulletin board and SDO json files
- FAKE_EC_NAME: Will be used for naming RtIPC config and SDO json file
- FAKE_EC_PREFIX: Prefix for RtIPC variables, useful to run multiple
simulators side by side.
- `FAKE_EC_HOMEDIR`: Directory for RtIPC bulletin board and SDO json files
- `FAKE_EC_NAME`: Will be used for naming RtIPC config and SDO json file
- `FAKE_EC_PREFIX`: Prefix for RtIPC variables, useful to run multiple simulators
side by side.
master/api_usage_notes.md
+6 -7
View File
@@ -1,5 +1,4 @@
Notes regaring API Usage {#apiusage}
========================
# Notes regaring API Usage {#apiusage}
There are some restrictions on the
[Application Interface](@ref ApplicationInterface) with respect to the state of
@@ -10,12 +9,12 @@ following.
All configuration (`ecrt_slave_config_*()`) has to be done in Linux process
context. They can be blocking, so take care when holding locks. After
ecrt_master_activate() ing the master, your application must not alter the
slave configuration. Instead, update process data using ecrt_domain_queue()
and ecrt_domain_process() or use the asynchronous interface like
`ecrt_master_activate()` ing the master, your application must not alter the
slave configuration. Instead, update process data using ecrt_domain_queue() and
ecrt_domain_process() or use the asynchronous interface like
ecrt_sdo_request_read(). Don't forget to ecrt_master_receive() and
ecrt_master_send(). These functions can be called from non-process context
too, like Xenomai/RTAI applications or custom kernel modules.
ecrt_master_send(). These functions can be called from non-process context too,
like Xenomai/RTAI applications or custom kernel modules.
## Master Phase