Lifetime of SubDeviceRef

[jbbjarnason]

I am trying to make a Driver abstraction where the Driver holds a SubDeviceRef,.
My issue is lifetime guarantees, it is not my strong suit.

The SubDeviceRef struct does not have lifetime arguments but the function returning the SubDeviceRef has two maindevice and group. What I deduce from that info is that I will be unable to store SubDeviceRef in some struct where maindevice and group will also be owned. This is probably better described by code example so here it is:

use arrayvec::ArrayVec;
use async_trait::async_trait;
use atomic_refcell::AtomicRefMut;
use env_logger::Env;
use ethercrab::{
    error::Error,
    std::{ethercat_now, tx_rx_task},
    MainDevice, MainDeviceConfig, PduStorage, SubDevice, SubDeviceGroup, SubDevicePdi,
    SubDeviceRef, Timeouts,
};
use std::{sync::Arc, time::Duration};
use tokio::time::MissedTickBehavior;

/// Maximum number of SubDevices that can be stored. This must be a power of 2 greater than 1.
const MAX_SUBDEVICES: usize = 16;
/// Maximum PDU data payload size - set this to the max PDI size or higher.
const MAX_PDU_DATA: usize = 1100;
/// Maximum number of EtherCAT frames that can be in flight at any one time.
const MAX_FRAMES: usize = 16;
/// Maximum total PDI length.
const PDI_LEN: usize = 64;

static PDU_STORAGE: PduStorage<MAX_FRAMES, MAX_PDU_DATA> = PduStorage::new();

// device_trait.rs

// Driver process data trait, the driver should own the subdevice and use that to obtain the buffer from the network
#[async_trait]
pub trait Driver: Send {
    async fn process_data(&mut self) -> Result<(), Error>;
}

// Static setup trait for drivers, useful for writing sdo for device functioning
#[async_trait]
pub trait DriverSetup {
    async fn setup<'maindevice, 'group>(
        _subdevice: SubDeviceRef<'maindevice, AtomicRefMut<'group, SubDevice>>,
    ) -> Result<(), Error> {
        Ok(())
    }
}

// Device info trait, used to identify the device and create the matching driver
pub trait DeviceInfo {
    const VENDOR_ID: u32;
    const PRODUCT_ID: u32;
    const NAME: &'static str;
}

struct UnimplementedDevice;

#[async_trait]
impl Driver for UnimplementedDevice {
    async fn process_data(&mut self) -> Result<(), Error> {
        Ok(())
    }
}

// ek1100.rs

// Example driver for the Beckhoff EK1100
struct EK1100<'maindevice, 'group> {
    device: SubDeviceRef<'maindevice, SubDevicePdi<'group>>,
    cnt: u128,
}

#[async_trait]
impl<'maindevice, 'group> Driver for EK1100<'maindevice, 'group> {
    async fn process_data(&mut self) -> Result<(), Error> {
        let (i, o) = self.device.io_raw();
        self.cnt += 1;
        if self.cnt % 1000 == 0 {
            log::info!("Inputs: {:?}, Outputs: {:?}", i, o);
        }
        Ok(())
    }
}

impl<'maindevice, 'group> DeviceInfo for EK1100<'maindevice, 'group> {
    const VENDOR_ID: u32 = 0x2;
    const PRODUCT_ID: u32 = 0x44c2c52;
    const NAME: &'static str = "Ek1100";
}

#[async_trait]
impl<'maindevice, 'group> DriverSetup for EK1100<'maindevice, 'group> {
    async fn setup<'maindevice2, 'group2>(
        _subdevice: SubDeviceRef<'maindevice2, AtomicRefMut<'group2, SubDevice>>,
    ) -> Result<(), Error> {
        Ok(())
    }
}

// drivers.rs

pub async fn setup_device<'maindevice, 'group>(
    device: SubDeviceRef<'maindevice, AtomicRefMut<'group, SubDevice>>,
) -> Result<(), Box<dyn std::error::Error>> {
    let id = device.identity();
    match (id.vendor_id, id.product_id) {
        (EK1100::VENDOR_ID, EK1100::PRODUCT_ID) => {
            EK1100::setup(device).await.map_err(|e| e.into())
        }
        _ => Err(format!("Device not found: {:?} {:?}", id.vendor_id, id.product_id).into()),
    }
}

pub fn make_device<'maindevice_group>(
    device: SubDeviceRef<'maindevice_group, SubDevicePdi<'maindevice_group>>,
) -> Box<dyn Driver + 'maindevice_group> {
    let id = device.identity();
    match (id.vendor_id, id.product_id) {
        (EK1100::VENDOR_ID, EK1100::PRODUCT_ID) => Box::new(EK1100 { device, cnt: 0 }),
        _ => Box::new(UnimplementedDevice),
    }
}

// main.rs

struct Group<'a, const N: usize, const PDI_LEN: usize> {
    pub subdevices: SubDeviceGroup<N, PDI_LEN, ethercrab::subdevice_group::Op>,
    pub drivers: ArrayVec<Box<dyn Driver + 'a>, N>,
    _marker: std::marker::PhantomData<&'a ()>, // To tie the lifetime to the struct
}

struct Ethercat<'bus> {
    main_device: Arc<MainDevice<'bus>>,
    group: Group<'bus, MAX_SUBDEVICES, PDI_LEN>,
}

impl<'bus> Ethercat<'bus> {
    fn new(
        main_device: Arc<MainDevice<'bus>>,
        mut group: SubDeviceGroup<MAX_SUBDEVICES, PDI_LEN, ethercrab::subdevice_group::Op>,
    ) -> Self {
        let drivers = group
            .iter(&main_device)
            .map(|subdevice| make_device(subdevice))
            .collect();
        Self {
            main_device,
            group: Group {
                subdevices: group,
                drivers,
                _marker: std::marker::PhantomData,
            },
        }
        // for i in 0..ethercat.group.subdevices.len() {
        //     let subdevice = ethercat
        //         .group
        //         .subdevices
        //         .subdevice(&ethercat.main_device, i)?;
        //     ethercat.group.drivers.push(make_device(subdevice));
        // }
    }
}

#[tokio::main]
async fn main() -> Result<(), Error> {
    env_logger::Builder::from_env(Env::default().default_filter_or("info")).init();

    let interface = std::env::args()
        .nth(1)
        .expect("Provide network interface as first argument.");

    let (tx, rx, pdu_loop) = PDU_STORAGE.try_split().expect("can only split once");

    let maindevice = Arc::new(MainDevice::new(
        pdu_loop,
        Timeouts {
            wait_loop_delay: Duration::from_millis(2),
            mailbox_response: Duration::from_millis(1000),
            ..Default::default()
        },
        MainDeviceConfig::default(),
    ));

    tokio::spawn(tx_rx_task(&interface, tx, rx).expect("spawn TX/RX task"));

    let mut group = maindevice
        .init_single_group::<MAX_SUBDEVICES, PDI_LEN>(ethercat_now)
        .await
        .expect("Init");

    log::info!("Discovered {} SubDevices", group.len());

    for subdevice in group.iter(&maindevice) {
        setup_device(subdevice).await.expect("Setup");
    }

    let mut group = group.into_op(&maindevice).await.expect("PRE-OP -> OP");

    let mut ethercat = Ethercat {
        main_device: maindevice,
        group: Group {
            drivers: ArrayVec::new(),
            subdevices: group,
            _marker: std::marker::PhantomData,
        },
    };

    let mut tick_interval = tokio::time::interval(Duration::from_millis(5));
    tick_interval.set_missed_tick_behavior(MissedTickBehavior::Skip);

    loop {
        // ethercat
        //     .group
        //     .subdevices
        //     .tx_rx(&ethercat.main_device)
        //     .await
        //     .expect("TX/RX");

        // // Increment every output byte for every SubDevice by one
        // for mut subdevice in group.iter(&maindevice) {
        //     let (_i, o) = subdevice.io_raw_mut();

        //     for byte in o.iter_mut() {
        //         *byte = byte.wrapping_add(1);
        //     }
        // }

        tick_interval.tick().await;
    }
}

BTW, my first initiative was to pass &mut SubDeviceRef into process_data trait which would also be nice, but then I wanted to try Ds402 struct which requires owning SubDeviceRef. Maybe it is trivial to construct SubDeviceRef so I could do something like the following:

for i...group.len() {
  driver.process_data(group.subdevice(maindevice, i));
}

and the driver trait would construct Ds402 each time

#[async_trait]
impl Driver for I550 {
   async fn process_data(SubDeviceRef<....> subdevice) {
     let ds402 = Ds402::new(subdevice);
     // ... 
   }
 }

At first sight this does not look cheap, but I am not sure on the internals of SubDeviceRef, therefore, my try of owning SubDeviceRef.

So the question is maybe have you made any driver abstraction around ethercrab or do you have suggestions on how this could be done?

[jbbjarnason]

nvm, made 402 in the following way

use crate::devices::device_trait::Index;
use ethercrab_wire::{EtherCrabWireRead, EtherCrabWireWrite};

#[derive(Default, Debug, EtherCrabWireWrite)]
#[wire(bytes = 2)]
pub struct ControlWord {
    #[wire(bits = 1)]
    switch_on: bool,
    #[wire(bits = 1)]
    enable_voltage: bool,
    #[wire(bits = 1)]
    quick_stop: bool, // FYI, enabled low
    #[wire(bits = 1)]
    enable_op: bool,
    #[wire(bits = 1)]
    op_specific_1: bool,
    #[wire(bits = 1)]
    op_specific_2: bool,
    #[wire(bits = 1)]
    op_specific_3: bool,
    #[wire(bits = 1)]
    reset_fault: bool,
    #[wire(bits = 1)]
    halt: bool,
    #[wire(bits = 1)]
    op_specific_4: bool,
    #[wire(bits = 1)]
    reserved_1: bool,
    #[wire(bits = 1)]
    reserved_2: bool,
    #[wire(bits = 1)]
    reserved_3: bool,
    #[wire(bits = 1)]
    reserved_4: bool,
    #[wire(bits = 1)]
    reserved_5: bool,
    #[wire(bits = 1)]
    reserved_6: bool,
}

impl Index for ControlWord {
    const INDEX: u16 = 0x6040;
    const SUBINDEX: u8 = 0x00;
}

impl ControlWord {
    fn state_shutdown() -> Self {
        Self {
            switch_on: false,
            enable_voltage: true,
            quick_stop: true,
            enable_op: false,
            ..Default::default()
        }
    }
    fn state_switch_on() -> Self {
        Self {
            switch_on: true,
            enable_voltage: true,
            quick_stop: true,
            ..Default::default()
        }
    }
    fn state_enable_operation() -> Self {
        Self {
            switch_on: true,
            enable_voltage: true,
            quick_stop: true,
            enable_op: true,
            ..Default::default()
        }
    }
    fn state_disable_operation() -> Self {
        Self {
            switch_on: true,
            enable_voltage: true,
            quick_stop: true,
            enable_op: false,
            ..Default::default()
        }
    }
    fn disable_voltage() -> Self {
        Self {
            ..Default::default()
        }
    }
    fn quick_stop() -> Self {
        Self {
            enable_voltage: true,
            ..Default::default()
        }
    }
    fn fault_reset() -> Self {
        Self {
            reset_fault: true,
            ..Default::default()
        }
    }
}

#[derive(Debug)]
pub enum State {
    NotReadyToSwitchOn = 1,
    SwitchOnDisabled = 2,
    ReadyToSwitchOn = 3,
    SwitchedOn = 4,
    OperationEnabled = 5,
    QuickStopActive = 6,
    FaultReactionActive = 7,
    Fault = 8,
}

#[derive(Default, Debug, EtherCrabWireRead)]
#[wire(bytes = 2)]
pub struct StatusWord {
    #[wire(bits = 1)]
    state_ready_to_switch_on: bool,
    #[wire(bits = 1)]
    state_switched_on: bool,
    #[wire(bits = 1)]
    state_operation_enabled: bool,
    #[wire(bits = 1)]
    state_fault: bool,
    #[wire(bits = 1)]
    voltage_enabled: bool,
    #[wire(bits = 1)]
    state_quick_stop: bool,
    #[wire(bits = 1)]
    state_switch_on_disabled: bool,
    #[wire(bits = 1)]
    warning: bool,
    #[wire(bits = 1)]
    halt_request_active: bool,
    #[wire(bits = 1)]
    remote: bool,
    #[wire(bits = 1)]
    target_reached: bool,
    #[wire(bits = 1)]
    internal_limit_active: bool,
    #[wire(bits = 1)]
    application_specific_1: bool,
    #[wire(bits = 1)]
    application_specific_2: bool,
    #[wire(bits = 1)]
    application_specific_3: bool,
    #[wire(bits = 1)]
    application_specific_4: bool,
}

impl Index for StatusWord {
    const INDEX: u16 = 0x6041;
    const SUBINDEX: u8 = 0x00;
}

impl StatusWord {
    pub fn parse_state(&self) -> State {
        /*
          Status Word Bit Mapping:
          Bit 0: Ready to switch on.
          Bit 1: Switched on.
          Bit 2: Operation enabled.
          Bit 3: Fault.
          Bit 4: Voltage enabled.
          Bit 5: Quick stop. (FYI, enabled low)
          Bit 6: Switch on disabled.

          Bit 6 | Bit 5 | Bit 4 | Bit 3 | Bit 2 | Bit 1 | Bit 0 | State
          ------------------------------------------------------------
            0   |   x   |   x   |   0   |   0   |   0   |   0   | State 1: Not ready to switch on
            1   |   x   |   x   |   0   |   0   |   0   |   0   | State 2: Switch on disabled
            0   |   1   |   x   |   0   |   0   |   0   |   1   | State 3: Ready to switch on
            0   |   1   |   1   |   0   |   0   |   1   |   1   | State 4: Switched on
            0   |   1   |   1   |   0   |   1   |   1   |   1   | State 5: Operation enabled
            0   |   0   |   1   |   0   |   1   |   1   |   1   | State 6: Quick stop active
            0   |   x   |   x   |   1   |   1   |   1   |   1   | State 7: Fault reaction active
            0   |   x   |   x   |   1   |   0   |   0   |   0   | State 8: Fault
        */
        if self.state_fault {
            if self.state_operation_enabled
                && self.state_switched_on
                && self.state_ready_to_switch_on
            {
                return State::FaultReactionActive;
            }
            return State::Fault;
        }
        if !self.state_ready_to_switch_on
            && !self.state_switched_on
            && !self.state_operation_enabled
            && !self.state_switch_on_disabled
        {
            return State::NotReadyToSwitchOn;
        }
        if self.state_switch_on_disabled {
            return State::SwitchOnDisabled;
        }
        if !self.state_quick_stop {
            return State::QuickStopActive;
        }
        if self.state_ready_to_switch_on && self.state_quick_stop && !self.state_switched_on {
            return State::ReadyToSwitchOn;
        }
        if self.state_ready_to_switch_on && self.state_switched_on && self.voltage_enabled {
            if self.state_operation_enabled {
                return State::OperationEnabled;
            }
            return State::SwitchedOn;
        }
        return State::NotReadyToSwitchOn;
    }
}

#[derive(Debug, PartialEq, Eq)]
pub enum TransitionAction {
    None = 0,
    Run,
    Stop,
    // Note. For now this is not directly used but has the same effect as none as run is not set.
    QuickStop,
    FreewheelStop,
    Reset,
}

/**
 * Transition to operational mode
 * @param current_state State parsed from status word determined to be the current status of a drive
 * @param action the action to change to another state in cia402 state machine
 * @param auto_reset_allowed allowance flag to indicate whether it is okay to move from fault state
 * @return the command to transition to operational mode / stick in quick stop mode.
 */
pub fn transition(
    current_state: State,
    action: TransitionAction,
    auto_reset_allowed: bool,
) -> ControlWord {
    match current_state {
        State::SwitchOnDisabled => return ControlWord::state_shutdown(),
        State::SwitchedOn | State::ReadyToSwitchOn => {
            if action == TransitionAction::Run {
                return ControlWord::state_enable_operation(); // This is a shortcut marked as 3B in ethercat manual for atv320
            }
            return ControlWord::state_disable_operation(); // Stay in this state if in ready to switch on else transition to switched on
        }
        State::OperationEnabled => {
            if action == TransitionAction::QuickStop {
                return ControlWord::quick_stop();
            }
            if action == TransitionAction::FreewheelStop {
                return ControlWord::disable_voltage(); // Freewheel stop
            }
            if action != TransitionAction::Run {
                return ControlWord::state_disable_operation();
            }

            return ControlWord::state_enable_operation();
        }
        State::Fault => {
            if action == TransitionAction::Reset || auto_reset_allowed {
                return ControlWord::fault_reset();
            }
            // We are not allowed to reset the fault that has occured.
            return ControlWord::state_shutdown();
        }
        State::QuickStopActive => {
            if action == TransitionAction::QuickStop {
                return ControlWord::quick_stop();
            }
            return ControlWord::disable_voltage();
        }
        State::NotReadyToSwitchOn => {
            return ControlWord::state_shutdown();
        }
        State::FaultReactionActive => {
            return ControlWord::disable_voltage();
        }
    }
    // Can only occur if someone casts an integer for state_e that is not defined in the enum
    return ControlWord::disable_voltage();
}