/*
 * SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
 *
 * SPDX-License-Identifier: Apache-2.0
 */

#pragma once

#include "driver/gpio.h"

#ifdef __cplusplus
extern "C" {
#endif

/* ========== GPIO Pin Definitions ========== */
#define IN1_PIN     (35)   /**< Stepper motor IN1 control pin */
#define IN2_PIN     (36)   /**< Stepper motor IN2 control pin */
#define IN3_PIN     (37)   /**< Stepper motor IN3 control pin */
#define IN4_PIN     (38)   /**< Stepper motor IN4 control pin */

/* ========== Speed Configuration (delay per step, unit: microseconds μs) ========== */
/**
 * @note Uses half-step driving mode for doubled precision and smoother motion
 * @note Smaller delay means faster speed
 */
#define STEPPER_SPEED_ULTRA_FAST    600     /**< Ultra fast mode: 600μs/step (0.6ms) */
#define STEPPER_SPEED_FAST          800     /**< Fast mode: 1000μs/step (1ms) */
#define STEPPER_SPEED_NORMAL        1500    /**< Normal mode: 1500μs/step (1.5ms) */
#define STEPPER_SPEED_SLOW          2000    /**< Slow mode: 2000μs/step (2ms) */

/* ========== Acceleration/Deceleration Configuration ========== */
#define STEPPER_START_DELAY_US      1500    /**< Start delay (slower, ensures smooth start) */
#define STEPPER_ACCEL_STEPS         30      /**< Acceleration steps */
#define STEPPER_DECEL_STEPS         30      /**< Deceleration steps */

/* ========== Stepper Motor Action Type Enumeration ========== */
/**
 * @brief Stepper motor predefined action types
 */
typedef enum {
    STEPPER_ACTION_SHAKE_HEAD,          /**< Shake head action (fixed amplitude and cycles) */
    STEPPER_ACTION_SHAKE_HEAD_DECAY,    /**< Gradually decaying shake head action */
    STEPPER_ACTION_LOOK_AROUND,         /**< Look around observation action */
    STEPPER_ACTION_BEAT_SWING,          /**< Follow drum beat swing motion */
    STEPPER_ACTION_CAT_NUZZLE,          /**< Cat nuzzling action */
    STEPPER_ACTION_MAX                  /**< Number of action types (for boundary check) */
} stepper_action_type_t;

/* ========== Function Declarations ========== */

/**
 * @brief Rotate by specified angle (with acceleration/deceleration)
 * 
 * @param angle Rotation angle, positive for right (clockwise), negative for left (counterclockwise)
 * @param target_delay_us Target speed delay (microseconds), will automatically accelerate from slow speed to this speed at start
 */
void stepper_rotate_angle_with_accel(float angle, int target_delay_us);

/**
 * @brief Shake head action function
 * 
 * @param amplitude Shake amplitude (one-sided angle), e.g., 30 means shake 30 degrees left and right
 * @param cycles Number of shake cycles, one complete left-right shake counts as 1
 * @param speed_us Shake speed (microsecond delay), recommend using STEPPER_SPEED_xxx macros
 */
void stepper_shake_head(float amplitude, int cycles, int speed_us);

/**
 * @brief Gradually decaying shake head action function
 * 
 * @param initial_amplitude Initial shake amplitude (one-sided angle), e.g., 30 means initially shake 30 degrees left and right
 * @param decay_rate Decay rate, range 0.0~1.0 for percentage decay, >1.0 for fixed angle decay
 *                   e.g., 0.8 means amplitude becomes 80% after each shake
 *                   e.g., 5.0 means decrease by 5 degrees each time
 * @param speed_us Shake speed (microsecond delay), recommend using STEPPER_SPEED_xxx macros
 */
void stepper_shake_head_decay(float initial_amplitude, float decay_rate, int speed_us);

/**
 * @brief Look around action function (with small amplitude scanning + random offset)
 * 
 * @param left_angle Main angle to turn left (positive value), e.g., 45 means turn left 45 degrees
 * @param right_angle Main angle to turn right (positive value), e.g., 45 means turn right 45 degrees
 * @param scan_angle Small amplitude scanning angle at left and right sides (positive value), e.g., 10 means scan 10 degrees left and right
 * @param pause_ms Pause time after each movement (milliseconds), simulating "observation" motion
 * @param large_speed_us Large movement speed (microsecond delay), used for main position rotation
 * @param small_speed_us Small scanning speed (microsecond delay), used for small range observation
 * 
 * @note Random offset is added to each rotation for more natural motion
 */
void stepper_look_around(float left_angle, float right_angle, float scan_angle, 
                         int pause_ms, int large_speed_us, int small_speed_us);

/**
 * @brief Follow drum beat swing function
 * 
 * @param angle Swing angle for each beat (positive value), e.g., 10 means swing 10 degrees left and right
 * @param speed_us Rotation speed (microsecond delay)
 * 
 * @note Each call to this function automatically switches direction (left-right-left-right...)
 */
void stepper_beat_swing(float angle, int speed_us);

/**
 * @brief Cat nuzzling action function (gently turn left and return to center, repeat several times)
 * 
 * @param angle Angle to turn left (positive value), e.g., 20 means turn left 20 degrees
 * @param cycles Number of nuzzles, each includes a complete "turn-return to center" motion
 * @param speed_us Rotation speed (microsecond delay), recommend using slower speed like STEPPER_SPEED_SLOW
 * 
 * @note Uses slow smooth acceleration/deceleration throughout for gentle feel
 */
void stepper_cat_nuzzle(float angle, int cycles, int speed_us);

/**
 * @brief Turn off all stepper motor coils (power off)
 * 
 * @note After calling this function, motor will no longer hold position and can be rotated by external force
 */
void stepper_motor_power_off(void);

/**
 * @brief Initialize stepper motor GPIO pins
 */
void stepper_motor_gpio_init(void);

#ifdef __cplusplus
}
#endif