use tmag5273::{Tmag5273, ConfigBuilder};

// 1. Plug-and-play: scan the I2C bus, auto-detect variant and address
let sensor = Tmag5273::scan(i2c).expect("no TMAG5273 found");

// 2. Build a validated configuration (defaults: continuous, XYZ, temp enabled)
let config = ConfigBuilder::new().build()?;

// 3. Initialize: verifies manufacturer ID, applies config → Configured state
let mut sensor = sensor.init(&config)?;

// 4. Read magnetic field (all enabled axes)
let reading = sensor.read_magnetic()?;
if let Some(x) = reading.x {
    // x.0 is in millitesla (f32)
}

// 5. Read temperature
let temp = sensor.read_temperature()?;
// temp.0 is degrees Celsius (f32)

// 6. Coherent T+XYZ burst read (single 8-byte I2C transaction)
let all = sensor.read_all()?;

use tmag5273::{Tmag5273, DeviceVariant, ConfigBuilder};

let sensor = Tmag5273::new(i2c, DeviceVariant::B1);

use tmag5273::{
    ConfigBuilder, OperatingMode, MagneticChannel, AngleEnable,
    ConversionAverage, Range, PowerNoiseMode, MagneticTempCoefficient,
};

let config = ConfigBuilder::new()
    .operating_mode(OperatingMode::ContinuousMeasure) // default
    .magnetic_channels_enabled(MagneticChannel::XYZ)  // default
    .temp_channel_enabled(true)                       // default
    .angle_enabled(AngleEnable::None)                 // default
    .conversion_average(ConversionAverage::X4)
    .xy_range(Range::High)                            // default: ±80 mT (v1)
    .z_range(Range::High)
    .power_noise_mode(PowerNoiseMode::LowNoise)        // default: LowActiveCurrent
    .magnetic_temp_coefficient(MagneticTempCoefficient::NdBFe)
    .build()?;

use tmag5273::{ConversionAverage, MagneticChannel, MicrosIsr};

let t: MicrosIsr = ConversionAverage::X8.conversion_time(MagneticChannel::XYZ, true);
// t.0 is microseconds

let reading = sensor.read_magnetic()?;
// reading.x, reading.y, reading.z are Option<MilliTesla>
// None for disabled channels

let temp: tmag5273::Celsius = sensor.read_temperature()?;
// temp.0 is degrees Celsius

use tmag5273::{ConfigBuilder, AngleEnable, MagneticChannel};

let config = ConfigBuilder::new()
    .angle_enabled(AngleEnable::XY)
    .magnetic_channels_enabled(MagneticChannel::XYX) // pseudo-simultaneous
    .build()?;

let mut sensor = sensor.init(&config)?;
let angle = sensor.read_angle()?;
// angle.angle.0 is degrees (0–360, f32)
// angle.magnitude.0 is millitesla (CordicMagnitude)

let reading = sensor.read_magnetic()?;
let planes = reading.plane_angles();

// Each plane is Option — None if axes missing or zero-magnitude field
if let Some(xy) = planes.xy {
    // xy.angle.0 — degrees (0–360), matching hardware CORDIC convention
    // xy.magnitude.0 — millitesla
    // xy.plane — PlaneAxis::XY
}

// Get the plane with the strongest signal
if let Some(dominant) = planes.dominant() {
    // dominant.plane tells you which axis pair has the strongest field
}

// 3-axis software magnitude
if let Some(mag) = reading.magnitude_3d() {
    // mag.0 — millitesla, sqrt(x² + y² + z²)
}

use tmag5273::{AxisCalibrator, ConfigBuilder};

// 1. Collect samples during magnet rotation
let mut cal = AxisCalibrator::default();
for _ in 0..50 {
    let reading = sensor.read_magnetic()?;
    cal.update(&reading);
    delay.delay_ms(100);
}

// 2. Get the recommended hardware configuration
if let Some(rec) = cal.recommend() {
    // rec.plane — the detected rotation plane (XY, YZ, or XZ)
    // rec.angle_enable — for ConfigBuilder::angle_enabled()
    // rec.magnetic_channel — for ConfigBuilder::magnetic_channels_enabled()
    // rec.variances — per-axis variance for transparency

    // 3. Apply to hardware
    let config = ConfigBuilder::new()
        .angle_enabled(rec.angle_enable)
        .magnetic_channels_enabled(rec.magnetic_channel)
        .build()?;

    let mut sensor = sensor.init(&config)?;
    let angle = sensor.read_angle()?; // hardware CORDIC, optimal axis pair
}

use tmag5273::{CordicTracker, MicrosIsr};

let mut tracker = CordicTracker::new(); // = RotationTracker::<2, Cordic>::new()

loop {
    let angle = sensor.read_angle()?;
    let elapsed = MicrosIsr(/* time since last update */);
    let _delta = tracker.update(angle.angle, elapsed);

    if let Some(rpm) = tracker.rpm() {
        // rpm.0 — revolutions per minute (f32)
    }
}

use tmag5273::{RotationTracker, ZeroCrossing, MilliTesla, MicrosIsr};

// 4-pole Gicar ring magnet, H ≈ 10% of peak-to-peak swing
let mut tracker = RotationTracker::<4, ZeroCrossing>::new(MilliTesla(0.8));

loop {
    let reading = sensor.read_magnetic()?;
    let elapsed = MicrosIsr(/* time since last update */);

    if let Some(x) = reading.x {
        if let Some(ipi) = tracker.update(x, elapsed) {
            // ipi.0 — microseconds between this and the previous pole transition
        }
    }

    if let Some(rpm) = tracker.rpm() {
        // average RPM since construction or last reset()
    }
}

let reading: tmag5273::SensorReading = sensor.read_all()?;
// reading.temperature: Option<Celsius>
// reading.magnetic:    MagneticReading { x, y, z: Option<MilliTesla> }

use tmag5273::{ConfigBuilder, OperatingMode};

let config = ConfigBuilder::new()
    .operating_mode(OperatingMode::Standby)
    .build()?;
let mut sensor = sensor.init(&config)?;

// Trigger a conversion, then poll for completion
sensor.trigger_conversion()?;
let status = sensor.wait_for_conversion()?;

// Now safe to read
let reading = sensor.read_magnetic()?;

use tmag5273::Diagnostics;

// Halt on fault — returns Error::DiagnosticFailure(DeviceStatus)
sensor.set_diagnostics(Diagnostics::Halt);

// Warn on fault — emits defmt::warn! but reads succeed (requires `defmt` feature)
sensor.set_diagnostics(Diagnostics::Warn);

// Ignore faults — for noisy environments (EMI, motor controllers)
sensor.set_diagnostics(Diagnostics::Ignore);

// Default — no overhead, no extra I2C transactions
sensor.set_diagnostics(Diagnostics::Off);

use tmag5273::{
    ThresholdConfig, MagneticThresholdDirection, TempThresholdConfig,
    InterruptConfig, InterruptMode, InterruptState, ThresholdHysteresis,
};

sensor.set_thresholds(&ThresholdConfig {
    x: 50, y: 50, z: 50,
    temperature: TempThresholdConfig::DISABLED,
    direction: MagneticThresholdDirection::Above,
    hysteresis: ThresholdHysteresis::LimitCross,
    ..Default::default()
})?;

sensor.set_interrupt(&InterruptConfig {
    on_conversion_complete: false,
    on_threshold_crossing: true,
    mode: InterruptMode::ThroughInt,
    pin_behavior: InterruptState::Pulse10us,
    ..Default::default()
})?;

use tmag5273::{CalibrationConfig, MagneticGainChannel};

sensor.set_calibration(&CalibrationConfig {
    gain: 128,
    offset_1: 0,
    offset_2: 0,
    gain_channel: MagneticGainChannel::First,
    ..Default::default()
})?;

// Set thresholds first, then activate wake-and-sleep
sensor.set_thresholds(&threshold_config)?;
sensor.configure_wake_and_sleep()?;

// Change address and verify the device responds at the new address
sensor.change_address(0x30)?;
// Note: resets to factory default on power cycle

match sensor.init(&config) {
    Ok(s)   => { /* use s */ }
    Err(e)  => {
        // e.error: Error<I2C::Error>
        // e.i2c:  I2C bus — returned for reuse
    }
}

use embedded_hal_bus::i2c::RefCellDevice;
use core::cell::RefCell;

let bus = RefCell::new(i2c);
let sensor_a = Tmag5273::new(RefCellDevice::new(&bus), DeviceVariant::A1);
let sensor_b = Tmag5273::new(RefCellDevice::new(&bus), DeviceVariant::C1);