#ifndef FAN_H
#define FAN_H

#include <stdint.h>
#include <stdbool.h>

/*
 * fan.h — Cooling fan PWM speed controller (Issue #263)
 *
 * STM32F722 driver for brushless cooling fan on PA9 using TIM1_CH2 PWM.
 * Temperature-based speed curve with smooth ramp transitions.
 *
 * Pin: PA9 (TIM1_CH2, alternate function AF1)
 * PWM Frequency: 25 kHz (suitable for brushless DC fan)
 * Speed Range: 0-100% duty cycle
 *
 * Temperature Curve:
 *   - Below 40°C: Fan off (0%)
 *   - 40-50°C: Linear ramp from 0% to 30%
 *   - 50-70°C: Linear ramp from 30% to 100%
 *   - Above 70°C: Fan at maximum (100%)
 */

/* Fan speed state */
typedef enum {
    FAN_OFF,       /* Motor disabled (0% duty) */
    FAN_LOW,       /* Low speed (5-30%) */
    FAN_MEDIUM,    /* Medium speed (31-60%) */
    FAN_HIGH,      /* High speed (61-99%) */
    FAN_FULL       /* Maximum speed (100%) */
} FanState;

/*
 * fan_init()
 *
 * Initialize fan controller:
 * - PA9 as TIM1_CH2 PWM output
 * - TIM1 configured for 25 kHz frequency
 * - PWM duty cycle control (0-100%)
 * - Ramp rate limiter for smooth transitions
 */
void fan_init(void);

/*
 * fan_set_speed(percentage)
 *
 * Set fan speed directly (bypasses temperature control).
 * Used for manual testing or emergency cooling.
 *
 * Arguments:
 *   - percentage: 0-100% duty cycle
 *
 * Returns: true if set successfully, false if invalid value
 */
bool fan_set_speed(uint8_t percentage);

/*
 * fan_get_speed()
 *
 * Get current fan speed setting.
 *
 * Returns: Current speed 0-100%
 */
uint8_t fan_get_speed(void);

/*
 * fan_set_target_speed(percentage)
 *
 * Set target speed with smooth ramping.
 * Speed transitions over time according to ramp rate.
 *
 * Arguments:
 *   - percentage: Target speed 0-100%
 *
 * Returns: true if set successfully
 */
bool fan_set_target_speed(uint8_t percentage);

/*
 * fan_update_temperature(temp_celsius)
 *
 * Update temperature reading and apply speed curve.
 * Calculates target speed based on temperature curve.
 * Speed transition is smoothed via ramp limiter.
 *
 * Temperature Curve:
 *   - temp < 40°C: 0% (off)
 *   - 40°C ≤ temp < 50°C: 0% + (temp - 40) * 3% per °C = linear to 30%
 *   - 50°C ≤ temp < 70°C: 30% + (temp - 50) * 3.5% per °C = linear to 100%
 *   - temp ≥ 70°C: 100% (full)
 *
 * Arguments:
 *   - temp_celsius: Temperature in degrees Celsius (int16_t for negative values)
 */
void fan_update_temperature(int16_t temp_celsius);

/*
 * fan_get_temperature()
 *
 * Get last recorded temperature.
 *
 * Returns: Temperature in °C (or 0 if not yet set)
 */
int16_t fan_get_temperature(void);

/*
 * fan_get_state()
 *
 * Get current fan operational state.
 *
 * Returns: FAN_OFF, FAN_LOW, FAN_MEDIUM, FAN_HIGH, or FAN_FULL
 */
FanState fan_get_state(void);

/*
 * fan_set_ramp_rate(percentage_per_ms)
 *
 * Configure speed ramp rate for smooth transitions.
 * Default: 5% per 100ms = 0.05% per ms.
 * Higher values = faster transitions.
 *
 * Arguments:
 *   - percentage_per_ms: Speed change per millisecond (e.g., 1 = 1% per ms)
 *
 * Typical ranges:
 *   - 0.01 = very slow (100% change in 10 seconds)
 *   - 0.05 = slow (100% change in 2 seconds)
 *   - 0.1 = medium (100% change in 1 second)
 *   - 1.0 = fast (100% change in 100ms)
 */
void fan_set_ramp_rate(float percentage_per_ms);

/*
 * fan_is_ramping()
 *
 * Check if speed is currently transitioning.
 *
 * Returns: true if speed is ramping toward target, false if at target
 */
bool fan_is_ramping(void);

/*
 * fan_tick(now_ms)
 *
 * Update function called periodically (recommended: every 10-100ms).
 * Processes speed ramp transitions.
 * Must be called regularly for smooth ramping operation.
 *
 * Arguments:
 *   - now_ms: current time in milliseconds (from HAL_GetTick() or similar)
 */
void fan_tick(uint32_t now_ms);

/*
 * fan_disable()
 *
 * Disable fan immediately (set to 0% duty).
 * Useful for shutdown or emergency stop.
 */
void fan_disable(void);

#endif /* FAN_H */