Skip to content

Rework README and doc in general #422

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
trns1997 merged 1 commit into from
Jun 22, 2026
Merged

Rework README and doc in general #422

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
10 changes: 8 additions & 2 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -61,7 +61,7 @@ against) -- contributions are welcome. See the

- **KickUI** -- ImGui bus dashboard: topology view, SDO/PDO panels, DS402 motor bench
- **EEPROM editor** -- ImGui structured SII/EEPROM editor
- **eeprom** -- CLI to read/write/dump slave EEPROM
- **eeprom** -- CLI to read/write slave EEPROM
- **scan_topology** -- enumerate slaves and per-port link status
- **check_network_stability** -- monitor packet loss/corruption over time (Linux)
- **od_generator** -- generate CoE Object Dictionary code from ESI files
Expand Down Expand Up @@ -92,9 +92,14 @@ cd build && make -j
Then run a master against an emulated slave -- no hardware, single process:

```bash
./build/examples/master/simulated_bus/simulated_bus -f "Beckhoff EL1xxx.xml" -t EL1008
./build/examples/master/simulated_bus/simulated_bus \
-f examples/slave/nuttx/lan9252/freedom-k64f/freedom-k64f.xml -t Board
```

Point `-f` at any vendor ESI XML and `-t` at the device `<Type>` to emulate a
different slave. Beckhoff publish ESI files for their devices at
<https://download.beckhoff.com/download/configuration-files/io/ethercat/xml-device-description>.

Where to go next:

- Build, install, Python bindings, Windows/PikeOS -- [docs/BUILDING.md](docs/BUILDING.md)
Expand Down Expand Up @@ -142,6 +147,7 @@ Reference boards: NXP Freedom K64F (LAN9252), Arduino Due with EasyCAT shield

- [ETG official documentation](https://www.ethercat.org/en/downloads.html)
- [Beckhoff EtherCAT documentation](https://infosys.beckhoff.com/english.php?content=../content/1033/tc3_io_intro/1257993099.html)
- [Beckhoff ESI (XML device description) files](https://download.beckhoff.com/download/configuration-files/io/ethercat/xml-device-description)
- [ESC datasheets](https://download.beckhoff.com/download/document/io/ethercat-development-products/)
- [EtherCAT Device Protocol Poster](https://www.ethercat.org/download/documents/EtherCAT_Device_Protocol_Poster.pdf)
- [ESC comparison](https://download.beckhoff.com/download/document/io/ethercat-development-products/an_esc_comparison_v2i7.pdf)
Expand Down
2 changes: 1 addition & 1 deletion docs/BUILDING.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -135,7 +135,7 @@ and the `conan/profile_windows_x86_64.txt` profile.
Tested on PikeOS 5.1 for the native personality (p4ext).

Provide a CMake cross-toolchain file that defines the `PIKEOS` variable. Example
process/thread configurations are in `examples/PikeOS/p4ext_config.c`.
process/thread configurations are in `lib/src/OS/PikeOS/p4ext_config.c`.

## Slave firmware

Expand Down
2 changes: 1 addition & 1 deletion docs/HARDWARE.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -53,7 +53,7 @@ sudo ./tools/eeprom -s 0 -c write -f examples/slave/nuttx/lan9252/freedom-k64f/e
C++ master:

```bash
sudo ./build/examples/master/freedom-k64f/freedom_k64f_example -i "?"
sudo ./build/examples/master/freedom-k64f/freedom_k64f_static_map_example -i "?"
```

Python master:
Expand Down
15 changes: 11 additions & 4 deletions docs/SIMULATION.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -68,11 +68,18 @@ and the easiest to debug (single process, single thread).
Canonical example -- `examples/master/simulated_bus`:

```bash
./build/examples/master/simulated_bus/simulated_bus -f "Beckhoff EL1xxx.xml" -t EL1008
./build/examples/master/simulated_bus/simulated_bus \
-f examples/slave/nuttx/lan9252/freedom-k64f/freedom-k64f.xml -t Board
```

It builds the selected device, drives INIT -> PRE_OP -> SAFE_OP -> OPERATIONAL,
and exchanges process data -- all in about 150 lines you can read top to bottom.
`-f` takes any vendor ESI XML and `-t` selects the device by its `<Type>`
(omit `-t` to use the first device in the file). It builds the selected device,
drives INIT -> PRE_OP -> SAFE_OP -> OPERATIONAL, and exchanges process data --
all in a short example you can read top to bottom.

Beckhoff publish ESI files for their devices at
<https://download.beckhoff.com/download/configuration-files/io/ethercat/xml-device-description>;
most vendors ship the matching ESI XML with their hardware.

`test/integration/bench/esi_boot` uses the same loopback to boot an entire ESI
catalog in parallel (a good template for batch/regression use).
Expand All @@ -95,7 +102,7 @@ sudo ./build/examples/master/easycat/easycat_example -i tap:client
To boot from an ESI device instead, point a config's `esi` key at your vendor's
ESI XML (see the schema below).

Chain several slaves by passing multiple configs, or repeat one with `-n N`:
Chain several slaves by passing multiple configs:

```bash
./build/simulation/network_simulator -i tap:server \
Expand Down
13 changes: 7 additions & 6 deletions docs/TOOLS.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -25,7 +25,7 @@ Off by default; build it with:
./scripts/configure.sh build --with=kickui
./scripts/setup_build.sh build
cd build && make -j
./kickui
./tools/kickui/kickui
```

## EEPROM editor (GUI)
Expand All @@ -38,12 +38,12 @@ FMMUs, and PDO mappings. Off by default:
./scripts/configure.sh build --with=eeprom_editor
./scripts/setup_build.sh build
cd build && make -j
./kickcat_eeprom_editor
./tools/eeprom_editor/kickcat_eeprom_editor
```

## eeprom (CLI)

Read, write, or dump EEPROM content from an EtherCAT Slave Controller
Read or write EEPROM content from an EtherCAT Slave Controller
(`tools/eeprom.cc`):

```bash
Expand All @@ -53,7 +53,7 @@ sudo ./tools/eeprom -s 0 -c write -f path/to/eeprom.bin -i <interface>
# Auto-detect the interface
sudo ./tools/eeprom -s 0 -c write -f path/to/eeprom.bin -i "?"

# Read EEPROM from the slave
# Read EEPROM from the slave (serializes the SII image to the output file)
sudo ./tools/eeprom -s 0 -c read -f output.bin -i <interface>
```

Expand All @@ -77,10 +77,11 @@ Generate Object Dictionary code from an ESI file (requires
./tools/od_generator -f your_device.esi
```

Include the generated file in your slave application:
The generated `od_populator.cc` defines `CoE::createOD()` (declared in
`kickcat/CoE/OD.h`). Add it to your slave application's build and call it:

```cpp
#include "od_populator.h"
#include "kickcat/CoE/OD.h"

int main()
{
Expand Down