Devices

We need to implement devices to communicate, configure, and identify them.

Implementation Checklist

Here is a checklist of what we need to implement:

• Device Port
  • derive #[derive(Debug, Clone, Copy)]
• Device Struct struct EL0000
  • derive #[derive(Device)] derives Device trait
  • derive or implement Debug trait
  • field txpdo instance of EL0000TxPdo (only if the device has inputs)
  • field rxpdo instance of EL0000RxPdo (only if the device has outputs)
  • field configuration instance of EL0000Configuration (only if configurable)
  • implement NewDevice trait
  • implement EthercatDeviceProcessing trait
    • optional: override input_post_process() method for custom input data processing
    • optional: override output_pre_process() method for custom output data preparation
• TxPdo / RxPdo Struct struct EL0000TxPdo and/or struct EL0000RxPdo
  • derive #[derive(Debug, Clone)]
  • derive #[derive(TxPdo)] and/or #[derive(RxPdo)]
  • fields
    • tag with #[pdo_object_index(0x1...)] for the PDO object index
    • wrap PDO object in Option
• PDO Objects struct EL0000PdoObject or other PDO object structs
  • derive #[derive(Debug, Clone, Default, PartialEq)]
  • derive #[derive(PdoObject)]
  • tag with #[pdo_object(bits = 16)] for the size of the object
  • implement TxPdoObject and/or RxPdoObject traits
• Predefined PDO Assignment enum EL0000PredefinedPdoAssignment (if supported)
  • derive #[derive(Debug, Clone)]
  • implement PredefinedPdoAssignment<EL0000TxPdo, EL0000RxPdo>
• Configuration struct EL0000Configuration (if supported)
  • derive #[derive(Debug, Clone)]
  • implement Configuration trait
  • field pdo_assignment of type EL0000PredefinedPdoAssignment
  • fields for the configuration parameters
• Device Identification Adresses

These are helpful resources:

• Other implementations of similar devices
• Configuration Values: the official datasheet
• Configuration Implementation: Docs
• PDO Schema: The "Process Data" tab in the TwinCAT Software by Beckhoff
• PDO Implementation: Docs
• Identification: Attach the device and read the identity values with QiTech Control in the "Setup > EtherCAT > Devices" tab

ESI Files are not needed but could be an alternative reference, though not a very readable one.

EthercatDeviceProcessing

The EthercatDeviceProcessing trait provides hooks for custom processing of input and output data that happens between the EtherCAT data exchange and the device's IO layer. Every EtherCAT device must implement this trait, even if it doesn't need custom processing.

This trait provides two optional methods:

• input_post_process(): Called after the device has received input data from the EtherCAT bus, allowing transformation of the raw PDO data before it's exposed through the IO interfaces.
• output_pre_process(): Called before data is sent to the EtherCAT bus, allowing preparation or transformation of data from the IO interfaces before it's written to the PDO objects.

For most devices, the default implementations (which do nothing) are sufficient. You only need to override these methods when the raw PDO data requires transformation before being used by the IO layer or vice versa.

Example implementation:

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(())
    }
}

Identity

We need to extract the possible EtherCAT identity values matching this driver implementation and provide them as constants.

Beckhoff has the official vendor ID of 0x2. The product ID is a u32 which is unique for each device like EL0000-...., EL2003-...., EL3001-...., etc.

Hardware revisions or variants (like EL2521-0024) change the revision ID.

There can be multiple revisions for one product ID which should be supported by the driver so we annotate different revision constants with a suffix like _A, _B, _0024_A, etc.

For each revision, we need a tuple combining all three values. This makes pattern matching easier.

pub const EL0000_VENDOR_ID: u32 = 0x2;
pub const EL0000_PRODUCT_ID: u32 = 0x07d83052;
pub const EL0000_REVISION_A: u32 = 0x00110000;

pub const EL0000_IDENTITY_A: SubDeviceIdentityTuple =
        (EL0000_VENDOR_ID, EL0000_PRODUCT_ID, EL0000_REVISION_A);

Creation

Add the device constructor to the device_from_subdevice function in the server crate. This function is used to create the device at runtime.

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()))),
        // ...
    }
}

Device Implementation Guide

This section describes how to implement EtherCAT devices in the framework used by the QiTech Control project (via ethercat-hal, server, etc.). We include a running example of a simple digital output device (EL2004) and discuss how it fits into the larger architecture.

Architecture & Context

The QiTech Control system is built as:

• ethercat-hal / ethercat-hal-derive: Hardware abstraction, PDO / CoE handling, device traits.
• server: Glue code that reads device identities, instantiates the correct device types, performs CoE configuration, and runs cyclic process data.
• The docs directory documents APIs and device patterns.
  :contentReference[oaicite:0]{index=0}

In this architecture:

1. During initialization, subdevice identity tuples (Vendor ID, Product ID, Revision) are read.
2. The server matches identity tuples to concrete Device types and constructs them (via NewEthercatDevice).
3. The device instance then handles PDO exchange, and optional CoE (configuration) writes.
4. Higher-level application code interacts with devices via traits like DigitalOutputDevice, DigitalInputDevice, etc.

---

Example: Simple Digital Output Device (EL2004)

Below is a minimal example of a digital-output-only EtherCAT device. It shows how to map PDOs, implement traits, and define identity constants.

use super::{EthercatDeviceProcessing, NewEthercatDevice, SubDeviceIdentityTuple};
use crate::helpers::ethercrab_types::EthercrabSubDevicePreoperational;
use crate::io::digital_output::{DigitalOutputDevice, DigitalOutputOutput};
use crate::pdo::{RxPdo, basic::BoolPdoObject};
use ethercat_hal_derive::{EthercatDevice, RxPdo};

/// EL2004 4-channel digital output device — 24 V DC, 0.5 A per channel
#[derive(EthercatDevice)]
pub struct EL2004 {
    /// The Rx PDO where output bits are written by the master
    pub rxpdo: EL2004RxPdo,
    is_used: bool,
}

impl EthercatDeviceProcessing for EL2004 {}

impl std::fmt::Debug for EL2004 {
    fn fmt(&self, f: &mut std::fmt::Formatter<'_>) -> std::fmt::Result {
        write!(f, "EL2004")
    }
}

impl NewEthercatDevice for EL2004 {
    fn new() -> Self {
        Self {
            rxpdo: EL2004RxPdo::default(),
            is_used: false,
        }
    }
}

impl DigitalOutputDevice<EL2004Port> for EL2004 {
    fn set_output(&mut self, port: EL2004Port, value: DigitalOutputOutput) {
        let expect_text = "All channels should be Some(_)";
        match port {
            EL2004Port::DO1 => {
                self.rxpdo.channel1.as_mut().expect(expect_text).value = value.into()
            }
            EL2004Port::DO2 => {
                self.rxpdo.channel2.as_mut().expect(expect_text).value = value.into()
            }
            EL2004Port::DO3 => {
                self.rxpdo.channel3.as_mut().expect(expect_text).value = value.into()
            }
            EL2004Port::DO4 => {
                self.rxpdo.channel4.as_mut().expect(expect_text).value = value.into()
            }
        }
    }

    fn get_output(&self, port: EL2004Port) -> DigitalOutputOutput {
        let expect_text = "All channels should be Some(_)";
        DigitalOutputOutput(match port {
            EL2004Port::DO1 => self.rxpdo.channel1.as_ref().expect(expect_text).value,
            EL2004Port::DO2 => self.rxpdo.channel2.as_ref().expect(expect_text).value,
            EL2004Port::DO3 => self.rxpdo.channel3.as_ref().expect(expect_text).value,
            EL2004Port::DO4 => self.rxpdo.channel4.as_ref().expect(expect_text).value,
        })
    }
}

#[derive(Debug, Clone)]
pub enum EL2004Port {
    DO1,
    DO2,
    DO3,
    DO4,
}

#[derive(Debug, Clone, RxPdo)]
pub struct EL2004RxPdo {
    #[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 EL2004RxPdo {
    fn default() -> Self {
        Self {
            channel1: Some(BoolPdoObject::default()),
            channel2: Some(BoolPdoObject::default()),
            channel3: Some(BoolPdoObject::default()),
            channel4: Some(BoolPdoObject::default()),
        }
    }
}

/// Identity constants for EL2004
pub const EL2004_VENDOR_ID: u32 = 0x2;
pub const EL2004_PRODUCT_ID: u32 = 131346514;
pub const EL2004_REVISION_A: u32 = 1179648;
pub const EL2004_IDENTITY_A: SubDeviceIdentityTuple =
    (EL2004_VENDOR_ID, EL2004_PRODUCT_ID, EL2004_REVISION_A);