error handling and cleanup

main/safety.h

@@ -1,56 +1,117 @@
+/**
+ * @file safety.h
+ * @brief Safety monitoring for temperature sensors.
+ *
+ * This module performs sanity checks on all temperature sensors and
+ * puts the system into a safe state if any sensor fails.
+ */
+
 #pragma once
 
 #include "outputs.h"
 #include "inputs.h"
 
 #include "sdkconfig.h"
+#include "esp_err.h"
 
 #include <stdint.h>
 
+/** @brief Maximum length of sensor name string. */
 #define MAX_ERROR_STRING_SIZE 64U
+
+/** @brief Number of sensors to monitor. */
 #define NUMBER_OF_SENSOR_SANITY_CHECKS 4U
 
+/** @brief Chamber sensor maximum temperature limit (°C). */
 #define SENSOR_LIMIT_CHAMBER_MAX (CONFIG_SENSOR_LIMIT_CHAMBER_MAX / 10.0f)
+
+/** @brief Chamber sensor minimum temperature limit (°C). */
 #define SENSOR_LIMIT_CHAMBER_MIN (CONFIG_SENSOR_LIMIT_CHAMBER_MIN / 10.0f)
+
+/** @brief Outdoor sensor maximum temperature limit (°C). */
 #define SENSOR_LIMIT_OUTDOOR_MAX (CONFIG_SENSOR_LIMIT_OUTDOOR_MAX / 10.0f)
+
+/** @brief Outdoor sensor minimum temperature limit (°C). */
 #define SENSOR_LIMIT_OUTDOOR_MIN (CONFIG_SENSOR_LIMIT_OUTDOOR_MIN / 10.0f)
+
+/** @brief Inlet flow sensor maximum temperature limit (°C). */
 #define SENSOR_LIMIT_INLET_MAX (CONFIG_SENSOR_LIMIT_INLET_MAX / 10.0f)
+
+/** @brief Inlet flow sensor minimum temperature limit (°C). */
 #define SENSOR_LIMIT_INLET_MIN (CONFIG_SENSOR_LIMIT_INLET_MIN / 10.0f)
+
+/** @brief Return flow sensor maximum temperature limit (°C). */
 #define SENSOR_LIMIT_RETURN_MAX (CONFIG_SENSOR_LIMIT_RETURN_MAX / 10.0f)
+
+/** @brief Return flow sensor minimum temperature limit (°C). */
 #define SENSOR_LIMIT_RETURN_MIN (CONFIG_SENSOR_LIMIT_RETURN_MIN / 10.0f)
 
+/**
+ * @brief Sensor error state enumeration.
+ */
 typedef enum _SensorErrorState
 {
-    SENSOR_NO_ERROR,
-    SENSOR_TOO_HIGH,
-    SENSOR_TOO_LOW,
-    SENSOR_UNCHANGED,
-    SENSOR_NOT_FOUND
+    SENSOR_NO_ERROR,  /**< Sensor operating normally. */
+    SENSOR_TOO_HIGH,  /**< Temperature above maximum limit. */
+    SENSOR_TOO_LOW,   /**< Temperature below minimum limit. */
+    SENSOR_UNCHANGED, /**< Temperature unchanged for too long. */
+    SENSOR_NOT_FOUND  /**< Sensor not responding. */
 } eSensorErrorState;
 
+/**
+ * @brief Overall safety state enumeration.
+ */
 typedef enum _SafetyState
 {
-    SAFETY_NO_ERROR,
-    SAFETY_SENSOR_ERROR,
-    SAFETY_INTERNAL_ERROR
+    SAFETY_NO_ERROR,      /**< All sensors OK. */
+    SAFETY_SENSOR_ERROR,  /**< At least one sensor failed. */
+    SAFETY_INTERNAL_ERROR /**< Internal module error. */
 } eSafetyState;
 
+/**
+ * @brief Function pointer type for sensor getter functions.
+ */
 typedef sMeasurement (*GetSensorValue)();
+
+/**
+ * @brief Temperature sensor limits.
+ */
 typedef struct _TemperatureSensorLimit
 {
-    float max; // Maximum temperature limit
-    float min; // Minimum temperature limit
+    float max; /**< Maximum temperature limit. */
+    float min; /**< Minimum temperature limit. */
 } sTemperatureSensorLimit;
+
+/**
+ * @brief Sensor sanity check state structure.
+ */
 typedef struct _SensorSanityCheck
 {
-    eSensorErrorState state;
-    char name[MAX_ERROR_STRING_SIZE];
-    sTemperatureSensorLimit sSensorLimit;
-    float fSensorTemperatureLast;
-    uint32_t uUnchangedCounter;
-    GetSensorValue getSensor;
+    eSensorErrorState state;              /**< Current error state. */
+    char name[MAX_ERROR_STRING_SIZE];     /**< Sensor name for logging. */
+    sTemperatureSensorLimit sSensorLimit; /**< Temperature limits. */
+    float fSensorTemperatureLast;         /**< Last temperature reading. */
+    uint32_t uUnchangedCounter;           /**< Counter for unchanged readings. */
+    GetSensorValue getSensor;             /**< Function to get sensor value. */
 } sSensorSanityCheck;
 
-void initSafety(void);
+/**
+ * @brief Initialize the safety module.
+ *
+ * Creates the safety monitoring task and sets initial safe state.
+ *
+ * @return ESP_OK on success, ESP_FAIL on error.
+ */
+esp_err_t initSafety(void);
+
+/**
+ * @brief Get the current sensor sanity states.
+ * @param[out] pSensorSanityChecks Array to receive sensor states.
+ */
 void getSensorSanityStates(sSensorSanityCheck *pSensorSanityChecks);
-eSafetyState getSafetyState(void);
+
+/**
+ * @brief Get the overall safety state.
+ * @return eSafetyState indicating current safety status.
+ */
+eSafetyState getSafetyState(void);