QiTech Control

QiTech Control is an industrial control panel software for the next generation of QiTech recycling machines built on top of Beckhoff Automation hardware.

Click here to watch a video demo of our software.

Click here to watch a full explainer Video of our Software.

Repo Structure

Frontend

• /electron: Frontend code for the control software built with React and Electron.

Backend

• /server: Glue between Beckhoff and Electron. Implements machine logic.
• /ethercat-hal: Hardware abstraction layer for Beckhoff (and possibly other EtherCat) devices and protocols.
• /ethercat-hal-derive: Macros for ethercat-hal
• /control-core: Core control logic for the server.

Operating System

• /nixos: Custom Linux with realtime kernel & preconfigured for touchscreens.

Other

• /docs: Documentation for the project.

Technology Choices

Backend

To interface with Beckhoff and other EtherCAT devices we need an EtherCAT master stoftware. Possibilities are PySOEM (Python), SOEM (C) and Ethercrab (Rust). For realtime operation only C and Rust are suitable. We chose Rust because of safety and confidence in the written code.

SocketIO was chosen for performant event driven communication from the backend to the server. But we still use REST with axum for the communication thet benefits from the request/response model.

We use Smol for EtherCAT IO in the control loop for it's performance and Tokio for server IO because of it's ecosystem and maturity.

Frontend

We could combine the code of the frontend and backend using Doxius but it lacks good Linux support. We chose Electron with React for it's maturity and ecosystem. For the UI we use Shadcn components and Tailwind for styling. For routing we use TanStack Router.

Dev Setup

Developer Documentation

Backend

• Rust stable 1.86^ toolchain (install via rustup)
• rust-analyzer extension for VSCode
• Set your interface in server/src/ethercat/init.rs like en10
• Connect a Beckhoff EK1100 to your interface
• run cd server && cargo run to start the server (localhost:3001)

Frontend

• nodejs and npm installed
• run cd electron && npm i && npm run start to start the frontend

Machines

Machine Type	Version	Release Date	Description	Change to Previous Version	Vendor ID	Machine ID	Implemented	Docs
Winder	V1	???	Winding Filaments & Similar	-	1 (Qitech Industries GmbH)	1	Reserved	-
Winder	V2	2025	Winding Filaments & Similar	Reengineered Traverse	1 (Qitech Industries GmbH)	2	Yes
Extruder	V1	???	Single Screw Extruder	-	1 (Qitech Industries GmbH)	3	Reserved	-
Extruder	V2	2025	Single Screw Extruder	PT100 Thermometers, Optional Additional Heating Zone 4	1 (Qitech Industries GmbH)	4	Yes
Waterway	V1	2025	Filament Water Cooling	-	1 (Qitech Industries GmbH)	5	In Progress
Laser	V1	???	Diameter Measuring Laser	-	1 (Qitech Industries GmbH)	6	Yes
Mock	-	???	Mock Machine for Testing	-	1 (Qitech Industries GmbH)	7	Yes	-

More Docs docs

/assets

• Architecture & Data Flow

  • Example Winder V2

• Electron

  • Folder Structure
  • Routing with TanStack Router
  • Design with Tailwind & Shadcn
  • ...

• Interfacing with Electron/Server

  • SocketIO
    • Machine Namespace
    • Main Namespace
  • REST
    • Machine Mutations
    • Write Device Identification

• Server

  • Threading
  • Logging
  • Control Loop Setup
    • Control Loop Thread
      • realtime
    • Maindevice
    • Group
    • Extracting Device Identifications
    • Identifying Groups
    • Validating Machines
    • Run Control Loop
  • Control Loop
  • Machine/Device Identification
  • Machines
    • When to create a new Machine?
      • Versioning
      • Code sharing
    • Creating/Validating a Machine
      • Validation
      • Configuration
  • Machine Implementation Guide
    • Link: How to create a Device
    • Link: How to create an Actor
    • Link: How to create a Machine
      • API (SocketIO + REST)
      • Creation/Validation Logic
        • Optional/Mandatory Devices
        • Validate Devices
      • Business Logic
    • Link: How to create Machine Abstraction (Like Traverse/Puller/...)
    • Forward act in winder.

• Control Core

  • Actors
  • SocketIO
    • Namespaces & Caching
    • Joining leaving namespaces
    • NamespaceId
    • Caching
      • Serverside Caching
      • Clientside Caching
  • REST

• Ethercat HAL

  • Devices
  • Configuration (CoE)
  • IO
  • PDO

• Ethercat Basics

• NixOS Operating System

Minimal Example — LED Control on the EL2004

A complete hardware + software walkthrough

---

Table of Contents

1. Introduction
2. Requirements
3. Hardware Setup
4. Software Setup
5. Demo
6. References
7. Acknowledgements

---

1. Introduction

The EL2004 LED Toggle Example is a minimal demonstration showing how to control digital outputs on a Beckhoff EL2004 EtherCAT terminal using the QiTech machine framework.
It represents the simplest possible hardware interaction in the system:
toggling LED outputs using the QiTech Control Dashboard.

---

2. Requirements

Hardware

• Beckhoff EL2004 EtherCAT Terminal (4-channel digital output)
• Beckhoff EK1100 EtherCAT Coupler
• 24 V DC power supply (AC/DC adapter + DC hollow plug)
• Jumper / bridge wires (0.5–1.5 mm² recommended)
• A Linux PC (Ubuntu/Debian recommended)
• Standard Ethernet cable
• Flat screwdriver

Software

(Installation steps in Section 4)

• Rust toolchain
• Node.js + npm
• Git
• QiTech Control repository
• EtherCAT HAL (included inside repo)

---

3. Hardware Setup

3.1 Schematic

---

3.2 EK1100 Wiring

This wiring configuration powers the EL2004 and prepares it for LED control.
It is not the only possible wiring but is the simplest functional setup.

⚠️ Safety Warning

Always disconnect power before wiring.
Working on live EtherCAT terminals can cause serious damage or electrical shock.

---

3.2.1 Safe Wiring Procedure (Beckhoff Recommended)

1. Insert a screwdriver straight into the square release hole.
2. Insert the stripped wire into the round opening.
3. Remove the screwdriver — the spring clamp locks the wire.

---

3.2.2 Wiring Steps (Used in This Example)

We supply power using a DC hollow-plug adapter, like this one:
https://www.amazon.de/dp/B093FTFZ8Q

Perform the following wiring on the EK1100:

1. Red wire (+24 V) → Terminal 2
2. Black wire (0 V) → Terminal 3
3. Jumper wire from Terminal 1 → Terminal 6
4. Jumper wire from Terminal 5 → Terminal 7

After wiring, your module should look like Figure 1.

---

Figure 1 — EK1100 Minimal Wiring

---

3.3 EL2004 Integration

Slide the EL2004 onto the right side of the EK1100 until it locks.
The EtherCAT E-Bus and power contacts connect automatically — no wiring required.

Figure 2 — EL2004 Terminal

---

3.4 Final Assembled Setup

Figure 3 — EK1100 + EL2004 Connected

---

3.5 Power & Ethernet

Power

Connect the 24 V adapter to the hollow plug used earlier. Example AC/DC Adapter (Figure 4):

Ethernet

Use a standard LAN cable to connect your PC → EK1100. The final powered up and connected setup should look like this:

---

4. Software Setup

4.1 Installing on Ubuntu/Debian

Paste this into your terminal:

# Press Enter when prompted
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

sudo apt update
sudo apt install -y npm nodejs git

git clone git@github.com:qitechgmbh/control.git
cd control/electron
npm install

4.2 Running the Backend

./cargo_run_linux.sh

This script:

• Builds the backend

• Grants required system capabilities (raw sockets)

• Starts EtherCAT communication

Ensure the EK1100 is connected.

4.3 Running the Frontend

cd electron
npm run start

This launches the QiTech Control dashboard.

5. Demo

5.1 Assigning Devices in the Dashboard

Once the backend + frontend are running, you should see:

EK1100 Coupler

EL2004 Digital Output Terminal

Steps:

• Click Assign on the EK1100

• Select TestMachine V1

• Enter a serial number (use the same for EK1100 + EL2004)

• Click Write

• Repeat for the EL2004

5.2 Testing LED Control

Navigate to:

Machines → TestMachine You will see this interface:

You can now toggle the four digital outputs of the EL2004.

6. References

This guide incorporates information from official Beckhoff documentation. All diagrams, product names, and figures belong to Beckhoff Automation GmbH & Co. KG and are used here solely for educational purposes.

Referenced Manuals

Beckhoff EK1100 Documentation

Beckhoff EL2004 Documentation

7. Acknowledgements

This tutorial is inspired by the clarity and educational quality of Beckhoff manuals. All wiring illustrations and hardware descriptions in this guide are provided for demonstration purposes only and do not replace official Beckhoff installation guidelines.

Special thanks to the QiTech engineering team for providing the backend architecture, EtherCAT HAL abstraction, and the TestMachine framework that makes this example possible.