NekoEcat Studio

A modern EtherCAT engineering workstation for Linux + IgH

Commission, debug, and diagnose your EtherCAT bus with confidence.

---

NekoEcat Studio is an EtherCAT commissioning and diagnostics workstation purpose-built for Linux systems using the IgH EtherCAT Master stack. It replaces the workflow of juggling terminals, spreadsheets, and custom scripts with a coherent, evidence-driven desktop application.

Whether you are integrating a new drive, tuning distributed clocks, debugging a startup sequence, or handing off a validated configuration — NekoEcat Studio gives you a single tool for the job.

✨ Features

🔌 Full EtherCAT Protocol Support

Protocol	Status	Details
CoE (CANopen over EtherCAT)	✅	SDO upload/download, dictionary browsing, emergency object monitoring
FoE (File over EtherCAT)	✅	Firmware read/write via daemon
EoE (Ethernet over EtherCAT)	✅	IP configuration, frame statistics
SoE (Servo over EtherCAT)	✅	IDN read/write, parameter validation

🛠️ 24 Purpose-Built Workspaces

Organized into logical groups — no clutter, just the right tool for each task. (34 plugins are compiled and registered; the 24 visible ones each contribute a workspace tab, the rest are hidden helper/preference plugins.)

Group	Workspaces
🏠 Overview	Dashboard with session brief, evidence matrix, next-best-action
🔍 Topology & Slaves	Topology graph, ESI browser, bus statistics, I/O variable table
📖 Dictionary & SDO	Object dictionary, startup SDO sequences, PDO mapping editor
📊 Monitoring	Watch window, signal analyzer, oscilloscope, trace, logic analyzer
⚡ Distributed Clocks	DC sync status, precision tuning, drift optimizer
🔄 Runtime	FreeRun process image, state machine controller
🩺 Diagnostics	Online diagnostics, consistency checks, AL events, alarm panel
🌐 Protocols	EoE tunnel, SoE drive interface, ENI export

🧠 Evidence-Driven Workflow

Every SDO write, state transition, and configuration change is tracked. Before writing to the bus, you can review the evidence trail — what was read, what changed, and whether it matches expectations.

🌍 8 Languages

Switch between English, 简体中文, 日本語, Deutsch, 한국어, 繁體中文, Français, and Español — at runtime, no restart needed.

🧪 Real-Time Client / Shared Memory

A first-class, Qt-free real-time data plane for external programs:

• SHM data plane — ecatd mirrors the Free Run process image into POSIX shared memory (/nekoecat_proc_0) using a lock-free double buffer with a version-counter consistency protocol. No JSON or TCP in the hot path.
• JSON-RPC control plane — start/stop Free Run and query the process-image layout over the daemon's normal TCP endpoint.
• Pure-C library — libnekoecat_client.a (header: client/nekoecat_client.h) provides typed reads/writes with bounds validation and a double-read attach protocol.
• Python example — examples/realtime/nekoecat_client_example.py shows raw mmap/ctypes access plus the C library via ctypes.

See docs/ARCHITECTURE.md for the shared-memory design.

🔌 Dual Backend Architecture

NekoEcat Studio  ←JSON-RPC→  ecatd daemon  ←ecrt/CLI→  IgH EtherCAT Master  ←→  Bus

• Native ecrt API — high-performance SDO, PDO, and slave operations
• CLI fallback — automatic fallback where ecrt is unavailable (ESI XML, SDO dictionary enumeration, state transitions)
• Backend selection — auto, native-only, or CLI-only modes

🚀 Quick Start

Prerequisites

• Linux x86_64 with IgH EtherCAT Master 1.6.x
• Qt6 (Core, Network, Widgets)
• CMake 3.20+

Install

# Debian / Ubuntu
sudo dpkg -i NekoEcatStudio-1.0.0_amd64.deb
sudo apt-get install -f
ecat-studio

# Fedora / RHEL
sudo dnf install ./NekoEcatStudio-1.0.0.x86_64.rpm
ecat-studio

# Portable (any distro)
tar -xzf NekoEcatStudio-1.0.0-linux-x64.tar.gz
./NekoEcatStudio-1.0.0-linux-x64/bin/ecat-studio

Build from source

git clone https://github.com/NekoRain/nekoecat-studio.git
cd nekoecat-studio
cmake -B build -DCMAKE_BUILD_TYPE=Release
cmake --build build -j$(nproc)

# Start the daemon (requires IgH master)
sudo ./build/apps/ecatd/ecatd

# Launch the GUI
./build/apps/ecat-studio/ecat-studio

cmake --install installs ecatd/ecat-studio to bin/, the real-time client library libnekoecat_client.a to lib/, and the client/SHM headers (nekoecat_client.h, shm_layout.h, nekoecat_shm.h) to include/nekoecat.

First Steps

1. Start the daemon — ecatd connects to the IgH EtherCAT Master
2. Launch the GUI — ecat-studio auto-connects via localhost:5877
3. Scan the bus — the Overview workspace will populate with detected slaves
4. Browse the Object Dictionary — read SDO entries with evidence tracking
5. Configure startup SDOs — build reusable configuration sequences
6. Go live — use FreeRun for process image monitoring and Watch for real-time SDO polling

🧪 Tested

• 179 automated tests (100% passing) — the default build runs 143 unit, 11 integration, and 25 performance tests covering the plugins, daemon handlers, and services that actually ship. Reaching additional (previously removed) services/plugins requires cmake -B build -DECAT_EXPERIMENTAL_SERVICES=ON
• Verified on real hardware — SDO read/write, slave scan, state transitions, and PDO mapping confirmed on Beckhoff-compatible digital I/O slave
• Test environment: IgH Master 1.6.9, Linux 7.0.12-zen, RTL8125 NIC

🏗️ Architecture Overview

┌──────────────────────────────────────────────────────────┐
│                    NekoEcat Studio                        │
│  ┌─────────────┐  ┌──────────────┐  ┌─────────────────┐  │
│  │ 34 Plugins   │  │ EventBus     │  │ ServiceContainer │  │
│  │ (24 visible) │  │ Pub/Sub      │  │ Dependency Inj.  │  │
│  └──────┬──────┘  └──────┬───────┘  └────────┬────────┘  │
│         │                │                    │           │
│  ┌──────┴────────────────┴────────────────────┴────────┐  │
│  │              EcatClient (JSON-RPC)                   │  │
│  └─────────────────────┬───────────────────────────────┘  │
└────────────────────────┼──────────────────────────────────┘
                         │ TCP localhost:5877
┌────────────────────────┼──────────────────────────────────┐
│  ┌─────────────────────┴───────────────────────────────┐  │
│  │                   ecatd daemon                       │  │
│  │  ┌──────────────┐  ┌─────────────┐  ┌────────────┐  │  │
│  │  │ CLI Backend   │  │ Native ecrt │  │ FreeRun    │  │  │
│  │  │ (ethercat cmd)│  │ Backend     │  │ Controller │  │  │
│  │  └──────┬───────┘  └──────┬──────┘  └─────┬──────┘  │  │
│  │         └─────────┬───────┘               │         │  │
│  │                   │                 ┌─────┴──────┐  │  │
│  │                   │                 │ SHM Mirror │  │  │
│  │                   │                 │(double-buf)│  │  │
│  └───────────────────┼─────────────────┼───────┬────┼──┘  │
└──────────────────────┼─────────────────┼───────┼────┼─────┘
                       │                 │       │    │
              ┌────────┴────────┐        │  ┌────┴─────┴──────┐
              │ IgH EtherCAT    │        │  │ POSIX SHM       │
              │ Master (ecrt)   │        │  │ /nekoecat_proc_0│
              └────────┬────────┘        │  │ (C client, Py)  │
                       │                 │  └─────────────────┘
              ┌────────┴────────┐        │
              │  EtherCAT Bus   │        │
              │  (real slaves)  │        │
              └─────────────────┘        │
                                         │
                            nekoecat_client (C) / Python example

📚 Documentation

Document	Description
User Manual	Getting started, workspace reference, troubleshooting
Installation Guide	System requirements, multiple install methods
Architecture	System design, IPC protocol, plugin system
Plugin Guide	Creating and integrating custom workspace plugins
Developer Guide	Build system, testing, contribution workflow
Changelog	Release history and version notes

🤝 Contributing

Contributions are welcome! Whether it is a bug report, feature request, or pull request:

1. Check the open issues for existing discussions
2. Read the Developer Guide for build and test setup
3. Submit a PR — the CI pipeline builds and runs the full default test suite automatically

📄 License

NekoEcat Studio is free software licensed under the GNU General Public License v3.0.

---

_{Built with Qt 6 · IgH EtherCAT Master · CMake · ❤️
Copyright © 2026 NekoRain}