Getting Started

TL;DR (Debian based)

1. Install

# Just press enter when prompted
curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
apt install npm nodejs git
git clone https://github.com/qitechgmbh/control.git
cd control/electron
npm install

2. Run Front-end

cd control/electron
npm start

4. Connect hardware

5. Run Back-end

cd control
# Grants permission for hardware (e.g. to use EtherCAT)
./cargo_run_linux.sh

Development Setup

QiTech control requires both the Rust toolchain as well as a working Node.js installation. Due to their low-levelness in nature and strict timing requirements of protocols like EtherCAT, only Linux based operating systems are currently supported.

Dependencies

Rust Toolchain

Either install cargo and rustc with your package manager, or to use rustup run

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

See the rust installation guide for details.

Node.js

Either install npm and node with your package manager, or to use the Node Version Manager run

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.4/install.sh | bash
export NVM_DIR="$([ -z "${XDG_CONFIG_HOME-}" ] && printf %s "${HOME}/.nvm" || printf %s "${XDG_CONFIG_HOME}/nvm")"
[ -s "$NVM_DIR/nvm.sh" ] && \. "$NVM_DIR/nvm.sh" # This loads nvm

See NVM's installation guide for details. See also https://docs.npmjs.com/downloading-and-installing-node-js-and-npm.

QiTech Control

Either clone the QiTech Control with

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

or download the latest release source tree.

Install NPM dependencies with

cd electron
npm install

Running the Control Server

Make sure all hardware you wish to interface with is connected, then run

./cargo_run_linux.sh

This helper script sets up capabilities (e.g. for use of raw sockets) and runs the control server in development mode. The most minimal working hardware setup is to connect Beckhoff's ek1100 terminal via Ethernet.

Mocking Hardware

If you don't have any supported hardware at hand, or simply wish to work on the front-end without hardware, you can also let the control server run with mocked machines instead.

./cargo_run_linux.sh mock-machine

Machines will appear in the front-end, but requests won't interface with hardware.

Release Mode

Run the control server without development mode with

./cargo_run_linux.sh release

WARNING: Release mode expects you to have configured your kernel accordingly. See details below.

Running the Front-end

You can run the front-end without the control server running, however, you will not see any machines. The following command opens the front-end in electron.

cd electron
npm start

Changes to the frond-end applied via Vite.

Recommended Editor Setup

We recommend you to use an Editor with rust-analyzer support like VSCode to speed up development and detect errors before compiling.

Configure the Kernel (e.g. for Release Mode)

To achieve minimal latency when working with low-level protocols, the control server assumes that the Linux kernel has real-time preemption enabled and that certain cores are not being used by any other process. Two threads inside the control server, one for EtherCAT communication and the other for general computations regarding the machines logic, are being allocated to run isolated on the cores with ID 2 and 3 respectively.

Real-time preemption is part of the mainline Linux kernel. The following kernel parameter can be used to enable it:

    preempt=full # Enable Real-Time Preemption.

    pcie_aspm=off # Disable PCIe power management for NICs.
    usbcore.autosuspend=-1 # Disable automatic suspend for USB connectors.

    isolcpus=2,3 # Isolate cpus 2 and 3 from scheduler for better latency, 2 runs EtherCAT protocol and 3 runs control server's loop.
    nohz_full=2,3 # In this mode, the periodic scheduler tick is stopped when only one task is running, reducing kernel interruptions on those CPUs.
    rcu_nocbs=2,3 # Moves RCU (Read-Copy Update) callback processing away from CPUs 2 and 3.

Please refer to your boot-loader's or Linux-distro's documentation to see how these options can be passed to the kernel at boot.

Working on NixOS

If you are using NixOS (or have an nix store installed), simply use the nix develop shell defined in flake.nix. Build control server and front-end via

nix build .#server
nix build .#electron

to nix' internal caching.

You can also install QiTech Control as a configuration.nix via

git checkout dev-on-nixos
git rebase master # or whichever branch you wan't to work on
sudo ./nixos-install.sh

and provide your favorite editor via Home Manager. This also takes care of setting up the kernel correctly. See our NixOS Guide for details.