icsneoc2 0.1002002.0-rc.4

//! Device settings management.
//!
//! [`Settings`] provides read/write access to a device's configuration:
//! CAN/CAN FD baudrates, bus termination, LIN mode, Ethernet PHY
//! parameters, 10BASE-T1S PLCA, and analog I/O.
//!
//! Obtain a `Settings` handle from [`Device::settings`](crate::Device::settings),
//! make changes, then call [`Settings::apply`] to commit them to the device.
//!
//! # Example
//!
//! ```no_run
//! use icsneoc2::{Device, OpenOptions, Netid};
//!
//! let device = Device::open_first(0, OpenOptions::DEFAULT)?;
//! let settings = device.settings();
//! settings.set_baudrate(Netid::Hscan, 500_000)?;
//! settings.apply()?;
//! # Ok::<(), icsneoc2::Error>(())
//! ```

use std::marker::PhantomData;

use crate::device::Device;
use crate::error::Result;
use crate::functions::check;
use crate::sys;

/// A view into the settings of a [`Device`].
///
/// Obtained via [`Device::settings`](crate::Device::settings). Borrows the
/// device for its lifetime so the device cannot be dropped while a
/// `Settings` reference is live.
///
/// Changes made through setter methods are staged locally until
/// [`apply`](Settings::apply) is called.
pub struct Settings<'a> {
    ptr: *mut sys::icsneoc2_device_t,
    _marker: PhantomData<&'a Device>,
}

// SAFETY: `Settings` holds a pointer derived from `Device`, which is
// `Send + Sync`. The lifetime ensures the device stays alive.
unsafe impl Send for Settings<'_> {}
unsafe impl Sync for Settings<'_> {}

impl<'a> Settings<'a> {
    pub(crate) fn new(ptr: *mut sys::icsneoc2_device_t) -> Self {
        Self {
            ptr,
            _marker: PhantomData,
        }
    }

    // -----------------------------------------------------------------------
    // Core settings management
    // -----------------------------------------------------------------------

    /// Applies the current pending settings to the device.
    ///
    /// This writes all staged changes to the device hardware. Must be
    /// called after setter methods for them to take effect.
    pub fn apply(&self) -> Result<()> {
        check(unsafe { sys::icsneoc2_settings_apply(self.ptr) })
    }

    /// Refreshes (re-reads) settings from the device.
    ///
    /// Discards any staged but unapplied changes.
    pub fn refresh(&self) -> Result<()> {
        check(unsafe { sys::icsneoc2_settings_refresh(self.ptr) })
    }

    /// Resets all settings to factory defaults.
    ///
    /// If `save` is `true`, the defaults are permanently saved to device
    /// flash so they persist across power cycles.
    pub fn apply_defaults(&self, save: bool) -> Result<()> {
        check(unsafe { sys::icsneoc2_settings_apply_defaults(self.ptr, save) })
    }

    /// Returns `true` if settings are read-only (device does not support changing them).
    pub fn is_readonly(&self) -> Result<bool> {
        let mut value = false;
        check(unsafe { sys::icsneoc2_settings_readonly_get(self.ptr, &raw mut value) })?;
        Ok(value)
    }

    /// Returns `true` if settings are disabled for this device.
    pub fn is_disabled(&self) -> Result<bool> {
        let mut value = false;
        check(unsafe { sys::icsneoc2_settings_disabled_get(self.ptr, &raw mut value) })?;
        Ok(value)
    }

    // -----------------------------------------------------------------------
    // CAN / CANFD baudrate
    // -----------------------------------------------------------------------

    /// Gets the CAN baudrate for a network (in bits per second).
    pub fn baudrate(&self, netid: sys::Netid) -> Result<i64> {
        let mut value: i64 = 0;
        check(unsafe {
            sys::icsneoc2_settings_baudrate_get(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                &raw mut value,
            )
        })?;
        Ok(value)
    }

    /// Sets the CAN baudrate for a network (in bits per second).
    ///
    /// Call [`apply`](Settings::apply) afterwards for the change to take effect.
    pub fn set_baudrate(&self, netid: sys::Netid, baudrate: i64) -> Result<()> {
        check(unsafe {
            sys::icsneoc2_settings_baudrate_set(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                baudrate,
            )
        })
    }

    /// Gets the CAN FD baudrate for a network (in bits per second).
    pub fn canfd_baudrate(&self, netid: sys::Netid) -> Result<i64> {
        let mut value: i64 = 0;
        check(unsafe {
            sys::icsneoc2_settings_canfd_baudrate_get(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                &raw mut value,
            )
        })?;
        Ok(value)
    }

    /// Sets the CAN FD baudrate for a network (in bits per second).
    ///
    /// Call [`apply`](Settings::apply) afterwards for the change to take effect.
    pub fn set_canfd_baudrate(&self, netid: sys::Netid, baudrate: i64) -> Result<()> {
        check(unsafe {
            sys::icsneoc2_settings_canfd_baudrate_set(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                baudrate,
            )
        })
    }

    // -----------------------------------------------------------------------
    // Termination
    // -----------------------------------------------------------------------

    /// Returns `true` if hardware bus termination is supported on this network.
    pub fn termination_is_supported(&self, netid: sys::Netid) -> Result<bool> {
        let mut value = false;
        check(unsafe {
            sys::icsneoc2_settings_termination_is_supported(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                &raw mut value,
            )
        })?;
        Ok(value)
    }

    /// Returns `true` if termination can be toggled via software on this network.
    pub fn termination_can_enable(&self, netid: sys::Netid) -> Result<bool> {
        let mut value = false;
        check(unsafe {
            sys::icsneoc2_settings_termination_can_enable(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                &raw mut value,
            )
        })?;
        Ok(value)
    }

    /// Returns `true` if termination is currently enabled on this network.
    pub fn termination_is_enabled(&self, netid: sys::Netid) -> Result<bool> {
        let mut value = false;
        check(unsafe {
            sys::icsneoc2_settings_termination_is_enabled(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                &raw mut value,
            )
        })?;
        Ok(value)
    }

    /// Enables or disables termination on a network.
    ///
    /// Call [`apply`](Settings::apply) afterwards for the change to take effect.
    pub fn set_termination(&self, netid: sys::Netid, enable: bool) -> Result<()> {
        check(unsafe {
            sys::icsneoc2_settings_termination_set(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                enable,
            )
        })
    }

    // -----------------------------------------------------------------------
    // Commander resistor (LIN)
    // -----------------------------------------------------------------------

    /// Returns `true` if the LIN commander pull-up resistor is enabled.
    pub fn commander_resistor_enabled(&self, netid: sys::Netid) -> Result<bool> {
        let mut value = false;
        check(unsafe {
            sys::icsneoc2_settings_commander_resistor_enabled(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                &raw mut value,
            )
        })?;
        Ok(value)
    }

    /// Enables or disables the LIN commander pull-up resistor on a network.
    ///
    /// Call [`apply`](Settings::apply) afterwards for the change to take effect.
    pub fn set_commander_resistor(&self, netid: sys::Netid, enable: bool) -> Result<()> {
        check(unsafe {
            sys::icsneoc2_settings_commander_resistor_set(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                enable,
            )
        })
    }

    // -----------------------------------------------------------------------
    // LIN
    // -----------------------------------------------------------------------

    /// Gets the LIN mode (Commander / Responder) for a network.
    pub fn lin_mode(&self, netid: sys::Netid) -> Result<sys::LinMode> {
        let mut raw: sys::icsneoc2_lin_mode_t = 0;
        check(unsafe {
            sys::icsneoc2_settings_lin_mode_get(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                &raw mut raw,
            )
        })?;
        Ok(sys::LinMode::try_from(raw)?)
    }

    /// Sets the LIN mode (Commander / Responder) for a network.
    ///
    /// Call [`apply`](Settings::apply) afterwards for the change to take effect.
    pub fn set_lin_mode(&self, netid: sys::Netid, value: sys::LinMode) -> Result<()> {
        check(unsafe {
            sys::icsneoc2_settings_lin_mode_set(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                sys::icsneoc2_lin_mode_t::from(value),
            )
        })
    }

    /// Gets the LIN commander break/sync response time for a network.
    pub fn lin_commander_response_time(&self, netid: sys::Netid) -> Result<u8> {
        let mut value: u8 = 0;
        check(unsafe {
            sys::icsneoc2_settings_lin_commander_response_time_get(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                &raw mut value,
            )
        })?;
        Ok(value)
    }

    /// Sets the LIN commander break/sync response time for a network.
    ///
    /// Call [`apply`](Settings::apply) afterwards for the change to take effect.
    pub fn set_lin_commander_response_time(&self, netid: sys::Netid, value: u8) -> Result<()> {
        check(unsafe {
            sys::icsneoc2_settings_lin_commander_response_time_set(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                value,
            )
        })
    }

    // -----------------------------------------------------------------------
    // PHY — index-based (switch devices: Epsilon/XL, Jupiter, etc.)
    // -----------------------------------------------------------------------

    /// Gets the PHY enable state for a switch port by zero-based index.
    ///
    /// For switch-based devices (Epsilon/XL, Jupiter, etc.) where ports
    /// are addressed by index rather than network ID.
    pub fn phy_enable(&self, index: u8) -> Result<bool> {
        let mut value = false;
        check(unsafe { sys::icsneoc2_settings_phy_enable_get(self.ptr, index, &raw mut value) })?;
        Ok(value)
    }

    /// Enables or disables a PHY on a switch port by zero-based index.
    ///
    /// Call [`apply`](Settings::apply) afterwards for the change to take effect.
    pub fn set_phy_enable(&self, index: u8, value: bool) -> Result<()> {
        check(unsafe { sys::icsneoc2_settings_phy_enable_set(self.ptr, index, value) })
    }

    /// Gets the PHY role (Master / Slave / Auto) for a switch port.
    pub fn phy_mode(&self, index: u8) -> Result<sys::AeLinkMode> {
        let mut raw: sys::icsneoc2_ae_link_mode_t = 0;
        check(unsafe { sys::icsneoc2_settings_phy_mode_get(self.ptr, index, &raw mut raw) })?;
        Ok(sys::AeLinkMode::try_from(raw)?)
    }

    /// Sets the PHY role (Master / Slave / Auto) for a switch port.
    ///
    /// Call [`apply`](Settings::apply) afterwards for the change to take effect.
    pub fn set_phy_mode(&self, index: u8, value: sys::AeLinkMode) -> Result<()> {
        check(unsafe {
            sys::icsneoc2_settings_phy_mode_set(
                self.ptr,
                index,
                sys::icsneoc2_ae_link_mode_t::from(value),
            )
        })
    }

    /// Gets the PHY link speed / duplex mode for a switch port.
    pub fn phy_speed(&self, index: u8) -> Result<sys::EthPhyLinkMode> {
        let mut raw: sys::icsneoc2_eth_phy_link_mode_t = 0;
        check(unsafe { sys::icsneoc2_settings_phy_speed_get(self.ptr, index, &raw mut raw) })?;
        Ok(sys::EthPhyLinkMode::try_from(raw)?)
    }

    /// Sets the PHY link speed / duplex mode for a switch port.
    ///
    /// Call [`apply`](Settings::apply) afterwards for the change to take effect.
    pub fn set_phy_speed(&self, index: u8, value: sys::EthPhyLinkMode) -> Result<()> {
        check(unsafe {
            sys::icsneoc2_settings_phy_speed_set(
                self.ptr,
                index,
                sys::icsneoc2_eth_phy_link_mode_t::from(value),
            )
        })
    }

    // -----------------------------------------------------------------------
    // PHY — network-based (non-switch devices)
    // -----------------------------------------------------------------------

    /// Gets the PHY role (Master / Slave / Auto) for a network-based (non-switch) device.
    pub fn phy_role_for(&self, netid: sys::Netid) -> Result<sys::AeLinkMode> {
        let mut raw: sys::icsneoc2_ae_link_mode_t = 0;
        check(unsafe {
            sys::icsneoc2_settings_phy_role_for_get(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                &raw mut raw,
            )
        })?;
        Ok(sys::AeLinkMode::try_from(raw)?)
    }

    /// Sets the PHY role (Master / Slave / Auto) for a network-based (non-switch) device.
    ///
    /// Call [`apply`](Settings::apply) afterwards for the change to take effect.
    pub fn set_phy_role_for(&self, netid: sys::Netid, value: sys::AeLinkMode) -> Result<()> {
        check(unsafe {
            sys::icsneoc2_settings_phy_role_for_set(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                sys::icsneoc2_ae_link_mode_t::from(value),
            )
        })
    }

    /// Gets the PHY link speed / duplex mode for a network-based (non-switch) device.
    pub fn phy_link_mode_for(&self, netid: sys::Netid) -> Result<sys::EthPhyLinkMode> {
        let mut raw: sys::icsneoc2_eth_phy_link_mode_t = 0;
        check(unsafe {
            sys::icsneoc2_settings_phy_link_mode_for_get(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                &raw mut raw,
            )
        })?;
        Ok(sys::EthPhyLinkMode::try_from(raw)?)
    }

    /// Sets the PHY link speed / duplex mode for a network-based (non-switch) device.
    ///
    /// Call [`apply`](Settings::apply) afterwards for the change to take effect.
    pub fn set_phy_link_mode_for(
        &self,
        netid: sys::Netid,
        value: sys::EthPhyLinkMode,
    ) -> Result<()> {
        check(unsafe {
            sys::icsneoc2_settings_phy_link_mode_for_set(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                sys::icsneoc2_eth_phy_link_mode_t::from(value),
            )
        })
    }

    /// Gets the PHY enable state for a network-based (non-switch) device.
    pub fn phy_enable_for(&self, netid: sys::Netid) -> Result<bool> {
        let mut value = false;
        check(unsafe {
            sys::icsneoc2_settings_phy_enable_for_get(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                &raw mut value,
            )
        })?;
        Ok(value)
    }

    /// Enables or disables the PHY for a network-based (non-switch) device.
    ///
    /// Call [`apply`](Settings::apply) afterwards for the change to take effect.
    pub fn set_phy_enable_for(&self, netid: sys::Netid, value: bool) -> Result<()> {
        check(unsafe {
            sys::icsneoc2_settings_phy_enable_for_set(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                value,
            )
        })
    }

    /// Returns the supported Ethernet PHY link modes for a network.
    ///
    /// The returned `Vec` is a copy of the library-owned array.
    pub fn supported_phy_link_modes_for(
        &self,
        netid: sys::Netid,
    ) -> Result<Vec<sys::EthPhyLinkMode>> {
        let mut ptr: *mut sys::icsneoc2_eth_phy_link_mode_t = std::ptr::null_mut();
        let mut count: usize = 0;
        check(unsafe {
            sys::icsneoc2_settings_supported_phy_link_modes_for(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                &raw mut ptr,
                &raw mut count,
            )
        })?;
        if ptr.is_null() || count == 0 {
            return Ok(vec![]);
        }
        let modes = unsafe { std::slice::from_raw_parts(ptr, count) }
            .iter()
            .map(|&raw| Ok(sys::EthPhyLinkMode::try_from(raw)?))
            .collect::<Result<Vec<_>>>()?;
        Ok(modes)
    }

    // -----------------------------------------------------------------------
    // 10BASE-T1S (PLCA / multi-drop)
    // -----------------------------------------------------------------------

    /// Returns `true` if PLCA (Physical Layer Collision Avoidance) is enabled
    /// for a 10BASE-T1S multi-drop network.
    pub fn t1s_is_plca_enabled_for(&self, netid: sys::Netid) -> Result<bool> {
        let mut value = false;
        check(unsafe {
            sys::icsneoc2_settings_t1s_is_plca_enabled_for(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                &mut value,
            )
        })?;
        Ok(value)
    }

    /// Enables or disables PLCA for a 10BASE-T1S network.
    ///
    /// Call [`apply`](Settings::apply) afterwards for the change to take effect.
    pub fn set_t1s_plca_enabled_for(&self, netid: sys::Netid, value: bool) -> Result<()> {
        check(unsafe {
            sys::icsneoc2_settings_t1s_plca_enabled_for_set(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                value,
            )
        })
    }

    /// Gets the PLCA local node ID for a 10BASE-T1S network.
    pub fn t1s_local_id(&self, netid: sys::Netid) -> Result<u8> {
        let mut value: u8 = 0;
        check(unsafe {
            sys::icsneoc2_settings_t1s_local_id_get(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                &mut value,
            )
        })?;
        Ok(value)
    }

    /// Sets the PLCA local node ID for a 10BASE-T1S network.
    ///
    /// Call [`apply`](Settings::apply) afterwards for the change to take effect.
    pub fn set_t1s_local_id(&self, netid: sys::Netid, value: u8) -> Result<()> {
        check(unsafe {
            sys::icsneoc2_settings_t1s_local_id_set(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                value,
            )
        })
    }

    /// Gets the maximum PLCA node count for a 10BASE-T1S network.
    pub fn t1s_max_nodes(&self, netid: sys::Netid) -> Result<u8> {
        let mut value: u8 = 0;
        check(unsafe {
            sys::icsneoc2_settings_t1s_max_nodes_get(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                &mut value,
            )
        })?;
        Ok(value)
    }

    /// Sets the maximum PLCA node count for a 10BASE-T1S network.
    ///
    /// Call [`apply`](Settings::apply) afterwards for the change to take effect.
    pub fn set_t1s_max_nodes(&self, netid: sys::Netid, value: u8) -> Result<()> {
        check(unsafe {
            sys::icsneoc2_settings_t1s_max_nodes_set(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                value,
            )
        })
    }

    /// Gets the PLCA transmit opportunity timer for a 10BASE-T1S network.
    pub fn t1s_tx_opp_timer(&self, netid: sys::Netid) -> Result<u8> {
        let mut value: u8 = 0;
        check(unsafe {
            sys::icsneoc2_settings_t1s_tx_opp_timer_get(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                &mut value,
            )
        })?;
        Ok(value)
    }

    /// Sets the PLCA transmit opportunity timer for a 10BASE-T1S network.
    ///
    /// Call [`apply`](Settings::apply) afterwards for the change to take effect.
    pub fn set_t1s_tx_opp_timer(&self, netid: sys::Netid, value: u8) -> Result<()> {
        check(unsafe {
            sys::icsneoc2_settings_t1s_tx_opp_timer_set(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                value,
            )
        })
    }

    /// Gets the PLCA max burst timer for a 10BASE-T1S network.
    pub fn t1s_max_burst_timer(&self, netid: sys::Netid) -> Result<u8> {
        let mut value: u8 = 0;
        check(unsafe {
            sys::icsneoc2_settings_t1s_max_burst_timer_for_get(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                &mut value,
            )
        })?;
        Ok(value)
    }

    /// Sets the PLCA max burst timer for a 10BASE-T1S network.
    ///
    /// Call [`apply`](Settings::apply) afterwards for the change to take effect.
    pub fn set_t1s_max_burst_timer(&self, netid: sys::Netid, value: u8) -> Result<()> {
        check(unsafe {
            sys::icsneoc2_settings_t1s_max_burst_timer_for_set(
                self.ptr,
                sys::icsneoc2_netid_t::from(netid),
                value,
            )
        })
    }

    // -----------------------------------------------------------------------
    // Misc I/O analog output
    // -----------------------------------------------------------------------

    /// Enables or disables a miscellaneous analog output pin.
    ///
    /// Call [`apply`](Settings::apply) afterwards for the change to take effect.
    pub fn set_misc_io_analog_output_enabled(&self, pin: u8, enable: bool) -> Result<()> {
        check(unsafe {
            sys::icsneoc2_settings_misc_io_analog_output_enabled_set(self.ptr, pin, enable as u8)
        })
    }

    /// Sets the voltage level for a miscellaneous analog output pin.
    ///
    /// Call [`apply`](Settings::apply) afterwards for the change to take effect.
    pub fn set_misc_io_analog_output(
        &self,
        pin: u8,
        voltage: sys::MiscIoAnalogVoltage,
    ) -> Result<()> {
        check(unsafe {
            sys::icsneoc2_settings_misc_io_analog_output_set(
                self.ptr,
                pin,
                sys::icsneoc2_misc_io_analog_voltage_t::from(voltage),
            )
        })
    }
}