/**
 * @file MotorController.h
 * @brief DC motor control using LM18200 H-Bridge driver
 * 
 * Provides bidirectional PWM motor control with brake functionality.
 * Suitable for DC analog model locomotive control.
 * 
 * @author Locomotive Test Bench Project
 * @date 2025
 */

#ifndef MOTOR_CONTROLLER_H
#define MOTOR_CONTROLLER_H

#include <Arduino.h>

// Pin definitions for LM18200
// Adjusted for ESP32-2432S028R available GPIOs
#define MOTOR_PWM_PIN 18      ///< PWM signal output pin
#define MOTOR_DIR_PIN 19      ///< Direction control pin
#define MOTOR_BRAKE_PIN 23    ///< Brake control pin (active low)

/**
 * @class MotorController
 * @brief Controls DC motor via LM18200 H-Bridge
 * 
 * Features:
 * - Variable speed control (0-100%)
 * - Bidirectional operation (forward/reverse)
 * - Electronic braking
 * - 20kHz PWM frequency for silent operation
 * - 8-bit resolution (256 speed steps)
 */
class MotorController {
public:
    /**
     * @brief Constructor
     */
    MotorController();
    
    /**
     * @brief Initialize motor controller hardware
     * 
     * Configures GPIO pins and PWM channels.
     * Sets motor to safe stopped state.
     */
    void begin();
    
    /**
     * @brief Set motor speed and direction
     * @param speed Speed value (0-100%)
     * @param direction Direction: 0 = reverse, 1 = forward
     */
    void setSpeed(uint8_t speed, uint8_t direction);
    
    /**
     * @brief Stop motor (coast to stop)
     * 
     * Sets speed to zero and releases brake.
     * Motor will coast to a stop.
     */
    void stop();
    
    /**
     * @brief Apply electronic brake
     * 
     * Activates LM18200 brake function for quick stop.
     * More aggressive than stop().
     */
    void brake();
    
    /**
     * @brief Update motor controller state
     * 
     * Called from main loop for safety checks.
     * Currently placeholder for future features.
     */
    void update();
    
    /**
     * @brief Get current speed setting
     * @return Speed (0-100%)
     */
    uint8_t getCurrentSpeed() { return currentSpeed; }
    
    /**
     * @brief Get current direction
     * @return Direction: 0 = reverse, 1 = forward
     */
    uint8_t getCurrentDirection() { return currentDirection; }
    
private:
    uint8_t currentSpeed;         ///< Current speed setting (0-100)
    uint8_t currentDirection;     ///< Current direction (0=rev, 1=fwd)
    
    static const int PWM_CHANNEL = 0;         ///< ESP32 PWM channel
    static const int PWM_FREQUENCY = 20000;   ///< PWM frequency in Hz
    static const int PWM_RESOLUTION = 8;      ///< PWM resolution in bits
};

#endif