error.rs

//! Error types for the firmware.

use esp_idf_svc::sys::EspError;
use std::{fmt::Display, string::FromUtf8Error};
use thiserror::Error;

/// A wrapper for several different lower-level error types.
#[allow(clippy::doc_markdown)]
#[derive(Debug, Error)]
pub enum OsError {
    /// Failed to initialize WiFi.
    #[error("wifi init: {0}")]
    WifiInit(EspError),

    /// Failed to connect to WiFi AP.
    #[error("wifi connect: {0}")]
    WifiConnect(EspError),

    /// Failed to set up a WiFi parameter.
    #[error("wifi param: {0}")]
    WifiParam(EspError),

    /// Failed to set WiFi configuration.
    #[error("wifi config: {0}")]
    WifiConfig(EspError),

    /// Failed to start the WiFi interface.
    #[error("wifi start: {0}")]
    WifiStart(EspError),

    /// Failed to start AP scan or fetch the results.
    #[error("wifi scan: {0}")]
    WifiScan(EspError),

    /// Failed to read WiFi interface information.
    #[error("wifi info read: {0}")]
    WifiInfo(EspError),

    /// Failed to find password for the specified AP.
    #[error("wifi psk not found")]
    WifiPskNotFound,

    /// Timeout while waiting for an event.
    #[error("event timeout: {0}")]
    EventTimeout(EspError),

    /// Failed to initialize event waiter ([Wait](esp_idf_svc::eventloop::Wait)).
    #[error("event waiter: {0}")]
    EventWaiterInit(EspError),

    /// No usable AP found.
    #[error("offline")]
    NoInternet,

    /// Error during connecting to or processing data from the PWMP server.
    #[error("pwmp: {0}")]
    PwmpError(#[from] pwmp_client::error::Error),

    /// No environment sensor detected.
    #[error("environment sensor")]
    NoEnvSensor,

    /// OTA module or update initialization has failed.
    #[error("Failed to initialize an OTA update ({0})")]
    OtaInit(EspError),

    /// Failed to write an OTA update chunk to flash.
    #[error("OTA chunk write failed ({0})")]
    OtaWrite(EspError),

    /// Failed to abort OTA update.
    #[error("OTA abort failed ({0})")]
    OtaAbort(EspError),

    /// An I/O operation on an OTA slot failed.
    #[error("Failed to operate on an OTA slot ({0})")]
    OtaSlot(EspError),

    /// NVS initialization has failed
    #[error("Failed to initialize NVS ({0})")]
    NvsInit(EspError),

    /// Error while reading from NVS.
    #[error("Failed to read from NVS ({0})")]
    NvsRead(EspError),

    /// Error while writing to NVS.
    #[error("Failed to write to NVS ({0})")]
    NvsWrite(EspError),

    /// Failed to initialize a GPIO pin.
    #[error("Failed to initialize a GPIO pin ({0})")]
    GpioInit(EspError),

    /// Failed to initialize ADC.
    #[error("Failed to initialize ADC ({0})")]
    AdcInit(EspError),

    /// Failed to read from the ADC.
    #[error("Failed to read ADC ({0})")]
    AdcRead(EspError),

    /// Error while performing a write-read operation on I2C.
    #[error("Failed to perform W/R on I2C ({esp_err}): Write {data:?} to addr {addr}")]
    I2cWr {
        data: heapless::Vec<u8, 4>,
        addr: u8,
        esp_err: EspError,
    },

    /// Error while performing a write operation on I2C.
    #[error("Failed to perform write on I2C ({esp_err}): Write {data:?} to addr {addr}")]
    I2cWrite {
        data: heapless::Vec<u8, 4>,
        addr: u8,
        esp_err: EspError,
    },

    /// Specified parameter was too long.
    #[error("Argument too long")]
    ArgumentTooLong,

    /// Partition metadata contains an invalid version string.
    #[error("Unexpected version format")]
    IllegalFirmwareVersion,

    /// Partition metadata is missing.
    #[error("Unexpected version format")]
    MissingPartitionMetadata,

    /// A buffer has been filled unexpectedly
    #[error("A buffer capacity has been exceeded")]
    UnexpectedBufferFailiure,

    /// A value was `None`, when `Some(..)` was expected.
    #[error("Unexpected NULL")]
    UnexpectedNull,

    /// Expected a UTF-8 string.
    #[error("String is not UTF-8 encoded")]
    InvalidUtf8(#[from] FromUtf8Error),

    /// Key not found in NVS storage.
    #[error("NVS key does not exist")]
    InvalidNvsKey,

    /// Failed to read data from internal temperature sensor.
    #[error("Failed to read internal temperature sensor")]
    InternalTempSensorRead(EspError),
}

/// Trait for non-fatal error types that can be "reported" to the console.
///
/// This trait is meant to be implemented for [`Result`]s.
pub trait ReportableError {
    /// Log a warning to the console if the [`Result`] variant is an [`Err`], or do nothing if it's [`Ok`].
    fn report(self, desc: &str);
}

impl<T, E: Display> ReportableError for Result<T, E> {
    fn report(self, desc: &str) {
        if let Err(why) = self {
            log::warn!("{desc}: {why}");
        }
    }
}

impl OsError {
    /// Returns whether the error is non-fatal.
    ///
    /// This returns `true`, for errors related to WiFi/Internet and PWNP connectivity/IO issues.
    pub const fn recoverable(&self) -> bool {
        matches!(
            self,
            Self::WifiConnect(..) | Self::NoInternet | Self::PwmpError(..)
        )
    }

    pub fn from_i2c_writeop(
        result: Result<(), EspError>,
        addr: u8,
        data: &[u8],
        wr: bool,
    ) -> Result<(), Self> {
        let Err(why) = result else {
            return Ok(());
        };

        let mut data_copy = heapless::Vec::<u8, 4>::new();

        // SAFETY: The copy operation will copy only as much as the vec can hold.
        unsafe { data_copy.extend_from_slice(data).unwrap_unchecked() };

        if wr {
            Err(Self::I2cWr {
                data: data_copy,
                addr,
                esp_err: why,
            })
        } else {
            Err(Self::I2cWrite {
                data: data_copy,
                addr,
                esp_err: why,
            })
        }
    }
}