#ifndef MOTOR_CONTROL_H
#define MOTOR_CONTROL_H

#include "freertos/FreeRTOS.h"
#include "freertos/timers.h"
#include "esp_err.h"
#include <stdbool.h>

// Motor mode enumeration
typedef enum {
    MOTOR_OFF,
    MOTOR_EXHAUST,
    MOTOR_INTAKE
} motor_mode_t;

// Motor state enumeration
typedef enum {
    MOTOR_STATE_IDLE,           // Motor is off or running normally
    MOTOR_STATE_RAMPING,        // Motor is ramping up/down
    MOTOR_STATE_STOPPING,       // Motor is stopping for direction change
    MOTOR_STATE_COOLDOWN,       // Motor is in cooldown period
    MOTOR_STATE_RESTARTING      // Motor is restarting after cooldown
} motor_state_enum_t;

// Motor state structure
typedef struct {
    motor_mode_t mode;
    motor_mode_t pending_mode;      // Mode to switch to after cooldown
    int target_speed;
    int pending_speed;              // Speed to set after cooldown
    int current_speed;
    motor_state_enum_t state;
    bool ramping;
    TimerHandle_t ramp_timer;
    TimerHandle_t cooldown_timer;
    uint32_t cooldown_remaining_ms; // For status reporting
    
    // State preservation
    motor_mode_t last_on_mode;      // Last non-OFF mode for ON button
    int last_on_speed;              // Last non-zero speed for ON button
    bool user_turned_off;           // Track if user manually turned off
} motor_state_t;

// Public API functions

/**
 * @brief Initialize the motor control system
 * 
 * Sets up GPIO pins, PWM channels, and creates FreeRTOS timers for ramping and cooldown.
 * Must be called before any other motor control functions.
 * 
 * @return ESP_OK on success, ESP_FAIL on error
 */
esp_err_t motor_control_init(void);

/**
 * @brief Set motor speed and mode
 * 
 * Controls the motor with automatic ramping and direction change safety.
 * Handles cooldown periods when changing directions to prevent mechanical stress.
 * 
 * @param mode Motor mode (MOTOR_OFF, MOTOR_EXHAUST, MOTOR_INTAKE)
 * @param speed_percent Speed percentage (0-100)
 */
void motor_set_speed(motor_mode_t mode, int speed_percent);

/**
 * @brief Get current motor state
 * 
 * Returns a pointer to the current motor state structure for status reporting.
 * The returned pointer should not be modified directly.
 * 
 * @return Pointer to motor_state_t structure
 */
const motor_state_t* motor_get_state(void);

/**
 * @brief Update cooldown time tracking
 * 
 * Should be called periodically (e.g., every 1 second) to update the
 * cooldown_remaining_ms field for status reporting.
 */
void motor_update_cooldown_time(void);

/**
 * @brief Get motor mode as string
 * 
 * @param mode Motor mode enum value
 * @return String representation of the mode
 */
const char* motor_mode_to_string(motor_mode_t mode);

/**
 * @brief Get motor state as string
 * 
 * @param state Motor state enum value
 * @return String representation of the state
 */
const char* motor_state_to_string(motor_state_enum_t state);

/**
 * @brief Check if motor is currently ramping
 * 
 * @return true if motor is ramping, false otherwise
 */
bool motor_is_ramping(void);

/**
 * @brief Check if motor is in cooldown
 * 
 * @return true if motor is in cooldown, false otherwise
 */
bool motor_is_in_cooldown(void);

/**
 * @brief Get cooldown remaining time in milliseconds
 * 
 * @return Remaining cooldown time in milliseconds, 0 if not in cooldown
 */
uint32_t motor_get_cooldown_remaining(void);

/**
 * @brief Set the "last on" state for the ON button functionality
 * 
 * This is called automatically when the motor is turned on, but can be
 * called manually to set the default state for the ON button.
 * 
 * @param mode Motor mode (should be MOTOR_EXHAUST or MOTOR_INTAKE)
 * @param speed Speed percentage (1-100)
 */
void motor_set_last_on_state(motor_mode_t mode, int speed);

/**
 * @brief Get the "last on" state
 * 
 * @param mode Pointer to store the last on mode
 * @param speed Pointer to store the last on speed
 */
void motor_get_last_on_state(motor_mode_t* mode, int* speed);

/**
 * @brief Resume last motor state (ON button functionality)
 * 
 * Sets the motor to the last known good state (mode and speed).
 * This is typically called when the user presses an "ON" button.
 */
void motor_resume_last_state(void);

/**
 * @brief Set user turned off flag
 * 
 * Tracks whether the user manually turned off the motor.
 * This affects state restoration behavior after power loss.
 * 
 * @param turned_off true if user manually turned off, false otherwise
 */
void motor_set_user_turned_off(bool turned_off);

/**
 * @brief Get user turned off flag
 * 
 * @return true if user manually turned off, false otherwise
 */
bool motor_get_user_turned_off(void);

#endif // MOTOR_CONTROL_H