Bairan.Zhang/stepper_base
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Initial commit

Browse Source
This commit is contained in:
Cedarium Zhang
2026-01-30 12:10:24 +08:00
commit 404f75cef5
18 changed files with 1279 additions and 0 deletions
Download Patch File Download Diff File Expand all files Collapse all files

3
components/stepper_motor/CMakeLists.txt Normal file
View File

@@ -0,0 +1,3 @@
idf_component_register(SRCS "stepper_motor.c"
INCLUDE_DIRS "include"
PRIV_REQUIRES "driver")

129
components/stepper_motor/include/stepper_motor.h Normal file
View File

@@ -0,0 +1,129 @@
/*
* 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

693
components/stepper_motor/stepper_motor.c Normal file
View File

@@ -0,0 +1,693 @@
/*
* SPDX-FileCopyrightText: 2024-2025 Espressif Systems (Shanghai) CO LTD
*
* SPDX-License-Identifier: Apache-2.0
*/
#include <stdio.h>
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"
#include "driver/gpio.h"
#include "esp_log.h"
#include "esp_rom_sys.h"
#include "esp_random.h"
#include "stepper_motor.h"
static const char *TAG = "Stepper Motor";
/* ========== Step Sequence Definitions ========== */
/**
* @brief 8-beat half-step sequence - Clockwise (forward rotation)
* @note Alternates single-phase and dual-phase excitation for smoother motion and higher precision
*/
static const int step_sequence_cw[8][4] = {
{1, 0, 0, 0}, // Step 1: IN1 (single phase)
{1, 1, 0, 0}, // Step 2: IN1+IN2 (dual phase)
{0, 1, 0, 0}, // Step 3: IN2 (single phase)
{0, 1, 1, 0}, // Step 4: IN2+IN3 (dual phase)
{0, 0, 1, 0}, // Step 5: IN3 (single phase)
{0, 0, 1, 1}, // Step 6: IN3+IN4 (dual phase)
{0, 0, 0, 1}, // Step 7: IN4 (single phase)
{1, 0, 0, 1} // Step 8: IN4+IN1 (dual phase)
};
/**
* @brief 8-beat half-step sequence - Counterclockwise (reverse rotation)
* @note Alternates single-phase and dual-phase excitation for smoother motion and higher precision
*/
static const int step_sequence_ccw[8][4] = {
{1, 0, 0, 1}, // Step 1: IN4+IN1 (dual phase)
{0, 0, 0, 1}, // Step 2: IN4 (single phase)
{0, 0, 1, 1}, // Step 3: IN3+IN4 (dual phase)
{0, 0, 1, 0}, // Step 4: IN3 (single phase)
{0, 1, 1, 0}, // Step 5: IN2+IN3 (dual phase)
{0, 1, 0, 0}, // Step 6: IN2 (single phase)
{1, 1, 0, 0}, // Step 7: IN1+IN2 (dual phase)
{1, 0, 0, 0} // Step 8: IN1 (single phase)
};
/* ========== Private Functions ========== */
/**
* @brief Set stepper motor pin states
*
* @param in1 IN1 pin state (0 or 1)
* @param in2 IN2 pin state (0 or 1)
* @param in3 IN3 pin state (0 or 1)
* @param in4 IN4 pin state (0 or 1)
*/
static void set_motor_pins(int in1, int in2, int in3, int in4)
{
gpio_set_level(IN1_PIN, in1);
gpio_set_level(IN2_PIN, in2);
gpio_set_level(IN3_PIN, in3);
gpio_set_level(IN4_PIN, in4);
}
/**
* @brief Stepper motor clockwise one step
*
* @param step Current step number (will be auto modulo 8)
*/
static void stepper_step_cw(int step)
{
step = step % 8; // Ensure step is in range 0-7 (8 steps in half-step mode)
set_motor_pins(step_sequence_cw[step][0],
step_sequence_cw[step][1],
step_sequence_cw[step][2],
step_sequence_cw[step][3]);
}
/**
* @brief Stepper motor counterclockwise one step
*
* @param step Current step number (will be auto modulo 8)
*/
static void stepper_step_ccw(int step)
{
step = step % 8; // Ensure step is in range 0-7 (8 steps in half-step mode)
set_motor_pins(step_sequence_ccw[step][0],
step_sequence_ccw[step][1],
step_sequence_ccw[step][2],
step_sequence_ccw[step][3]);
}
/**
* @brief Microsecond precision delay function
*
* @param delay_us Delay time (microseconds)
*/
static inline void precise_delay_us(int delay_us)
{
if (delay_us > 0) {
esp_rom_delay_us(delay_us);
}
}
/* ========== Public Function Implementations ========== */
/**
* @brief Clockwise rotation with acceleration/deceleration
*
* @param steps Number of rotation steps
* @param target_delay_us Target speed delay (microseconds)
*
* @note Uses linear acceleration/deceleration algorithm, divided into acceleration, constant speed, and deceleration phases
*/
static void stepper_rotate_cw_with_accel(int steps, int target_delay_us)
{
int start_delay_us = STEPPER_START_DELAY_US;
int accel_steps = STEPPER_ACCEL_STEPS;
int decel_steps = STEPPER_DECEL_STEPS;
// If total steps too few, adjust acceleration/deceleration steps
if (steps < (accel_steps + decel_steps)) {
accel_steps = steps / 3;
decel_steps = steps / 3;
}
int constant_steps = steps - accel_steps - decel_steps;
int current_delay_us;
ESP_LOGD(TAG, "Accel-Decel profile: accel=%d, constant=%d, decel=%d steps",
accel_steps, constant_steps, decel_steps);
// Acceleration phase
for (int i = 0; i < accel_steps; i++) {
// Linear interpolation: gradually decrease from start_delay to target_delay
current_delay_us = start_delay_us - (start_delay_us - target_delay_us) * i / accel_steps;
stepper_step_cw(i);
precise_delay_us(current_delay_us);
}
// Constant speed phase
for (int i = accel_steps; i < accel_steps + constant_steps; i++) {
stepper_step_cw(i);
precise_delay_us(target_delay_us);
}
// Deceleration phase
for (int i = accel_steps + constant_steps; i < steps; i++) {
// Linear interpolation: gradually increase from target_delay to start_delay
int decel_progress = i - (accel_steps + constant_steps);
current_delay_us = target_delay_us + (start_delay_us - target_delay_us) * decel_progress / decel_steps;
stepper_step_cw(i);
precise_delay_us(current_delay_us);
}
}
/**
* @brief Counterclockwise rotation with acceleration/deceleration
*
* @param steps Number of rotation steps
* @param target_delay_us Target speed delay (microseconds)
*
* @note Uses linear acceleration/deceleration algorithm, divided into acceleration, constant speed, and deceleration phases
*/
static void stepper_rotate_ccw_with_accel(int steps, int target_delay_us)
{
int start_delay_us = STEPPER_START_DELAY_US;
int accel_steps = STEPPER_ACCEL_STEPS;
int decel_steps = STEPPER_DECEL_STEPS;
// If total steps too few, adjust acceleration/deceleration steps
if (steps < (accel_steps + decel_steps)) {
accel_steps = steps / 3;
decel_steps = steps / 3;
}
int constant_steps = steps - accel_steps - decel_steps;
int current_delay_us;
ESP_LOGD(TAG, "Accel-Decel profile: accel=%d, constant=%d, decel=%d steps",
accel_steps, constant_steps, decel_steps);
// Acceleration phase
for (int i = 0; i < accel_steps; i++) {
current_delay_us = start_delay_us - (start_delay_us - target_delay_us) * i / accel_steps;
stepper_step_ccw(i);
precise_delay_us(current_delay_us);
}
// Constant speed phase
for (int i = accel_steps; i < accel_steps + constant_steps; i++) {
stepper_step_ccw(i);
precise_delay_us(target_delay_us);
}
// Deceleration phase
for (int i = accel_steps + constant_steps; i < steps; i++) {
int decel_progress = i - (accel_steps + constant_steps);
current_delay_us = target_delay_us + (start_delay_us - target_delay_us) * decel_progress / decel_steps;
stepper_step_ccw(i);
precise_delay_us(current_delay_us);
}
}
/**
* @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
*
* @note Half-step mode: 4128 steps = 360 degrees
* @note Uses linear acceleration/deceleration algorithm to ensure smooth start and stop
*/
void stepper_rotate_angle_with_accel(float angle, int target_delay_us)
{
// Half-step mode: 4128 steps = 360 degrees
int steps = (int)(angle * 4128.0 / 360.0 + 0.5);
if (steps == 0) {
ESP_LOGI(TAG, "Angle too small, no rotation needed");
return;
}
if (steps > 0) {
ESP_LOGD(TAG, "Rotating %.1f° CW with acceleration (%d steps, target %dus/step)",
angle, steps, target_delay_us);
stepper_rotate_cw_with_accel(steps, target_delay_us);
} else {
ESP_LOGD(TAG, "Rotating %.1f° CCW with acceleration (%d steps, target %dus/step)",
angle, -steps, target_delay_us);
stepper_rotate_ccw_with_accel(-steps, 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
*
* Motion sequence (example with amplitude=30, cycles=2):
* 1. Turn left to -30° → pause
* 2. Turn right to +30° → pause → turn left to -30° → pause (cycle 1)
* 3. Turn right to +30° → pause → turn left to -30° → pause (cycle 2)
* 4. Return to center 0°
*/
void stepper_shake_head(float amplitude, int cycles, int speed_us)
{
if (amplitude <= 0 || cycles <= 0) {
ESP_LOGW(TAG, "Invalid shake head parameters: amplitude=%.1f, cycles=%d", amplitude, cycles);
return;
}
ESP_LOGD(TAG, "Shake head started: amplitude=%.1f°, cycles=%d, speed=%dus/step",
amplitude, cycles, speed_us);
// Step 1: Turn left from center to start position
ESP_LOGD(TAG, "Moving to left start position (%.1f°)", -amplitude);
stepper_rotate_angle_with_accel(-amplitude, speed_us);
vTaskDelay(pdMS_TO_TICKS(10)); // Brief pause
// Shake cycles
for (int i = 0; i < cycles; i++) {
ESP_LOGD(TAG, "Shake cycle %d/%d", i + 1, cycles);
// Turn right (from left to right, rotate 2*amplitude degrees)
stepper_rotate_angle_with_accel(2 * amplitude, speed_us);
vTaskDelay(pdMS_TO_TICKS(10)); // Brief pause
// Turn left (from right to left, rotate 2*amplitude degrees)
stepper_rotate_angle_with_accel(-2 * amplitude, speed_us);
vTaskDelay(pdMS_TO_TICKS(10)); // Brief pause
}
// Last step: Return from left to center position
ESP_LOGD(TAG, "Returning to center position");
stepper_rotate_angle_with_accel(amplitude, 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: Percentage decay, e.g., 0.8 means amplitude becomes 80% each time
* - >1.0: Fixed angle decay, e.g., 5.0 means decrease by 5 degrees each time
* @param speed_us Shake speed (microsecond delay), recommend using STEPPER_SPEED_xxx macros
*
* @note Shake amplitude gradually decreases until below minimum threshold (5 degrees) then stops
* @note Speed automatically decreases when amplitude is small to avoid jitter
*/
void stepper_shake_head_decay(float initial_amplitude, float decay_rate, int speed_us)
{
if (initial_amplitude <= 0) {
ESP_LOGW(TAG, "Invalid amplitude: %.1f", initial_amplitude);
return;
}
if (decay_rate <= 0) {
ESP_LOGW(TAG, "Invalid decay rate: %.3f", decay_rate);
return;
}
ESP_LOGD(TAG, "Decay shake head started: initial_amplitude=%.1f°, decay_rate=%.3f, speed=%dus/step",
initial_amplitude, decay_rate, speed_us);
float current_amplitude = initial_amplitude;
float min_amplitude = 5.0; // Minimum amplitude threshold (degrees), stop shaking below this to avoid small angle jitter
float smooth_threshold = 8.0; // Smooth threshold (degrees), reduce speed below this
int cycle_count = 0;
bool use_percentage_decay = (decay_rate > 0.0 && decay_rate < 1.0); // Determine if percentage decay or fixed value decay
float current_position = 0.0; // Track current position relative to center
// Step 1: Turn left from center to start position
ESP_LOGD(TAG, "Moving to left start position (%.1f°)", -current_amplitude);
stepper_rotate_angle_with_accel(-current_amplitude, speed_us);
current_position = -current_amplitude;
vTaskDelay(pdMS_TO_TICKS(10)); // Brief pause
// Shake loop, until amplitude below threshold
while (current_amplitude >= min_amplitude) {
cycle_count++;
// Dynamically adjust speed based on current amplitude, slower speed for smaller amplitude to avoid jitter
int current_speed_us = speed_us;
if (current_amplitude < smooth_threshold) {
// Linear interpolation: speed factor increases from 1.0 to 1.3 (max 30% slowdown) as amplitude decreases from smooth_threshold to min_amplitude
float speed_factor = 1.0 + 0.3 * (smooth_threshold - current_amplitude) / (smooth_threshold - min_amplitude);
current_speed_us = (int)(speed_us * speed_factor);
ESP_LOGD(TAG, "Decay shake cycle %d: amplitude=%.1f°, speed adjusted to %dus/step (factor=%.2f)",
cycle_count, current_amplitude, current_speed_us, speed_factor);
} else {
ESP_LOGD(TAG, "Decay shake cycle %d: amplitude=%.1f°", cycle_count, current_amplitude);
}
// Turn right (from left to right, rotate 2*current_amplitude degrees)
stepper_rotate_angle_with_accel(2 * current_amplitude, current_speed_us);
current_position += 2 * current_amplitude;
vTaskDelay(pdMS_TO_TICKS(15)); // Brief pause, longer when amplitude is small
// Calculate next amplitude
float next_amplitude;
if (use_percentage_decay) {
// Percentage decay mode: amplitude = current amplitude × decay rate
next_amplitude = current_amplitude * decay_rate;
ESP_LOGD(TAG, "Percentage decay: next amplitude=%.1f° (%.1f%%)",
next_amplitude, decay_rate * 100);
} else {
// Fixed value decay mode: amplitude = current amplitude - decay value
next_amplitude = current_amplitude - decay_rate;
ESP_LOGD(TAG, "Fixed decay: next amplitude=%.1f° (-%.1f°)",
next_amplitude, decay_rate);
}
// Check if should continue shaking
if (next_amplitude < min_amplitude) {
ESP_LOGD(TAG, "Next amplitude too small (%.1f° < %.1f°), stopping at position %.1f°",
next_amplitude, min_amplitude, current_position);
break;
}
current_amplitude = next_amplitude;
// Dynamically adjust speed based on current amplitude
current_speed_us = speed_us;
if (current_amplitude < smooth_threshold) {
float speed_factor = 1.0 + 0.3 * (smooth_threshold - current_amplitude) / (smooth_threshold - min_amplitude);
current_speed_us = (int)(speed_us * speed_factor);
}
// Turn left (from right to left, rotate 2*current_amplitude degrees)
stepper_rotate_angle_with_accel(-2 * current_amplitude, current_speed_us);
current_position -= 2 * current_amplitude;
vTaskDelay(pdMS_TO_TICKS(15)); // Brief pause
// Calculate next amplitude again (symmetric decay)
if (use_percentage_decay) {
next_amplitude = current_amplitude * decay_rate;
} else {
next_amplitude = current_amplitude - decay_rate;
}
// Check next amplitude
if (next_amplitude < min_amplitude) {
ESP_LOGD(TAG, "Next amplitude too small (%.1f° < %.1f°), stopping at position %.1f°",
next_amplitude, min_amplitude, current_position);
break;
}
current_amplitude = next_amplitude;
}
// Last step: Return to center position
ESP_LOGD(TAG, "Returning to center from position %.1f°", current_position);
// Use slightly slower speed when returning to center to ensure smoothness
float abs_position = (current_position > 0) ? current_position : -current_position;
int return_speed_us = speed_us;
if (abs_position < smooth_threshold) {
// If remaining angle is small, slightly reduce return speed (max 20% slowdown)
float speed_factor = 1.2;
return_speed_us = (int)(speed_us * speed_factor);
ESP_LOGD(TAG, "Using slower speed for return: %dus/step", return_speed_us);
}
stepper_rotate_angle_with_accel(-current_position, return_speed_us);
ESP_LOGD(TAG, "Decay shake head completed: total cycles=%d", cycle_count);
}
/**
* @brief Generate random angle offset (within ±max_offset range)
*
* @param max_offset Maximum offset (degrees)
* @return float Random offset angle, range [-max_offset, +max_offset]
*
* @note Used to add randomness to motions for more natural movement
*/
static float get_random_angle_offset(float max_offset)
{
if (max_offset <= 0) {
return 0;
}
// Generate random number between 0 and 1
uint32_t random_value = esp_random();
float normalized = (float)(random_value % 10000) / 10000.0; // 0.0 ~ 1.0
// Convert to range -max_offset to +max_offset
float offset = (normalized * 2.0 - 1.0) * max_offset;
return offset;
}
/**
* @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, recommend slower than large_speed_us
*
* @note Random offset is added to each rotation for more natural motion
* @note Large movement: random offset ±10°
* @note Small scanning: random offset ±10°
*
* Motion sequence (example with left_angle=45, scan_angle=10, actual values will have random offset):
* 1. Turn left to -45°±10° (large speed) → pause
* 2. Scan left to -55°±10° (small speed) → pause
* 3. Scan right to -35°±10° (small speed) → pause
* 4. Turn right to +45°±10° (large speed) → pause
* 5. Scan right to +55°±10° (small speed) → pause
* 6. Scan left to +35°±10° (small speed) → pause
* 7. Return to center 0° (large speed)
*/
void stepper_look_around(float left_angle, float right_angle, float scan_angle, int pause_ms, int large_speed_us, int small_speed_us)
{
if (left_angle < 0 || right_angle < 0 || scan_angle < 0) {
ESP_LOGW(TAG, "Invalid angles: left=%.1f, right=%.1f, scan=%.1f (should be positive)",
left_angle, right_angle, scan_angle);
return;
}
if (pause_ms < 0) {
pause_ms = 0;
}
ESP_LOGD(TAG, "Look around started: left=%.1f°, right=%.1f°, scan=%.1f°, pause=%dms, large_speed=%dus, small_speed=%dus",
left_angle, right_angle, scan_angle, pause_ms, large_speed_us, small_speed_us);
// Accumulated position tracking (relative to starting center position)
float accumulated_position = 0.0;
// ========== Phase 1: Look Left ==========
if (left_angle > 0) {
// 1. Turn left to main position (large amplitude, fast) + random offset
float left_offset = get_random_angle_offset(10.0); // ±10 degrees random
float actual_left_angle = left_angle + left_offset;
stepper_rotate_angle_with_accel(-actual_left_angle, large_speed_us);
accumulated_position -= actual_left_angle; // Track accumulated position
vTaskDelay(pdMS_TO_TICKS(pause_ms));
// 2. Scan left with small amplitude (slow speed) + random offset
if (scan_angle > 0) {
float scan_left_offset = get_random_angle_offset(10.0); // ±10 degrees random
float actual_scan_left = scan_angle + scan_left_offset;
// Ensure small amplitude rotation is not less than 5 degrees
if (actual_scan_left < 5.0) {
actual_scan_left = 5.0;
scan_left_offset = actual_scan_left - scan_angle;
}
stepper_rotate_angle_with_accel(-actual_scan_left, small_speed_us);
accumulated_position -= actual_scan_left; // Track accumulated position
vTaskDelay(pdMS_TO_TICKS(pause_ms));
// 3. Scan right directly with small amplitude (slow speed, don't return to main position) + random offset
float scan_right_offset = get_random_angle_offset(10.0); // ±10 degrees random
float actual_scan_range = 2 * scan_angle + scan_left_offset - scan_right_offset;
// Ensure small amplitude rotation is not less than 5 degrees
if (actual_scan_range < 5.0) {
actual_scan_range = 5.0;
}
stepper_rotate_angle_with_accel(actual_scan_range, small_speed_us);
accumulated_position += actual_scan_range; // Track accumulated position
vTaskDelay(pdMS_TO_TICKS(pause_ms));
}
}
// ========== Phase 2: Look Right ==========
if (right_angle > 0) {
// 4. Turn from current position to right main position (fast) + random offset
float right_offset = get_random_angle_offset(10.0); // ±10 degrees random
float actual_right_angle = right_angle + right_offset;
// Calculate rotation angle: turn from current accumulated position to right side
float turn_angle = actual_right_angle - accumulated_position;
stepper_rotate_angle_with_accel(turn_angle, large_speed_us);
accumulated_position += turn_angle; // Add actual rotated angle to avoid precision errors
vTaskDelay(pdMS_TO_TICKS(pause_ms));
// 5. Scan right with small amplitude (slow speed) + random offset
if (scan_angle > 0) {
float scan_right2_offset = get_random_angle_offset(10.0); // ±10 degrees random
float actual_scan_right = scan_angle + scan_right2_offset;
// Ensure small amplitude rotation is not less than 5 degrees
if (actual_scan_right < 5.0) {
actual_scan_right = 5.0;
scan_right2_offset = actual_scan_right - scan_angle;
}
stepper_rotate_angle_with_accel(actual_scan_right, small_speed_us);
accumulated_position += actual_scan_right; // Track accumulated position
vTaskDelay(pdMS_TO_TICKS(pause_ms));
// 6. Scan left directly with small amplitude (slow speed, don't return to main position) + random offset
float scan_left2_offset = get_random_angle_offset(10.0); // ±10 degrees random
float actual_scan_range2 = 2 * scan_angle + scan_right2_offset - scan_left2_offset;
// Ensure small amplitude rotation is not less than 5 degrees
if (actual_scan_range2 < 5.0) {
actual_scan_range2 = 5.0;
}
stepper_rotate_angle_with_accel(-actual_scan_range2, small_speed_us);
accumulated_position -= actual_scan_range2; // Track accumulated position
vTaskDelay(pdMS_TO_TICKS(pause_ms));
}
}
// ========== Phase 3: Return to Center ==========
// Use accumulated position to return directly to center (tolerance: 0.5 degrees)
float abs_position = (accumulated_position > 0) ? accumulated_position : -accumulated_position;
if (abs_position > 0.5) {
stepper_rotate_angle_with_accel(-accumulated_position, large_speed_us);
} else {
ESP_LOGD(TAG, "Already near center (offset=%.2f°)", accumulated_position);
}
ESP_LOGD(TAG, "Look around completed");
}
/**
* @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 (using static variable to track state)
* @note Call sequence: left → right → left → right ...
*
* Typical usage: Call this function when music beat is detected, motor will swing left and right following the beat
*/
void stepper_beat_swing(float angle, int speed_us)
{
// Static variable to track current swing direction, false=left, true=right
static bool swing_direction = false;
if (angle <= 0) {
ESP_LOGW(TAG, "Invalid angle: %.1f (should be positive)", angle);
return;
}
if (swing_direction) {
// Turn right
stepper_rotate_angle_with_accel(angle, speed_us);
} else {
// Turn left
stepper_rotate_angle_with_accel(-angle, speed_us);
}
// Switch direction
swing_direction = !swing_direction;
}
/**
* @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 for gentle feel
*
* Motion sequence (example with angle=20, cycles=3):
* 1. Turn left to -20° (slow) → pause 100ms → return to center 0° (slow) → pause 50ms
* 2. Turn left to -20° (slow) → pause 100ms → return to center 0° (slow) → pause 50ms
* 3. Turn left to -20° (slow) → pause 100ms → return to center 0° (slow)
*
* @note Uses slow smooth acceleration/deceleration throughout for gentle feel
* @note Brief pause after each turn to simulate cat nuzzling contact feel
*/
void stepper_cat_nuzzle(float angle, int cycles, int speed_us)
{
if (angle <= 0) {
ESP_LOGW(TAG, "Invalid angle: %.1f (should be positive)", angle);
return;
}
if (cycles <= 0) {
ESP_LOGW(TAG, "Invalid cycles: %d (should be positive)", cycles);
return;
}
ESP_LOGD(TAG, "Cat nuzzle started: angle=%.1f°, cycles=%d, speed=%dus/step",
angle, cycles, speed_us);
// Execute nuzzle cycles
for (int i = 0; i < cycles; i++) {
ESP_LOGD(TAG, "Nuzzle cycle %d/%d", i + 1, cycles);
// Slowly turn left
stepper_rotate_angle_with_accel(-angle, speed_us);
vTaskDelay(pdMS_TO_TICKS(100)); // Pause 100ms to simulate nuzzling contact feel
// Slowly return to center
stepper_rotate_angle_with_accel(angle, speed_us);
// Add brief pause between cycles (not after last cycle)
if (i < cycles - 1) {
vTaskDelay(pdMS_TO_TICKS(50)); // Brief pause after each nuzzle, prepare for next one
}
}
ESP_LOGD(TAG, "Cat nuzzle completed");
}
/**
* @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
* @note Saves power consumption and avoids motor heating from prolonged energization
*/
void stepper_motor_power_off(void)
{
set_motor_pins(0, 0, 0, 0);
}
/**
* @brief Initialize stepper motor GPIO pins
*
* @note Configures IN1-IN4 pins as output mode, initial state is low level
*/
void stepper_motor_gpio_init(void)
{
gpio_config_t io_conf = {
.pin_bit_mask = (1ULL << IN1_PIN) | (1ULL << IN2_PIN) | (1ULL << IN3_PIN) | (1ULL << IN4_PIN),
.mode = GPIO_MODE_OUTPUT,
.pull_up_en = GPIO_PULLUP_DISABLE,
.pull_down_en = GPIO_PULLDOWN_DISABLE,
.intr_type = GPIO_INTR_DISABLE
};
gpio_config(&io_conf);
// Set all pins to low level
gpio_set_level(IN1_PIN, 0);
gpio_set_level(IN2_PIN, 0);
gpio_set_level(IN3_PIN, 0);
gpio_set_level(IN4_PIN, 0);
ESP_LOGI(TAG, "GPIO initialization completed, IN1-IN4 pins set as output mode with default low level");
}