error handling and cleanup

main/inputs.h

@@ -1,59 +1,133 @@
+/**
+ * @file inputs.h
+ * @brief Input handling for temperature sensors and burner fault detection.
+ *
+ * This module reads DS18B20 temperature sensors via 1-Wire and monitors
+ * the burner fault input. It provides averaged, damped, and predicted
+ * temperature values.
+ */
+
 #pragma once
 
 #include "sdkconfig.h"
 
+#include "esp_err.h"
+
 #include <stddef.h>
 
+/** @brief Returns the maximum of two values. */
 #define MAX(a, b) ((a) > (b) ? (a) : (b))
+
+/** @brief Initial value for measurements before first reading. */
 #define INITIALISATION_VALUE 0.0f
+
+/** @brief Sample buffer size for 10-second average. */
 #define AVG10S_SAMPLE_SIZE 10U
+
+/** @brief Sample buffer size for 60-second average. */
 #define AVG60S_SAMPLE_SIZE 60U
+
+/** @brief Sample buffer size for 24-hour average. */
 #define AVG24H_SAMPLE_SIZE 24U
+
+/** @brief Sample buffer size for 60-second prediction. */
 #define PRED60S_SAMPLE_SIZE 60U
+
+/** @brief Damping factor for rising temperatures (from Kconfig). */
 #define DAMPING_FACTOR_WARMER (CONFIG_DAMPING_FACTOR_WARMER * 0.00001f)
+
+/** @brief Damping factor for falling temperatures (from Kconfig). */
 #define DAMPING_FACTOR_COLDER (CONFIG_DAMPING_FACTOR_COLDER * 0.00001f)
 
+/**
+ * @brief Burner error state enumeration.
+ */
 typedef enum _BurnerErrorState
 {
-    NO_ERROR,
-    FAULT
+    NO_ERROR, /**< No burner fault detected. */
+    FAULT     /**< Burner fault signal active. */
 } eBurnerErrorState;
 
+/**
+ * @brief Measurement error state enumeration.
+ */
 typedef enum _MeasurementErrorState
 {
-    MEASUREMENT_NO_ERROR,
-    MEASUREMENT_FAULT
+    MEASUREMENT_NO_ERROR, /**< Measurement valid. */
+    MEASUREMENT_FAULT     /**< Measurement failed or sensor not found. */
 } eMeasurementErrorState;
 
+/**
+ * @brief Circular buffer for averaging temperature values.
+ */
 typedef struct _Average
 {
-    float fValue;
-    float samples[MAX(AVG10S_SAMPLE_SIZE, MAX(AVG60S_SAMPLE_SIZE, AVG24H_SAMPLE_SIZE))];
-    size_t bufferIndex;
-    size_t bufferCount;
+    float fValue;                                                                        /**< Current average value. */
+    float samples[MAX(AVG10S_SAMPLE_SIZE, MAX(AVG60S_SAMPLE_SIZE, AVG24H_SAMPLE_SIZE))]; /**< Sample buffer. */
+    size_t bufferIndex;                                                                  /**< Current write index. */
+    size_t bufferCount;                                                                  /**< Number of valid samples. */
 } sAverage;
 
+/**
+ * @brief Circular buffer for temperature prediction.
+ */
 typedef struct _Predict
 {
-    float fValue;
-    float samples[PRED60S_SAMPLE_SIZE];
-    size_t bufferIndex;
-    size_t bufferCount;
+    float fValue;                       /**< Predicted value. */
+    float samples[PRED60S_SAMPLE_SIZE]; /**< Sample buffer. */
+    size_t bufferIndex;                 /**< Current write index. */
+    size_t bufferCount;                 /**< Number of valid samples. */
 } sPredict;
 
+/**
+ * @brief Complete measurement data structure.
+ */
 typedef struct _Measurement
 {
-    float fCurrentValue;
-    float fDampedValue;
-    sAverage average10s;
-    sAverage average60s;
-    sPredict predict60s;
-    eMeasurementErrorState state;
+    float fCurrentValue;          /**< Current raw temperature value. */
+    float fDampedValue;           /**< Damped temperature value. */
+    sAverage average10s;          /**< 10-second rolling average. */
+    sAverage average60s;          /**< 60-second rolling average. */
+    sPredict predict60s;          /**< 60-second prediction. */
+    eMeasurementErrorState state; /**< Measurement state. */
 } sMeasurement;
 
-void initInputs(void);
+/**
+ * @brief Initialize the inputs module.
+ *
+ * Configures GPIO for burner fault input and starts the input task
+ * for reading DS18B20 temperature sensors.
+ *
+ * @return ESP_OK on success, ESP_FAIL on error.
+ */
+esp_err_t initInputs(void);
+
+/**
+ * @brief Get the current chamber temperature measurement.
+ * @return sMeasurement structure with current values and state.
+ */
 sMeasurement getChamberTemperature(void);
+
+/**
+ * @brief Get the current outdoor temperature measurement.
+ * @return sMeasurement structure with current values and state.
+ */
 sMeasurement getOutdoorTemperature(void);
+
+/**
+ * @brief Get the current inlet flow temperature measurement.
+ * @return sMeasurement structure with current values and state.
+ */
 sMeasurement getInletFlowTemperature(void);
+
+/**
+ * @brief Get the current return flow temperature measurement.
+ * @return sMeasurement structure with current values and state.
+ */
 sMeasurement getReturnFlowTemperature(void);
+
+/**
+ * @brief Get the current burner error state.
+ * @return eBurnerErrorState indicating fault status.
+ */
 eBurnerErrorState getBurnerError(void);