Construye una brújula inteligente en Android con Kotlin y Jetpack Compose

adb devices

List of devices attached
XXXXXXXXXXXX    device

adb shell pm list features | findstr /I "android.hardware.sensor.accelerometer android.hardware.sensor.compass"

feature:android.hardware.sensor.accelerometer
feature:android.hardware.sensor.compass

.\gradlew.bat --version

.\gradlew.bat assembleDebug

BUILD SUCCESSFUL

Acelerómetro
    └── Dirección de la gravedad e inclinación

Magnetómetro
    └── Campo magnético en X, Y y Z

Acelerómetro + magnetómetro
    └── Orientación del dispositivo

Acelerómetro + magnetómetro
            ↓
     Matriz de rotación
            ↓
Corrección por rotación de pantalla
            ↓
   Azimut, pitch y roll
            ↓
 Conversión de radianes a grados
            ↓
 Normalización del rumbo
            ↓
       Filtro circular
            ↓
 Interfaz con Jetpack Compose

-1°   → 359°
360°  → 0°
721°  → 1°

Magnetómetro
     ↓
Campo magnético
     ↓
Norte magnético
     ↓
Rumbo mostrado por SmartCompass


Norte magnético
     +
Ubicación, fecha y modelo geomagnético
     ↓
Corrección por declinación
     ↓
Norte verdadero

SmartCompass/
├── app/
│   └── src/
│       └── main/
│           ├── AndroidManifest.xml
│           ├── java/
│           │   └── com/
│           │       └── tucodigocotidiano/
│           │           └── smartcompass/
│           │               ├── MainActivity.kt
│           │               └── ui/
│           │                   └── theme/
│           └── res/
├── build.gradle.kts
├── settings.gradle.kts
├── gradlew
└── gradlew.bat

package com.tucodigocotidiano.smartcompass

.\gradlew.bat assembleDebug

BUILD SUCCESSFUL

dependencies {
    implementation(libs.androidx.core.ktx)

    implementation(libs.androidx.activity.compose)

    implementation(platform(libs.androidx.compose.bom))
    implementation(libs.androidx.compose.ui)
    implementation(libs.androidx.compose.ui.graphics)
    implementation(libs.androidx.compose.ui.tooling.preview)
    implementation(libs.androidx.compose.material3)

    implementation(libs.androidx.lifecycle.runtime.ktx)
    implementation(libs.androidx.lifecycle.runtime.compose)
    implementation(libs.androidx.lifecycle.viewmodel.ktx)

    implementation(libs.kotlinx.coroutines.android)

    testImplementation(libs.junit)

    androidTestImplementation(platform(libs.androidx.compose.bom))
    androidTestImplementation(libs.androidx.compose.ui.test.junit4)

    debugImplementation(libs.androidx.compose.ui.tooling)
    debugImplementation(libs.androidx.compose.ui.test.manifest)
}

android {
    defaultConfig {
        testInstrumentationRunner = "androidx.test.runner.AndroidJUnitRunner"
    }
}

.\gradlew.bat assembleDebug

BUILD SUCCESSFUL

<?xml version="1.0" encoding="utf-8"?>
<manifest xmlns:android="http://schemas.android.com/apk/res/android">

    <application
        android:allowBackup="true"
        android:dataExtractionRules="@xml/data_extraction_rules"
        android:fullBackupContent="@xml/backup_rules"
        android:icon="@mipmap/ic_launcher"
        android:label="@string/app_name"
        android:roundIcon="@mipmap/ic_launcher_round"
        android:supportsRtl="true"
        android:theme="@style/Theme.Smartcompass">

        <activity
            android:name=".MainActivity"
            android:exported="true"
            android:label="@string/app_name"
            android:theme="@style/Theme.Smartcompass"
            android:windowSoftInputMode="adjustResize">

            <intent-filter>
                <action android:name="android.intent.action.MAIN" />
                <category android:name="android.intent.category.LAUNCHER" />
            </intent-filter>

        </activity>

    </application>

</manifest>

package com.tucodigocotidiano.smartcompass.domain

/**
 * Funciones matemáticas puras utilizadas por la brújula.
 *
 * Esta clase no depende de Android, SensorManager, Compose
 * ni de ninguna API específica del sistema operativo.
 */
object AngleMath {

    private const val FULL_CIRCLE_DEGREES = 360f
    private const val HALF_CIRCLE_DEGREES = 180f

    /**
     * Normaliza cualquier ángulo para que quede dentro del intervalo:
     *
     * 0° <= resultado < 360°
     *
     * Ejemplos:
     * - normalizeDegrees(-1f) = 359f
     * - normalizeDegrees(360f) = 0f
     * - normalizeDegrees(721f) = 1f
     */
    fun normalizeDegrees(angle: Float): Float {
        require(angle.isFinite()) {
            "El ángulo debe ser un número finito."
        }

        val normalized =
            ((angle % FULL_CIRCLE_DEGREES) + FULL_CIRCLE_DEGREES) %
                    FULL_CIRCLE_DEGREES

        // Evita devolver -0.0f.
        return if (normalized == 0f) {
            0f
        } else {
            normalized
        }
    }

    /**
     * Convierte radianes a grados.
     *
     * Esta función no normaliza el resultado porque una conversión
     * puede necesitar conservar valores negativos o superiores a 360°.
     */
    fun radiansToDegrees(radians: Float): Float {
        require(radians.isFinite()) {
            "El valor en radianes debe ser un número finito."
        }

        return Math.toDegrees(radians.toDouble()).toFloat()
    }

    /**
     * Calcula la diferencia angular mínima para pasar desde [from]
     * hasta [to].
     *
     * El resultado estará dentro del intervalo:
     *
     * -180° <= resultado < 180°
     *
     * Un resultado positivo significa giro horario.
     * Un resultado negativo significa giro antihorario.
     *
     * Ejemplos:
     * - de 350° a 10° = 20°
     * - de 10° a 350° = -20°
     */
    fun shortestAngleDifference(
        from: Float,
        to: Float
    ): Float {
        require(from.isFinite() && to.isFinite()) {
            "Los ángulos deben ser números finitos."
        }

        val normalizedFrom = normalizeDegrees(from)
        val normalizedTo = normalizeDegrees(to)

        return normalizeDegrees(
            normalizedTo - normalizedFrom + HALF_CIRCLE_DEGREES
        ) - HALF_CIRCLE_DEGREES
    }
}

val sectorIndex = (
    (normalizedAngle + HALF_SECTOR_DEGREES) /
        SECTOR_SIZE_DEGREES
    ).toInt() % orderedDirections.size

package com.tucodigocotidiano.smartcompass.domain

/**
 * Representa las ocho direcciones cardinales principales.
 *
 * Cada dirección incluye:
 * - abreviatura para la interfaz;
 * - nombre completo en español.
 */
enum class CardinalDirection(
    val abbreviation: String,
    val displayName: String
) {
    NORTH(
        abbreviation = "N",
        displayName = "Norte"
    ),

    NORTHEAST(
        abbreviation = "NE",
        displayName = "Noreste"
    ),

    EAST(
        abbreviation = "E",
        displayName = "Este"
    ),

    SOUTHEAST(
        abbreviation = "SE",
        displayName = "Sureste"
    ),

    SOUTH(
        abbreviation = "S",
        displayName = "Sur"
    ),

    SOUTHWEST(
        abbreviation = "SO",
        displayName = "Suroeste"
    ),

    WEST(
        abbreviation = "O",
        displayName = "Oeste"
    ),

    NORTHWEST(
        abbreviation = "NO",
        displayName = "Noroeste"
    );

    companion object {

        private const val SECTOR_SIZE_DEGREES = 45f
        private const val HALF_SECTOR_DEGREES = 22.5f

        private val orderedDirections = values()

        /**
         * Convierte un ángulo en una dirección cardinal.
         *
         * Sectores:
         * - Norte: 337.5° hasta menos de 22.5°
         * - Noreste: 22.5° hasta menos de 67.5°
         * - Este: 67.5° hasta menos de 112.5°
         * - Sureste: 112.5° hasta menos de 157.5°
         * - Sur: 157.5° hasta menos de 202.5°
         * - Suroeste: 202.5° hasta menos de 247.5°
         * - Oeste: 247.5° hasta menos de 292.5°
         * - Noroeste: 292.5° hasta menos de 337.5°
         */
        fun fromDegrees(angle: Float): CardinalDirection {
            val normalizedAngle = AngleMath.normalizeDegrees(angle)

            val sectorIndex = (
                    (normalizedAngle + HALF_SECTOR_DEGREES) /
                            SECTOR_SIZE_DEGREES
                    ).toInt() % orderedDirections.size

            return orderedDirections[sectorIndex]
        }
    }
}

val direction =
    CardinalDirection.fromDegrees(
        23f
    )

println(direction.abbreviation)
println(direction.displayName)

NE
Noreste

package com.tucodigocotidiano.smartcompass.domain

/**
 * Filtro pasa-bajos para vectores de sensores.
 *
 * Aplica por separado la fórmula:
 *
 * valorFiltrado =
 *     alpha * valorAnterior +
 *     (1 - alpha) * valorNuevo
 *
 * Un valor alpha cercano a 1 produce mayor suavizado,
 * pero también aumenta ligeramente el retraso.
 *
 * La clase mantiene arreglos internos reutilizables para no crear
 * objetos nuevos durante cada evento del sensor.
 *
 * @param alpha peso asignado al valor filtrado anterior.
 * Debe estar entre 0 y 1.
 *
 * @param dimensions cantidad de componentes del vector.
 * Para acelerómetro y magnetómetro se utilizan tres: X, Y y Z.
 */
class LowPassVectorFilter(
    private val alpha: Float,
    val dimensions: Int = DEFAULT_DIMENSIONS
) {

    init {
        require(alpha.isFinite()) {
            "El valor alpha debe ser finito."
        }

        require(alpha in MINIMUM_ALPHA..MAXIMUM_ALPHA) {
            "El valor alpha debe estar entre 0 y 1."
        }

        require(dimensions > 0) {
            "La cantidad de dimensiones debe ser mayor que cero."
        }
    }

    private val state = FloatArray(dimensions)

    private var initialized = false

    /**
     * Indica si el filtro ya recibió una primera muestra válida.
     */
    val isInitialized: Boolean
        get() = initialized

    /**
     * Filtra [input] y escribe el resultado en [output].
     *
     * Los dos arreglos deben tener al menos [dimensions] posiciones.
     *
     * La primera muestra válida se copia directamente. Esto evita que
     * el filtro comience artificialmente desde cero.
     *
     * @return true cuando la muestra fue procesada.
     * Devuelve false si contiene NaN o infinito.
     */
    fun filter(
        input: FloatArray,
        output: FloatArray
    ): Boolean {
        require(input.size >= dimensions) {
            "El arreglo de entrada debe tener al menos $dimensions componentes."
        }

        require(output.size >= dimensions) {
            "El arreglo de salida debe tener al menos $dimensions componentes."
        }

        for (index in 0 until dimensions) {
            if (!input[index].isFinite()) {
                return false
            }
        }

        if (!initialized) {
            for (index in 0 until dimensions) {
                state[index] = input[index]
                output[index] = input[index]
            }

            initialized = true
            return true
        }

        val newValueWeight = 1f - alpha

        for (index in 0 until dimensions) {
            val filteredValue =
                alpha * state[index] +
                        newValueWeight * input[index]

            state[index] = filteredValue
            output[index] = filteredValue
        }

        return true
    }

    /**
     * Reinicia el filtro.
     *
     * La siguiente muestra volverá a considerarse como primera lectura.
     */
    fun reset() {
        state.fill(0f)
        initialized = false
    }

    companion object {
        const val DEFAULT_DIMENSIONS = 3

        private const val MINIMUM_ALPHA = 0f
        private const val MAXIMUM_ALPHA = 1f
    }
}

val filter =
    LowPassVectorFilter(
        alpha = 0.8f
    )

val output =
    FloatArray(3)

filter.filter(
    input = floatArrayOf(
        9.8f,
        0.2f,
        -0.1f
    ),
    output = output
)

filter.filter(
    input = floatArrayOf(
        10.2f,
        0.6f,
        0.3f
    ),
    output = output
)

println(output.contentToString())

[9.88, 0.28, -0.02]

package com.tucodigocotidiano.smartcompass.domain

import kotlin.math.atan2
import kotlin.math.cos
import kotlin.math.hypot
import kotlin.math.sin

/**
 * Filtro circular para rumbos expresados en grados.
 *
 * Los ángulos no deben promediarse como números lineales.
 *
 * Ejemplo:
 *
 * 359° y 1°
 *
 * El promedio correcto está cerca de 0°, no de 180°.
 *
 * El filtro realiza dos operaciones:
 *
 * 1. Calcula una media móvil circular utilizando seno y coseno.
 * 2. Se desplaza hacia el promedio utilizando la diferencia angular
 *    mínima, evitando recorridos largos al cruzar entre 359° y 0°.
 *
 * Los datos se almacenan en arreglos primitivos circulares para evitar
 * crear objetos nuevos en cada lectura.
 *
 * @param windowSize cantidad de muestras utilizadas por la media circular.
 *
 * @param responseFactor proporción del desplazamiento angular aplicada
 * en cada actualización:
 *
 * - 1.0: alcanza inmediatamente el promedio circular.
 * - 0.5: recorre la mitad de la diferencia.
 * - 0.25: movimiento más suave, pero con mayor retraso.
 */
class CircularAngleFilter(
    private val windowSize: Int = DEFAULT_WINDOW_SIZE,
    private val responseFactor: Float = DEFAULT_RESPONSE_FACTOR
) {

    init {
        require(windowSize > 0) {
            "El tamaño de la ventana debe ser mayor que cero."
        }

        require(responseFactor.isFinite()) {
            "El factor de respuesta debe ser finito."
        }

        require(
            responseFactor > MINIMUM_RESPONSE_FACTOR &&
                    responseFactor <= MAXIMUM_RESPONSE_FACTOR
        ) {
            "El factor de respuesta debe ser mayor que 0 y menor o igual que 1."
        }
    }

    /*
     * Arreglos circulares reutilizables.
     *
     * Cada posición almacena los componentes seno y coseno de una muestra.
     */
    private val sineSamples = DoubleArray(windowSize)
    private val cosineSamples = DoubleArray(windowSize)

    private var nextSampleIndex = 0
    private var storedSampleCount = 0

    private var sineSum = 0.0
    private var cosineSum = 0.0

    private var filteredHeading: Float? = null

    /**
     * Cantidad actual de muestras almacenadas.
     */
    val sampleCount: Int
        get() = storedSampleCount

    /**
     * Último rumbo filtrado.
     *
     * Será null antes de recibir la primera muestra.
     */
    val currentValue: Float?
        get() = filteredHeading

    /**
     * Agrega una nueva muestra y devuelve el rumbo estabilizado.
     */
    fun add(angleDegrees: Float): Float {
        val normalizedAngle =
            AngleMath.normalizeDegrees(angleDegrees)

        val radians =
            Math.toRadians(normalizedAngle.toDouble())

        val newSine = sin(radians)
        val newCosine = cos(radians)

        /*
         * Cuando la ventana está llena se elimina primero la muestra
         * que será reemplazada.
         */
        if (storedSampleCount == windowSize) {
            sineSum -= sineSamples[nextSampleIndex]
            cosineSum -= cosineSamples[nextSampleIndex]
        } else {
            storedSampleCount++
        }

        sineSamples[nextSampleIndex] = newSine
        cosineSamples[nextSampleIndex] = newCosine

        sineSum += newSine
        cosineSum += newCosine

        nextSampleIndex =
            (nextSampleIndex + 1) % windowSize

        val vectorMagnitude = hypot(
            sineSum,
            cosineSum
        )

        /*
         * Vectores opuestos pueden cancelarse.
         *
         * Ejemplo:
         * 0° y 180°
         *
         * En ese caso no existe una dirección promedio bien definida.
         * Conservamos el último resultado válido.
         */
        if (vectorMagnitude < MIN_VECTOR_MAGNITUDE) {
            val fallback =
                filteredHeading ?: normalizedAngle

            filteredHeading = fallback
            return fallback
        }

        val averagedRadians = atan2(
            sineSum,
            cosineSum
        )

        val circularAverage =
            AngleMath.normalizeDegrees(
                Math.toDegrees(
                    averagedRadians
                ).toFloat()
            )

        val previousHeading = filteredHeading

        if (previousHeading == null) {
            filteredHeading = circularAverage
            return circularAverage
        }

        /*
         * La diferencia angular mínima siempre está entre -180° y 180°.
         *
         * Por ejemplo:
         *
         * desde 359° hasta 1° = +2°
         *
         * y no:
         *
         * desde 359° hasta 1° = -358°
         */
        val shortestDifference =
            AngleMath.shortestAngleDifference(
                from = previousHeading,
                to = circularAverage
            )

        val smoothedHeading =
            AngleMath.normalizeDegrees(
                previousHeading +
                        shortestDifference * responseFactor
            )

        filteredHeading = smoothedHeading

        return smoothedHeading
    }

    /**
     * Elimina todas las muestras y reinicia el estado.
     */
    fun reset() {
        sineSamples.fill(0.0)
        cosineSamples.fill(0.0)

        nextSampleIndex = 0
        storedSampleCount = 0

        sineSum = 0.0
        cosineSum = 0.0

        filteredHeading = null
    }

    companion object {
        const val DEFAULT_WINDOW_SIZE = 5
        const val DEFAULT_RESPONSE_FACTOR = 1f

        private const val MINIMUM_RESPONSE_FACTOR = 0f
        private const val MAXIMUM_RESPONSE_FACTOR = 1f

        private const val MIN_VECTOR_MAGNITUDE = 1e-6
    }
}

val filter =
    CircularAngleFilter(
        windowSize = 2,
        responseFactor = 1f
    )

val firstResult =
    filter.add(
        359f
    )

val secondResult =
    filter.add(
        1f
    )

println(firstResult)
println(secondResult)

359.0
0.0

.\gradlew.bat assembleDebug

BUILD SUCCESSFUL

package com.tucodigocotidiano.smartcompass.domain

import com.tucodigocotidiano.smartcompass.sensor.SensorAccuracy

/**
 * Lectura completa producida por la fuente de sensores.
 *
 * @property magneticHeading rumbo magnético normalizado entre
 * 0° y menos de 360°.
 *
 * @property pitch inclinación hacia delante o hacia atrás, en grados.
 *
 * @property roll inclinación lateral, en grados.
 *
 * @property accuracy precisión reportada por el magnetómetro.
 *
 * @property magneticFieldStrength intensidad total del campo magnético,
 * expresada en microteslas.
 *
 * @property calibration evaluación de precisión, calibración
 * e interferencia magnética.
 */
data class CompassReading(
    val magneticHeading: Float,
    val pitch: Float,
    val roll: Float,
    val accuracy: SensorAccuracy,
    val magneticFieldStrength: Float?,
    val calibration: CalibrationAssessment =
        CalibrationAssessment.INITIALIZING
) {

    init {
        require(magneticHeading.isFinite()) {
            "El rumbo magnético debe ser un número finito."
        }

        require(
            magneticHeading >= MINIMUM_HEADING &&
                    magneticHeading < MAXIMUM_HEADING
        ) {
            "El rumbo magnético debe estar entre 0° y menos de 360°."
        }

        require(pitch.isFinite()) {
            "La inclinación pitch debe ser un número finito."
        }

        require(roll.isFinite()) {
            "La inclinación roll debe ser un número finito."
        }

        magneticFieldStrength?.let { strength ->
            require(strength.isFinite()) {
                "La intensidad magnética debe ser un número finito."
            }

            require(strength >= 0f) {
                "La intensidad magnética no puede ser negativa."
            }
        }
    }

    /**
     * Accesos simplificados para la futura capa de presentación.
     */
    val calibrationRequired: Boolean
        get() =
            calibration.calibrationRequired

    val magneticInterferenceDetected: Boolean
        get() =
            calibration.magneticInterferenceDetected

    companion object {
        private const val MINIMUM_HEADING = 0f
        private const val MAXIMUM_HEADING = 360f
    }
}

package com.tucodigocotidiano.smartcompass.domain

import com.tucodigocotidiano.smartcompass.sensor.SensorAccuracy
import kotlin.math.hypot

/**
 * Convierte los resultados matemáticos obtenidos de los sensores
 * en una lectura de brújula válida.
 *
 * Esta clase no depende de Android, SensorManager ni Compose.
 * Por ello puede probarse mediante pruebas unitarias locales.
 */
class CompassEngine {

    /**
     * Crea una lectura completa a partir de los ángulos de orientación
     * y de los tres componentes del campo magnético.
     *
     * Los valores de azimut, pitch y roll se reciben en radianes porque
     * SensorManager.getOrientation() utiliza esa unidad.
     */
    fun createReading(
        azimuthRadians: Float,
        pitchRadians: Float,
        rollRadians: Float,
        magneticFieldX: Float,
        magneticFieldY: Float,
        magneticFieldZ: Float,
        accuracy: SensorAccuracy
    ): CompassReading {
        requireOrientationValuesAreFinite(
            azimuthRadians = azimuthRadians,
            pitchRadians = pitchRadians,
            rollRadians = rollRadians
        )

        requireMagneticValuesAreFinite(
            magneticFieldX = magneticFieldX,
            magneticFieldY = magneticFieldY,
            magneticFieldZ = magneticFieldZ
        )

        val magneticHeading = AngleMath.normalizeDegrees(
            AngleMath.radiansToDegrees(azimuthRadians)
        )

        val pitchDegrees = AngleMath.radiansToDegrees(
            pitchRadians
        )

        val rollDegrees = AngleMath.radiansToDegrees(
            rollRadians
        )

        val magneticFieldStrength = calculateMagneticFieldStrength(
            magneticFieldX = magneticFieldX,
            magneticFieldY = magneticFieldY,
            magneticFieldZ = magneticFieldZ
        )

        return CompassReading(
            magneticHeading = magneticHeading,
            pitch = pitchDegrees,
            roll = rollDegrees,
            accuracy = accuracy,
            magneticFieldStrength = magneticFieldStrength
        )
    }

    /**
     * Calcula la magnitud del vector magnético:
     *
     * |B| = √(Bx² + By² + Bz²)
     *
     * El resultado se expresa en microteslas porque los valores del
     * magnetómetro de Android utilizan esa unidad.
     */
    fun calculateMagneticFieldStrength(
        magneticFieldX: Float,
        magneticFieldY: Float,
        magneticFieldZ: Float
    ): Float {
        requireMagneticValuesAreFinite(
            magneticFieldX = magneticFieldX,
            magneticFieldY = magneticFieldY,
            magneticFieldZ = magneticFieldZ
        )

        /*
         * hypot ofrece mayor estabilidad numérica que calcular
         * directamente x*x + y*y + z*z usando Float.
         */
        val xyMagnitude = hypot(
            magneticFieldX.toDouble(),
            magneticFieldY.toDouble()
        )

        val totalMagnitude = hypot(
            xyMagnitude,
            magneticFieldZ.toDouble()
        ).toFloat()

        require(totalMagnitude.isFinite()) {
            "La intensidad magnética calculada debe ser finita."
        }

        return totalMagnitude
    }

    private fun requireOrientationValuesAreFinite(
        azimuthRadians: Float,
        pitchRadians: Float,
        rollRadians: Float
    ) {
        require(azimuthRadians.isFinite()) {
            "El azimut debe ser un número finito."
        }

        require(pitchRadians.isFinite()) {
            "El pitch debe ser un número finito."
        }

        require(rollRadians.isFinite()) {
            "El roll debe ser un número finito."
        }
    }

    private fun requireMagneticValuesAreFinite(
        magneticFieldX: Float,
        magneticFieldY: Float,
        magneticFieldZ: Float
    ) {
        require(magneticFieldX.isFinite()) {
            "El componente X del campo magnético debe ser finito."
        }

        require(magneticFieldY.isFinite()) {
            "El componente Y del campo magnético debe ser finito."
        }

        require(magneticFieldZ.isFinite()) {
            "El componente Z del campo magnético debe ser finito."
        }
    }
}

Azimut en radianes
        ↓
Conversión a grados
        ↓
Normalización entre 0° y menos de 360°
        ↓
Rumbo magnético

Pitch y roll en radianes
        ↓
Conversión a grados
        ↓
Inclinaciones conservando el signo

Bx, By y Bz
        ↓
Magnitud del vector
        ↓
Intensidad en μT

Todos los resultados
        ↓
CompassReading

val engine =
    CompassEngine()

val reading =
    engine.createReading(
        azimuthRadians = 0f,
        pitchRadians = 0f,
        rollRadians = 0f,
        magneticFieldX = 3f,
        magneticFieldY = 4f,
        magneticFieldZ = 12f
    )

println(reading)

CompassReading(magneticHeading=0.0, pitch=0.0, roll=0.0, magneticFieldStrength=13.0)

.\gradlew.bat assembleDebug

BUILD SUCCESSFUL

package com.tucodigocotidiano.smartcompass.sensor

/**
 * Representa la calidad de los datos entregados por el magnetómetro.
 *
 * Esta enumeración no depende de las constantes de Android. La traducción
 * desde SensorManager.SENSOR_STATUS_* se realizará más adelante dentro
 * de AndroidCompassSensorSource.
 */
enum class SensorAccuracy {

    /**
     * Todavía no se ha recibido información de precisión.
     */
    UNKNOWN,

    /**
     * Los datos no deberían considerarse confiables.
     */
    UNRELIABLE,

    /**
     * La precisión es baja y probablemente requiere calibración.
     */
    LOW,

    /**
     * La precisión es suficiente para mostrar el rumbo.
     */
    MEDIUM,

    /**
     * El sensor informa su nivel más alto de precisión.
     */
    HIGH;

    /**
     * Indica si la precisión es suficientemente buena para utilizar
     * las lecturas normalmente.
     */
    val isReliable: Boolean
        get() = this == MEDIUM || this == HIGH

    /**
     * Indica si la interfaz debería recomendar una calibración.
     */
    val requiresCalibration: Boolean
        get() = when (this) {
            UNKNOWN,
            UNRELIABLE,
            LOW -> true

            MEDIUM,
            HIGH -> false
        }
}

package com.tucodigocotidiano.smartcompass.sensor

/**
 * Sensores físicos requeridos para calcular una orientación magnética.
 */
enum class RequiredSensor {
    ACCELEROMETER,
    MAGNETOMETER
}

/**
 * Describe qué sensores requeridos están disponibles en el teléfono.
 */
data class SensorAvailability(
    val accelerometerAvailable: Boolean,
    val magnetometerAvailable: Boolean
) {

    /**
     * La brújula necesita simultáneamente acelerómetro y magnetómetro.
     */
    val isCompassSupported: Boolean
        get() = accelerometerAvailable && magnetometerAvailable

    /**
     * Conjunto de sensores que no están disponibles.
     */
    val missingSensors: Set<RequiredSensor>
        get() {
            val missing = mutableSetOf<RequiredSensor>()

            if (!accelerometerAvailable) {
                missing += RequiredSensor.ACCELEROMETER
            }

            if (!magnetometerAvailable) {
                missing += RequiredSensor.MAGNETOMETER
            }

            return missing
        }

    companion object {

        /**
         * Estado utilizado cuando ambos sensores existen.
         */
        val ALL_AVAILABLE = SensorAvailability(
            accelerometerAvailable = true,
            magnetometerAvailable = true
        )

        /**
         * Estado utilizado cuando ninguno de los sensores existe.
         */
        val NONE_AVAILABLE = SensorAvailability(
            accelerometerAvailable = false,
            magnetometerAvailable = false
        )
    }
}

package com.tucodigocotidiano.smartcompass.sensor

import com.tucodigocotidiano.smartcompass.domain.CompassReading
import kotlinx.coroutines.flow.Flow

/**
 * Contrato utilizado para obtener lecturas de orientación.
 *
 * Las capas superiores dependerán de esta interfaz y no directamente
 * de SensorManager. Esto permite reemplazar la implementación real
 * por una fuente falsa durante las pruebas.
 */
interface CompassSensorSource {

    /**
     * Flujo de lecturas calculadas por la fuente.
     */
    val readings: Flow<CompassReading>

    /**
     * Sensores físicos disponibles en el dispositivo.
     */
    val availability: SensorAvailability

    /**
     * Indica si la fuente se encuentra activa.
     */
    val isRunning: Boolean

    /**
     * Inicia la producción de lecturas.
     *
     * La implementación debe permitir que llamar varias veces a start()
     * sea seguro.
     */
    fun start()

    /**
     * Detiene la producción de lecturas y libera los recursos asociados.
     *
     * La implementación debe permitir que llamar varias veces a stop()
     * sea seguro.
     */
    fun stop()
}

SensorManager y SensorEvent
          ↓
Implementación Android
          ↓
CompassSensorSource
          ↓
Flow<CompassReading>
          ↓
ViewModel y presentación

import com.tucodigocotidiano.smartcompass.sensor.SensorAccuracy

data class CompassReading(
    val magneticHeading: Float,
    val pitch: Float,
    val roll: Float,
    val accuracy: SensorAccuracy,
    val magneticFieldStrength: Float?
)

fun createReading(
    azimuthRadians: Float,
    pitchRadians: Float,
    rollRadians: Float,
    magneticFieldX: Float,
    magneticFieldY: Float,
    magneticFieldZ: Float,
    accuracy: SensorAccuracy
): CompassReading {
    // Se mantienen las conversiones y validaciones
    // implementadas en la sección anterior.

    return CompassReading(
        magneticHeading = magneticHeading,
        pitch = pitchDegrees,
        roll = rollDegrees,
        accuracy = accuracy,
        magneticFieldStrength =
            magneticFieldStrength
    )
}

val availability =
    SensorAvailability(
        accelerometerAvailable = true,
        magnetometerAvailable = false
    )

println(
    availability.isCompassSupported
)

println(
    availability.missingSensors
)

println(
    SensorAccuracy.MEDIUM.isReliable
)

false
[MAGNETOMETER]
true

.\gradlew.bat assembleDebug

BUILD SUCCESSFUL

package com.tucodigocotidiano.smartcompass.sensor

/**
 * Ejes lógicos que pueden utilizarse para expresar nuevamente
 * la matriz de rotación del dispositivo.
 *
 * Este enum no depende de las constantes de Android, por lo que
 * la selección de ejes puede probarse mediante pruebas JVM.
 */
enum class CoordinateAxis {
    X,
    Y,
    MINUS_X,
    MINUS_Y
}

/**
 * Pareja de ejes requerida por SensorManager.remapCoordinateSystem().
 *
 * Solo se especifican X e Y porque el tercer eje se obtiene
 * automáticamente mediante un producto vectorial.
 */
data class CoordinateAxisMapping(
    val xAxis: CoordinateAxis,
    val yAxis: CoordinateAxis
)

/**
 * Representa la rotación de la pantalla con respecto a su
 * orientación natural.
 */
enum class DisplayRotation(
    val degrees: Int
) {
    ROTATION_0(
        degrees = 0
    ),

    ROTATION_90(
        degrees = 90
    ),

    ROTATION_180(
        degrees = 180
    ),

    ROTATION_270(
        degrees = 270
    );

    /**
     * Ejes que permiten expresar la matriz de orientación con respecto
     * a la parte superior actual de la pantalla.
     */
    val axisMapping: CoordinateAxisMapping
        get() = when (this) {
            ROTATION_0 -> {
                CoordinateAxisMapping(
                    xAxis = CoordinateAxis.X,
                    yAxis = CoordinateAxis.Y
                )
            }

            ROTATION_90 -> {
                CoordinateAxisMapping(
                    xAxis = CoordinateAxis.Y,
                    yAxis = CoordinateAxis.MINUS_X
                )
            }

            ROTATION_180 -> {
                CoordinateAxisMapping(
                    xAxis = CoordinateAxis.MINUS_X,
                    yAxis = CoordinateAxis.MINUS_Y
                )
            }

            ROTATION_270 -> {
                CoordinateAxisMapping(
                    xAxis = CoordinateAxis.MINUS_Y,
                    yAxis = CoordinateAxis.X
                )
            }
        }
}

Rotación 0°
X → X
Y → Y

Rotación 90°
X → Y
Y → −X

Rotación 180°
X → −X
Y → −Y

Rotación 270°
X → −Y
Y → X

package com.tucodigocotidiano.smartcompass.sensor

/**
 * Abstracción para consultar la rotación actual de la pantalla.
 *
 * AndroidCompassSensorSource depende de esta interfaz en lugar
 * de consultar directamente WindowManager o Display.
 *
 * Esto permitirá reemplazarla por una implementación falsa
 * en pruebas futuras.
 */
fun interface DisplayRotationProvider {

    /**
     * Devuelve la rotación actual de la pantalla.
     */
    fun currentRotation(): DisplayRotation
}

val fakeRotationProvider =
    DisplayRotationProvider {
        DisplayRotation.ROTATION_90
    }

println(
    fakeRotationProvider
        .currentRotation()
        .degrees
)

90

package com.tucodigocotidiano.smartcompass.sensor

import android.content.Context
import android.os.Build
import android.view.Surface
import android.view.WindowManager

/**
 * Obtiene la rotación de la pantalla mediante las APIs de Android.
 *
 * En Android 11 y versiones posteriores se utiliza Context.display.
 *
 * Para Android 10 y anteriores se conserva una ruta de compatibilidad
 * mediante WindowManager.defaultDisplay, ya que el proyecto admite
 * dispositivos desde API 24.
 */
class AndroidDisplayRotationProvider(
    private val context: Context
) : DisplayRotationProvider {

    private val windowManager: WindowManager =
        context.getSystemService(
            Context.WINDOW_SERVICE
        ) as WindowManager

    override fun currentRotation(): DisplayRotation {
        return when (currentSurfaceRotation()) {
            Surface.ROTATION_0 ->
                DisplayRotation.ROTATION_0

            Surface.ROTATION_90 ->
                DisplayRotation.ROTATION_90

            Surface.ROTATION_180 ->
                DisplayRotation.ROTATION_180

            Surface.ROTATION_270 ->
                DisplayRotation.ROTATION_270

            else ->
                DisplayRotation.ROTATION_0
        }
    }

    private fun currentSurfaceRotation(): Int {
        return if (
            Build.VERSION.SDK_INT >= Build.VERSION_CODES.R
        ) {
            context.display?.rotation
                ?: Surface.ROTATION_0
        } else {
            /*
             * Context.display fue incorporado para sustituir
             * WindowManager.defaultDisplay en API 30.
             *
             * Esta rama solo se utiliza entre API 24 y API 29.
             */
            @Suppress("DEPRECATION")
            windowManager.defaultDisplay.rotation
        }
    }
}

val displayRotation =
    displayRotationProvider
        .currentRotation()

val axisMapping =
    displayRotation.axisMapping

.\gradlew.bat assembleDebug

BUILD SUCCESSFUL

package com.tucodigocotidiano.smartcompass.domain

/**
 * Resultado del análisis de la intensidad del campo magnético.
 *
 * La línea base no representa una verdad universal. Es una referencia
 * local aprendida durante los primeros segundos de funcionamiento.
 *
 * @property interferenceDetected indica si se detectó una alteración
 * magnética persistente.
 *
 * @property isBaselineReady indica si ya existen suficientes muestras
 * para utilizar la referencia local.
 *
 * @property baselineStrength intensidad magnética local de referencia,
 * expresada en microteslas.
 *
 * @property absoluteDeviation diferencia absoluta respecto a la línea base.
 *
 * @property relativeDeviation diferencia relativa respecto a la línea base.
 *
 * @property sampleCount cantidad de muestras magnéticas procesadas.
 */
data class MagneticFieldAssessment(
    val interferenceDetected: Boolean,
    val isBaselineReady: Boolean,
    val baselineStrength: Float?,
    val absoluteDeviation: Float?,
    val relativeDeviation: Float?,
    val sampleCount: Int
) {

    init {
        require(sampleCount >= 0) {
            "La cantidad de muestras no puede ser negativa."
        }

        baselineStrength?.let { baseline ->
            require(baseline.isFinite()) {
                "La línea base magnética debe ser finita."
            }

            require(baseline >= 0f) {
                "La línea base magnética no puede ser negativa."
            }
        }

        absoluteDeviation?.let { deviation ->
            require(deviation.isFinite()) {
                "La desviación absoluta debe ser finita."
            }

            require(deviation >= 0f) {
                "La desviación absoluta no puede ser negativa."
            }
        }

        relativeDeviation?.let { deviation ->
            require(deviation.isFinite()) {
                "La desviación relativa debe ser finita."
            }

            require(deviation >= 0f) {
                "La desviación relativa no puede ser negativa."
            }
        }
    }

    companion object {

        /**
         * Estado inicial antes de recibir datos del magnetómetro.
         */
        val INITIAL = MagneticFieldAssessment(
            interferenceDetected = false,
            isBaselineReady = false,
            baselineStrength = null,
            absoluteDeviation = null,
            relativeDeviation = null,
            sampleCount = 0
        )
    }
}

val initialAssessment =
    MagneticFieldAssessment.INITIAL

println(
    initialAssessment
        .isBaselineReady
)

println(
    initialAssessment
        .baselineStrength
)

println(
    initialAssessment
        .sampleCount
)

false
null
0

val currentFieldStrength =
    48f

val assessment =
    MagneticFieldAssessment(
        interferenceDetected = false,
        isBaselineReady = true,
        baselineStrength = 40f,
        absoluteDeviation = 8f,
        relativeDeviation = 0.20f,
        sampleCount = 30
    )

println(
    "Intensidad actual: " +
        "$currentFieldStrength μT"
)

println(
    "Referencia local: " +
        "${assessment.baselineStrength} μT"
)

println(
    "Desviación absoluta: " +
        "${assessment.absoluteDeviation} μT"
)

println(
    "Desviación relativa: " +
        "${assessment.relativeDeviation!! * 100f} %"
)

println(
    "Muestras: " +
        assessment.sampleCount
)

println(
    "Posible interferencia: " +
        assessment.interferenceDetected
)

Intensidad actual: 48.0 μT
Referencia local: 40.0 μT
Desviación absoluta: 8.0 μT
Desviación relativa: 20.0 %
Muestras: 30
Posible interferencia: false

Bx, By y Bz
      ↓
Magnitud actual en μT
      ↓
MagneticInterferenceDetector
      ↓
Referencia y desviaciones
      ↓
MagneticFieldAssessment
      ↓
Calibración y presentación

package com.tucodigocotidiano.smartcompass.domain

import kotlin.math.abs

/**
 * Detector adaptativo de interferencia magnética.
 *
 * No considera una cifra única como verdad absoluta. Primero aprende
 * una línea base local y después compara las lecturas nuevas contra
 * esa referencia.
 *
 * Para reducir falsas alarmas:
 *
 * - espera varias muestras antes de analizar;
 * - exige una desviación absoluta y relativa;
 * - exige varias anomalías consecutivas;
 * - exige varias muestras normales para recuperar el estado.
 *
 * También utiliza límites muy amplios únicamente como protección ante
 * lecturas extremas. Estos límites no representan una calibración
 * geográfica ni una medición científica del campo terrestre.
 */
class MagneticInterferenceDetector(
    private val warmupSamples: Int =
        DEFAULT_WARMUP_SAMPLES,
    private val baselineAlpha: Float =
        DEFAULT_BASELINE_ALPHA,
    private val relativeDeviationThreshold: Float =
        DEFAULT_RELATIVE_DEVIATION_THRESHOLD,
    private val minimumAbsoluteDeviation: Float =
        DEFAULT_MINIMUM_ABSOLUTE_DEVIATION,
    private val consecutiveAnomaliesRequired: Int =
        DEFAULT_CONSECUTIVE_ANOMALIES_REQUIRED,
    private val recoverySamplesRequired: Int =
        DEFAULT_RECOVERY_SAMPLES_REQUIRED,
    private val minimumGuardrail: Float =
        DEFAULT_MINIMUM_GUARDRAIL,
    private val maximumGuardrail: Float =
        DEFAULT_MAXIMUM_GUARDRAIL
) {

    init {
        require(warmupSamples > 0) {
            "La cantidad de muestras iniciales debe ser mayor que cero."
        }

        require(
            baselineAlpha.isFinite() &&
                    baselineAlpha > 0f &&
                    baselineAlpha <= 1f
        ) {
            "El factor de actualización debe estar entre 0 y 1."
        }

        require(
            relativeDeviationThreshold.isFinite() &&
                    relativeDeviationThreshold > 0f
        ) {
            "El umbral relativo debe ser mayor que cero."
        }

        require(
            minimumAbsoluteDeviation.isFinite() &&
                    minimumAbsoluteDeviation >= 0f
        ) {
            "La desviación absoluta mínima no puede ser negativa."
        }

        require(consecutiveAnomaliesRequired > 0) {
            "La cantidad de anomalías consecutivas debe ser mayor que cero."
        }

        require(recoverySamplesRequired > 0) {
            "La cantidad de muestras de recuperación debe ser mayor que cero."
        }

        require(
            minimumGuardrail.isFinite() &&
                    maximumGuardrail.isFinite() &&
                    minimumGuardrail >= 0f &&
                    maximumGuardrail > minimumGuardrail
        ) {
            "Los límites magnéticos deben formar un intervalo válido."
        }
    }

    private var baselineStrength: Float? = null

    private var samplesSeen = 0
    private var anomalyStreak = 0
    private var recoveryStreak = 0

    private var interferenceDetected = false

    /**
     * Procesa una nueva magnitud del campo magnético.
     */
    fun add(
        fieldStrength: Float
    ): MagneticFieldAssessment {
        require(
            fieldStrength.isFinite() &&
                    fieldStrength >= 0f
        ) {
            "La intensidad magnética debe ser finita y no negativa."
        }

        samplesSeen++

        val currentBaseline = baselineStrength

        if (currentBaseline == null) {
            baselineStrength = fieldStrength

            return createAssessment(
                fieldStrength = fieldStrength
            )
        }

        /*
         * Durante el calentamiento se utiliza una media acumulada.
         *
         * No se emiten alertas antes de reunir suficientes muestras,
         * porque los primeros valores del sensor pueden estar
         * transitorios.
         */
        if (samplesSeen <= warmupSamples) {
            val sampleWeight =
                1f / samplesSeen.toFloat()

            baselineStrength =
                currentBaseline +
                        (
                                fieldStrength -
                                        currentBaseline
                                ) * sampleWeight

            anomalyStreak = 0
            recoveryStreak = 0
            interferenceDetected = false

            return createAssessment(
                fieldStrength = fieldStrength
            )
        }

        val absoluteDeviation =
            abs(
                fieldStrength -
                        currentBaseline
            )

        val relativeDeviation =
            if (
                currentBaseline >
                MINIMUM_BASELINE_FOR_DIVISION
            ) {
                absoluteDeviation /
                        currentBaseline
            } else {
                null
            }

        /*
         * Una anomalía adaptativa necesita superar simultáneamente:
         *
         * - una diferencia mínima en microteslas;
         * - una diferencia proporcional respecto a la referencia.
         */
        val adaptiveAnomaly =
            relativeDeviation != null &&
                    absoluteDeviation >=
                    minimumAbsoluteDeviation &&
                    relativeDeviation >=
                    relativeDeviationThreshold

        /*
         * Los límites amplios actúan únicamente ante valores extremos.
         */
        val outsideGuardrails =
            fieldStrength < minimumGuardrail ||
                    fieldStrength > maximumGuardrail

        val anomalousSample =
            adaptiveAnomaly ||
                    outsideGuardrails

        if (anomalousSample) {
            anomalyStreak++
            recoveryStreak = 0

            if (
                anomalyStreak >=
                consecutiveAnomaliesRequired
            ) {
                interferenceDetected = true
            }
        } else {
            anomalyStreak = 0

            if (interferenceDetected) {
                recoveryStreak++

                if (
                    recoveryStreak >=
                    recoverySamplesRequired
                ) {
                    interferenceDetected = false
                    recoveryStreak = 0

                    /*
                     * Después de recuperarse se vuelve a centrar
                     * suavemente la referencia.
                     */
                    baselineStrength =
                        currentBaseline +
                                baselineAlpha *
                                (
                                        fieldStrength -
                                                currentBaseline
                                        )
                }
            } else {
                recoveryStreak = 0

                /*
                 * La referencia sigue lentamente los cambios normales
                 * del entorno sin perseguir alteraciones repentinas.
                 */
                baselineStrength =
                    currentBaseline +
                            baselineAlpha *
                            (
                                    fieldStrength -
                                            currentBaseline
                                    )
            }
        }

        return createAssessment(
            fieldStrength = fieldStrength
        )
    }

    /**
     * Elimina la referencia y todos los contadores.
     */
    fun reset() {
        baselineStrength = null

        samplesSeen = 0
        anomalyStreak = 0
        recoveryStreak = 0

        interferenceDetected = false
    }

    private fun createAssessment(
        fieldStrength: Float
    ): MagneticFieldAssessment {
        val baseline =
            baselineStrength

        val absoluteDeviation =
            baseline?.let { value ->
                abs(
                    fieldStrength -
                            value
                )
            }

        val relativeDeviation =
            if (
                baseline != null &&
                baseline >
                MINIMUM_BASELINE_FOR_DIVISION &&
                absoluteDeviation != null
            ) {
                absoluteDeviation /
                        baseline
            } else {
                null
            }

        return MagneticFieldAssessment(
            interferenceDetected =
                interferenceDetected,
            isBaselineReady =
                samplesSeen >= warmupSamples,
            baselineStrength =
                baseline,
            absoluteDeviation =
                absoluteDeviation,
            relativeDeviation =
                relativeDeviation,
            sampleCount =
                samplesSeen
        )
    }

    companion object {

        /**
         * Con SENSOR_DELAY_UI estas muestras suelen reunirse
         * rápidamente, pero evitan analizar los primeros transitorios.
         */
        const val DEFAULT_WARMUP_SAMPLES = 24

        /**
         * La referencia se actualiza lentamente.
         */
        const val DEFAULT_BASELINE_ALPHA = 0.04f

        /**
         * La lectura debe alejarse al menos un 45 % de la referencia.
         */
        const val DEFAULT_RELATIVE_DEVIATION_THRESHOLD =
            0.45f

        /**
         * Además debe existir una diferencia absoluta significativa.
         */
        const val DEFAULT_MINIMUM_ABSOLUTE_DEVIATION =
            15f

        /**
         * Una sola lectura extrema no activa la alarma.
         */
        const val DEFAULT_CONSECUTIVE_ANOMALIES_REQUIRED =
            4

        /**
         * La advertencia desaparece después de varias lecturas normales.
         */
        const val DEFAULT_RECOVERY_SAMPLES_REQUIRED =
            8

        /**
         * Límites amplios usados únicamente como señal auxiliar.
         */
        const val DEFAULT_MINIMUM_GUARDRAIL =
            8f

        const val DEFAULT_MAXIMUM_GUARDRAIL =
            120f

        private const val
                MINIMUM_BASELINE_FOR_DIVISION = 0.001f
    }
}

val detector =
    MagneticInterferenceDetector(
        warmupSamples = 3,
        baselineAlpha = 0.10f,
        relativeDeviationThreshold = 0.25f,
        minimumAbsoluteDeviation = 10f,
        consecutiveAnomaliesRequired = 2,
        recoverySamplesRequired = 3,
        minimumGuardrail = 5f,
        maximumGuardrail = 200f
    )

detector.add(40f)
detector.add(41f)

val baselineReady =
    detector.add(39f)

val firstAnomaly =
    detector.add(60f)

val secondAnomaly =
    detector.add(60f)

detector.add(40f)
detector.add(40f)

val recovered =
    detector.add(40f)

println(
    "Referencia lista: " +
        baselineReady.isBaselineReady
)

println(
    "Después de una anomalía: " +
        firstAnomaly.interferenceDetected
)

println(
    "Después de dos anomalías: " +
        secondAnomaly.interferenceDetected
)

println(
    "Después de tres lecturas normales: " +
        recovered.interferenceDetected
)

Referencia lista: true
Después de una anomalía: false
Después de dos anomalías: true
Después de tres lecturas normales: false

.\gradlew.bat assembleDebug

BUILD SUCCESSFUL

package com.tucodigocotidiano.smartcompass.domain

/**
 * Estado comprensible de calibración de la brújula.
 *
 * Este modelo no depende de Android ni de Compose.
 */
enum class CalibrationStatus(
    val requiresCalibration: Boolean
) {

    /**
     * Todavía no existe información suficiente.
     */
    INITIALIZING(
        requiresCalibration = false
    ),

    /**
     * Android informa precisión alta.
     */
    GOOD(
        requiresCalibration = false
    ),

    /**
     * Android informa precisión media.
     */
    ACCEPTABLE(
        requiresCalibration = false
    ),

    /**
     * Android informa precisión baja.
     */
    NEEDS_CALIBRATION(
        requiresCalibration = true
    ),

    /**
     * Android considera que los datos no son confiables.
     */
    UNRELIABLE(
        requiresCalibration = true
    )
}

package com.tucodigocotidiano.smartcompass.domain

/**
 * Evaluación completa de calibración.
 *
 * Combina:
 *
 * - precisión reportada por Android;
 * - comportamiento de la intensidad magnética;
 * - posible interferencia local.
 */
data class CalibrationAssessment(
    val status: CalibrationStatus,
    val magneticField: MagneticFieldAssessment
) {

    /**
     * Se recomienda calibrar cuando:
     *
     * - Android informa precisión baja o no confiable;
     * - se detecta una alteración magnética persistente.
     */
    val calibrationRequired: Boolean
        get() =
            status.requiresCalibration ||
                    magneticField.interferenceDetected

    /**
     * Acceso simplificado para las capas superiores.
     */
    val magneticInterferenceDetected: Boolean
        get() = magneticField.interferenceDetected

    /**
     * La lectura está lista cuando la precisión es suficiente,
     * existe una línea base y no hay interferencia.
     */
    val isReady: Boolean
        get() =
            (
                    status == CalibrationStatus.GOOD ||
                            status == CalibrationStatus.ACCEPTABLE
                    ) &&
                    magneticField.isBaselineReady &&
                    !magneticField.interferenceDetected

    companion object {

        val INITIALIZING = CalibrationAssessment(
            status = CalibrationStatus.INITIALIZING,
            magneticField = MagneticFieldAssessment.INITIAL
        )
    }
}

package com.tucodigocotidiano.smartcompass.domain

import com.tucodigocotidiano.smartcompass.sensor.SensorAccuracy

/**
 * Traduce la precisión técnica del magnetómetro a un estado
 * comprensible para la aplicación.
 *
 * No depende de Android ni de Compose.
 */
class CalibrationEvaluator {

    fun evaluate(
        accuracy: SensorAccuracy,
        magneticFieldAssessment: MagneticFieldAssessment
    ): CalibrationAssessment {
        val status = when (accuracy) {
            SensorAccuracy.UNKNOWN ->
                CalibrationStatus.INITIALIZING

            SensorAccuracy.UNRELIABLE ->
                CalibrationStatus.UNRELIABLE

            SensorAccuracy.LOW ->
                CalibrationStatus.NEEDS_CALIBRATION

            SensorAccuracy.MEDIUM ->
                CalibrationStatus.ACCEPTABLE

            SensorAccuracy.HIGH ->
                CalibrationStatus.GOOD
        }

        return CalibrationAssessment(
            status = status,
            magneticField = magneticFieldAssessment
        )
    }
}

SensorAccuracy
      ↓
CalibrationEvaluator
      ↓
CalibrationStatus
      │
      ├───────────────┐
      ↓               ↓
Precisión       MagneticFieldAssessment
                      ↓
          Referencia e interferencia
                      ↓
           CalibrationAssessment
                      ↓
     calibrationRequired / isReady

val evaluator =
    CalibrationEvaluator()

val stableMagneticField =
    MagneticFieldAssessment(
        interferenceDetected = false,
        isBaselineReady = true,
        baselineStrength = 42f,
        absoluteDeviation = 1f,
        relativeDeviation = 0.024f,
        sampleCount = 30
    )

val interferenceMagneticField =
    stableMagneticField.copy(
        interferenceDetected = true,
        absoluteDeviation = 22f,
        relativeDeviation = 0.52f
    )

val acceptable =
    evaluator.evaluate(
        accuracy = SensorAccuracy.MEDIUM,
        magneticFieldAssessment =
            stableMagneticField
    )

val lowAccuracy =
    evaluator.evaluate(
        accuracy = SensorAccuracy.LOW,
        magneticFieldAssessment =
            stableMagneticField
    )

val interference =
    evaluator.evaluate(
        accuracy = SensorAccuracy.HIGH,
        magneticFieldAssessment =
            interferenceMagneticField
    )

println(
    "Precisión media: " +
        "${acceptable.status}, " +
        "lista=${acceptable.isReady}"
)

println(
    "Precisión baja: " +
        "${lowAccuracy.status}, " +
        "calibrar=${lowAccuracy.calibrationRequired}"
)

println(
    "Precisión alta con interferencia: " +
        "${interference.status}, " +
        "lista=${interference.isReady}, " +
        "calibrar=${interference.calibrationRequired}"
)

Precisión media: ACCEPTABLE, lista=true
Precisión baja: NEEDS_CALIBRATION, calibrar=true
Precisión alta con interferencia: GOOD, lista=false, calibrar=true