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.

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.

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.

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.

Developer Documentation

• 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)

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

/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

A complete hardware + software walkthrough

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

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.

• 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

(Installation steps in Section 4)

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

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.

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

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.

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.

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.

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

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

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

./cargo_run_linux.sh

This script:

• Builds the backend

• Grants required system capabilities (raw sockets)

• Starts EtherCAT communication

Ensure the EK1100 is connected.

cd electron
npm run start

This launches the QiTech Control 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

Navigate to:

Machines → TestMachine You will see this interface:

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

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

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.

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

The EL3021 Analog Input example demonstrates how to measure analog current on a Beckhoff EL3021 EtherCAT teminal using the QiTech machine framework.

• Beckhoff EL3021 EtherCAT Terminal (1-channel analog input)
• Beckhoff EK1100 EtherCAT Coupler
• 24 V DC power supply (AC/DC adapter + DC hollow plug)
• Adjustable DC power supply (or any other means of producing 4-20mA DC @ <10V )
• Jumper / bridge wires (0.5–1.5 mm² recommended)
• A Linux PC (Ubuntu/Debian recommended)
• Standard Ethernet cable
• Flat screwdriver

The 24V supply powers the EL2004, while the adjustable power supply generates the analog input signal for the EL3021.

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

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.

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.

Slide the EL3021 onto the right side of the EK1100 until it locks.
The EtherCAT E-Bus and power contacts connect automatically. Then you need to wire the adjustable power supply to the EL3021.

1. Wire ⊕ to Terminal 1
2. Wire ⊖ to Terminal 2

Connect the 24 V adapter to the hollow plug used earlier.

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

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

./cargo_run_linux.sh

This script:

• Builds the backend

• Grants required system capabilities (raw sockets)

• Starts EtherCAT communication

Ensure the EK1100 is connected.

cd electron
npm run start

This launches the QiTech Control dashboard.

Once both backend and frontend are running, the Setup -> EtherCat page should look something like this: Listing the EK1100 and the EL3021.

To assign the two devices to a machine, click "Assign" on both devices. This should open the following pop-up modal:

EK1100

1. Select "AnalogTest V1" under "Maschine"
2. Choose a serial number to uniquely identify the machine (1 in this example)
3. Under "Device Role" select "0 - Bus Coupler"

EL3021

1. Select "AnalogTest V1" under "Maschine"
2. Use the same serial number you chose for the EK1100
3. Under "Device Role" select "1 - EL3021"

The machine is now configured. A new Tab "AnalogTest" should appear in the right sidebar. Clicking that tab should show the machine control interface: Results should show the current measured by the analog input - the current set on the adjustable power supply.

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 EL3021 Documentation