### Initial Project Setup and Execution

Source: https://github.com/qitechgmbh/control/blob/master/electron/README.md

Provides step-by-step instructions for cloning the repository, installing project dependencies, and starting the Electron application in development mode.

```bash
git clone https://github.com/LuanRoger/electron-shadcn.git
```

```bash
npm install
```

```bash
npm run start
```

--------------------------------

### Manage QiTech Electron Application

Source: https://github.com/qitechgmbh/control/blob/master/docs/nixos/quick-start.md

These commands control the QiTech electron application. The first command manually starts the application, while the second command is used to terminate all running instances of the electron app.

```bash
qitech-control-electron

pkill -f qitech-control-electron
```

--------------------------------

### Build and Apply NixOS Configuration

Source: https://github.com/qitechgmbh/control/blob/master/docs/nixos/quick-start.md

This command builds the NixOS system configuration defined in the current directory's flake and switches the system to use this new configuration. It's essential for applying changes after modifying NixOS files.

```bash
sudo nixos-rebuild switch --flake .#nixos
```

--------------------------------

### Roll Back NixOS Configuration

Source: https://github.com/qitechgmbh/control/blob/master/docs/nixos/quick-start.md

This command allows rolling back the NixOS system to its previous configuration. Alternatively, a specific previous generation can be selected from the boot menu during system startup.

```bash
sudo nixos-rebuild switch --flake .#nixos --rollback
```

--------------------------------

### Manage QiTech Control Service on NixOS

Source: https://github.com/qitechgmbh/control/blob/master/docs/nixos/quick-start.md

These commands are used for managing the `qitech-control-server` service. They allow viewing logs (both static and real-time), checking the service's current status, and restarting the service to apply changes or recover from issues.

```bash
journalctl -u qitech-control-server

journalctl -u qitech-control-server -f

systemctl status qitech-control-server

sudo systemctl restart qitech-control-server
```

--------------------------------

### Add Home Manager Channel to NixOS

Source: https://github.com/qitechgmbh/control/blob/master/docs/nixos/quick-start.md

This snippet adds the Home Manager channel to the Nix package manager and updates the channels. Home Manager is used for managing user-specific configurations on NixOS.

```bash
sudo nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager
sudo nix-channel --update
```

--------------------------------

### Run QiTech Control Frontend Application

Source: https://github.com/qitechgmbh/control/blob/master/README.md

This command navigates into the `electron` directory, installs all necessary Node.js dependencies using npm, and then starts the Electron-based frontend application. It requires Node.js and npm to be installed on the system.

```Shell
cd electron && npm i && npm run start
```

--------------------------------

### Update NixOS System and Flake Inputs

Source: https://github.com/qitechgmbh/control/blob/master/docs/nixos/quick-start.md

These commands facilitate updating a NixOS system. The first command updates all flake inputs, the second specifically updates the `qitech-control` input, and the third rebuilds and applies the system configuration with the latest updates.

```bash
nix flake update

nix flake lock --update-input qitech-control

sudo nixos-rebuild switch --flake .#nixos
```

--------------------------------

### Building and Developing QiTech Control without Nix Flakes

Source: https://github.com/qitechgmbh/control/blob/master/docs/nixos/details.md

Commands for starting a development shell and building server/Electron components using the legacy non-flake interface defined in `nixos/default.nix`.

```bash
nix-shell ./nixos
nix-build ./nixos -A server
nix-build ./nixos -A electron
```

--------------------------------

### Development Setup: Console Logging

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Command for local development, enabling debug-level console logging using the `tracing-fmt` feature. This configuration provides immediate feedback directly in the terminal for debugging purposes.

```bash
RUST_LOG=debug cargo run --features tracing-fmt
```

--------------------------------

### Run QiTech Control Server with Multiple Logging Features

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Illustrates how to combine multiple logging and tracing features using Cargo, enabling flexible configurations. Examples include activating all features for comprehensive debugging or setting up a production environment with both journald and OpenTelemetry.

```bash
cargo run --features "tracing-fmt,tracing-journald,tracing-otel"
```

```bash
cargo run --features "tracing-journald,tracing-otel" --no-default-features
```

--------------------------------

### Manage Jaeger with Docker Compose

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Provides a `docker-compose.yml` configuration for easily deploying and managing a Jaeger instance. Includes all necessary ports and environment variables for OTLP trace collection. Also includes the command to start Jaeger using this compose file.

```yaml
version: '3.8'
services:
  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686"  # Jaeger UI
      - "14268:14268"  # HTTP collector
      - "14250:14250"  # gRPC collector
      - "4317:4317"    # OTLP gRPC
      - "4318:4318"    # OTLP HTTP
    environment:
      - COLLECTOR_OTLP_ENABLED=true
```

```bash
docker-compose up -d jaeger
```

--------------------------------

### Integrate Tracing for Error Handling in Rust

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Provides an example of integrating `tracing`'s `info!` and `error!` macros with `anyhow::Result` for robust error handling. It logs success and failure states of an operation, providing clear visibility into execution outcomes.

```rust
use tracing::{error, warn};
use anyhow::Result;

pub fn operation_with_error_handling() -> Result<()> {
    match risky_operation() {
        Ok(result) => {
            info!("Operation completed successfully result={:?}", result);
            Ok(())
        }
        Err(e) => {
            error!("Operation failed error={}", e);
            Err(e)
        }
    }
}
```

--------------------------------

### Run Rust Application with Console and OpenTelemetry Tracing

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Initial command to run the Rust application with both console output (tracing-fmt) and OpenTelemetry tracing (tracing-otel) features enabled. The `--no-default-features` flag ensures a clean setup by disabling any default features that might conflict or are not needed.

```bash
cargo run --features "tracing-fmt,tracing-otel" --no-default-features
```

--------------------------------

### Production Setup: Journald and OpenTelemetry Tracing

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Configuration for production deployment on NixOS systems, utilizing `journald` for system-level logging and `OpenTelemetry` for distributed tracing. This setup is designed to integrate seamlessly with NixOS system service configurations.

```bash
RUST_LOG=info cargo run --features "tracing-journald,tracing-otel" --no-default-features
```

--------------------------------

### Set Up Jaeger Docker Container for OpenTelemetry Tracing

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Instructions to run a Jaeger all-in-one Docker container, configured to accept OpenTelemetry Protocol (OTLP) gRPC traces on port 4317. This setup is essential for visualizing distributed traces exported by the QiTech control server during development.

```bash
docker run -d --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 \
  -p 14268:14268 \
  -p 4317:4317 \
  -p 4318:4318 \
  jaegertracing/all-in-one:latest
```

```bash
open http://localhost:16686
```

--------------------------------

### Run Jaeger Trace Collector with Docker

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Command to start a Jaeger instance as a Docker container, enabling OTLP endpoints for receiving traces. This sets up Jaeger to collect and visualize distributed traces from applications, making the UI accessible on port 16686.

```bash
docker run -d --name jaeger \
  -e COLLECTOR_OTLP_ENABLED=true \
  -p 16686:16686 \
  -p 14268:14268 \
  -p 14250:14250 \
  -p 4317:4317 \
  -p 4318:4318 \
  jaegertracing/all-in-one:latest
```

--------------------------------

### Apply EL2521 Device Configuration in Rust

Source: https://github.com/qitechgmbh/control/blob/master/docs/coe.md

Demonstrates how to instantiate an `EL2521` device and apply a specific configuration to it. This example shows how to use `Default::default()` to fill in non-specified configuration fields and then write the complete configuration to the device, setting `direct_input_mode` to true.

```rust
let el2521 = EL2521::new();
el2521
    .write()
    .await
    .write_config(
        &subdevice,
        &EL2521Configuration {
            direct_input_mode: true,
            ..Default::default()
        },
    )
    .await?;
```

--------------------------------

### Configure Rust Application Log Levels with RUST_LOG

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Demonstrates how to control the logging verbosity of a Rust application using the `RUST_LOG` environment variable. Examples include setting basic log levels (debug, info, warn, error), applying module-specific filtering, and combining multiple filters for complex logging requirements.

```bash
# Basic log levels
RUST_LOG=debug cargo run
RUST_LOG=info cargo run  # Default
RUST_LOG=warn cargo run
RUST_LOG=error cargo run

# Module-specific filtering
RUST_LOG=server=debug,ethercat=info cargo run

# Complex filtering
RUST_LOG="info,tower_http=debug,axum=debug" cargo run
```

--------------------------------

### Define EL3001 Predefined PDO Assignments in Rust

Source: https://github.com/qitechgmbh/control/blob/master/docs/pdo.md

Defines an `EL3001PredefinedPdoAssignment` enum to manage different predefined PDO configurations (Standard, Compact) for the EL3001 device. It implements the `PdoPreset` trait to provide specific `TxPdo` and `RxPdo` assignments based on the selected preset, simplifying device setup.

```Rust
#[derive(Debug, Clone)]
pub enum EL3001PredefinedPdoAssignment {
    Standard,
    Compact,
}

impl PdoPreset<EL3001TxPdo, EL3001RxPdo> for EL3001PredefinedPdoAssignment {
    fn txpdo_assignment(&self) -> EL3001TxPdo {
        match self {
            EL3001PredefinedPdoAssignment::Standard => EL3001TxPdo {
                ai_standard: Some(AiStandard::default()),
                ai_compact: None,
            },
            EL3001PredefinedPdoAssignment::Compact => EL3001TxPdo {
                ai_standard: None,
                ai_compact: Some(AiCompact::default()),
            },
        }
    }

    fn rxpdo_assignment(&self) -> EL3001RxPdo {
        match self {
            EL3001PredefinedPdoAssignment::Standard => EL3001RxPdo {},
            EL3001PredefinedPdoAssignment::Compact => EL3001RxPdo {},
        }
    }
}
```

--------------------------------

### Define Multi-Channel EtherCAT Device Configuration with Default Trait in Rust

Source: https://github.com/qitechgmbh/control/blob/master/docs/coe.md

This Rust example demonstrates how to structure configuration for multi-channel EtherCAT devices, using separate structs for channel-specific settings (`EL2522ChannelConfiguration`) and a main device configuration (`EL2522Configuration`). It also illustrates the implementation of the `Default` trait for both, ensuring consistent initial values for complex configurations.

```Rust
#[derive(Debug, Clone)]
pub struct EL2522ChannelConfiguration {
    // PTO Settings
    /// # 0x8000:01 (Ch.1) / 0x8010:01 (Ch.2)
    /// If the counter value is set to "0", the C-track goes into the "high" state
    /// Default: false (0x00)
    pub adapt_a_b_on_position_set: bool,

    // ...
}

impl Default for EL2522ChannelConfiguration {
    fn default() -> Self {
        Self {
            adapt_a_b_on_position_set: false,
            // ...
        }
    }
}

#[derive(Debug, Clone)]
pub struct EL2522Configuration {
    // ...
    pub channel1_configuration: EL2522ChannelConfiguration,
    pub channel2_configuration: EL2522ChannelConfiguration,
}

impl Default for EL2522Configuration {
    fn default() -> Self {
        Self {
            // ...
            channel1_configuration: EL2522ChannelConfiguration::default(),
            channel2_configuration: EL2522ChannelConfiguration::default(),
        }
    }
}
```

--------------------------------

### Nest Multiple Actors in a Rust Machine Implementation

Source: https://github.com/qitechgmbh/control/blob/master/docs/actors.md

This example illustrates how to compose multiple actors by nesting them within a parent actor, such as a 'Machine'. The `Machine1` struct holds instances of `DigitalOutputToggler` and its `act` function asynchronously calls the `act` function of each nested sub-actor, demonstrating a common pattern for building complex control logic from simpler, reusable components.

```Rust
struct Machine1 {
    toggler1: DigitalOutputToggler,
    toggler2: DigitalOutputToggler,
    // ...
}

impl Actor for Machine1 {
    fn act(&mut self, now: Instant) -> Pin<Box<dyn Future<Output = ()> + Send + '_>> {
        Box::pin(async move {
            self.toggler1.act(now).await;
            self.toggler2.act(now).await;
        })
    }
}
```

--------------------------------

### Configure QiTech Control Server with `tracing-fmt`

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Demonstrates how to run the QiTech control server with `tracing-fmt` enabled, either by relying on the default behavior or by explicitly selecting the feature. This provides structured, human-readable console output with features like colored output, thread info, and configurable time formats.

```bash
cargo run
```

```bash
cargo run --features tracing-fmt --no-default-features
```

--------------------------------

### Building and Running QiTech Control Packages

Source: https://github.com/qitechgmbh/control/blob/master/docs/nixos/details.md

Commands for building all QiTech Control packages, testing specific component builds, and running the compiled server and Electron applications.

```bash
nix flake check

nix build .#server

nix build .#electron

./result/bin/qitech-control-server

./result/bin/qitech-control-electron
```

--------------------------------

### Building QiTech Control Components with Nix Flakes

Source: https://github.com/qitechgmbh/control/blob/master/docs/nixos/details.md

Commands to build the server and Electron frontend components of QiTech Control using Nix flakes. The default build target is the server component.

```bash
nix build .#server
nix build .#electron
nix build
```

--------------------------------

### Local Development Workflow for QiTech Control

Source: https://github.com/qitechgmbh/control/blob/master/docs/nixos/details.md

Commands to set up a local development environment for QiTech Control, including entering the Nix development shell and running the server and Electron frontend in development mode.

```bash
nix develop
## OR for non-flake users
nix-shell ./nixos

cd server
cargo run

cd electron
npm run dev
```

--------------------------------

### Implement Basic Logging with Tracing in Rust

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Demonstrates fundamental logging levels (trace, debug, info, warn, error) using the `tracing` crate in Rust for simple message output, providing varying verbosity for different debugging and operational needs.

```rust
use tracing::{info, debug, warn, error, trace};

pub fn my_function() {
    trace!("Very detailed debug information");
    debug!("Debug information for developers");
    info!("General information about program execution");
    warn!("Something unexpected happened");
    error!("An error occurred: {}", error_message);
}
```

--------------------------------

### Run QiTech Control Server with Default Logging

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Executes the QiTech control server using its default logging configuration. By default, this enables human-readable console output via the `tracing-fmt` feature, suitable for development and debugging.

```bash
cargo run
```

--------------------------------

### Manually Managing QiTech Electron Application

Source: https://github.com/qitechgmbh/control/blob/master/docs/nixos/details.md

Provides commands to manually launch the QiTech Electron application and to terminate any running instances. This is useful for development, debugging, or when the automatic startup needs to be overridden for specific testing scenarios.

```bash
## Manually start the QiTech electron app
qitech-control-electron

## Kill any running instances (if needed)
pkill -f qitech-control-electron
```

--------------------------------

### Configure QiTech Server Package for Journald in NixOS

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Nix configuration snippet showing how to build the QiTech server package with the `tracing-journald` feature enabled and default features disabled, optimizing it for systemd's logging service within a NixOS environment.

```nix
# In nixos/packages/server.nix
buildFeatures = [ "tracing-journald" ];
buildNoDefaultFeatures = true;
```

--------------------------------

### Set Up Observability Stack with Jaeger using Docker Compose

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

A Docker Compose configuration for deploying a complete observability stack, including Jaeger for tracing and the `control-server` configured to export traces and logs. It demonstrates setting up environment variables for `tracing-otel` and `journald` logging.

```yaml
version: '3.8'
services:
  jaeger:
    image: jaegertracing/all-in-one:latest
    ports:
      - "16686:16686"
      - "14268:14268"
    environment:
      - COLLECTOR_OTLP_ENABLED=true

  control-server:
    build: .
    environment:
      - RUST_LOG=info
      - OTEL_EXPORTER=jaeger
      - OTEL_EXPORTER_JAEGER_ENDPOINT=http://jaeger:14268/api/traces
      - OTEL_SERVICE_NAME=qitech-control-server
    depends_on:
      - jaeger
    # Use journald for system logs
    logging:
      driver: journald
```

--------------------------------

### Setting up Home Manager for NixOS System Configuration

Source: https://github.com/qitechgmbh/control/blob/master/docs/nixos/details.md

Commands to add and update the Home Manager channel, which is necessary for managing the user environment configuration within the NixOS system.

```bash
sudo nix-channel --add https://github.com/nix-community/home-manager/archive/master.tar.gz home-manager

sudo nix-channel --update
```

--------------------------------

### NixOS System Rebuild and Test Operations

Source: https://github.com/qitechgmbh/control/blob/master/docs/nixos/details.md

This section provides essential `nixos-rebuild` commands for applying, testing, and building system configuration changes. It leverages Nix flakes for declarative system management, ensuring reproducible builds and allowing for safe experimentation.

```bash
## Rebuild the system and switch to the new configuration
sudo nixos-rebuild switch --flake .#nixos

## Test a configuration without applying it
sudo nixos-rebuild test --flake .#nixos

## Build but don't activate (creates result symlink)
sudo nixos-rebuild build --flake .#nixos
```

--------------------------------

### Restarting and Verifying QiTech Control Service

Source: https://github.com/qitechgmbh/control/blob/master/docs/nixos/details.md

This snippet shows how to restart the `qitech-control-server` service using `systemctl` and immediately check its status to ensure it has resumed operation correctly. This is useful for applying configuration changes, resolving minor issues, or refreshing the service state.

```bash
## Restart the QiTech server
sudo systemctl restart qitech-control-server

## Check if it's running properly
sudo systemctl status qitech-control-server
```

--------------------------------

### Implement Structured Logging and Spans in Rust

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Illustrates best practices for structured logging with `tracing` in Rust, emphasizing string formatting for journald compatibility over direct key-value pairs in event logs. Also shows how to use `#[instrument]` to add structured fields to spans for better context.

```rust
use tracing::{info, instrument};

// ❌ Don't use key-value pairs in event logs (won't work with journald)
info!(
    user_id = %user.id,
    email = %user.email,
    "Updating user profile"
);

// ✅ Use string formatting instead (works with journald)
info!(
    "Updating user profile user_id={} email={}",
    user.id,
    user.email
);

// ✅ Spans can still use structured fields
#[instrument(fields(user_id = %user.id, operation = "update"))]
pub fn update_user(user: &User) {
    info!(
        "Updating user profile user_id={} email={}",
        user.id,
        user.email
    );
}
```

--------------------------------

### OpenTelemetry Service Configuration and Implementation Details

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Details the hardcoded service configuration for OpenTelemetry tracing, including service name, version, namespace, and the OTLP endpoint. Explains the custom `ChannelSpanExporter` implementation, highlighting its role in isolating the OpenTelemetry async runtime and ensuring reliable span export to Jaeger without runtime conflicts.

```APIDOC
Service Configuration:
  Service Name: "qitech-control-server"
  Service Version: Automatically set from Cargo.toml package version
  Service Namespace: "qitech"
  OTLP Endpoint: "http://localhost:4317" (Jaeger gRPC endpoint)

Implementation Details:
  The OpenTelemetry implementation uses a custom ChannelSpanExporter that:
  1. Receives spans from the tracing layer via an MPSC channel
  2. Spawns a dedicated Tokio thread for OTLP gRPC export
  3. Isolates OpenTelemetry's async runtime from the main smol-based application
  4. Provides reliable span export to Jaeger without runtime conflicts
  This design ensures that the OpenTelemetry tracing system works seamlessly with applications using different async runtimes (smol, tokio, etc.).
```

--------------------------------

### Run QiTech Control Backend Server

Source: https://github.com/qitechgmbh/control/blob/master/README.md

This command navigates into the `server` directory and executes the Rust backend application. It requires a Rust stable toolchain (version 1.86 or higher) and a Beckhoff EK1100 connected to the specified network interface. The server will listen on `localhost:3001`.

```Shell
cd server && cargo run
```

--------------------------------

### Configure QiTech Control Server with `tracing-otel`

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Demonstrates how to enable `tracing-otel` for distributed tracing with OpenTelemetry. This configures the server to export traces to an OTLP endpoint (e.g., Jaeger), allowing for comprehensive observability of service interactions and trace correlation.

```bash
cargo run --features tracing-otel --no-default-features
```

```bash
cargo run --features "tracing-fmt,tracing-otel"
```

--------------------------------

### Configure QiTech Server Systemd Service for Journald in NixOS

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Nix configuration snippet for a systemd service, demonstrating how to set up the QiTech control server to use journald for logging, ensuring proper integration with the NixOS environment's systemd service management.

```nix

```

--------------------------------

### Configure QiTech Control Server with `tracing-journald`

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Shows how to enable `tracing-journald` for integrating the server's logs with systemd's journal. This is the standard logging backend for production Linux systems, offering native systemd integration, structured metadata preservation, and system-level log aggregation.

```bash
cargo run --features tracing-journald --no-default-features
```

```bash
cargo run --features "tracing-journald,tracing-otel"
```

--------------------------------

### Viewing QiTech Service Logs and Status

Source: https://github.com/qitechgmbh/control/blob/master/docs/nixos/details.md

Commands for inspecting the `qitech-control-server` service logs and checking its current operational status. `journalctl` is used for log viewing, while `systemctl` provides service status information, aiding in troubleshooting and monitoring the service's health.

```bash
## View service logs
journalctl -u qitech-control-server

## View logs in real-time
journalctl -u qitech-control-server -f

## Check service status
systemctl status qitech-control-server
```

--------------------------------

### View QiTech Control Server Logs with `journalctl`

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Provides various `journalctl` commands to view and filter logs from the `qitech-control-server` service on NixOS or other systemd-based distributions. Includes options for following logs, filtering by log level, outputting structured JSON data, and specifying time ranges.

```bash
journalctl -u qitech-control-server -f
```

```bash
journalctl -u qitech-control-server -p info
```

```bash
journalctl -u qitech-control-server -o json-pretty
```

```bash
journalctl -u qitech-control-server -f --since "1 hour ago"
```

--------------------------------

### Implement Rust DigitalOutput Constructor with Async Closures

Source: https://github.com/qitechgmbh/control/blob/master/docs/io.md

This snippet provides the `new` constructor for `DigitalOutput`. It takes a device (wrapped in `Arc<RwLock>`) and a port, then constructs the `write` and `state` asynchronous closures. The implementation demonstrates how to capture and move `Arc` references into the closures to ensure safe access to the shared device across asynchronous operations.

```Rust
impl DigitalOutput {
    pub fn new<PORT>(
        device: Arc<RwLock<dyn DigitalOutputDevice<PORT>>>,
        port: PORT,
    ) -> DigitalOutput
    where
        PORT: Clone + Send + Sync + 'static,
    {
        // build async write closure
        let port1 = port.clone();
        let device1 = device.clone();
        let write = Box::new(
            move |value: DigitalOutputOutput| -> Pin<Box<dyn Future<Output = ()> + Send>> {
                let device_clone = device1.clone();
                let port_clone = port1.clone();
                Box::pin(async move {
                    let mut device = device_clone.write().await;
                    device.digital_output_write(port_clone, value);
                })
            },
        );

        // build async get closure
        let port2 = port.clone();
        let device2 = device.clone();
        let state = Box::new(
            move || -> Pin<Box<dyn Future<Output = DigitalOutputState> + Send>> {
                let device2 = device2.clone();
                let port_clone = port2.clone();
                Box::pin(async move {
                    let device = device2.read().await;
                    device.digital_output_state(port_clone)
                })
            },
        );
        DigitalOutput { write, state }
    }
}
```

--------------------------------

### Updating QiTech Control Software on NixOS

Source: https://github.com/qitechgmbh/control/blob/master/docs/nixos/details.md

These commands facilitate updating the QiTech Control application by refreshing its flake input and then rebuilding the NixOS system to incorporate the new software version. This ensures the system runs the latest QiTech release by pulling updates from the defined flake source.

```bash
## Update the QiTech Control flake input
nix flake lock --update-input qitech-control

## Rebuild the system with the updated package
sudo nixos-rebuild switch --flake .#nixos
```

--------------------------------

### Instantiate DigitalOutput and Actor in Rust

Source: https://github.com/qitechgmbh/control/blob/master/docs/io.md

This Rust code demonstrates how to create an instance of `EL2002`, then use it to construct a `DigitalOutput` for a specific port (`DO1`), and finally initialize a `DigitalOutputToggler` actor with this digital output. This sets up the necessary components for controlling a digital output via an actor within the IO abstraction.

```Rust
let el2002 = EL2002::new();
let digital_output = DigitalOutput::new(el2002, EL2002Port::DO1);
let actor = DigitalOutputToggler::new(digital_output);
```

--------------------------------

### Configure qitech-control-server Systemd Service in NixOS

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

This NixOS configuration defines the `qitech-control-server` systemd service. It directs standard output and error to the systemd journal, sets a syslog identifier, and configures environment variables for Rust logging levels and legacy compatibility.

```Nix
systemd.services.qitech-control-server = {
  serviceConfig = {
    StandardOutput = "journal";
    StandardError = "journal";
    SyslogIdentifier = "qitech-control-server";
  };
  
  environment = {
    RUST_LOG = "info,tower_http=debug,axum=debug";
    QITECH_OS = "1";  # Legacy compatibility
  };
};
```

--------------------------------

### Updating Nix Flake Inputs for QiTech Control

Source: https://github.com/qitechgmbh/control/blob/master/docs/nixos/details.md

Commands to update all flake inputs to their latest versions or specifically update the `qitech-control` input, ensuring the system uses the most recent dependencies.

```bash
nix flake update

nix flake lock --update-input qitech-control
```

--------------------------------

### Run Application to Export Traces to Jaeger

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Executes the Rust application with OpenTelemetry tracing enabled, ensuring traces are automatically exported to the running Jaeger instance. This command assumes Jaeger is already set up and listening for OTLP data on the default endpoint.

```bash
cargo run --features "tracing-fmt,tracing-otel"
```

--------------------------------

### NPM Scripts for Electron Project Management

Source: https://github.com/qitechgmbh/control/blob/master/electron/README.md

Defines the available `npm` commands for development, packaging, testing, and maintenance of the Electron application, including their purpose and usage. Note that Playwright tests require the application to be built first.

```APIDOC
npm run <script>\n\nstart: Start the app in development mode\npackage: Package your application into a platform-specific executable bundle and put the result in a folder.\nmake: Generate platform-specific distributables (e.g. .exe, .dmg, etc) of your application for distribution.\npublish: Electron Forge's way of taking the artifacts generated by the `make` command and sending them to a service somewhere for you to distribute or use as updates.\nlint: Run ESLint to lint the code\nformat: Run Prettier to check the code (it doesn't change the code)\nformat:write: Run Prettier to format the code\ntest: Run the default unit-test script (Vitest)\ntest:watch: Run the default unit-test script in watch mode (Vitest)\ntest:unit: Run the Vitest tests\ntest:e2e: Run the Playwright tests\ntest:all: Run all tests (Vitest and Playwright)\n\nNote: The test scripts involving Playwright require the app to be built before running the tests. So, before running these tests, execute `package`, `make`, or `publish`.
```

--------------------------------

### Define EL2024 RxPdo Struct for Digital Outputs in Rust

Source: https://github.com/qitechgmbh/control/blob/master/docs/pdo.md

Defines the `EL2024RxPdo` struct for the EL2024 4-channel digital output device. It uses the `RxPdo` derive macro and includes optional `BoolPdoObject` fields for each channel, representing individual 1-bit digital outputs. A `Default` implementation ensures all channels are initialized.

```Rust
#[derive(Debug, Clone, RxPdo)]
pub struct EL2024RxPdo {
    #[pdo_object_index(0x1600)]
    pub channel1: Option<BoolPdoObject>,
    #[pdo_object_index(0x1601)]
    pub channel2: Option<BoolPdoObject>,
    #[pdo_object_index(0x1602)]
    pub channel3: Option<BoolPdoObject>,
    #[pdo_object_index(0x1603)]
    pub channel4: Option<BoolPdoObject>,
}

impl Default for EL2024RxPdo {
    fn default() -> Self {
        Self {
            channel1: Some(BoolPdoObject::default()),
            channel2: Some(BoolPdoObject::default()),
            channel3: Some(BoolPdoObject::default()),
            channel4: Some(BoolPdoObject::default()),
        }
    }
}
```

--------------------------------

### Electron Project Directory Structure

Source: https://github.com/qitechgmbh/control/blob/master/electron/README.md

Illustrates the standard directory layout for an Electron application built with this template, detailing the purpose of each main directory and its subdirectories.

```plaintext
.\n└── ./src/\n    ├── ./src/assets/\n    │   └── ./src/assets/fonts/\n    ├── ./src/components/\n    │   ├── ./src/components/template\n    │   └── ./src/components/ui/\n    ├── ./src/helpers/\n    │   └── ./src/helpers/ipc/\n    ├── ./src/layout/\n    ├── ./src/lib/\n    ├── ./src/pages/\n    ├── ./src/style/\n    └── ./src/tests/
```

--------------------------------

### NixOS System Rollback to Previous Generation

Source: https://github.com/qitechgmbh/control/blob/master/docs/nixos/details.md

Instructions for reverting the NixOS system to a previous working configuration. This can be done by selecting an older generation from the boot menu or by using the `nixos-rebuild --rollback` command for an immediate revert without requiring a system reboot.

```bash
## Boot into previous generation
## Select previous generation from boot menu
## Or roll back without rebooting
sudo nixos-rebuild switch --flake .#nixos --rollback
```

--------------------------------

### Create Custom Spans for Operation Tracing in Rust

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Demonstrates how to manually create and enter `tracing` spans, including nested child spans, to track complex operations. This allows for adding contextual information like `operation_id` and `stage` to specific execution blocks.

```rust
use tracing::{Span, instrument};

pub fn complex_operation() {
    let span = tracing::info_span!(
        "complex_operation",
        operation_id = 123,
        stage = "initialization"
    );
    let _enter = span.enter();

    info!("Starting complex operation");
    
    // Create child span
    let child_span = tracing::debug_span!("database_query");
    let _child_enter = child_span.enter();
    
    debug!("Executing database query");
}
```

--------------------------------

### Define EL3001 TxPdo and RxPdo Structs in Rust

Source: https://github.com/qitechgmbh/control/blob/master/docs/pdo.md

Defines the `EL3001TxPdo` and `EL3001RxPdo` structs using `TxPdo` and `RxPdo` derive macros for EtherCAT Process Data Objects. These structs represent the input and output process data for the EL3001 device, with optional fields for different PDO configurations, ensuring flexibility in device assignments.

```Rust
#[derive(Debug, Clone, TxPdo)]
pub struct EL3001TxPdo {
    #[pdo_object_index(0x1A00)]
    pub ai_standard: Option<AiStandard>,
    #[pdo_object_index(0x1A01)]
    pub ai_compact: Option<AiCompact>,
}

#[derive(Debug, Clone, RxPdo)]
pub struct EL3001RxPdo {}
```

--------------------------------

### Enable Distributed Tracing with OpenTelemetry and Console Output

Source: https://github.com/qitechgmbh/control/blob/master/docs/logging.md

Runs the application with debug-level console logging and OpenTelemetry tracing enabled. Spans are automatically exported to Jaeger via a custom channel-based exporter, allowing visualization of distributed traces in the Jaeger UI.

```bash
RUST_LOG=debug cargo run --features "tracing-fmt,tracing-otel"
```

--------------------------------

### Implement Predefined PDO Assignments for EL2521 in Rust

Source: https://github.com/qitechgmbh/control/blob/master/docs/pdo.md

This Rust implementation provides a mechanism to define and retrieve predefined PDO assignments for the EL2521 device. The `PdoPreset` trait is implemented for the `EL2521PredefinedPdoAssignment` enum, specifically for the `EnhancedOperatingMode32Bit`. This allows for a structured way to initialize `EL2521TxPdo` and `EL2521RxPdo` with default PDO object instances based on a selected operating mode.

```Rust
#[derive(Debug, Clone)]
pub enum EL2521PredefinedPdoAssignment {
    EnhancedOperatingMode32Bit,
}

impl PdoPreset<EL2521TxPdo, EL2521RxPdo> for EL2521PredefinedPdoAssignment {
    fn txpdo_assignment(&self) -> EL2521TxPdo {
        match self {
            EL2521PredefinedPdoAssignment::EnhancedOperatingMode32Bit => EL2521TxPdo {
                pto_status: Some(PtoStatus::default()),
                enc_status: Some(EncStatus::default()),
            },
        }
    }

    fn rxpdo_assignment(&self) -> EL2521RxPdo {
        match self {
            EL2521PredefinedPdoAssignment::EnhancedOperatingMode32Bit => EL2521RxPdo {
                pto_control: Some(PtoControl::default()),
                pto_target: Some(PtoTarget::default()),
                enc_control: Some(EncControl::default()),
            },
        }
    }
}
```

--------------------------------

### Implement EtherCAT Device Processing Trait in Rust

Source: https://github.com/qitechgmbh/control/blob/master/docs/devices.md

This snippet demonstrates how to implement the `EthercatDeviceProcessing` trait for an EtherCAT device struct (e.g., `EL0000`) in Rust. It shows the optional `input_post_process` and `output_pre_process` methods, which allow custom data transformation after receiving input from the EtherCAT bus and before sending output to it, respectively. These methods are crucial for handling raw PDO data requiring transformation.

```Rust
impl EthercatDeviceProcessing for EL0000 {
    // Optional: Only override when needed
    fn input_post_process(&mut self) -> Result<(), anyhow::Error> {
        // Process data after it's received from EtherCAT but before it's accessed via IO interfaces
        // Example: Transform raw sensor data into engineering units
        Ok(())
    }
    
    // Optional: Only override when needed
    fn output_pre_process(&mut self) -> Result<(), anyhow::Error> {
        // Process data before it's sent to EtherCAT
        // Example: Apply limits or transforms to output values
        Ok(())
    }
}
```

--------------------------------

### Implement EL3001 AiStandard and AiCompact PDO Objects in Rust

Source: https://github.com/qitechgmbh/control/blob/master/docs/pdo.md

Implements the `AiStandard` and `AiCompact` structs, which represent specific PDO objects for the EL3001. These structs use the `PdoObject` derive macro and implement the `TxPdoObject` trait for binary decoding of process data, handling bit-level parsing and value extraction based on the TwinCAT configuration.

```Rust
#[derive(Debug, Clone, Default, PdoObject, PartialEq)]
#[pdo_object(bits = 32)]
pub struct AiStandard {
    pub undervoltage: bool,
    pub overvoltage: bool,
    pub limit1: Limit,
    pub limit2: Limit,
    pub error: bool,
    pub txpdo_state: bool,
    pub txpdo_toggle: bool,
    pub value: u16,
}

impl TxPdoObject for AiStandard {
    fn read(&mut self, bits: &BitSlice<u8, Lsb0>) {
        // only read other values if txpdo_toggle is true
        self.txpdo_toggle = bits[8 + 7];
        if !self.txpdo_toggle {
            return;
        }

        self.undervoltage = bits[0];
        self.overvoltage = bits[1];
        self.limit1 = bits[2..4].load_le::<u8>().into();
        self.limit2 = bits[4..6].load_le::<u8>().into();
        self.error = bits[7];
        self.txpdo_state = bits[8 + 6];
        self.value = bits[16..16 + 16].load_le::<u16>();
    }
}

#[derive(Debug, Clone, Default, PdoObject, PartialEq)]
#[pdo_object(bits = 16)]
pub struct AiCompact {
    pub value: u16,
}

impl TxPdoObject for AiCompact {
    fn read(&mut self, bits: &BitSlice<u8, Lsb0>) {
        self.value = bits[0..16].load_le::<u16>();
    }
}
```

--------------------------------

### Add Device Constructor to device_from_subdevice in Rust

Source: https://github.com/qitechgmbh/control/blob/master/docs/devices.md

This Rust code snippet illustrates how to extend the `device_from_subdevice` function to incorporate new device constructors. It utilizes a `match` statement on a `SubDeviceIdentityTuple` to return a new `Device` instance, typically wrapped in an `Arc<RwLock<dyn Device>>`, enabling the creation of different device types at runtime based on their unique identities.

```Rust
pub fn (
    subdevice_identity_tuple: SubDeviceIdentityTuple,
) -> Result<Arc<RwLock<dyn Device>>, anyhow::Error> {
    match subdevice_identity_tuple {
        EK0000_IDENTITY_A => Ok(Arc::new(RwLock::new(EL0000::new()))),
        // ...
    }
}
```

--------------------------------

### Implement DigitalOutputDevice Trait for EL2002 in Rust

Source: https://github.com/qitechgmbh/control/blob/master/docs/io.md

This Rust implementation block shows how the EL2002 device adheres to the DigitalOutputDevice trait. It defines the `digital_output_write` function to set the state of a specified port and `digital_output_state` to read its current state, handling internal channel access and ensuring all channels are properly initialized.

```Rust
impl DigitalOutputDevice<EL2002Port> for EL2002 {
    fn digital_output_write(&mut self, port: EL2002Port, value: DigitalOutputOutput) {
        let expect_text = "All channels should be Some(_)";
        match port {
            EL2002Port::DO1 => self.rxpdo.channel1.as_mut().expect(&expect_text).value = value.into(),
            EL2002Port::DO2 => self.rxpdo.channel2.as_mut().expect(&expect_text).value = value.into(),
        }
    }

    fn digital_output_state(&self, port: EL2002Port) -> DigitalOutputState {
        let expect_text = "All channels should be Some(_)";
        DigitalOutputState {
            output: DigitalOutputOutput(match port {
                EL2002Port::DO1 => self.rxpdo.channel1.as_ref().expect(&expect_text).value,
                EL2002Port::DO2 => self.rxpdo.channel2.as_ref().expect(&expect_text).value,
            }),
        }
    }
}
```

--------------------------------

### Implement EtherCAT CoE Configuration Write for Multi-Channel Device in Rust

Source: https://github.com/qitechgmbh/control/blob/master/docs/coe.md

This Rust implementation extends the `Configuration` trait for multi-channel EtherCAT devices, demonstrating a pattern for writing channel-specific configurations. It abstracts the SDO write logic by calling a helper function (`write_channel_config`) with base indices, allowing efficient configuration of multiple identical channels.

```Rust
impl Configuration for EL2522Configuration {
    async fn write_config<'a>(
        &self,
        device: &EthercrabSubDevicePreoperational<'a>,
    ) -> Result<(), anyhow::Error> {
        // Write configuration for Channel 1
        self.write_channel_config(device, 0x8000, 0x8020, &self.channel1_configuration)
            .await?;

        // Write configuration for Channel 2
        self.write_channel_config(device, 0x8010, 0x8030, &self.channel2_configuration)
            .await?;

        // ...

        Ok(())
    }
}
```

--------------------------------

### Implement BoolPdoObject for Single-Bit PDOs in Rust

Source: https://github.com/qitechgmbh/control/blob/master/docs/pdo.md

Implements the `BoolPdoObject` struct, a generic 1-bit PDO object used for digital inputs/outputs like those in the EL2024. It uses the `PdoObject` derive macro and implements `TxPdoObject` for reading a single boolean value from a bit slice, providing a reusable component for single-bit process data.

```Rust
#[derive(Debug, Clone, Default, PdoObject)]
#[pdo_object(bits = 1)]
pub struct BoolPdoObject {
    pub value: bool,
}

impl TxPdoObject for BoolPdoObject {
    fn read(&mut self, buffer: &BitSlice<u8, Lsb0>) {
        self.value = buffer[0].into();
    }
}
```

--------------------------------

### Define Rust DigitalOutputDevice Trait for Device Interaction

Source: https://github.com/qitechgmbh/control/blob/master/docs/io.md

This snippet defines the `DigitalOutputDevice` trait. Any device that wishes to interact with the `DigitalOutput` type must implement this trait. It specifies two methods: `digital_output_write` for setting the output value on a given port, and `digital_output_state` for retrieving the current state of the output on a port.

```Rust
pub trait DigitalOutputDevice<PORT>: Send + Sync
where
    PORT: Clone,
{
    fn digital_output_write(&mut self, port: PORT, value: DigitalOutputOutput);
    fn digital_output_state(&self, port: PORT) -> DigitalOutputState;
}
```

--------------------------------

### Implement Rust DigitalOutputState and DigitalOutputOutput Types

Source: https://github.com/qitechgmbh/control/blob/master/docs/io.md

This section defines the data structures used by `DigitalOutput`. `DigitalOutputState` holds the current output value. `DigitalOutputOutput` is a newtype wrapper around `bool` representing the actual output value (true for high, false for low). It also provides `From` trait implementations to allow seamless conversion between `DigitalOutputOutput` and `bool` for convenience.

```Rust
#[derive(Debug, Clone)]
pub struct DigitalOutputState {
    pub output: DigitalOutputOutput,
}

/// Output value
/// true: high
/// false: low
#[derive(Debug, Clone)]
pub struct DigitalOutputOutput(pub bool);

impl From<bool> for DigitalOutputOutput {
    fn from(value: bool) -> Self {
        DigitalOutputOutput(value)
    }
}

impl From<DigitalOutputOutput> for bool {
    fn from(value: DigitalOutputOutput) -> Self {
        value.0
    }
}
```