error handling and cleanup

main/control.h

@@ -1,38 +1,74 @@
+/**
+ * @file control.h
+ * @brief Heating control logic with schedule-based temperature management.
+ *
+ * This module implements the main heating control loop. It manages
+ * burner operation based on time schedules, temperature targets,
+ * and summer mode detection.
+ */
+
 #pragma once
 
 #include "sdkconfig.h"
+#include "esp_err.h"
 
-#include <time.h>
+#include <stdint.h>
+#include <stddef.h>
 
+/** @brief Maximum number of temperature entries per day. */
 #define MAX_TEMPERATURE_ENTRIES_PER_DAY 24U
 
+/** @brief Return flow target temperature for day mode (°C). */
 #define RETURN_FLOW_TEMPERATURE_LOWER_LIMIT_DAY (CONFIG_TEMP_RETURN_FLOW_LOWER_LIMIT_DAY / 10.0f)
+
+/** @brief Return flow target temperature for night mode (°C). */
 #define RETURN_FLOW_TEMPERATURE_LOWER_LIMIT_NIGHT (CONFIG_TEMP_RETURN_FLOW_LOWER_LIMIT_NIGHT / 10.0f)
+
+/** @brief Chamber target temperature (°C). */
 #define CHAMBER_TEMPERATURE_TARGET (CONFIG_TEMP_CHAMBER_TARGET / 10.0f)
+
+/** @brief Chamber temperature threshold to enable burner (°C). */
 #define CHAMBER_TEMPERATURE_THRESHOLD (CONFIG_TEMP_CHAMBER_THRESHOLD / 10.0f)
+
+/** @brief Outdoor temperature to activate summer mode (°C). */
 #define SUMMER_MODE_TEMPERATURE_THRESHOLD_HIGH (CONFIG_TEMP_SUMMER_MODE_HIGH / 10.0f)
+
+/** @brief Outdoor temperature to deactivate summer mode (°C). */
 #define SUMMER_MODE_TEMPERATURE_THRESHOLD_LOW (CONFIG_TEMP_SUMMER_MODE_LOW / 10.0f)
+
+/** @brief Chamber temperature threshold for circulation pump (°C). */
 #define CIRCULATION_PUMP_TEMPERATURE_THRESHOLD (CONFIG_TEMP_CIRCULATION_PUMP_THRESHOLD / 10.0f)
+
+/** @brief Time to wait before checking burner fault (seconds). */
 #define BURNER_FAULT_DETECTION_THRESHOLD CONFIG_BURNER_FAULT_DETECTION_SECONDS
 
+/**
+ * @brief Control state enumeration.
+ */
 typedef enum _ControlState
 {
-    CONTROL_STARTING,
-    CONTROL_HEATING,
-    CONTROL_OUTDOOR_TOO_WARM,
-    CONTROL_RETURN_FLOW_TOO_WARM,
-    CONTROL_FAULT_BURNER,
-    CONTROL_FAULT_SAFETY,
-    CONTROL_FAULT_SNTP,
+    CONTROL_STARTING,             /**< System starting up. */
+    CONTROL_HEATING,              /**< Burner running. */
+    CONTROL_OUTDOOR_TOO_WARM,     /**< Summer mode active. */
+    CONTROL_RETURN_FLOW_TOO_WARM, /**< Target temperature reached. */
+    CONTROL_FAULT_BURNER,         /**< Burner fault detected. */
+    CONTROL_FAULT_SAFETY,         /**< Safety fault detected. */
+    CONTROL_FAULT_SNTP,           /**< SNTP sync failed. */
 } eControlState;
 
+/**
+ * @brief Burner operational state enumeration.
+ */
 typedef enum _BurnerState
 {
-    BURNER_UNKNOWN, // Burner is disabled or state after enabling is still unkown
-    BURNER_FIRED,   // Burner fired successfully
-    BURNER_FAULT    // Burner was unable to fire successfully
+    BURNER_UNKNOWN, /**< Burner state unknown after enable. */
+    BURNER_FIRED,   /**< Burner fired successfully. */
+    BURNER_FAULT    /**< Burner failed to fire. */
 } eBurnerState;
 
+/**
+ * @brief Weekday enumeration (Monday = 0).
+ */
 typedef enum _ControlWeekday
 {
     MONDAY,
@@ -44,27 +80,58 @@ typedef enum _ControlWeekday
     SUNDAY,
 } eControlWeekday;
 
+/**
+ * @brief Time of day structure.
+ */
 typedef struct _ControlTimestamp
 {
-    uint8_t hour;
-    uint8_t minute;
+    uint8_t hour;   /**< Hour (0-23). */
+    uint8_t minute; /**< Minute (0-59). */
 } sControlTimestamp;
 
+/**
+ * @brief Temperature schedule entry.
+ */
 typedef struct _ControlTemperatureEntry
 {
-    sControlTimestamp timestamp;
-    float fReturnFlowTemperature;
-    float fChamberTemperature;
+    sControlTimestamp timestamp;  /**< Time when entry becomes active. */
+    float fReturnFlowTemperature; /**< Target return flow temperature. */
+    float fChamberTemperature;    /**< Target chamber temperature. */
 } sControlTemperatureEntry;
 
+/**
+ * @brief Daily schedule structure.
+ */
 typedef struct _ControlDay
 {
-    eControlWeekday day;
-    size_t entryCount; // number of entries for each day
-    sControlTemperatureEntry aTemperatureEntries[MAX_TEMPERATURE_ENTRIES_PER_DAY];
+    eControlWeekday day;                                                           /**< Day of week. */
+    size_t entryCount;                                                             /**< Number of entries for this day. */
+    sControlTemperatureEntry aTemperatureEntries[MAX_TEMPERATURE_ENTRIES_PER_DAY]; /**< Schedule entries. */
 } sControlDay;
 
-void initControl(void);
+/**
+ * @brief Initialize the control module.
+ *
+ * Creates the control task that manages heating operation.
+ *
+ * @return ESP_OK on success, ESP_FAIL on error.
+ */
+esp_err_t initControl(void);
+
+/**
+ * @brief Get the current control state.
+ * @return eControlState indicating current operation mode.
+ */
 eControlState getControlState(void);
+
+/**
+ * @brief Get the current weekday.
+ * @return eControlWeekday (Monday = 0, Sunday = 6).
+ */
 eControlWeekday getControlCurrentWeekday(void);
+
+/**
+ * @brief Get the currently active temperature entry.
+ * @return sControlTemperatureEntry with current targets.
+ */
 sControlTemperatureEntry getControlCurrentTemperatureEntry(void);