qitech-control/docs/devices.md

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