maxxfan-controller/main/wifi_manager.h

#ifndef WIFI_MANAGER_H
#define WIFI_MANAGER_H

#include "esp_err.h"
#include "esp_wifi.h"
#include "esp_netif.h"
#include <stdbool.h>
#include <stdint.h>

// WiFi connection status
typedef enum {
    WIFI_STATUS_DISCONNECTED,
    WIFI_STATUS_CONNECTING,
    WIFI_STATUS_CONNECTED,
    WIFI_STATUS_FAILED,
    WIFI_STATUS_RECONNECTING
} wifi_status_t;

// WiFi connection information
typedef struct {
    wifi_status_t status;
    char ssid[33];              // WiFi SSID (max 32 chars + null terminator)
    uint32_t ip_address;        // IP address (0 if not connected)
    int8_t rssi;               // Signal strength in dBm
    uint8_t retry_count;        // Current retry attempt
    uint32_t connect_time_ms;   // Time since connection started
    bool auto_reconnect;        // Whether auto-reconnect is enabled
} wifi_info_t;

/**
 * @brief Initialize the WiFi manager
 * 
 * Sets up WiFi in station mode and prepares for connection.
 * Must be called before any other WiFi manager functions.
 * 
 * @return ESP_OK on success, ESP_FAIL on error
 */
esp_err_t wifi_manager_init(void);

/**
 * @brief Connect to WiFi network with specified credentials
 * 
 * Attempts to connect to the specified WiFi network. This function
 * returns immediately and connection happens asynchronously.
 * 
 * @param ssid WiFi network name (max 32 characters)
 * @param password WiFi password (max 64 characters)
 * @param max_retries Maximum number of connection attempts (0 = infinite)
 * @return ESP_OK if connection attempt started, ESP_FAIL on error
 */
esp_err_t wifi_manager_connect(const char* ssid, const char* password, uint8_t max_retries);

/**
 * @brief Connect using credentials from config.h
 * 
 * Convenience function that uses WIFI_SSID and WIFI_PASS from config.h
 * with WIFI_MAXIMUM_RETRY attempts.
 * 
 * @return ESP_OK if connection attempt started, ESP_FAIL on error
 */
esp_err_t wifi_manager_connect_default(void);

/**
 * @brief Disconnect from WiFi network
 * 
 * @return ESP_OK on success, ESP_FAIL on error
 */
esp_err_t wifi_manager_disconnect(void);

/**
 * @brief Get current WiFi connection status
 * 
 * @return Current WiFi status
 */
wifi_status_t wifi_manager_get_status(void);

/**
 * @brief Get comprehensive WiFi information
 * 
 * @param info Pointer to wifi_info_t structure to fill
 * @return ESP_OK on success, ESP_ERR_INVALID_ARG if info is NULL
 */
esp_err_t wifi_manager_get_info(wifi_info_t* info);

/**
 * @brief Check if WiFi is connected
 * 
 * @return true if connected, false otherwise
 */
bool wifi_manager_is_connected(void);

/**
 * @brief Get current IP address
 * 
 * @return IP address as uint32_t (0 if not connected)
 */
uint32_t wifi_manager_get_ip(void);

/**
 * @brief Get current IP address as string
 * 
 * @param ip_str Buffer to store IP string (minimum 16 bytes)
 * @param max_len Maximum length of buffer
 * @return ESP_OK on success, ESP_ERR_INVALID_ARG on error
 */
esp_err_t wifi_manager_get_ip_string(char* ip_str, size_t max_len);

/**
 * @brief Get signal strength (RSSI)
 * 
 * @return Signal strength in dBm (0 if not connected)
 */
int8_t wifi_manager_get_rssi(void);

/**
 * @brief Enable or disable auto-reconnect
 * 
 * When enabled, the WiFi manager will automatically attempt to reconnect
 * if the connection is lost.
 * 
 * @param enable true to enable auto-reconnect, false to disable
 * @return ESP_OK on success
 */
esp_err_t wifi_manager_set_auto_reconnect(bool enable);

/**
 * @brief Wait for WiFi connection to complete
 * 
 * Blocks until WiFi connection succeeds or fails. Useful for synchronous
 * operation during initialization.
 * 
 * @param timeout_ms Maximum time to wait in milliseconds (0 = wait forever)
 * @return ESP_OK if connected, ESP_ERR_TIMEOUT if timeout, ESP_FAIL if connection failed
 */
esp_err_t wifi_manager_wait_for_connection(uint32_t timeout_ms);

/**
 * @brief Get WiFi status as string
 * 
 * @param status WiFi status enum value
 * @return String representation of the status
 */
const char* wifi_manager_status_to_string(wifi_status_t status);

/**
 * @brief Scan for available WiFi networks
 * 
 * Initiates a WiFi scan. Results can be retrieved with wifi_manager_get_scan_results().
 * 
 * @return ESP_OK if scan started, ESP_FAIL on error
 */
esp_err_t wifi_manager_start_scan(void);

/**
 * @brief Get WiFi scan results
 * 
 * @param ap_info Array to store access point information
 * @param max_aps Maximum number of APs to return
 * @param num_aps Pointer to store actual number of APs found
 * @return ESP_OK on success, ESP_FAIL on error
 */
esp_err_t wifi_manager_get_scan_results(wifi_ap_record_t* ap_info, uint16_t max_aps, uint16_t* num_aps);

/**
 * @brief Force immediate reconnection attempt
 * 
 * Useful for testing or when you want to retry connection immediately
 * instead of waiting for the automatic retry.
 * 
 * @return ESP_OK if reconnection attempt started, ESP_FAIL on error
 */
esp_err_t wifi_manager_reconnect(void);

/**
 * @brief Get detailed connection statistics
 * 
 * Provides information about connection attempts, success rate, etc.
 * 
 * @param total_attempts Pointer to store total connection attempts
 * @param successful_connections Pointer to store successful connections
 * @param last_error Pointer to store last connection error
 * @return ESP_OK on success
 */
esp_err_t wifi_manager_get_stats(uint32_t* total_attempts, uint32_t* successful_connections, esp_err_t* last_error);

/**
 * @brief Reset WiFi manager statistics
 * 
 * @return ESP_OK on success
 */
esp_err_t wifi_manager_reset_stats(void);

#endif // WIFI_MANAGER_H