tmag5273 3.6.10

//! Public types, newtypes, and raw-to-physical conversion helpers for the
//! TMAG5273 Hall-effect sensor driver.

use crate::register::{
    DIAG_STATUS_MASK, DIAG_STATUS_SHIFT, INT_ER_MASK, INT_ER_SHIFT, INTB_RB_MASK, INTB_RB_SHIFT,
    OSC_ER_MASK, OSC_ER_SHIFT, OTP_CRC_ER_MASK, OTP_CRC_ER_SHIFT, POR_MASK, POR_SHIFT,
    RESULT_STATUS_MASK, RESULT_STATUS_SHIFT, SET_COUNT_MASK, SET_COUNT_SHIFT, T_THR_CONFIG_MAX,
    T_THR_CONFIG_MIN, VCC_UV_ER_MASK, VCC_UV_ER_SHIFT, VER_V1, VER_V2, extract,
};

/// I2C read mode for the TMAG5273.
///
/// Controls how the sensor formats I2C read responses. All high-level
/// read methods ([`read_magnetic`](crate::Tmag5273::read_magnetic),
/// [`read_temperature`](crate::Tmag5273::read_temperature),
/// [`read_angle`](crate::Tmag5273::read_angle)) require
/// [`Standard`](Self::Standard) mode.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
pub enum I2cReadMode {
    /// Standard 3-byte read (register address + 2 data bytes). Default.
    Standard = 0x00,
    /// 1-byte read returning 16-bit sensor data + conversion status.
    OneByte16Bit = 0x01,
    /// 1-byte read returning 8-bit MSB data + conversion status.
    OneByte8Bit = 0x02,
}

impl_try_from_u8!(I2cReadMode {
    0x00 => Standard,
    0x01 => OneByte16Bit,
    0x02 => OneByte8Bit,
});

/// Operating mode for the TMAG5273.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
pub enum OperatingMode {
    /// Stand-by mode — triggered by I2C command or INT pin.
    Standby = 0x00,
    /// Sleep mode — low power, I2C active.
    Sleep = 0x01,
    /// Continuous measurement mode.
    ContinuousMeasure = 0x02,
    /// Wake-up and sleep mode — periodic measurement with threshold check.
    WakeUpAndSleep = 0x03,
}

impl_try_from_u8!(OperatingMode {
    0x00 => Standby,
    0x01 => Sleep,
    0x02 => ContinuousMeasure,
    0x03 => WakeUpAndSleep,
});

/// Single physical sensor axis.
///
/// This is a software-only convenience type for logic that needs to refer to
/// exactly one of the TMAG5273's three physical magnetic axes. Unlike
/// [`MagneticChannel`], it cannot represent multi-axis or pseudo-simultaneous
/// measurement modes.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
pub enum Axis {
    /// X axis.
    X = 0,
    /// Y axis.
    Y = 1,
    /// Z axis.
    Z = 2,
}

impl_try_from_u8!(Axis {
    0 => X,
    1 => Y,
    2 => Z,
});

/// Supported magnet pole counts for rotation tracking.
///
/// [`ZeroCrossing`](crate::ZeroCrossing) supports 2 to 4 poles.
/// [`Cordic`](crate::Cordic) requires [`Two`](Self::Two).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
pub enum PoleCount {
    /// Two-pole assembly (one pole pair).
    Two = 2,
    /// Three-pole assembly.
    Three = 3,
    /// Four-pole assembly (two pole pairs).
    Four = 4,
}

impl_try_from_u8!(PoleCount {
    2 => Two,
    3 => Three,
    4 => Four,
});

impl PoleCount {
    /// Returns the pole count as a raw integer.
    #[inline]
    pub const fn count(self) -> u8 {
        self as u8
    }
}

impl From<PoleCount> for u8 {
    #[inline]
    fn from(v: PoleCount) -> Self {
        v.count()
    }
}

/// Magnetic channel selection.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
pub enum MagneticChannel {
    /// All channels off.
    Off = 0x0,
    /// X axis only.
    X = 0x1,
    /// Y axis only.
    Y = 0x2,
    /// X and Y axes.
    XY = 0x3,
    /// Z axis only.
    Z = 0x4,
    /// Z and X axes.
    ZX = 0x5,
    /// Y and Z axes.
    YZ = 0x6,
    /// X, Y, and Z axes.
    XYZ = 0x7,
    /// Pseudo-simultaneous X-Y-X — use with [`AngleEnable::XY`].
    XYX = 0x8,
    /// Pseudo-simultaneous Y-X-Y — use with [`AngleEnable::XY`].
    YXY = 0x9,
    /// Pseudo-simultaneous Y-Z-Y — use with [`AngleEnable::YZ`].
    YZY = 0xA,
    /// Pseudo-simultaneous X-Z-X — use with [`AngleEnable::XZ`].
    XZX = 0xB,
}

impl_try_from_u8!(MagneticChannel {
    0x0 => Off,
    0x1 => X,
    0x2 => Y,
    0x3 => XY,
    0x4 => Z,
    0x5 => ZX,
    0x6 => YZ,
    0x7 => XYZ,
    0x8 => XYX,
    0x9 => YXY,
    0xA => YZY,
    0xB => XZX,
});

impl From<Axis> for MagneticChannel {
    #[inline]
    fn from(axis: Axis) -> Self {
        match axis {
            Axis::X => Self::X,
            Axis::Y => Self::Y,
            Axis::Z => Self::Z,
        }
    }
}

impl MagneticChannel {
    /// Returns the number of distinct physical axes enabled.
    ///
    /// Pseudo-simultaneous modes (XYX, YXY, YZY, XZX) measure 2 distinct
    /// axes even though they perform 3 measurement slots. Use
    /// [`measurement_slots`](Self::measurement_slots) for conversion time
    /// calculations.
    pub(crate) const fn axis_count(self) -> u8 {
        match self {
            Self::Off => 0,
            Self::X | Self::Y | Self::Z => 1,
            Self::XY | Self::ZX | Self::YZ | Self::XYX | Self::YXY | Self::YZY | Self::XZX => 2,
            Self::XYZ => 3,
        }
    }

    /// Returns the number of measurement slots per conversion cycle.
    ///
    /// Pseudo-simultaneous modes perform 3 measurements (e.g., XYX = X, Y, X).
    /// This is the value used by [`ConversionAverage::conversion_time`] since
    /// the sensor's conversion duration depends on measurement slots, not
    /// distinct axes.
    pub(crate) const fn measurement_slots(self) -> u8 {
        match self {
            Self::Off => 0,
            Self::X | Self::Y | Self::Z => 1,
            Self::XY | Self::ZX | Self::YZ => 2,
            Self::XYZ | Self::XYX | Self::YXY | Self::YZY | Self::XZX => 3,
        }
    }

    /// Whether the X axis is enabled.
    pub(crate) const fn has_x(self) -> bool {
        matches!(
            self,
            Self::X | Self::XY | Self::ZX | Self::XYZ | Self::XYX | Self::YXY | Self::XZX
        )
    }

    /// Whether the Y axis is enabled.
    pub(crate) const fn has_y(self) -> bool {
        matches!(
            self,
            Self::Y | Self::XY | Self::YZ | Self::XYZ | Self::XYX | Self::YXY | Self::YZY
        )
    }

    /// Whether the Z axis is enabled.
    pub(crate) const fn has_z(self) -> bool {
        matches!(
            self,
            Self::Z | Self::ZX | Self::YZ | Self::XYZ | Self::YZY | Self::XZX
        )
    }
}

/// Conversion averaging samples (maps to `CONV_AVG` field in
/// `DEVICE_CONFIG_1[4:2]`).
///
/// Values `0b110` and `0b111` are **not defined** in the TI datasheet
/// (SBASAI4, Table 8-3) and are blocked by this enum.
///
/// Reference: TI TMAG5273 datasheet SBASAI4, Table 8-3 (DEVICE_CONFIG_1).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
pub enum ConversionAverage {
    /// 1x (no averaging).
    X1 = 0b000,
    /// 2x averaging.
    X2 = 0b001,
    /// 4x averaging.
    X4 = 0b010,
    /// 8x averaging.
    X8 = 0b011,
    /// 16x averaging.
    X16 = 0b100,
    /// 32x averaging.
    X32 = 0b101,
    // 0b110 and 0b111 are not defined per TI datasheet — not representable.
}

impl_try_from_u8!(ConversionAverage {
    0b000 => X1,
    0b001 => X2,
    0b010 => X4,
    0b011 => X8,
    0b100 => X16,
    0b101 => X32,
});

impl ConversionAverage {
    /// Single-sample, single-channel conversion quantum in micros_isreconds.
    ///
    /// Derived from datasheet §5.11 `t_measure` notes:
    /// - Note (2): "Add **25 µs** for each additional magnetic channel"
    ///   at `CONV_AVG = 000b`.
    /// - Note (3): "add **32×25 µs = 800 µs**" per additional channel
    ///   at `CONV_AVG = 101b`.
    ///
    /// The datasheet reports `t_measure = 50 µs` for one channel at X1
    /// because that includes one overhead slot: `25 × (1×1 + 1) = 50`.
    const T_SAMPLE_US: u32 = 25;

    /// Number of samples collected per channel for this averaging mode.
    ///
    /// Datasheet §6.3.6, Table 6-4: X1 = 1, X2 = 2, … X32 = 32.
    /// The `CONV_AVG` register field encodes the exponent (0–5), so
    /// the sample count is `2^CONV_AVG`.
    #[inline]
    pub const fn samples_per_channel(self) -> u32 {
        1 << (self as u32)
    }

    /// Returns the expected conversion time in micros_isreconds for the given
    /// channel configuration.
    ///
    /// Formula derived from datasheet §5.11 `t_measure` and notes (2)/(3):
    ///
    /// `T_SAMPLE_US × (samples_per_channel × num_channels + 1)`
    ///
    /// where the `+ 1` accounts for the fixed overhead slot.
    ///
    /// Per datasheet §5.11 note (2): "When CONV_AVG = 000b, the
    /// conversion time doesn't change with the T_CH_EN bit setting."
    /// Temperature only adds a measurement slot when averaging is enabled.
    pub const fn conversion_time(
        self,
        channels: MagneticChannel,
        temp_channel_enabled: bool,
    ) -> MicrosIsr {
        // Temperature doesn't add conversion time at CONV_AVG = 000b (X1)
        // per datasheet §5.11 note (2).
        let temp_adds_slot = !matches!(self, Self::X1);
        let temp_channel: u32 = if temp_channel_enabled && temp_adds_slot {
            1
        } else {
            0
        };
        let num_channels = channels.measurement_slots() as u32 + temp_channel;
        let us = Self::T_SAMPLE_US * (self.samples_per_channel() * num_channels + 1);
        MicrosIsr(us)
    }

    /// Returns the next-lower averaging level, or `None` if already at `X1`.
    ///
    /// Chain: `X32 → X16 → X8 → X4 → X2 → X1 → None`.
    ///
    /// Used by auto-commissioning Nyquist validation to find the highest
    /// averaging level whose effective sample rate satisfies the safety ratio.
    #[must_use]
    #[inline]
    pub const fn lower(self) -> Option<Self> {
        match self {
            Self::X32 => Some(Self::X16),
            Self::X16 => Some(Self::X8),
            Self::X8 => Some(Self::X4),
            Self::X4 => Some(Self::X2),
            Self::X2 => Some(Self::X1),
            Self::X1 => None,
        }
    }

    /// Maximum poll count for conversion timeout (2x safety margin over
    /// datasheet max at 400 kHz I2C, ~50 µs per poll).
    pub(crate) const fn max_polls(self) -> u16 {
        match self {
            Self::X1 => 10,
            Self::X2 => 15,
            Self::X4 => 25,
            Self::X8 => 40,
            Self::X16 => 70,
            Self::X32 => 100,
        }
    }
}

/// Sleep duration between measurements in wake-up-and-sleep mode
/// (maps to `SLEEPTIME` field in `SENSOR_CONFIG_1[3:0]`).
///
/// Values `0xD`–`0xF` are **not defined** in the TI datasheet
/// (SBASAI4, Table 8-5) and are blocked by this enum.
///
/// Reference: TI TMAG5273 datasheet SBASAI4, Table 8-5 (SENSOR_CONFIG_1).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
pub enum SleepTime {
    /// 1 ms.
    Ms1 = 0x0,
    /// 5 ms.
    Ms5 = 0x1,
    /// 10 ms.
    Ms10 = 0x2,
    /// 15 ms.
    Ms15 = 0x3,
    /// 20 ms.
    Ms20 = 0x4,
    /// 30 ms.
    Ms30 = 0x5,
    /// 50 ms.
    Ms50 = 0x6,
    /// 100 ms.
    Ms100 = 0x7,
    /// 500 ms.
    Ms500 = 0x8,
    /// 1000 ms.
    Ms1000 = 0x9,
    /// 2000 ms.
    Ms2000 = 0xA,
    /// 5000 ms.
    Ms5000 = 0xB,
    /// 20000 ms.
    Ms20000 = 0xC,
    // 0xD–0xF are not defined per TI datasheet — not representable.
}

impl_try_from_u8!(SleepTime {
    0x0 => Ms1,
    0x1 => Ms5,
    0x2 => Ms10,
    0x3 => Ms15,
    0x4 => Ms20,
    0x5 => Ms30,
    0x6 => Ms50,
    0x7 => Ms100,
    0x8 => Ms500,
    0x9 => Ms1000,
    0xA => Ms2000,
    0xB => Ms5000,
    0xC => Ms20000,
});

impl SleepTime {
    /// Returns the sleep duration in micros_isreconds.
    pub const fn as_micros_isr(self) -> MicrosIsr {
        MicrosIsr(match self {
            Self::Ms1 => 1_000,
            Self::Ms5 => 5_000,
            Self::Ms10 => 10_000,
            Self::Ms15 => 15_000,
            Self::Ms20 => 20_000,
            Self::Ms30 => 30_000,
            Self::Ms50 => 50_000,
            Self::Ms100 => 100_000,
            Self::Ms500 => 500_000,
            Self::Ms1000 => 1_000_000,
            Self::Ms2000 => 2_000_000,
            Self::Ms5000 => 5_000_000,
            Self::Ms20000 => 20_000_000,
        })
    }
}

/// Power mode.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
pub enum PowerNoiseMode {
    /// Low active current mode (default).
    LowActiveCurrent = 0,
    /// Low noise mode.
    LowNoise = 1,
}

impl_try_from_u8!(PowerNoiseMode {
    0 => LowActiveCurrent,
    1 => LowNoise,
});

/// Trigger mode for standby conversions.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
pub enum TriggerMode {
    /// I2C command triggers conversion.
    I2cCommand = 0,
    /// INT pin triggers conversion.
    IntPin = 1,
}

impl_try_from_u8!(TriggerMode {
    0 => I2cCommand,
    1 => IntPin,
});

/// Magnetic temperature compensation coefficient (maps to `MAG_TEMPCO`
/// field in `DEVICE_CONFIG_1[6:5]`).
///
/// **Note:** Discriminant `0b10` is intentionally skipped — it is
/// **reserved** in the TI datasheet (SBASAI4, Table 8-3) and must not
/// be written to the device.  The enum makes this value unrepresentable
/// at compile time.
///
/// Reference: TI TMAG5273 datasheet SBASAI4, Table 8-3 (DEVICE_CONFIG_1).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
pub enum MagneticTempCoefficient {
    /// No temperature compensation (0%).  `MAG_TEMPCO = 00b`.
    None = 0b00,
    /// NdBFe magnets (0.12%/°C).  `MAG_TEMPCO = 01b`.
    NdBFe = 0b01,
    // 0b10 is reserved per TI datasheet — not representable.
    /// Ceramic/Ferrite magnets (0.2%/°C).  `MAG_TEMPCO = 11b`.
    Ceramic = 0b11,
}

impl_try_from_u8!(MagneticTempCoefficient {
    0b00 => None,
    0b01 => NdBFe,
    0b11 => Ceramic,
});

/// Angle calculation axis pair.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
pub enum AngleEnable {
    /// Angle calculation disabled.
    None = 0b00,
    /// X-Y plane angle.
    XY = 0b01,
    /// Y-Z plane angle.
    YZ = 0b10,
    /// X-Z plane angle.
    XZ = 0b11,
}

impl_try_from_u8!(AngleEnable {
    0b00 => None,
    0b01 => XY,
    0b10 => YZ,
    0b11 => XZ,
});

/// Threshold crossing direction.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
pub enum MagneticThresholdDirection {
    /// Interrupt when field exceeds threshold (above).
    Above = 0,
    /// Interrupt when field falls below threshold (below).
    Below = 1,
}

impl_try_from_u8!(MagneticThresholdDirection {
    0 => Above,
    1 => Below,
});

/// Number of threshold crossings before the interrupt is asserted
/// (maps to `THRX_COUNT` field in `SENSOR_CONFIG_2[6]`).
///
/// Use [`Four`](Self::Four) in noisy environments to debounce
/// the threshold comparison — the interrupt only fires after 4
/// consecutive threshold crossings.
///
/// Reference: TI TMAG5273 datasheet SBASAI4, Table 8-6.
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
pub enum ThresholdCrossingCount {
    /// Interrupt after 1 threshold crossing (default).
    #[default]
    One = 0,
    /// Interrupt after 4 threshold crossings (debounce).
    Four = 1,
}

impl_try_from_u8!(ThresholdCrossingCount {
    0 => One,
    1 => Four,
});

/// Temperature threshold register code (7-bit, `T_CONFIG` bits \[7:1\]).
///
/// Valid codes per datasheet §8.1.8:
/// - `0x00` — disabled (no threshold comparison, the default)
/// - `0x1A`–`0x34` — active threshold (≈ −41 °C to ≈ 170 °C, ~8 °C/LSB)
///
/// Construct via [`from_code`](Self::from_code) or use the [`DISABLED`](Self::DISABLED)
/// constant. Invalid codes are rejected at the type level.
///
/// # Examples
///
/// ```
/// use tmag5273::TempThresholdConfig;
///
/// // Disabled (default)
/// let t = TempThresholdConfig::DISABLED;
/// assert!(!t.is_enabled());
///
/// // Valid active threshold
/// let t = TempThresholdConfig::from_code(0x1A).unwrap();
/// assert!(t.is_enabled());
/// assert_eq!(t.code(), 0x1A);
///
/// // Invalid code rejected
/// assert!(TempThresholdConfig::from_code(0x50).is_none());
/// ```
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub struct TempThresholdConfig(u8);

impl TempThresholdConfig {
    /// No threshold comparison (register code `0x00`). This is the default.
    pub const DISABLED: Self = Self(0);

    /// Construct from a raw 7-bit register code.
    ///
    /// Returns `Some` for `0x00` (disabled) or `0x1A..=0x34` (active range).
    /// Returns `None` for any other value.
    #[inline]
    pub const fn from_code(code: u8) -> Option<Self> {
        if code == 0 || (code >= T_THR_CONFIG_MIN && code <= T_THR_CONFIG_MAX) {
            Some(Self(code))
        } else {
            None
        }
    }

    /// The raw 7-bit code written to the register.
    #[inline]
    pub const fn code(self) -> u8 {
        self.0
    }

    /// Returns `true` if this threshold is active (not disabled).
    #[inline]
    pub const fn is_enabled(self) -> bool {
        self.0 != 0
    }
}

impl_try_from_u8!(TempThresholdConfig);

/// Interrupt routing mode (maps to `INT_MODE` field in `INT_CONFIG_1[4:2]`).
///
/// Controls which pin carries the interrupt signal and whether the interrupt
/// is suppressed when the I2C bus is busy with another device.
///
/// **Note:** Latched vs pulsed interrupt behavior is controlled separately
/// by [`InterruptState`], not by this enum.
///
/// Reference: TI TMAG5273 datasheet SBASAI4, Table 8-11.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
pub enum InterruptMode {
    /// No interrupt (`INT_MODE = 000b`).
    None = 0b000,
    /// Interrupt through INT pin (`INT_MODE = 001b`).
    ThroughInt = 0b001,
    /// Interrupt through INT pin, except when I2C bus is busy
    /// (`INT_MODE = 010b`).
    ///
    /// The interrupt is suppressed while the I2C bus is in use by another
    /// device (not this TMAG5273). Use this mode on shared I2C buses to
    /// prevent interrupt assertions from corrupting ongoing transactions
    /// with other devices.
    ThroughIntExceptI2cBusy = 0b010,
    /// Interrupt through SCL pin (`INT_MODE = 011b`).
    ///
    /// TI does not recommend sharing the I2C bus with other devices when
    /// using SCL for interrupts — the SCL interrupt may corrupt transactions
    /// with other secondary devices.
    ThroughScl = 0b011,
    /// Interrupt through SCL pin, except when I2C bus is busy
    /// (`INT_MODE = 100b`).
    ///
    /// The interrupt and result register updates are suppressed unless the
    /// TMAG5273 is being actively addressed by the primary.
    ThroughSclExceptI2cBusy = 0b100,
}

impl_try_from_u8!(InterruptMode {
    0b000 => None,
    0b001 => ThroughInt,
    0b010 => ThroughIntExceptI2cBusy,
    0b011 => ThroughScl,
    0b100 => ThroughSclExceptI2cBusy,
});

/// INT pin assertion behavior.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
pub enum InterruptState {
    /// INT pin stays asserted until host clears it.
    Latched = 0,
    /// INT pin pulses for 10 µs then deasserts.
    Pulse10us = 1,
}

impl_try_from_u8!(InterruptState {
    0 => Latched,
    1 => Pulse10us,
});

/// Gain adjustment channel selection.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
pub enum MagneticGainChannel {
    /// Apply gain to first axis pair.
    First = 0,
    /// Apply gain to second axis pair.
    Second = 1,
}

impl_try_from_u8!(MagneticGainChannel {
    0 => First,
    1 => Second,
});

/// Per-sample diagnostic checking policy.
///
/// Controls whether the driver checks `CONV_STATUS.DIAG_FAIL` after each
/// measurement read, and what happens when a fault is detected.
///
/// | Variant  | Checks diag? | On fault                                  |
/// |----------|-------------|-------------------------------------------|
/// | `Off`    | No          | —                                         |
/// | `Halt`   | Yes         | Returns `Error::DiagnosticFailure`        |
/// | `Warn`   | Yes         | Emits `defmt::warn!` (no error returned)  |
/// | `Ignore` | Yes         | Silently discards the fault               |
///
/// `Warn` without the `defmt` feature behaves identically to `Ignore`.
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
pub enum Diagnostics {
    /// Diagnostics disabled — no overhead. (default)
    #[default]
    Off = 0,
    /// Check diagnostics; return [`Error::DiagnosticFailure`](crate::Error::DiagnosticFailure) on fault.
    Halt = 1,
    /// Check diagnostics; emit `defmt::warn!` on fault but do not return an error.
    ///
    /// Without the `defmt` Cargo feature this behaves like [`Ignore`](Self::Ignore).
    Warn = 2,
    /// Check diagnostics; silently discard faults.
    Ignore = 3,
}

/// Magnetic field measurement range.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[repr(u8)]
pub enum Range {
    /// Low range (±40 mT for version 1, ±133 mT for version 2).
    Low = 0,
    /// High range (±80 mT for version 1, ±266 mT for version 2).
    High = 1,
}

impl_try_from_u8!(Range {
    0 => Low,
    1 => High,
});

/// TMAG5273 device variant.
///
/// The letter (A–D) determines the default I2C address and the number (1/2)
/// determines the magnetic sensitivity range (version).
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub enum DeviceVariant {
    /// TMAG5273A1 — address 0x35, version 1.
    A1,
    /// TMAG5273A2 — address 0x35, version 2.
    A2,
    /// TMAG5273B1 — address 0x22, version 1.
    B1,
    /// TMAG5273B2 — address 0x22, version 2.
    B2,
    /// TMAG5273C1 — address 0x78, version 1.
    C1,
    /// TMAG5273C2 — address 0x78, version 2.
    C2,
    /// TMAG5273D1 — address 0x44, version 1.
    D1,
    /// TMAG5273D2 — address 0x44, version 2.
    D2,
}

impl DeviceVariant {
    // -- Factory I2C addresses -----------------------------------------------
    // Datasheet §6.3.4, Table 6-2 "I²C Default Address",
    // column "I²C ADDRESS (7 MSB BITS)".

    /// Default 7-bit I2C address for A-family (TMAG5273Ax).
    const I2C_ADDR_A: u8 = 0x35;
    /// Default 7-bit I2C address for B-family (TMAG5273Bx).
    const I2C_ADDR_B: u8 = 0x22;
    /// Default 7-bit I2C address for C-family (TMAG5273Cx).
    const I2C_ADDR_C: u8 = 0x78;
    /// Default 7-bit I2C address for D-family (TMAG5273Dx).
    const I2C_ADDR_D: u8 = 0x44;

    // -- Full-scale magnetic input range (B_R) -------------------------------
    // Datasheet §6.3.5, Table 6-3 "Magnetic Range Selection".
    // Rows are keyed by axis group (X_Y_RANGE / Z_RANGE) and register
    // setting (0b = Low, 1b = High); columns split by version (x1 / x2).

    /// X_Y_RANGE = 0b, version x1: ±40 mT.
    const XY_RANGE_V1_LOW: f32 = 40.0;
    /// X_Y_RANGE = 1b, version x1: ±80 mT.
    const XY_RANGE_V1_HIGH: f32 = 80.0;
    /// X_Y_RANGE = 0b, version x2: ±133 mT.
    const XY_RANGE_V2_LOW: f32 = 133.0;
    /// X_Y_RANGE = 1b, version x2: ±266 mT.
    const XY_RANGE_V2_HIGH: f32 = 266.0;

    /// Z_RANGE = 0b, version x1: ±40 mT.
    const Z_RANGE_V1_LOW: f32 = 40.0;
    /// Z_RANGE = 1b, version x1: ±80 mT.
    const Z_RANGE_V1_HIGH: f32 = 80.0;
    /// Z_RANGE = 0b, version x2: ±133 mT.
    const Z_RANGE_V2_LOW: f32 = 133.0;
    /// Z_RANGE = 1b, version x2: ±266 mT.
    const Z_RANGE_V2_HIGH: f32 = 266.0;

    /// Factory-default I2C addresses for all TMAG5273 families.
    ///
    /// Ordered B, A, D, C — B-family (0x22, SparkFun default) first since
    /// it's the most common breakout board.
    pub const KNOWN_ADDRESSES: [u8; 4] = [
        Self::I2C_ADDR_B,
        Self::I2C_ADDR_A,
        Self::I2C_ADDR_D,
        Self::I2C_ADDR_C,
    ];

    /// Resolve the device variant from a known I2C address and version byte.
    ///
    /// Returns `None` if the address does not match any known family (A–D)
    /// or the version is not 1 or 2.
    #[inline]
    pub const fn from_address_version(address: u8, version: u8) -> Option<Self> {
        match (address, version) {
            (Self::I2C_ADDR_A, VER_V1) => Some(Self::A1),
            (Self::I2C_ADDR_A, VER_V2) => Some(Self::A2),
            (Self::I2C_ADDR_B, VER_V1) => Some(Self::B1),
            (Self::I2C_ADDR_B, VER_V2) => Some(Self::B2),
            (Self::I2C_ADDR_C, VER_V1) => Some(Self::C1),
            (Self::I2C_ADDR_C, VER_V2) => Some(Self::C2),
            (Self::I2C_ADDR_D, VER_V1) => Some(Self::D1),
            (Self::I2C_ADDR_D, VER_V2) => Some(Self::D2),
            _ => None,
        }
    }

    /// Returns the factory-default I2C address for this variant.
    #[inline]
    pub const fn default_address(&self) -> u8 {
        match self {
            Self::A1 | Self::A2 => Self::I2C_ADDR_A,
            Self::B1 | Self::B2 => Self::I2C_ADDR_B,
            Self::C1 | Self::C2 => Self::I2C_ADDR_C,
            Self::D1 | Self::D2 => Self::I2C_ADDR_D,
        }
    }

    /// Returns the sensitivity version number (1 or 2).
    #[inline]
    pub const fn version(&self) -> u8 {
        match self {
            Self::A1 | Self::B1 | Self::C1 | Self::D1 => VER_V1,
            Self::A2 | Self::B2 | Self::C2 | Self::D2 => VER_V2,
        }
    }

    /// Returns the full-scale magnetic range in mT for the X and Y axes.
    #[inline]
    pub const fn range_xy(&self, range: Range) -> MilliTesla {
        MilliTesla(match (self, range) {
            (Self::A1 | Self::B1 | Self::C1 | Self::D1, Range::Low) => Self::XY_RANGE_V1_LOW,
            (Self::A1 | Self::B1 | Self::C1 | Self::D1, Range::High) => Self::XY_RANGE_V1_HIGH,
            (Self::A2 | Self::B2 | Self::C2 | Self::D2, Range::Low) => Self::XY_RANGE_V2_LOW,
            (Self::A2 | Self::B2 | Self::C2 | Self::D2, Range::High) => Self::XY_RANGE_V2_HIGH,
        })
    }

    /// Returns the full-scale magnetic range in mT for the Z axis.
    #[inline]
    pub const fn range_z(&self, range: Range) -> MilliTesla {
        MilliTesla(match (self, range) {
            (Self::A1 | Self::B1 | Self::C1 | Self::D1, Range::Low) => Self::Z_RANGE_V1_LOW,
            (Self::A1 | Self::B1 | Self::C1 | Self::D1, Range::High) => Self::Z_RANGE_V1_HIGH,
            (Self::A2 | Self::B2 | Self::C2 | Self::D2, Range::Low) => Self::Z_RANGE_V2_LOW,
            (Self::A2 | Self::B2 | Self::C2 | Self::D2, Range::High) => Self::Z_RANGE_V2_HIGH,
        })
    }
}

// ---------------------------------------------------------------------------
// Measurement newtypes
// ---------------------------------------------------------------------------

/// Raw 8-bit threshold register value.
///
/// One LSB (Least Significant Bit) equals `range / 128` mT, where `range` is the sensor's configured
/// full-scale (e.g., ±40 mT → 1 LSB ≈ 0.3125 mT). This is the same scale
/// used by the CORDIC magnitude register (datasheet §8.1.12) and the
/// magnetic threshold registers (§8.1.5–§8.1.7).
///
/// Use [`ThresholdHysteresis::encode_threshold`](crate::config::ThresholdHysteresis::encode_threshold)
/// to convert from [`MilliTesla`] and
/// [`ThresholdHysteresis::decode_threshold`](crate::config::ThresholdHysteresis::decode_threshold)
/// to convert back.
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub struct Lsb(pub i8);

impl From<Lsb> for i8 {
    #[inline]
    fn from(v: Lsb) -> Self {
        v.0
    }
}

impl From<Lsb> for u8 {
    /// Bitwise reinterpretation for I2C register writes.
    /// The bit pattern is preserved: `Lsb(-128).into::<u8>() == 0x80`.
    #[inline]
    fn from(v: Lsb) -> Self {
        v.0 as u8
    }
}

/// Magnetic flux density in millitesla.
#[derive(Debug, Default, Clone, Copy, PartialEq, PartialOrd)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[must_use]
pub struct MilliTesla(pub f32);

impl From<MilliTesla> for f32 {
    #[inline]
    fn from(v: MilliTesla) -> Self {
        v.0
    }
}

impl core::ops::Add for MilliTesla {
    type Output = Self;
    #[inline]
    fn add(self, rhs: Self) -> Self {
        Self(self.0 + rhs.0)
    }
}

impl core::ops::Sub for MilliTesla {
    type Output = Self;
    #[inline]
    fn sub(self, rhs: Self) -> Self {
        Self(self.0 - rhs.0)
    }
}

impl core::ops::AddAssign for MilliTesla {
    #[inline]
    fn add_assign(&mut self, rhs: Self) {
        self.0 += rhs.0;
    }
}

impl core::ops::SubAssign for MilliTesla {
    #[inline]
    fn sub_assign(&mut self, rhs: Self) {
        self.0 -= rhs.0;
    }
}

impl core::ops::Neg for MilliTesla {
    type Output = Self;
    #[inline]
    fn neg(self) -> Self {
        Self(-self.0)
    }
}

impl MilliTesla {
    /// 16-bit ADC full-scale code count: 2^15 = 32 768.
    ///
    /// The TMAG5273 ADC produces signed 16-bit results where ±32 768 maps
    /// to ±`range` mT. Used by [`to_raw`](Self::to_raw) to convert mT back
    /// to an ADC code.
    ///
    /// Datasheet §6.5.2.1, Equation 10 solved for `raw`:
    /// `raw = round(mT × ADC_FULL_SCALE / range)`.
    const ADC_FULL_SCALE: f32 = 32768.0;

    /// Reciprocal of [`ADC_FULL_SCALE`](Self::ADC_FULL_SCALE) — pre-inverted
    /// so [`from_raw`](Self::from_raw) multiplies instead of divides.
    ///
    /// Datasheet §6.5.2.1, Equation 10: `B = raw / 2^16 × 2|B_R|`,
    /// rewritten as `B = raw × range × INV_ADC_FULL_SCALE`.
    const INV_ADC_FULL_SCALE: f32 = 1.0 / Self::ADC_FULL_SCALE;

    /// 8-bit register full-scale code count: 128.
    ///
    /// Shared by the CORDIC magnitude register (0x1B) and magnetic threshold
    /// registers (0x04–0x06). Both encode magnetic field as 8 bits of a
    /// 16-bit full-scale: [`ADC_FULL_SCALE`](Self::ADC_FULL_SCALE) / 256 = 128.
    ///
    /// See datasheet §8.1.12 (CORDIC) and §8.1.5–§8.1.7 (thresholds).
    const EIGHT_BIT_FULL_SCALE: f32 = 128.0;

    /// MilliTesla per 8-bit register LSB: `range / 128`.
    ///
    /// Used by [`CordicMagnitude::from_raw`] and
    /// [`ThresholdHysteresis::decode_threshold`](crate::config::ThresholdHysteresis::decode_threshold)
    /// to convert an 8-bit register code to physical mT.
    #[inline]
    pub(crate) fn mt_per_lsb(self) -> f32 {
        self.0 / Self::EIGHT_BIT_FULL_SCALE
    }

    /// 8-bit register LSBs per milliTesla: `128 / range`.
    ///
    /// Used by [`CordicMagnitude::to_raw`] and
    /// [`ThresholdHysteresis::encode_threshold`](crate::config::ThresholdHysteresis::encode_threshold)
    /// to convert a physical mT value to an 8-bit register code.
    #[inline]
    #[cfg(feature = "libm")]
    pub(crate) fn lsb_per_mt(self) -> f32 {
        Self::EIGHT_BIT_FULL_SCALE / self.0
    }

    /// Absolute value of the magnetic flux density.
    #[inline]
    pub fn abs(self) -> Self {
        Self(self.0.abs())
    }

    /// Construct from a raw 16-bit 2's complement ADC code.
    ///
    /// Follows TI datasheet Equation 10 (§6.5.2.1):
    /// `B = raw / 2^16 × 2|B_R|` = `raw × B_R / 2^15`.
    ///
    /// Sign convention matches the datasheet (§6.3.1): positive values
    /// indicate a magnetic **north** pole approaching the sensor's
    /// sensitive face; negative values indicate a **south** pole.
    #[inline]
    pub fn from_raw(raw: i16, range: MilliTesla) -> Self {
        Self((raw as f32) * range.0 * Self::INV_ADC_FULL_SCALE)
    }
}

#[cfg(feature = "libm")]
impl MilliTesla {
    /// Convert a physical mT value back to the raw 16-bit 2's complement ADC code.
    ///
    /// Inverse of [`MilliTesla::from_raw`]; follows TI datasheet §6.5.2.1
    /// Equation 10 solved for `raw`: `raw = round(mT × ADC_FULL_SCALE / range)`.
    ///
    /// Returns `None` if `self` or `range` is non-finite, `range` is zero,
    /// or the rounded result overflows `i16`.
    #[inline]
    pub fn to_raw(self, range: MilliTesla) -> Option<i16> {
        if !self.0.is_finite() || !range.0.is_finite() || range == MilliTesla(0.0) {
            return None;
        }
        let rounded = libm::roundf(self.0 * Self::ADC_FULL_SCALE / range.0);
        if rounded < i16::MIN as f32 || rounded > i16::MAX as f32 {
            return None;
        }
        Some(rounded as i16)
    }
}

/// Hardware-computed 2-axis CORDIC magnitude in millitesla.
#[derive(Debug, Default, Clone, Copy, PartialEq, PartialOrd)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[must_use]
pub struct CordicMagnitude(pub f32);

impl From<CordicMagnitude> for f32 {
    #[inline]
    fn from(v: CordicMagnitude) -> Self {
        v.0
    }
}

impl CordicMagnitude {
    /// Construct from the raw 8-bit `MAGNITUDE_RESULT` register value (0x1B).
    ///
    /// The CORDIC hardware computes `M = sqrt(Ch1² + Ch2²)` using the same
    /// unsigned 16-bit scale as the magnetic ADC: 32 768 codes = `range`.
    /// The register stores only the upper 8 bits of that 16-bit result, so
    /// `raw = 128` corresponds to a single-axis full-scale vector (one axis at
    /// `range`, the other at zero). Two axes simultaneously at full scale
    /// yields `raw ≈ 181` (`√2 × 128`), producing `~√2 × range`.
    ///
    /// This gives a strictly monotonic unsigned output: every increment of
    /// `raw` increases the returned value.
    #[inline]
    pub fn from_raw(raw: u8, range: MilliTesla) -> Self {
        Self(raw as f32 * range.mt_per_lsb())
    }
}

#[cfg(feature = "libm")]
impl CordicMagnitude {
    /// Convert a physical CORDIC magnitude back to the raw 8-bit register value.
    ///
    /// Inverse of [`CordicMagnitude::from_raw`]; see datasheet §8.1.12.
    /// Formula: `raw = round(mT × 128 / range)`.
    ///
    /// Returns `None` if `self` is non-finite or negative, `range` is
    /// non-finite or zero, or the rounded result overflows `u8`.
    #[inline]
    pub fn to_raw(self, range: MilliTesla) -> Option<u8> {
        if !self.0.is_finite() || self.0 < 0.0 || !range.0.is_finite() || range.0 == 0.0 {
            return None;
        }
        let rounded = libm::roundf(self.0 * range.lsb_per_mt());
        if rounded > u8::MAX as f32 {
            return None;
        }
        Some(rounded as u8)
    }
}

/// Temperature in degrees Celsius.
#[derive(Debug, Default, Clone, Copy, PartialEq, PartialOrd)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[must_use]
pub struct Celsius(pub f32);

impl From<Celsius> for f32 {
    #[inline]
    fn from(v: Celsius) -> Self {
        v.0
    }
}

impl Celsius {
    // -- Datasheet §5.6 "Temperature Sensor" electrical characteristics -------
    // and §6.5.2.2 Equation 12: T = T_SENS_T0 + (T_ADC_T − T_ADC_T0) / T_ADC_RES

    /// `T_SENS_T0`: reference temperature (°C).
    /// Datasheet §5.6, electrical characteristics table.
    const T_SENS_T0: f32 = 25.0;

    /// `T_ADC_T0`: ADC code at the reference temperature (16-bit format).
    /// Datasheet §5.6, electrical characteristics table.
    const T_ADC_T0: f32 = 17508.0;

    /// Reciprocal of `T_ADC_RES` (60.1 LSB/°C).
    /// Datasheet §5.6, electrical characteristics table.
    /// Pre-inverted so `from_raw` multiplies instead of divides.
    const T_ADC_RES_INV: f32 = 1.0 / 60.1;

    /// Construct from a raw 16-bit 2's complement ADC code.
    ///
    /// Datasheet §6.5.2.2, Equation 12:
    /// `T = T_SENS_T0 + (T_ADC_T − T_ADC_T0) / T_ADC_RES`
    #[inline]
    pub fn from_raw(raw: i16) -> Self {
        Self(Self::T_SENS_T0 + ((raw as f32) - Self::T_ADC_T0) * Self::T_ADC_RES_INV)
    }
}

#[cfg(feature = "libm")]
impl Celsius {
    /// Convert a physical temperature back to the raw 16-bit ADC code.
    ///
    /// Inverse of [`Celsius::from_raw`]; follows TI datasheet §6.5.2.2
    /// Equation 12 solved for `T_ADC_T`:
    /// `raw = round((T − T_SENS_T0) / T_ADC_RES_INV + T_ADC_T0)`.
    ///
    /// Returns `None` if `self` is non-finite or the rounded result
    /// overflows `i16`.
    #[inline]
    pub fn to_raw(self) -> Option<i16> {
        if !self.0.is_finite() {
            return None;
        }
        let rounded =
            libm::roundf((self.0 - Self::T_SENS_T0) / Self::T_ADC_RES_INV + Self::T_ADC_T0);
        if rounded < i16::MIN as f32 || rounded > i16::MAX as f32 {
            return None;
        }
        Some(rounded as i16)
    }
}

/// Rotational speed in revolutions per minute.
#[derive(Debug, Default, Clone, Copy, PartialEq, PartialOrd)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[must_use]
pub struct Rpm(pub f32);

impl From<Rpm> for f32 {
    #[inline]
    fn from(v: Rpm) -> Self {
        v.0
    }
}

/// Absolute sensor angle in degrees, always in the range [0°, 360°].
///
/// Represents the output of the TMAG5273 CORDIC engine. Constructed from
/// hardware register values via [`Degrees::from_raw`]; validated by
/// [`Degrees::is_valid`].
///
/// For signed angular deltas (rotation steps), use [`SignedDegrees`].
#[derive(Debug, Default, Clone, Copy, PartialEq, PartialOrd)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[must_use]
pub struct Degrees(pub f32);

impl From<Degrees> for f32 {
    #[inline]
    fn from(v: Degrees) -> Self {
        v.0
    }
}

impl core::ops::Sub for Degrees {
    type Output = SignedDegrees;
    #[inline]
    fn sub(self, rhs: Self) -> SignedDegrees {
        SignedDegrees(self.0 - rhs.0)
    }
}

impl Degrees {
    /// Minimum valid angle (0°).
    pub const MIN: Self = Self(0.0);

    /// Maximum valid angle (360°).
    pub const MAX: Self = Self(360.0);

    /// Returns `true` if this angle is finite and within the valid 0–360° range.
    ///
    /// Rejects `NaN`, `Infinity`, negative values, and values above 360°.
    #[inline]
    pub fn is_valid(self) -> bool {
        self.0 >= Self::MIN.0 && self.0 <= Self::MAX.0
    }

    // -- Angle bit layout from datasheet §6.5.2.3, Equation 14 ---------------
    // The register map (§8.1.26–8.1.27) describes ANGLE_RESULT_MSB/LSB as
    // opaque bytes; the 9.4 fixed-point layout is only implied by Eq. 14:
    //   A = Σ(D_i × 2^(i−4)), i=4..12  +  Σ(D_i × 2^i) / 16, i=0..3

    /// Bit mask for the 9-bit integer part (bits [12:4]).
    const INT_MASK: u16 = 0x1FF;
    /// Bit shift to extract the integer part.
    const INT_SHIFT: u16 = 4;
    /// Bit mask for the 4-bit fractional part (bits [3:0]).
    const FRAC_MASK: u16 = 0x0F;
    /// Reciprocal of 2^4 — converts the fractional field to degrees.
    const FRAC_SCALE: f32 = 1.0 / 16.0;

    /// Construct from a raw 16-bit angle register value (9.4 fixed-point).
    ///
    /// Bits \[12:4\]: 9-bit integer part (0–360).
    /// Bits \[3:0\]: 4-bit fractional part (resolution 1/16 degree).
    ///
    /// Returns `None` if the decoded angle exceeds 360°. The hardware CORDIC
    /// guarantees 0–360° under normal operation; a value above 360° indicates
    /// a corrupted I2C read (enable the `crc` feature to detect this reliably).
    #[inline]
    pub fn from_raw(raw: u16) -> Option<Self> {
        let integer = ((raw >> Self::INT_SHIFT) & Self::INT_MASK) as f32;
        let fraction = (raw & Self::FRAC_MASK) as f32 * Self::FRAC_SCALE;
        let candidate = Self(integer + fraction);
        if candidate.is_valid() {
            Some(candidate)
        } else {
            defmt_warn!(
                "from_raw: angle {}° out of valid range, corrupted I2C read",
                candidate.0
            );
            None
        }
    }
}

#[cfg(feature = "libm")]
impl Degrees {
    /// Convert a physical angle back to the raw 16-bit 9.4 fixed-point register value.
    ///
    /// Inverse of [`Degrees::from_raw`]; follows the 9.4 fixed-point encoding
    /// described in datasheet §6.5.2.3, Equation 14.
    /// Formula: `raw = round(degrees × 16)`.
    ///
    /// Returns `None` if `self` is non-finite, negative, or above 360°.
    #[inline]
    pub fn to_raw(self) -> Option<u16> {
        if !self.0.is_finite() || self.0 < 0.0 || self.0 > 360.0 {
            return None;
        }
        let rounded = libm::roundf(self.0 * 16.0);
        if rounded > 5760.0 {
            return None;
        }
        Some(rounded as u16)
    }
}

/// Signed angular delta in degrees, used for rotation steps and displacements.
///
/// Represents a signed difference between two [`Degrees`] angles — for example,
/// the output of [`RotationTracker::update`](crate::RotationTracker::update).
/// Values are in the range (−180°, +180°] after shortest-path normalization.
///
/// Unlike [`Degrees`], this type has no valid-range restriction and supports
/// negation and absolute value.
#[derive(Debug, Default, Clone, Copy, PartialEq, PartialOrd)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[must_use]
pub struct SignedDegrees(pub f32);

impl From<SignedDegrees> for f32 {
    #[inline]
    fn from(v: SignedDegrees) -> Self {
        v.0
    }
}

impl core::ops::Neg for SignedDegrees {
    type Output = Self;
    #[inline]
    fn neg(self) -> Self {
        Self(-self.0)
    }
}

impl core::ops::Add for SignedDegrees {
    type Output = Self;
    #[inline]
    fn add(self, rhs: Self) -> Self {
        Self(self.0 + rhs.0)
    }
}

impl core::ops::Sub for SignedDegrees {
    type Output = Self;
    #[inline]
    fn sub(self, rhs: Self) -> Self {
        Self(self.0 - rhs.0)
    }
}

impl core::ops::AddAssign for SignedDegrees {
    #[inline]
    fn add_assign(&mut self, rhs: Self) {
        self.0 += rhs.0;
    }
}

impl core::ops::SubAssign for SignedDegrees {
    #[inline]
    fn sub_assign(&mut self, rhs: Self) {
        self.0 -= rhs.0;
    }
}

impl SignedDegrees {
    /// One full revolution forward (+360°).
    pub const MAX: Self = Self(360.0);

    /// One full revolution backward (−360°).
    pub const MIN: Self = Self(-360.0);

    /// Absolute value of this delta.
    #[inline]
    pub fn abs(self) -> Self {
        Self(self.0.abs())
    }
}

// Cross-type ops: update an absolute Degrees position by a signed displacement.

impl core::ops::AddAssign<SignedDegrees> for Degrees {
    #[inline]
    fn add_assign(&mut self, rhs: SignedDegrees) {
        self.0 += rhs.0;
    }
}

impl core::ops::Add<SignedDegrees> for Degrees {
    type Output = Degrees;
    #[inline]
    fn add(self, rhs: SignedDegrees) -> Degrees {
        Degrees(self.0 + rhs.0)
    }
}

impl core::ops::SubAssign<SignedDegrees> for Degrees {
    #[inline]
    fn sub_assign(&mut self, rhs: SignedDegrees) {
        self.0 -= rhs.0;
    }
}

impl core::ops::Sub<SignedDegrees> for Degrees {
    type Output = Degrees;
    #[inline]
    fn sub(self, rhs: SignedDegrees) -> Degrees {
        Degrees(self.0 - rhs.0)
    }
}

/// Duration in micros_isreconds.
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[must_use]
pub struct MicrosIsr(pub u32);

impl MicrosIsr {
    /// Convert to milliseconds as `f32`.
    #[inline]
    pub const fn to_millis(self) -> f32 {
        self.0 as f32 / 1_000.0
    }

    /// Convert to seconds as `f32`.
    #[inline]
    pub const fn to_seconds(self) -> f32 {
        self.0 as f32 / 1_000_000.0
    }
}

impl From<MicrosIsr> for u32 {
    #[inline]
    fn from(v: MicrosIsr) -> Self {
        v.0
    }
}

/// Required by `thiserror` `#[error()]` formatting in [`ConfigError::SleepShorterThanConversion`].
impl core::fmt::Display for MicrosIsr {
    fn fmt(&self, f: &mut core::fmt::Formatter<'_>) -> core::fmt::Result {
        write!(f, "{}", self.0)
    }
}

/// A range of micros_isrecond durations, matching Linux `usleep_range(min, max)` semantics.
#[derive(Debug, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub struct MicrosRange {
    /// Minimum delay (used by the driver for actual `delay_us` calls).
    pub min: MicrosIsr,
    /// Maximum acceptable delay (documentary — for RTOS scheduler batching).
    pub max: MicrosIsr,
}

/// Wake-up delay range after transitioning from Sleep to an active mode.
///
/// From TI TMAG5273 datasheet: device needs >=80 µs to wake. The Linux kernel
/// driver uses `usleep_range(80, 200)` for this boundary.
pub const WAKE_DELAY: MicrosRange = MicrosRange {
    min: MicrosIsr(80),
    max: MicrosIsr(200),
};

/// Inter-retry delay between NACK'd register reads during `set_mode()` wake.
///
/// The datasheet specifies a 50 µs typical wake time, but ESP32-S3 hardware
/// with a TMAG5273 B1 under active magnetic field can need up to ~6 ms before
/// the first I2C read ACKs. Empirically validated from HIL tests: under
/// ambient conditions 1 ms suffices; under a strong magnetic field (bar magnet)
/// the ADC settling extends wake time. 5 ms provides reliable margin across
/// all observed conditions (ambient, idle frother, spinning frother, bar magnet).
///
/// See: docs/solutions/hardware-validation/tmag5273-hil-findings-2026-03-26.md
pub const WAKE_RETRY_DELAY: MicrosIsr = MicrosIsr(5_000);

/// Total zero-crossings counted by a [`ZeroCrossing`](crate::ZeroCrossing) tracker.
///
/// Each crossing represents a polarity-flip event — the magnetic signal
/// passing through the Schmitt trigger's hysteresis band.  Divide by
/// `POLES_COUNT` for mechanical revolutions, or use
/// [`cumulative_revolutions()`](crate::RotationTracker::cumulative_revolutions).
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, PartialOrd, Ord, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[must_use]
pub struct Crossings(pub u32);

impl Crossings {
    /// Saturating increment by `n`, capping at `u32::MAX`.
    #[inline]
    pub const fn saturating_add(self, n: u32) -> Self {
        Self(self.0.saturating_add(n))
    }

    /// Saturating subtraction: returns `Crossings(0)` instead of wrapping on underflow.
    pub const fn saturating_sub(self, rhs: Self) -> Self {
        Self(self.0.saturating_sub(rhs.0))
    }
}

impl From<Crossings> for u32 {
    #[inline]
    fn from(v: Crossings) -> Self {
        v.0
    }
}

/// Zero-sized no-op delay backend (default).
///
/// All `delay_*()` calls compile to nothing. When used as the delay backend
/// for [`Tmag5273`](crate::Tmag5273), the driver falls back to bounded I2C
/// polling for conversion completion and does not insert wake-up delays.
///
/// This is the default — existing callers need no changes.
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
pub struct NoDelay;

impl embedded_hal::delay::DelayNs for NoDelay {
    #[inline]
    fn delay_ns(&mut self, _ns: u32) {}
}

// ---------------------------------------------------------------------------
// Composite reading structs
// ---------------------------------------------------------------------------

/// Magnetic field reading from all enabled axes.
///
/// Disabled channels are represented as `None`.
#[derive(Debug, Default, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[must_use]
pub struct MagneticReading {
    /// X-axis magnetic flux density, or `None` if the channel is disabled.
    pub x: Option<MilliTesla>,
    /// Y-axis magnetic flux density, or `None` if the channel is disabled.
    pub y: Option<MilliTesla>,
    /// Z-axis magnetic flux density, or `None` if the channel is disabled.
    pub z: Option<MilliTesla>,
}

/// Angle measurement result from the TMAG5273 angle engine.
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[must_use]
pub struct AngleReading {
    /// Computed angle in degrees (0–360).
    pub angle: Degrees,
    /// Hardware-computed 2-axis CORDIC magnitude in millitesla.
    pub magnitude: CordicMagnitude,
}

/// Complete sensor reading from a single conversion cycle.
///
/// All values are guaranteed to come from the same conversion — no risk
/// of data from different cycles mixing. Produced by
/// [`Tmag5273::read_all`](crate::Tmag5273::read_all).
#[derive(Debug, Clone, Copy, PartialEq)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[must_use]
pub struct SensorReading {
    /// Temperature in degrees Celsius, or `None` if the channel is disabled.
    pub temperature: Option<Celsius>,
    /// Magnetic field reading from all enabled axes.
    pub magnetic: MagneticReading,
}

// ---------------------------------------------------------------------------
// Status structs
// ---------------------------------------------------------------------------

/// Parsed contents of the `DEVICE_STATUS` register (0x1C).
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[must_use]
pub struct DeviceStatus {
    /// VCC supply is below the undervoltage threshold.
    pub vcc_undervoltage_error: bool,
    /// OTP memory CRC check failed.
    pub otp_crc_error: bool,
    /// Internal error detected.
    pub int_error: bool,
    /// Oscillator error detected.
    pub oscillator_error: bool,
    /// `INTB_RB` readback: `true` = INT̅ pin reads high (inactive),
    /// `false` = INT̅ pin driven low (asserted). Datasheet §8.1.29.
    pub int_bar_readback_high: bool,
}

impl DeviceStatus {
    /// Returns `true` if no fault flags are set.
    #[inline]
    pub const fn is_ok(&self) -> bool {
        !self.vcc_undervoltage_error
            && !self.otp_crc_error
            && !self.int_error
            && !self.oscillator_error
    }

    /// Parses a raw `DEVICE_STATUS` register byte into structured flags.
    #[inline]
    pub const fn from_register(register: u8) -> Self {
        Self {
            vcc_undervoltage_error: extract(register, VCC_UV_ER_MASK, VCC_UV_ER_SHIFT) != 0,
            otp_crc_error: extract(register, OTP_CRC_ER_MASK, OTP_CRC_ER_SHIFT) != 0,
            int_error: extract(register, INT_ER_MASK, INT_ER_SHIFT) != 0,
            oscillator_error: extract(register, OSC_ER_MASK, OSC_ER_SHIFT) != 0,
            int_bar_readback_high: extract(register, INTB_RB_MASK, INTB_RB_SHIFT) != 0,
        }
    }
}

/// Parsed contents of the `CONV_STATUS` register (0x18).
#[derive(Debug, Default, Clone, Copy, PartialEq, Eq, Hash)]
#[cfg_attr(feature = "defmt", derive(defmt::Format))]
#[must_use]
pub struct ConversionStatus {
    /// Rolling conversion set counter (0–7).
    pub set_count: u8,
    /// A power-on-reset event was detected since the last read.
    pub power_on_reset: bool,
    /// Diagnostic self-test failed.
    pub diag_status_fail: bool,
    /// A new conversion result is available.
    pub result_status_ready: bool,
}

impl ConversionStatus {
    /// Returns `true` if a new conversion result is available.
    #[inline]
    pub const fn result_status_ready(&self) -> bool {
        self.result_status_ready
    }

    /// Parses a raw `CONV_STATUS` register byte into structured fields.
    #[inline]
    pub const fn from_register(register: u8) -> Self {
        Self {
            set_count: extract(register, SET_COUNT_MASK, SET_COUNT_SHIFT),
            power_on_reset: extract(register, POR_MASK, POR_SHIFT) != 0,
            diag_status_fail: extract(register, DIAG_STATUS_MASK, DIAG_STATUS_SHIFT) != 0,
            result_status_ready: extract(register, RESULT_STATUS_MASK, RESULT_STATUS_SHIFT) != 0,
        }
    }
}

// ---------------------------------------------------------------------------
// Tests
// ---------------------------------------------------------------------------

#[cfg(test)]
mod tests {
    use super::*;
    use crate::register::CONV_AVG_SHIFT;

    // Floating-point comparison tolerance.
    const EPSILON: f32 = 0.15;

    fn approx_eq(a: f32, b: f32) -> bool {
        (a - b).abs() < EPSILON
    }

    // -- DeviceVariant: default addresses ------------------------------------

    #[test]
    fn variant_a1_address() {
        assert_eq!(DeviceVariant::A1.default_address(), 0x35);
    }

    #[test]
    fn variant_a2_address() {
        assert_eq!(DeviceVariant::A2.default_address(), 0x35);
    }

    #[test]
    fn variant_b1_address() {
        assert_eq!(DeviceVariant::B1.default_address(), 0x22);
    }

    #[test]
    fn variant_b2_address() {
        assert_eq!(DeviceVariant::B2.default_address(), 0x22);
    }

    #[test]
    fn variant_c1_address() {
        assert_eq!(DeviceVariant::C1.default_address(), 0x78);
    }

    #[test]
    fn variant_c2_address() {
        assert_eq!(DeviceVariant::C2.default_address(), 0x78);
    }

    #[test]
    fn variant_d1_address() {
        assert_eq!(DeviceVariant::D1.default_address(), 0x44);
    }

    #[test]
    fn variant_d2_address() {
        assert_eq!(DeviceVariant::D2.default_address(), 0x44);
    }

    // -- DeviceVariant: version ----------------------------------------------

    #[test]
    fn version_1_variants() {
        assert_eq!(DeviceVariant::A1.version(), 1);
        assert_eq!(DeviceVariant::B1.version(), 1);
        assert_eq!(DeviceVariant::C1.version(), 1);
        assert_eq!(DeviceVariant::D1.version(), 1);
    }

    #[test]
    fn version_2_variants() {
        assert_eq!(DeviceVariant::A2.version(), 2);
        assert_eq!(DeviceVariant::B2.version(), 2);
        assert_eq!(DeviceVariant::C2.version(), 2);
        assert_eq!(DeviceVariant::D2.version(), 2);
    }

    // -- DeviceVariant: from_address_version ----------------------------------

    #[test]
    fn from_address_version_all_variants() {
        assert_eq!(
            DeviceVariant::from_address_version(0x35, 1),
            Some(DeviceVariant::A1)
        );
        assert_eq!(
            DeviceVariant::from_address_version(0x35, 2),
            Some(DeviceVariant::A2)
        );
        assert_eq!(
            DeviceVariant::from_address_version(0x22, 1),
            Some(DeviceVariant::B1)
        );
        assert_eq!(
            DeviceVariant::from_address_version(0x22, 2),
            Some(DeviceVariant::B2)
        );
        assert_eq!(
            DeviceVariant::from_address_version(0x78, 1),
            Some(DeviceVariant::C1)
        );
        assert_eq!(
            DeviceVariant::from_address_version(0x78, 2),
            Some(DeviceVariant::C2)
        );
        assert_eq!(
            DeviceVariant::from_address_version(0x44, 1),
            Some(DeviceVariant::D1)
        );
        assert_eq!(
            DeviceVariant::from_address_version(0x44, 2),
            Some(DeviceVariant::D2)
        );
    }

    #[test]
    fn from_address_version_unknown_address() {
        assert_eq!(DeviceVariant::from_address_version(0x30, 1), None);
    }

    #[test]
    fn from_address_version_unknown_version() {
        assert_eq!(DeviceVariant::from_address_version(0x22, 3), None);
        assert_eq!(DeviceVariant::from_address_version(0x22, 0), None);
    }

    // -- DeviceVariant: range tables -----------------------------------------

    #[test]
    fn range_v1_low_xy() {
        assert_eq!(DeviceVariant::A1.range_xy(Range::Low), MilliTesla(40.0));
    }

    #[test]
    fn range_v1_high_xy() {
        assert_eq!(DeviceVariant::B1.range_xy(Range::High), MilliTesla(80.0));
    }

    #[test]
    fn range_v2_low_xy() {
        assert_eq!(DeviceVariant::C2.range_xy(Range::Low), MilliTesla(133.0));
    }

    #[test]
    fn range_v2_high_xy() {
        assert_eq!(DeviceVariant::D2.range_xy(Range::High), MilliTesla(266.0));
    }

    #[test]
    fn range_v1_low_z() {
        assert_eq!(DeviceVariant::A1.range_z(Range::Low), MilliTesla(40.0));
    }

    #[test]
    fn range_v1_high_z() {
        assert_eq!(DeviceVariant::B1.range_z(Range::High), MilliTesla(80.0));
    }

    #[test]
    fn range_v2_low_z() {
        assert_eq!(DeviceVariant::C2.range_z(Range::Low), MilliTesla(133.0));
    }

    #[test]
    fn range_v2_high_z() {
        assert_eq!(DeviceVariant::D2.range_z(Range::High), MilliTesla(266.0));
    }

    // -- Temperature conversion ----------------------------------------------

    #[test]
    fn temp_reference_point() {
        let c = Celsius::from_raw(17508);
        assert!(approx_eq(c.0, 25.0), "expected ~25.0, got {}", c.0);
    }

    #[test]
    fn temp_raw_zero() {
        // T = 25.0 + (0 - 17508) / 60.1 ≈ -266.36
        let c = Celsius::from_raw(0);
        assert!(approx_eq(c.0, -266.36), "expected ~-266.36, got {}", c.0);
    }

    #[test]
    fn celsius_from_raw_i16_min() {
        // T = 25.0 + (-32768.0 - 17508.0) / 60.1 ≈ -811.6
        let c = Celsius::from_raw(i16::MIN);
        assert!(approx_eq(c.0, -811.6), "expected ~-811.6, got {}", c.0);
    }

    #[test]
    fn temp_raw_max() {
        // T = 25.0 + (32767 - 17508) / 60.1 ≈ 279.0
        let c = Celsius::from_raw(i16::MAX);
        assert!(approx_eq(c.0, 279.0), "expected ~279.0, got {}", c.0);
    }

    // -- Magnetic conversion -------------------------------------------------

    #[test]
    fn from_raw_zero_returns_zero_mt() {
        let m = MilliTesla::from_raw(0, MilliTesla(40.0));
        assert_eq!(m.0, 0.0);
    }

    #[test]
    fn from_raw_i16_min_returns_negative_range() {
        // raw = i16::MIN = -32768 → B = -32768 * 40 / 32768 = -40.0
        // Negative = south pole approaching (datasheet §6.3.1)
        let m = MilliTesla::from_raw(i16::MIN, MilliTesla(40.0));
        assert!(approx_eq(m.0, -40.0), "expected ~-40.0, got {}", m.0);
    }

    #[test]
    fn from_raw_i16_max_returns_positive_range() {
        // raw = 32767 → B = 32767 * 40 / 32768 ≈ +39.9988
        // Positive = north pole approaching (datasheet §6.3.1)
        let m = MilliTesla::from_raw(i16::MAX, MilliTesla(40.0));
        assert!(approx_eq(m.0, 40.0), "expected ~40.0, got {}", m.0);
    }

    #[test]
    fn from_raw_i16_min_v2_high_returns_negative_266mt() {
        // i16::MIN = -32768 → B = -32768 * 266 / 32768 = -266.0
        // South pole → negative (datasheet §6.3.1)
        let m = MilliTesla::from_raw(i16::MIN, MilliTesla(266.0));
        assert!(approx_eq(m.0, -266.0), "expected ~-266.0, got {}", m.0);
    }

    // -- Angle conversion ----------------------------------------------------

    #[test]
    fn angle_zero() {
        let d = Degrees::from_raw(0x0000).unwrap();
        assert_eq!(d.0, 0.0);
    }

    #[test]
    fn angle_180() {
        // 180 << 4 = 0x0B40
        let d = Degrees::from_raw(0x0B40).unwrap();
        assert!(approx_eq(d.0, 180.0), "expected 180.0, got {}", d.0);
    }

    #[test]
    fn angle_360() {
        // 360 << 4 = 0x1680
        let d = Degrees::from_raw(0x1680).unwrap();
        assert!(approx_eq(d.0, 360.0), "expected 360.0, got {}", d.0);
    }

    #[test]
    fn angle_fractional() {
        // 90 degrees + 8/16 = 90.5 degrees → (90 << 4) | 8 = 0x05A8
        let d = Degrees::from_raw(0x05A8).unwrap();
        assert!(approx_eq(d.0, 90.5), "expected 90.5, got {}", d.0);
    }

    #[test]
    fn angle_out_of_range_returns_none() {
        // 0xFFFF → integer = (0xFFFF >> 4) & 0x1FF = 511, frac = 15/16 → 511.9375° → None
        assert!(Degrees::from_raw(0xFFFF).is_none(), "0xFFFF must be None");
        // 361° encoded: (361 << 4) = 0x1690 → None
        assert!(Degrees::from_raw(0x1690).is_none(), "361° must be None");
        // 360° exactly is still valid
        assert!(Degrees::from_raw(0x1680).is_some(), "360° must be Some");
    }

    // -- DeviceStatus parsing ------------------------------------------------

    #[test]
    fn device_status_all_clear() {
        let s = DeviceStatus::from_register(0x00);
        assert!(!s.vcc_undervoltage_error);
        assert!(!s.otp_crc_error);
        assert!(!s.int_error);
        assert!(!s.oscillator_error);
        assert!(!s.int_bar_readback_high);
    }

    #[test]
    fn device_status_all_set() {
        let s = DeviceStatus::from_register(0x1F);
        assert!(s.vcc_undervoltage_error);
        assert!(s.otp_crc_error);
        assert!(s.int_error);
        assert!(s.oscillator_error);
        assert!(s.int_bar_readback_high);
    }

    #[test]
    fn device_status_individual_bits() {
        let s = DeviceStatus::from_register(0b0000_0001);
        assert!(s.vcc_undervoltage_error);
        assert!(!s.otp_crc_error);

        let s = DeviceStatus::from_register(0b0000_0010);
        assert!(!s.vcc_undervoltage_error);
        assert!(s.otp_crc_error);

        let s = DeviceStatus::from_register(0b0000_0100);
        assert!(s.int_error);
        assert!(!s.oscillator_error);

        let s = DeviceStatus::from_register(0b0000_1000);
        assert!(!s.int_error);
        assert!(s.oscillator_error);
    }

    #[test]
    fn device_status_int_bar_readback_high() {
        let s = DeviceStatus::from_register(0b0001_0000);
        assert!(s.int_bar_readback_high);
        assert!(s.is_ok()); // INT is not a fault
    }

    // -- ConversionStatus parsing --------------------------------------------

    #[test]
    fn conv_status_all_clear() {
        let s = ConversionStatus::from_register(0x00);
        assert_eq!(s.set_count, 0);
        assert!(!s.power_on_reset);
        assert!(!s.diag_status_fail);
        assert!(!s.result_status_ready);
    }

    #[test]
    fn conv_status_set_count() {
        // set_count occupies bits [7:5] — value 5 = 0b101 << 5 = 0xA0
        let s = ConversionStatus::from_register(0b1010_0000);
        assert_eq!(s.set_count, 5);
        assert!(!s.power_on_reset);
    }

    #[test]
    fn conv_status_set_count_max() {
        // 7 = 0b111 << 5 = 0xE0
        let s = ConversionStatus::from_register(0b1110_0000);
        assert_eq!(s.set_count, 7);
    }

    #[test]
    fn conv_status_power_on_reset() {
        // POR = bit 4 = 0x10
        let s = ConversionStatus::from_register(0b0001_0000);
        assert_eq!(s.set_count, 0);
        assert!(s.power_on_reset);
        assert!(!s.diag_status_fail);
        assert!(!s.result_status_ready);
    }

    #[test]
    fn conv_status_diag_fail() {
        // DIAG_STATUS = bit 1 = 0x02
        let s = ConversionStatus::from_register(0b0000_0010);
        assert!(s.diag_status_fail);
        assert!(!s.result_status_ready);
    }

    #[test]
    fn conv_status_result_ready() {
        // RESULT_STATUS = bit 0 = 0x01
        let s = ConversionStatus::from_register(0b0000_0001);
        assert!(s.result_status_ready);
        assert!(!s.diag_status_fail);
    }

    #[test]
    fn conv_status_all_flags() {
        // SET_COUNT=7 (bits [7:5]) | POR (bit 4) | DIAG (bit 1) | RESULT (bit 0)
        // = 0b1110_0000 | 0b0001_0000 | 0b0000_0010 | 0b0000_0001 = 0xF3
        let s = ConversionStatus::from_register(0b1111_0011);
        assert_eq!(s.set_count, 7);
        assert!(s.power_on_reset);
        assert!(s.diag_status_fail);
        assert!(s.result_status_ready);
    }

    // -- Magnitude conversion (unsigned monotonic CORDIC) --------------------

    #[test]
    fn cordic_magnitude_from_raw_zero_returns_zero() {
        let m = CordicMagnitude::from_raw(0, MilliTesla(80.0));
        assert_eq!(m.0, 0.0);
    }

    #[test]
    fn cordic_magnitude_from_raw_monotonic() {
        // Every increment of raw must produce a strictly larger mT value.
        let range = MilliTesla(80.0);
        let mut prev = CordicMagnitude::from_raw(0, range).0;
        for raw in 1u8..=255 {
            let cur = CordicMagnitude::from_raw(raw, range).0;
            assert!(cur > prev, "non-monotonic at raw={raw}: {prev} >= {cur}");
            prev = cur;
        }
    }

    // -- Wake delay constants ------------------------------------------------

    #[test]
    fn wake_delay_constants() {
        assert_eq!(WAKE_DELAY.min.0, 80);
        assert_eq!(WAKE_DELAY.max.0, 200);
    }

    // -- CordicMagnitude::from_raw key anchor values -------------------------

    #[test]
    fn magnitude_raw_128_is_single_axis_full_scale() {
        // raw=128 → CORDIC 16-bit value ≈ 32768 = range → exactly range.
        let m = CordicMagnitude::from_raw(128, MilliTesla(80.0));
        assert!(approx_eq(m.0, 80.0), "expected ~80.0, got {}", m.0);
    }

    #[test]
    fn magnitude_raw_181_is_two_axis_full_scale() {
        // raw≈181 → √2·128 → √2·range (both X and Y at full scale).
        let m = CordicMagnitude::from_raw(181, MilliTesla(80.0));
        let expected = 80.0_f32 * core::f32::consts::SQRT_2;
        assert!(
            (m.0 - expected).abs() < 1.0,
            "expected ~{expected:.3}, got {}",
            m.0
        );
    }

    #[test]
    fn magnitude_raw_255_is_finite_and_positive() {
        // Maximum raw value must produce a finite, positive result.
        let m = CordicMagnitude::from_raw(255, MilliTesla(80.0));
        assert!(
            m.0.is_finite() && m.0 > 0.0,
            "expected finite >0, got {}",
            m.0
        );
        // Should be roughly 2×range (255/128 ≈ 1.992).
        assert!(approx_eq(m.0, 159.375), "expected ~159.375, got {}", m.0);
    }

    // -- MilliTesla::from_raw boundary values ---------------------------------

    #[test]
    fn millitesla_max_positive_raw() {
        // i16::MAX = 32767 → 32767 * 80 / 32768 ≈ +79.9976 mT
        // North pole → positive (datasheet §6.3.1)
        let m = MilliTesla::from_raw(i16::MAX, MilliTesla(80.0));
        assert!(m.0 > 0.0, "max positive raw should give positive mT");
        assert!(approx_eq(m.0, 80.0), "expected ~80.0, got {}", m.0);
    }

    #[test]
    fn millitesla_min_negative_raw() {
        // i16::MIN = -32768 → -32768 * 80 / 32768 = -80.0 mT
        // South pole → negative (datasheet §6.3.1)
        let m = MilliTesla::from_raw(i16::MIN, MilliTesla(80.0));
        assert!(m.0 < 0.0, "min negative raw should give negative mT");
        assert!(approx_eq(m.0, -80.0), "expected ~-80.0, got {}", m.0);
    }

    #[test]
    fn millitesla_zero_raw() {
        let m = MilliTesla::from_raw(0, MilliTesla(80.0));
        assert_eq!(m.0, 0.0);
    }

    #[test]
    fn millitesla_zero_range() {
        let m = MilliTesla::from_raw(16384, MilliTesla(0.0));
        assert_eq!(m.0, 0.0);
    }

    // -- Celsius::from_raw boundary values ------------------------------------

    // -- From impls -----------------------------------------------------------

    #[test]
    fn millitesla_into_f32() {
        assert_eq!(f32::from(MilliTesla(3.14)), 3.14);
    }

    #[test]
    fn celsius_into_f32() {
        assert_eq!(f32::from(Celsius(25.0)), 25.0);
    }

    #[test]
    fn degrees_into_f32() {
        assert_eq!(f32::from(Degrees(180.0)), 180.0);
    }

    #[test]
    fn degrees_constants() {
        assert_eq!(Degrees::MIN.0, 0.0);
        assert_eq!(Degrees::MAX.0, 360.0);
    }

    #[test]
    fn degrees_is_valid_in_range() {
        assert!(Degrees(0.0).is_valid());
        assert!(Degrees(180.0).is_valid());
        assert!(Degrees(360.0).is_valid());
    }

    #[test]
    fn degrees_is_valid_out_of_range() {
        assert!(!Degrees(-0.1).is_valid());
        assert!(!Degrees(360.1).is_valid());
        assert!(!Degrees(f32::NAN).is_valid());
        assert!(!Degrees(f32::INFINITY).is_valid());
        assert!(!Degrees(f32::NEG_INFINITY).is_valid());
    }

    // -- SignedDegrees -------------------------------------------------------

    #[test]
    fn signed_degrees_into_f32() {
        assert_eq!(f32::from(SignedDegrees(90.5)), 90.5);
    }

    #[test]
    fn signed_degrees_add() {
        assert_eq!(
            SignedDegrees(90.0) + SignedDegrees(30.0),
            SignedDegrees(120.0)
        );
    }

    #[test]
    fn signed_degrees_sub_signed() {
        assert_eq!(
            SignedDegrees(10.0) - SignedDegrees(30.0),
            SignedDegrees(-20.0)
        );
    }

    #[test]
    fn signed_degrees_neg() {
        assert_eq!(-SignedDegrees(45.0), SignedDegrees(-45.0));
    }

    #[test]
    fn signed_degrees_abs_negative() {
        assert_eq!(SignedDegrees(-45.0).abs(), SignedDegrees(45.0));
    }

    #[test]
    fn signed_degrees_abs_positive() {
        assert_eq!(SignedDegrees(45.0).abs(), SignedDegrees(45.0));
    }

    #[test]
    fn signed_degrees_abs_zero() {
        assert_eq!(SignedDegrees(0.0).abs(), SignedDegrees(0.0));
    }

    #[test]
    fn signed_degrees_abs_nan_no_panic() {
        assert!(SignedDegrees(f32::NAN).abs().0.is_nan());
    }

    #[test]
    fn degrees_add_signed_degrees_cross_type() {
        assert_eq!(Degrees(270.0) + SignedDegrees(45.0), Degrees(315.0));
    }

    #[test]
    fn degrees_add_assign_signed_degrees_positive() {
        let mut d = Degrees(100.0);
        d += SignedDegrees(30.0);
        assert_eq!(d, Degrees(130.0));
    }

    #[test]
    fn degrees_add_assign_signed_degrees_negative() {
        let mut d = Degrees(100.0);
        d += SignedDegrees(-30.0);
        assert_eq!(d, Degrees(70.0));
    }

    #[test]
    fn degrees_is_valid_still_works_after_refactor() {
        assert!(Degrees(0.0).is_valid());
        assert!(Degrees(180.0).is_valid());
        assert!(Degrees(360.0).is_valid());
        assert!(!Degrees(-0.1).is_valid());
        assert!(!Degrees(f32::NAN).is_valid());
    }

    #[test]
    fn cordic_magnitude_into_f32() {
        assert_eq!(f32::from(CordicMagnitude(3.14)), 3.14);
    }

    #[test]
    fn micros_isr_into_u32() {
        assert_eq!(u32::from(MicrosIsr(1000)), 1000);
    }

    // -- AngleReading magnitude field ---------------------------------------

    #[test]
    fn angle_reading_magnitude_field() {
        let reading = AngleReading {
            angle: Degrees(90.0),
            magnitude: CordicMagnitude(80.0),
        };
        let m = reading.magnitude;
        assert!(approx_eq(m.0, 80.0), "expected ~80.0, got {}", m.0);
    }

    #[test]
    fn angle_reading_magnitude_field_zero() {
        let reading = AngleReading {
            angle: Degrees(0.0),
            magnitude: CordicMagnitude(0.0),
        };
        assert_eq!(reading.magnitude.0, 0.0);
    }

    // -- MagneticChannel helpers ----------------------------------------------

    #[test]
    fn axis_try_from() {
        for v in [Axis::X, Axis::Y, Axis::Z] {
            assert_eq!(Axis::try_from(v as u8), Ok(v));
        }
        assert_eq!(Axis::try_from(0x03), Err(0x03));
    }

    #[test]
    fn poles_try_from() {
        for v in [PoleCount::Two, PoleCount::Three, PoleCount::Four] {
            assert_eq!(PoleCount::try_from(v as u8), Ok(v));
        }
        assert_eq!(PoleCount::try_from(0x00), Err(0x00));
        assert_eq!(PoleCount::try_from(0x05), Err(0x05));
    }

    #[test]
    fn magnetic_channel_axis_count() {
        assert_eq!(MagneticChannel::Off.axis_count(), 0);
        assert_eq!(MagneticChannel::X.axis_count(), 1);
        assert_eq!(MagneticChannel::XY.axis_count(), 2);
        assert_eq!(MagneticChannel::XYZ.axis_count(), 3);
        // Pseudo-sim: 2 distinct axes even though 3 measurement slots
        assert_eq!(MagneticChannel::XYX.axis_count(), 2);
        assert_eq!(MagneticChannel::YXY.axis_count(), 2);
        assert_eq!(MagneticChannel::YZY.axis_count(), 2);
        assert_eq!(MagneticChannel::XZX.axis_count(), 2);
    }

    #[test]
    fn magnetic_channel_measurement_slots() {
        assert_eq!(MagneticChannel::Off.measurement_slots(), 0);
        assert_eq!(MagneticChannel::X.measurement_slots(), 1);
        assert_eq!(MagneticChannel::XY.measurement_slots(), 2);
        assert_eq!(MagneticChannel::XYZ.measurement_slots(), 3);
        // Pseudo-sim: 3 measurement slots (e.g. X, Y, X)
        assert_eq!(MagneticChannel::XYX.measurement_slots(), 3);
        assert_eq!(MagneticChannel::YXY.measurement_slots(), 3);
        assert_eq!(MagneticChannel::YZY.measurement_slots(), 3);
        assert_eq!(MagneticChannel::XZX.measurement_slots(), 3);
    }

    #[test]
    fn magnetic_channel_has_axes_all_variants() {
        //                          has_x  has_y  has_z
        let cases: &[(MagneticChannel, bool, bool, bool)] = &[
            (MagneticChannel::Off, false, false, false),
            (MagneticChannel::X, true, false, false),
            (MagneticChannel::Y, false, true, false),
            (MagneticChannel::XY, true, true, false),
            (MagneticChannel::Z, false, false, true),
            (MagneticChannel::ZX, true, false, true),
            (MagneticChannel::YZ, false, true, true),
            (MagneticChannel::XYZ, true, true, true),
            // Pseudo-simultaneous: physical axes measured, not register layout
            (MagneticChannel::XYX, true, true, false), // measures X, Y
            (MagneticChannel::YXY, true, true, false), // measures Y, X
            (MagneticChannel::YZY, false, true, true), // measures Y, Z
            (MagneticChannel::XZX, true, false, true), // measures X, Z
        ];
        for &(ch, x, y, z) in cases {
            assert_eq!(ch.has_x(), x, "{ch:?}.has_x()");
            assert_eq!(ch.has_y(), y, "{ch:?}.has_y()");
            assert_eq!(ch.has_z(), z, "{ch:?}.has_z()");
        }
    }

    #[test]
    fn i2c_read_mode_try_from() {
        for v in [
            I2cReadMode::Standard,
            I2cReadMode::OneByte16Bit,
            I2cReadMode::OneByte8Bit,
        ] {
            assert_eq!(I2cReadMode::try_from(v as u8), Ok(v));
        }
        assert_eq!(I2cReadMode::try_from(0x03), Err(0x03));
    }

    // -- Exhaustive from_register fuzz ----------------------------------------

    #[test]
    fn fuzz_device_status_from_register() {
        for byte in 0u8..=255 {
            let s = DeviceStatus::from_register(byte);

            // All fields must be valid bools (no panic) — the mere act of
            // reading them is the check. Additionally verify is_ok() doesn't
            // panic.
            let _ = s.vcc_undervoltage_error;
            let _ = s.otp_crc_error;
            let _ = s.int_error;
            let _ = s.oscillator_error;
            let _ = s.int_bar_readback_high;
            let _ = s.is_ok();
        }

        // Spot-check: byte 0x00 — all flags clear.
        let s = DeviceStatus::from_register(0x00);
        assert!(!s.vcc_undervoltage_error);
        assert!(!s.otp_crc_error);
        assert!(!s.int_error);
        assert!(!s.oscillator_error);
        assert!(!s.int_bar_readback_high);
        assert!(s.is_ok());

        // Spot-check: byte 0x1F — all five defined bits set.
        let s = DeviceStatus::from_register(0x1F);
        assert!(s.vcc_undervoltage_error);
        assert!(s.otp_crc_error);
        assert!(s.int_error);
        assert!(s.oscillator_error);
        assert!(s.int_bar_readback_high);
        assert!(!s.is_ok()); // faults present
    }

    #[test]
    fn fuzz_conversion_status_from_register() {
        for byte in 0u8..=255 {
            let s = ConversionStatus::from_register(byte);

            // set_count must always be in 0..=7 (3-bit field).
            assert!(
                s.set_count <= 7,
                "set_count out of range for byte 0x{byte:02X}: {}",
                s.set_count
            );

            // Bool fields readable without panic.
            let _ = s.power_on_reset;
            let _ = s.diag_status_fail;
            let _ = s.result_status_ready;
            let _ = s.result_status_ready();
        }

        // Spot-check: byte 0x00 — all defaults.
        let s = ConversionStatus::from_register(0x00);
        assert_eq!(s.set_count, 0);
        assert!(!s.power_on_reset);
        assert!(!s.diag_status_fail);
        assert!(!s.result_status_ready);

        // Spot-check: byte 0xFF — all bits set.
        // SET_COUNT=7 (bits [7:5]), POR (bit 4), reserved [3:2], DIAG (bit 1), RESULT (bit 0)
        let s = ConversionStatus::from_register(0xFF);
        assert_eq!(s.set_count, 7);
        assert!(s.power_on_reset);
        assert!(s.diag_status_fail);
        assert!(s.result_status_ready);
    }

    // -- Exhaustive TryFrom fuzz ----------------------------------------------

    /// Test helper: for every byte 0..=255, calls `T::try_from(byte)` and
    /// asserts:
    ///   - `Ok(v)` ⇒ `v as u8 == byte` (round-trip) — via the caller-supplied
    ///     `to_u8` closure (needed because `#[repr(u8)]` does not provide
    ///     `Into<u8>`).
    ///   - `Err(e)` ⇒ `e == byte`.
    ///   - The total valid count matches `expected_valid`.
    fn assert_exhaustive_try_from<T>(name: &str, expected_valid: usize, to_u8: impl Fn(T) -> u8)
    where
        T: TryFrom<u8, Error = u8> + Copy + core::fmt::Debug + PartialEq,
    {
        let mut valid = 0usize;
        for byte in 0..=255u8 {
            match T::try_from(byte) {
                Ok(v) => {
                    let back = to_u8(v);
                    assert_eq!(
                        back, byte,
                        "{name}: round-trip failed for Ok({v:?}): {back} != {byte}"
                    );
                    valid += 1;
                }
                Err(e) => {
                    assert_eq!(e, byte, "{name}: Err payload mismatch: {e} != {byte}");
                }
            }
        }
        assert_eq!(
            valid, expected_valid,
            "{name}: expected {expected_valid} valid variants, got {valid}"
        );
    }

    #[test]
    fn exhaustive_i2c_read_mode() {
        assert_exhaustive_try_from::<I2cReadMode>("I2cReadMode", 3, |v| v as u8);
    }

    #[test]
    fn exhaustive_operating_mode() {
        assert_exhaustive_try_from::<OperatingMode>("OperatingMode", 4, |v| v as u8);
    }

    #[test]
    fn exhaustive_axis() {
        assert_exhaustive_try_from::<Axis>("Axis", 3, |v| v as u8);
    }

    #[test]
    fn exhaustive_poles() {
        assert_exhaustive_try_from::<PoleCount>("PoleCount", 3, |v| v as u8);
    }

    #[test]
    fn exhaustive_magnetic_channel() {
        assert_exhaustive_try_from::<MagneticChannel>("MagneticChannel", 12, |v| v as u8);
    }

    #[test]
    fn exhaustive_conversion_average() {
        assert_exhaustive_try_from::<ConversionAverage>("ConversionAverage", 6, |v| v as u8);
    }

    #[test]
    fn exhaustive_sleep_time() {
        assert_exhaustive_try_from::<SleepTime>("SleepTime", 13, |v| v as u8);
    }

    #[test]
    fn exhaustive_power_noise_mode() {
        assert_exhaustive_try_from::<PowerNoiseMode>("PowerNoiseMode", 2, |v| v as u8);
    }

    #[test]
    fn exhaustive_trigger_mode() {
        assert_exhaustive_try_from::<TriggerMode>("TriggerMode", 2, |v| v as u8);
    }

    #[test]
    fn exhaustive_magnetic_temp_coefficient() {
        assert_exhaustive_try_from::<MagneticTempCoefficient>("MagneticTempCoefficient", 3, |v| {
            v as u8
        });
    }

    #[test]
    fn exhaustive_angle_enabled() {
        assert_exhaustive_try_from::<AngleEnable>("AngleEnable", 4, |v| v as u8);
    }

    #[test]
    fn exhaustive_threshold_direction() {
        assert_exhaustive_try_from::<MagneticThresholdDirection>("ThresholdDirection", 2, |v| {
            v as u8
        });
    }

    #[test]
    fn exhaustive_threshold_crossing_count() {
        assert_exhaustive_try_from::<ThresholdCrossingCount>("ThresholdCrossingCount", 2, |v| {
            v as u8
        });
    }

    // -- TempThresholdConfig boundaries (§8.1.8) ----------------------------

    #[test]
    fn temp_threshold_disabled_is_zero() {
        assert_eq!(TempThresholdConfig::DISABLED.code(), 0);
        assert!(!TempThresholdConfig::DISABLED.is_enabled());
    }

    #[test]
    fn temp_threshold_valid_range_boundaries() {
        // Below min active code → rejected
        assert!(TempThresholdConfig::from_code(0x19).is_none());
        // Min active code → accepted
        assert!(TempThresholdConfig::from_code(0x1A).is_some());
        // Max active code → accepted
        assert!(TempThresholdConfig::from_code(0x34).is_some());
        // Above max active code → rejected
        assert!(TempThresholdConfig::from_code(0x35).is_none());
    }

    #[test]
    fn temp_threshold_all_valid_codes_accepted() {
        // Code 0 (disabled)
        assert!(TempThresholdConfig::try_from(0u8).is_ok());
        // All active codes
        for code in 0x1A..=0x34u8 {
            assert!(
                TempThresholdConfig::try_from(code).is_ok(),
                "code 0x{code:02X} should be valid"
            );
        }
    }

    #[test]
    fn temp_threshold_invalid_codes_rejected() {
        // Gap between disabled (0) and min active (0x1A)
        for code in 1..0x1Au8 {
            assert!(
                TempThresholdConfig::try_from(code).is_err(),
                "code 0x{code:02X} should be invalid"
            );
        }
        // Above max active
        for code in 0x35..=0x7Fu8 {
            assert!(
                TempThresholdConfig::try_from(code).is_err(),
                "code 0x{code:02X} should be invalid"
            );
        }
    }

    #[test]
    fn temp_threshold_default_is_disabled() {
        let t = TempThresholdConfig::default();
        assert_eq!(t, TempThresholdConfig::DISABLED);
    }

    #[test]
    fn exhaustive_interrupt_mode() {
        assert_exhaustive_try_from::<InterruptMode>("InterruptMode", 5, |v| v as u8);
    }

    #[test]
    fn exhaustive_int_pin_behavior() {
        assert_exhaustive_try_from::<InterruptState>("InterruptState", 2, |v| v as u8);
    }

    #[test]
    fn exhaustive_gain_channel() {
        assert_exhaustive_try_from::<MagneticGainChannel>("MagneticGainChannel", 2, |v| v as u8);
    }

    #[test]
    fn exhaustive_range() {
        assert_exhaustive_try_from::<Range>("Range", 2, |v| v as u8);
    }

    // -- Linux kernel driver cross-reference (v6.14) --------------------------
    // Cross-reference: Linux kernel drivers/iio/magnetometer/tmag5273.c (v6.14)

    #[test]
    fn linux_xref_averaging_modes() {
        // Linux stores pre-shifted values via FIELD_PREP into CONV_AVG_MASK.
        // Our enum stores unshifted raw values (0-5).
        // Comparison: (variant as u8) << CONV_AVG_SHIFT == linux_value
        let table: &[(ConversionAverage, u8, &str)] = &[
            (ConversionAverage::X1, 0x00, "TMAG5273_AVG_1"),
            (ConversionAverage::X2, 0x04, "TMAG5273_AVG_2"),
            (ConversionAverage::X4, 0x08, "TMAG5273_AVG_4"),
            (ConversionAverage::X8, 0x0C, "TMAG5273_AVG_8"),
            (ConversionAverage::X16, 0x10, "TMAG5273_AVG_16"),
            (ConversionAverage::X32, 0x14, "TMAG5273_AVG_32"),
        ];
        for &(variant, linux_shifted, name) in table {
            let shifted = (variant as u8) << CONV_AVG_SHIFT;
            assert_eq!(
                shifted, linux_shifted,
                "averaging mode mismatch for {name}: (rust {variant:?} as u8) << {CONV_AVG_SHIFT} = 0x{shifted:02X}, linux=0x{linux_shifted:02X}"
            );
        }
    }

    #[test]
    fn linux_xref_operating_modes() {
        let table: &[(OperatingMode, u8, &str)] = &[
            (OperatingMode::Standby, 0, "TMAG5273_OP_MODE_STANDBY"),
            (OperatingMode::Sleep, 1, "TMAG5273_OP_MODE_SLEEP"),
            (
                OperatingMode::ContinuousMeasure,
                2,
                "TMAG5273_OP_MODE_CONTINUOUS",
            ),
            (OperatingMode::WakeUpAndSleep, 3, "TMAG5273_OP_MODE_WAKEUP"),
        ];
        for &(variant, linux_value, name) in table {
            assert_eq!(
                variant as u8, linux_value,
                "operating mode mismatch for {name}: rust={}, linux={linux_value}",
                variant as u8
            );
        }
    }

    #[test]
    fn linux_xref_angle_enable() {
        let table: &[(AngleEnable, u8, &str)] = &[
            (AngleEnable::None, 0, "TMAG5273_ANGLE_EN_OFF"),
            (AngleEnable::XY, 1, "TMAG5273_ANGLE_EN_X_Y"),
            (AngleEnable::YZ, 2, "TMAG5273_ANGLE_EN_Y_Z"),
            (AngleEnable::XZ, 3, "TMAG5273_ANGLE_EN_X_Z"),
        ];
        for &(variant, linux_value, name) in table {
            assert_eq!(
                variant as u8, linux_value,
                "angle enable mismatch for {name}: rust={}, linux={linux_value}",
                variant as u8
            );
        }
    }

    #[test]
    fn linux_xref_mag_channel_xyz() {
        // Linux: TMAG5273_MAG_CH_EN_X_Y_Z = 7
        assert_eq!(
            MagneticChannel::XYZ as u8,
            7,
            "MagneticChannel::XYZ should be 7 (TMAG5273_MAG_CH_EN_X_Y_Z)"
        );
    }

    #[test]
    fn linux_xref_magnetic_scale() {
        // Linux tmag5273_scale table: microgauss per LSB for each range.
        // Our range constants are in mT; convert:
        //   1 mT = 10 Gauss = 10_000_000 microgauss
        //   microgauss_per_lsb = range * 10_000_000 / 32768
        // Linux rounds these to integers (e.g., 12200 vs exact 12207.03).
        let table: &[(f64, f64, &str)] = &[
            (40.0, 12200.0, "v1 low (40 mT)"),
            (80.0, 24400.0, "v1 high (80 mT)"),
            (133.0, 40600.0, "v2 low (133 mT)"),
            (266.0, 81200.0, "v2 high (266 mT)"),
        ];
        for &(range, linux_ugauss_per_lsb, name) in table {
            let our_ugauss_per_lsb = range * 10_000_000.0 / 32768.0;
            let rel_error =
                ((our_ugauss_per_lsb - linux_ugauss_per_lsb) / linux_ugauss_per_lsb).abs();
            assert!(
                rel_error < 0.005,
                "magnetic scale mismatch for {name}: ours={our_ugauss_per_lsb:.2}, linux={linux_ugauss_per_lsb}, error={:.3}%",
                rel_error * 100.0
            );
        }
    }

    #[test]
    fn linux_xref_temp_formula() {
        // Linux integer formula: millidegrees = (raw - 16005) * 10000 / 601
        // Our float formula: celsius = 25.0 + (raw - 17508.0) / 60.1
        // Both implement the same datasheet curve but diverge by ~8 millidegrees
        // due to integer vs float rounding. Assert within 0.5°C at 3 reference points.
        let table: &[(i16, f64, &str)] = &[
            (0, -266.305, "raw=0"),
            (17508, 25.008, "raw=17508 (reference)"),
            (32767, 278.902, "raw=i16::MAX"),
        ];
        for &(raw, linux_millideg_approx, name) in table {
            // Linux: (raw - 16005) * 10000 / 601 millidegrees
            let linux_celsius = ((raw as i64 - 16005) * 10000) as f64 / 601.0 / 1000.0;
            // Verify our Linux reference values are correct
            assert!(
                (linux_celsius - linux_millideg_approx).abs() < 0.01,
                "Linux formula sanity check failed for {name}: computed={linux_celsius}, expected={linux_millideg_approx}"
            );

            // Our formula
            let our_celsius = 25.0_f64 + (raw as f64 - 17508.0) / 60.1;

            let diff = (our_celsius - linux_celsius).abs();
            assert!(
                diff < 0.5,
                "temperature formula mismatch for {name}: ours={our_celsius:.3}°C, linux={linux_celsius:.3}°C, diff={diff:.3}°C"
            );
        }
    }

    // -- coverage: max_polls for all ConversionAverage variants ---------------

    #[test]
    fn max_polls_all_variants() {
        assert_eq!(ConversionAverage::X1.max_polls(), 10);
        assert_eq!(ConversionAverage::X2.max_polls(), 15);
        assert_eq!(ConversionAverage::X4.max_polls(), 25);
        assert_eq!(ConversionAverage::X8.max_polls(), 40);
        assert_eq!(ConversionAverage::X16.max_polls(), 70);
        assert_eq!(ConversionAverage::X32.max_polls(), 100);
    }

    // -- coverage: ConversionAverage::lower step-down chain --------------------

    #[test]
    fn lower_full_chain() {
        assert_eq!(ConversionAverage::X32.lower(), Some(ConversionAverage::X16));
        assert_eq!(ConversionAverage::X16.lower(), Some(ConversionAverage::X8));
        assert_eq!(ConversionAverage::X8.lower(), Some(ConversionAverage::X4));
        assert_eq!(ConversionAverage::X4.lower(), Some(ConversionAverage::X2));
        assert_eq!(ConversionAverage::X2.lower(), Some(ConversionAverage::X1));
    }

    #[test]
    fn lower_x1_is_none() {
        assert_eq!(ConversionAverage::X1.lower(), None);
    }

    #[test]
    fn lower_chain_has_exactly_5_steps() {
        let mut current = ConversionAverage::X32;
        let mut steps = 0u32;
        while let Some(next) = current.lower() {
            steps += 1;
            current = next;
        }
        assert_eq!(steps, 5);
        assert_eq!(current, ConversionAverage::X1);
    }

    // -- coverage: SleepTime::as_micros_isr for all variants ------------------

    #[test]
    fn sleep_time_as_micros_isr_all_variants() {
        assert_eq!(SleepTime::Ms1.as_micros_isr(), MicrosIsr(1_000));
        assert_eq!(SleepTime::Ms5.as_micros_isr(), MicrosIsr(5_000));
        assert_eq!(SleepTime::Ms10.as_micros_isr(), MicrosIsr(10_000));
        assert_eq!(SleepTime::Ms15.as_micros_isr(), MicrosIsr(15_000));
        assert_eq!(SleepTime::Ms20.as_micros_isr(), MicrosIsr(20_000));
        assert_eq!(SleepTime::Ms30.as_micros_isr(), MicrosIsr(30_000));
        assert_eq!(SleepTime::Ms50.as_micros_isr(), MicrosIsr(50_000));
        assert_eq!(SleepTime::Ms100.as_micros_isr(), MicrosIsr(100_000));
        assert_eq!(SleepTime::Ms500.as_micros_isr(), MicrosIsr(500_000));
        assert_eq!(SleepTime::Ms1000.as_micros_isr(), MicrosIsr(1_000_000));
        assert_eq!(SleepTime::Ms2000.as_micros_isr(), MicrosIsr(2_000_000));
        assert_eq!(SleepTime::Ms5000.as_micros_isr(), MicrosIsr(5_000_000));
        assert_eq!(SleepTime::Ms20000.as_micros_isr(), MicrosIsr(20_000_000));
    }

    // -------------------------------------------------------------------
    // Crossings
    // -------------------------------------------------------------------

    #[test]
    fn crossings_default_and_ordering() {
        assert_eq!(Crossings::default(), Crossings(0));
        assert!(Crossings(1) < Crossings(2));
        assert_eq!(Crossings(42).0, 42);
    }

    #[test]
    fn crossings_from_u32() {
        assert_eq!(u32::from(Crossings(0)), 0_u32);
        assert_eq!(u32::from(Crossings(42)), 42_u32);
        assert_eq!(u32::from(Crossings(u32::MAX)), u32::MAX);
    }

    #[test]
    fn crossings_saturating_add() {
        assert_eq!(Crossings(0).saturating_add(1), Crossings(1));
        assert_eq!(Crossings(10).saturating_add(5), Crossings(15));
        assert_eq!(Crossings(u32::MAX).saturating_add(1), Crossings(u32::MAX));
        assert_eq!(
            Crossings(u32::MAX - 1).saturating_add(2),
            Crossings(u32::MAX)
        );
    }

    // -------------------------------------------------------------------
    // to_raw() inverse conversions (libm-gated)
    // -------------------------------------------------------------------

    #[cfg(feature = "libm")]
    mod to_raw {
        use super::*;

        // -- MilliTesla round-trips ------------------------------------------

        #[test]
        fn millitesla_round_trip_zero() {
            let ranges = [40.0, 80.0, 133.0, 266.0];
            for r in ranges {
                let range = MilliTesla(r);
                assert_eq!(MilliTesla::from_raw(0, range).to_raw(range), Some(0));
            }
        }

        #[test]
        fn millitesla_round_trip_one() {
            let range = MilliTesla(40.0);
            assert_eq!(MilliTesla::from_raw(1, range).to_raw(range), Some(1));
        }

        #[test]
        fn millitesla_round_trip_neg_one() {
            let range = MilliTesla(40.0);
            assert_eq!(MilliTesla::from_raw(-1, range).to_raw(range), Some(-1));
        }

        #[test]
        fn millitesla_round_trip_extremes() {
            let range = MilliTesla(40.0);
            assert_eq!(
                MilliTesla::from_raw(i16::MAX, range).to_raw(range),
                Some(i16::MAX)
            );
            assert_eq!(
                MilliTesla::from_raw(i16::MIN, range).to_raw(range),
                Some(i16::MIN)
            );
        }

        #[test]
        fn millitesla_round_trip_midpoint() {
            let range = MilliTesla(80.0);
            assert_eq!(
                MilliTesla::from_raw(16384, range).to_raw(range),
                Some(16384)
            );
        }

        #[test]
        fn millitesla_round_trip_all_ranges() {
            let ranges = [40.0, 80.0, 133.0, 266.0];
            let raws: [i16; 6] = [0, 1, -1, i16::MAX, i16::MIN, 16384];
            for r in ranges {
                let range = MilliTesla(r);
                for raw in raws {
                    assert_eq!(
                        MilliTesla::from_raw(raw, range).to_raw(range),
                        Some(raw),
                        "MilliTesla round-trip failed: raw={raw}, range={r}"
                    );
                }
            }
        }

        #[test]
        fn millitesla_overflow_returns_none() {
            assert_eq!(MilliTesla(100.0).to_raw(MilliTesla(40.0)), None);
        }

        #[test]
        fn millitesla_nan_returns_none() {
            assert_eq!(MilliTesla(f32::NAN).to_raw(MilliTesla(40.0)), None);
        }

        #[test]
        fn millitesla_infinity_returns_none() {
            assert_eq!(MilliTesla(f32::INFINITY).to_raw(MilliTesla(40.0)), None);
            assert_eq!(MilliTesla(f32::NEG_INFINITY).to_raw(MilliTesla(40.0)), None);
        }

        #[test]
        fn millitesla_zero_range_returns_none() {
            assert_eq!(MilliTesla(0.0).to_raw(MilliTesla(0.0)), None);
        }

        #[test]
        fn millitesla_nan_range_returns_none() {
            assert_eq!(MilliTesla(1.0).to_raw(MilliTesla(f32::NAN)), None);
        }

        // -- CordicMagnitude round-trips -------------------------------------

        #[test]
        fn cordic_magnitude_round_trip_key_values() {
            let range = MilliTesla(80.0);
            for raw in [0_u8, 1, 128, 181, 255] {
                assert_eq!(
                    CordicMagnitude::from_raw(raw, range).to_raw(range),
                    Some(raw),
                    "CordicMagnitude round-trip failed: raw={raw}"
                );
            }
        }

        #[test]
        fn cordic_magnitude_negative_returns_none() {
            assert_eq!(CordicMagnitude(-1.0).to_raw(MilliTesla(80.0)), None);
        }

        #[test]
        fn cordic_magnitude_nan_returns_none() {
            assert_eq!(CordicMagnitude(f32::NAN).to_raw(MilliTesla(80.0)), None);
        }

        #[test]
        fn cordic_magnitude_zero_range_returns_none() {
            assert_eq!(CordicMagnitude(1.0).to_raw(MilliTesla(0.0)), None);
        }

        // -- Celsius round-trips ---------------------------------------------

        #[test]
        fn celsius_round_trip_reference_point() {
            // raw = 17508 → 25°C
            assert_eq!(Celsius::from_raw(17508).to_raw(), Some(17508));
        }

        #[test]
        fn celsius_round_trip_zero() {
            assert_eq!(Celsius::from_raw(0).to_raw(), Some(0));
        }

        #[test]
        fn celsius_round_trip_extremes() {
            assert_eq!(Celsius::from_raw(i16::MIN).to_raw(), Some(i16::MIN));
            assert_eq!(Celsius::from_raw(i16::MAX).to_raw(), Some(i16::MAX));
        }

        #[test]
        fn celsius_nan_returns_none() {
            assert_eq!(Celsius(f32::NAN).to_raw(), None);
        }

        #[test]
        fn celsius_infinity_returns_none() {
            assert_eq!(Celsius(f32::INFINITY).to_raw(), None);
            assert_eq!(Celsius(f32::NEG_INFINITY).to_raw(), None);
        }

        // -- Degrees round-trips ---------------------------------------------

        #[test]
        fn degrees_round_trip_zero() {
            assert_eq!(Degrees::from_raw(0x0000).unwrap().to_raw(), Some(0x0000));
        }

        #[test]
        fn degrees_round_trip_180() {
            assert_eq!(Degrees::from_raw(0x0B40).unwrap().to_raw(), Some(0x0B40));
        }

        #[test]
        fn degrees_round_trip_360() {
            assert_eq!(Degrees::from_raw(0x1680).unwrap().to_raw(), Some(0x1680));
        }

        #[test]
        fn degrees_round_trip_fractional() {
            // 90.5° → (90 << 4) | 8 = 0x05A8
            assert_eq!(Degrees::from_raw(0x05A8).unwrap().to_raw(), Some(0x05A8));
        }

        #[test]
        fn degrees_negative_returns_none() {
            assert_eq!(Degrees(-1.0).to_raw(), None);
        }

        #[test]
        fn degrees_above_360_returns_none() {
            assert_eq!(Degrees(361.0).to_raw(), None);
        }

        #[test]
        fn degrees_nan_returns_none() {
            assert_eq!(Degrees(f32::NAN).to_raw(), None);
        }

        #[test]
        fn degrees_infinity_returns_none() {
            assert_eq!(Degrees(f32::INFINITY).to_raw(), None);
        }
    }

    // -------------------------------------------------------------------
    // Exhaustive round-trip verification (Unit 7)
    //
    // Verifies `from_raw(x).to_raw() == Some(x)` for ALL valid register
    // values across all hardware ranges. Any f32 precision issue must be
    // documented, not silently masked.
    // -------------------------------------------------------------------

    #[cfg(feature = "libm")]
    mod exhaustive_round_trip {
        use super::*;

        #[test]
        fn millitesla_exhaustive_round_trip() {
            let ranges = [
                MilliTesla(40.0),
                MilliTesla(80.0),
                MilliTesla(133.0),
                MilliTesla(266.0),
            ];
            for range in ranges {
                for raw in i16::MIN..=i16::MAX {
                    let mt = MilliTesla::from_raw(raw, range);
                    assert_eq!(
                        mt.to_raw(range),
                        Some(raw),
                        "MilliTesla round-trip failed: raw={raw}, range={}",
                        range.0,
                    );
                }
            }
        }

        #[test]
        fn cordic_magnitude_exhaustive_round_trip() {
            let ranges = [
                MilliTesla(40.0),
                MilliTesla(80.0),
                MilliTesla(133.0),
                MilliTesla(266.0),
            ];
            for range in ranges {
                for raw in 0..=u8::MAX {
                    let cm = CordicMagnitude::from_raw(raw, range);
                    assert_eq!(
                        cm.to_raw(range),
                        Some(raw),
                        "CordicMagnitude round-trip failed: raw={raw}, range={}",
                        range.0,
                    );
                }
            }
        }

        #[test]
        fn celsius_exhaustive_round_trip() {
            for raw in i16::MIN..=i16::MAX {
                let c = Celsius::from_raw(raw);
                assert_eq!(
                    c.to_raw(),
                    Some(raw),
                    "Celsius round-trip failed: raw={raw}, celsius={}",
                    c.0,
                );
            }
        }

        #[test]
        fn degrees_exhaustive_round_trip() {
            for raw in 0u16..=0x1680 {
                if let Some(d) = Degrees::from_raw(raw) {
                    assert_eq!(
                        d.to_raw(),
                        Some(raw),
                        "Degrees round-trip failed: raw=0x{raw:04X}, degrees={}",
                        d.0,
                    );
                }
            }
        }
    }
}