From a32f43ec35c863da8fae9c1aa33252eb03b75992 Mon Sep 17 00:00:00 2001 From: YoungSoo Shin Date: Mon, 1 Sep 2025 12:49:15 +0900 Subject: [PATCH] Refactor: Add Doxygen comments for functions, enums, and macros in headers Signed-off-by: YoungSoo Shin --- main/include/indicator.h | 43 +++++++++++++++----- main/include/nconfig.h | 87 +++++++++++++++++++++++++++++----------- main/include/system.h | 29 ++++++++++++-- main/service/webserver.c | 1 + 4 files changed, 124 insertions(+), 36 deletions(-) diff --git a/main/include/indicator.h b/main/include/indicator.h index 40e9802..96a7b80 100644 --- a/main/include/indicator.h +++ b/main/include/indicator.h @@ -5,25 +5,50 @@ #ifndef LED_H #define LED_H +/** + * @brief Defines the different blinking patterns for the LEDs. + */ enum blink_type { - BLINK_SLOW = 0, - BLINK_FAST, - BLINK_DOUBLE, - BLINK_TRIPLE, - BLINK_SOLID, - BLINK_MAX, + BLINK_SLOW = 0, ///< Slow blinking pattern. + BLINK_FAST, ///< Fast blinking pattern. + BLINK_DOUBLE, ///< Double blink pattern. + BLINK_TRIPLE, ///< Triple blink pattern. + BLINK_SOLID, ///< Solid (always on) state. + BLINK_MAX, ///< Sentinel for the number of blink types. }; +/** + * @brief Defines the available LEDs that can be controlled. + */ enum blink_led { - LED_RED = 0, - LED_BLU = 1, - LED_MAX, + LED_RED = 0, ///< The red LED. + LED_BLU = 1, ///< The blue LED. + LED_MAX, ///< Sentinel for the number of LEDs. }; +/** + * @brief Initializes the LED indicator system. + * + * This function sets up the GPIOs and timers required for the LED blinking patterns. + * It should be called once during application startup. + */ void init_led(void); + +/** + * @brief Sets a specific blinking pattern for an LED. + * + * @param led The LED to control (e.g., LED_RED, LED_BLU). + * @param type The blinking pattern to apply (e.g., BLINK_FAST, BLINK_SOLID). + */ void led_set(enum blink_led led, enum blink_type type); + +/** + * @brief Turns off a specific LED. + * + * @param led The LED to turn off. + */ void led_off(enum blink_led led); #endif // LED_H diff --git a/main/include/nconfig.h b/main/include/nconfig.h index b1db042..d1d2b31 100644 --- a/main/include/nconfig.h +++ b/main/include/nconfig.h @@ -1,6 +1,7 @@ -// -// Created by shinys on 25. 7. 10. -// +/** + * @file nconfig.h + * @brief Provides an interface for managing system configuration using Non-Volatile Storage (NVS). + */ #ifndef NCONFIG_H #define NCONFIG_H @@ -8,41 +9,81 @@ #include "esp_err.h" #include "nvs.h" -#define NCONFIG_NVS_NAMESPACE "er" -#define NCONFIG_NOT_FOUND ESP_ERR_NVS_NOT_FOUND +#define NCONFIG_NVS_NAMESPACE "er" ///< The NVS namespace where all configurations are stored. +#define NCONFIG_NOT_FOUND ESP_ERR_NVS_NOT_FOUND ///< Alias for the NVS not found error code. +/** + * @brief Initializes the nconfig module. + * + * This function initializes the Non-Volatile Storage (NVS) component, which is required + * for all other nconfig operations. It should be called once at application startup. + * @return ESP_OK on success, or an error code on failure. + */ esp_err_t init_nconfig(); +/** + * @brief Defines the keys for all configuration values managed by nconfig. + */ enum nconfig_type { - WIFI_SSID, - WIFI_PASSWORD, - WIFI_MODE, - AP_SSID, - AP_PASSWORD, - NETIF_HOSTNAME, - NETIF_IP, - NETIF_GATEWAY, - NETIF_SUBNET, - NETIF_DNS1, - NETIF_DNS2, - NETIF_TYPE, - UART_BAUD_RATE, - NCONFIG_TYPE_MAX, + WIFI_SSID, ///< The SSID of the Wi-Fi network to connect to (STA mode). + WIFI_PASSWORD, ///< The password for the Wi-Fi network (STA mode). + WIFI_MODE, ///< The Wi-Fi operating mode (e.g., "sta" or "apsta"). + AP_SSID, ///< The SSID for the device's Access Point mode. + AP_PASSWORD, ///< The password for the device's Access Point mode. + NETIF_HOSTNAME, ///< The hostname of the device on the network. + NETIF_IP, ///< The static IP address for the STA interface. + NETIF_GATEWAY, ///< The gateway address for the STA interface. + NETIF_SUBNET, ///< The subnet mask for the STA interface. + NETIF_DNS1, ///< The primary DNS server address. + NETIF_DNS2, ///< The secondary DNS server address. + NETIF_TYPE, ///< The network interface type (e.g., "dhcp" or "static"). + UART_BAUD_RATE, ///< The baud rate for the UART communication. + NCONFIG_TYPE_MAX, ///< Sentinel for the maximum number of configuration types. }; +/** + * @brief Checks if a specific configuration value has been set. + * + * @param type The configuration key to check. + * @return True if the value is not set, false otherwise. + */ bool nconfig_value_is_not_set(enum nconfig_type type); -// Write config +/** + * @brief Writes a configuration value to NVS. + * + * @param type The configuration key to write. + * @param data A pointer to the string data to be stored. + * @return ESP_OK on success, or an error code on failure. + */ esp_err_t nconfig_write(enum nconfig_type type, const char* data); -// Check config is set and get config value length +/** + * @brief Gets the length of a stored string configuration value. + * + * @param type The configuration key to query. + * @param[out] len A pointer to a size_t variable to store the length. + * @return ESP_OK on success, NCONFIG_NOT_FOUND if the key doesn't exist, or another error code. + */ esp_err_t nconfig_get_str_len(enum nconfig_type type, size_t* len); -// Read config +/** + * @brief Reads a configuration value from NVS. + * + * @param type The configuration key to read. + * @param[out] data A buffer to store the read data. + * @param len The length of the buffer. It should be large enough to hold the value. + * @return ESP_OK on success, or an error code on failure. + */ esp_err_t nconfig_read(enum nconfig_type type, char* data, size_t len); -// Remove key +/** + * @brief Deletes a configuration key-value pair from NVS. + * + * @param type The configuration key to delete. + * @return ESP_OK on success, or an error code on failure. + */ esp_err_t nconfig_delete(enum nconfig_type type); #endif // NCONFIG_H diff --git a/main/include/system.h b/main/include/system.h index e61057c..6db419d 100644 --- a/main/include/system.h +++ b/main/include/system.h @@ -1,12 +1,33 @@ -// -// Created by shinys on 25. 8. 5. -// +/** + * @file system.h + * @brief Declares system-level functions for core operations like rebooting and starting services. + */ #ifndef SYSTEM_H #define SYSTEM_H +/** + * @brief Starts a timer that will reboot the system after a specified duration. + * + * This function is non-blocking. It schedules a system reboot to occur in the future. + * @param sec The number of seconds to wait before rebooting. + */ void start_reboot_timer(int sec); + +/** + * @brief Stops any pending reboot timer that was previously started. + * + * If a reboot timer is active, this function will cancel it, preventing the system from rebooting. + */ void stop_reboot_timer(); -void start_webserver(); + +/** + * @brief Initializes and starts the main web server. + * + * This function sets up the HTTP server, registers all URI handlers for web pages, + * API endpoints (like control and settings), and the WebSocket endpoint. It also + * initializes the status monitor that provides real-time data. + */ +void start_webserver(void); #endif // SYSTEM_H diff --git a/main/service/webserver.c b/main/service/webserver.c index 0518b56..ca42bf0 100644 --- a/main/service/webserver.c +++ b/main/service/webserver.c @@ -11,6 +11,7 @@ #include "lwip/sys.h" #include "monitor.h" #include "nconfig.h" +#include "system.h" static const char* TAG = "WEBSERVER";