Device Example Basics

Device Example Basics

Read this page before working through any minimal device example.

All device examples share the same software prerequisites, safety requirements, and wiring procedure. Complete the steps here first, then return to the specific example for the hardware-specific wiring and demo.

---

1. Software Setup

Choose one of the two options below depending on your setup. Then use the always-visible Run Control section below to start frontend and backend on non-NixOS systems.

---

🖥️ Option A: Mini PC with Control NixOS (recommended for production)

We use the following mini PCs: https://amzn.to/4gv6CCB *
You will also need a USB drive with at least 4 GB of storage.

Flashing NixOS onto the USB Drive

To create the bootable USB drive, we recommend Balena Etcher. It works on nearly all operating systems and is easier to use than the method shown in the video.

A NixOS image can be downloaded here: https://nightly.link/qitechgmbh/control/workflows/nix/master

1. Download the file from any of the links on that link above.
2. If the downloaded file ends in .zip, extract the ISO file from it.
3. Open Balena Etcher and click "Flash from file", then select the downloaded ISO file.
4. Select the target USB drive.
5. Click "Flash" and wait until the write and verification process is complete.

Booting the ISO

1. Connect the mini PC as usual – a keyboard must be connected.
2. Insert the flashed USB drive and press F7 at startup to open the boot menu.
3. In the boot menu, select the USB drive (General UDisk 5.0) instead of the default drive and confirm with Enter.

Installing the

1. Press the Windows/Super/Cmd key (depending on your keyboard) to reveal the GNOME overview.
2. Use the quick settings on the top right corner to connect to WiFi.
3. Select the right of the 2 QiTech icons.
4. Connect to Wi-Fi to proceed with the next steps.
5. A terminal window will open. Select and confirm the storage drive to start the installation process

This may take some time – perfect opportunity for a coffee break. The hard part is now done!

Restart the MiniPC

After an reboot the NixOS Control System can be opened and the backend service starts by itself.

---

🖥️ Option B: Mini PC with Control NixOS via regular NixOS ISO

We use the following mini PCs: https://amzn.to/4gv6CCB *
You will also need a USB drive with at least 4 GB of storage.

Flashing NixOS onto the USB Drive

To create the bootable USB drive, we recommend Balena Etcher. It works on nearly all operating systems and is easier to use than the method shown in the video.

The NixOS 25.11 image can be downloaded here: https://channels.nixos.org/nixos-25.11/latest-nixos-graphical-x86_64-linux.iso

1. Open Balena Etcher and click "Flash from file", then select the downloaded ISO file.
2. Select the target USB drive.
3. Click "Flash" and wait until the write and verification process is complete.

Installing NixOS

1. Connect the mini PC as usual – a keyboard must be connected.
2. Insert the flashed USB drive and press F7 at startup to open the boot menu.
3. In the boot menu, select the USB drive (General UDisk 5.0) instead of the default drive and confirm with Enter.

4. Run through the NixOS installer, then connect to Wi-Fi to proceed with the next steps.

Configuring NixOS

Installing Git

First, open a terminal and edit the NixOS configuration:

sudo nano /etc/nixos/configuration.nix

Scroll down in the configuration until you see the thunderbird entry. Add git on a new line below it:

# Enable touchpad support (enabled default in most desktop environments)
# services.xserver.libinput.enable = true;

# Define a user account. Don't forget to set a password with 'passwd'.
users.users.admin = {
  isNormalUser = true;
  description = "admin";
  extraGroups = [ "networkmanager" "wheel" ];
  packages = with pkgs; [
    # thunderbird
       git
  ];
};

# Install Firefox.
programs.firefox.enable = true;

Save with Ctrl + X followed by S.

Then apply the new configuration:

sudo nixos-rebuild switch

Cloning the Control Repository

git clone https://github.com/qitechgmbh/control.git

Installing Dependencies

cd control/
./nixos-install.sh

This may take some time – perfect opportunity for a coffee break. The hard part is now done!

Restart the MiniPC

After an reboot the NixOS Control System can be opened and the backend service starts by itself.

---

💻 Option C: Setup on Your Own PC (Linux, macOS, or Windows)

For development or a quick test, the software can be run directly on an existing PC. Complete these prerequisites first:

1. Install Rust

Rust is required for the backend and can most easily be installed via rustup. Run the following command in your terminal and follow the installer's instructions:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

2. Install Node.js and npm

Node.js and npm are required for the Electron frontend. The current LTS version can be downloaded from nodejs.org. Alternatively, install via a package manager:

# macOS (Homebrew)
brew install node

# Debian/Ubuntu
sudo apt install nodejs npm

3. Clone the Repository

Download the control repository and navigate into the newly created folder:

git clone https://github.com/qitechgmbh/control.git
cd control

All subsequent steps are executed within this control folder.

4. Install Frontend Dependencies

From the control folder:

cd electron
npm install

This step downloads all required JavaScript dependencies and may take a moment depending on your internet connection.

---

2. Run Control (Frontend + Backend)

If you use Control NixOS (Option A or B), this section is not needed.
After reboot, the backend service starts automatically and you can open the frontend by clicking on the QiTech logo.

Use this section when running control on your own Linux/macOS/Windows PC.

2.1 Start the Frontend

Still in the electron folder:

npm start

On some systems (especially Linux), sudo is required so that Electron can access network interfaces:

sudo npm start

The Electron window will open. In the next step, start the backend in a separate terminal.

2.2 Start the Backend

In a separate terminal, go to the main control folder:

cd /path/to/control

On Linux, you can use the helper script which automatically grants the required capabilities for EtherCAT (raw sockets):

./cargo_run_linux.sh

Alternatively, or on macOS/Windows, run the backend directly with cargo:

cargo run --features development-build

On some systems, sudo is required:

sudo cargo run --features development-build

Note: The --features development-build flag enables development mode with more relaxed real-time requirements. The first build may take several minutes as Rust compiles all dependencies. Subsequent builds are significantly faster.

---

3. Safety Warning

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

---

4. Safe Wiring Procedure

This applies to both Beckhoff and WAGO spring-clamp terminals:

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.