/**********************************************************************
*   Copyright: (C)2024 LingYun IoT System Studio
*      Author: GuoWenxue<guowenxue@gmail.com>
* Description: SG90 Servo Motor Driver for ISKBoard
*
*   ChangeLog:
*        Version    Date       Author            Description
*        V1.0.0  2024.08.29    GuoWenxue      Release initial version
***********************************************************************/

#ifndef __SERVO_SG90_H
#define __SERVO_SG90_H

/* SG90 的物理行程一般标称 0°~180°，但实际齿轮限位比这个略窄（大概 170°~185°）
 *  如果你让它往超过物理极限的角度硬顶：
 *  1. 电机持续出力试图转到不存在的位置
 *  2. 内部齿轮卡死 -> 长时间堵转
 *  3. 大电流持续流过线圈 -> 发热、烧线圈、融塑料齿轮
 * 钳位角度到 1°~180°（更保守 5°~175°）就给机械留了一点余量，避免顶死。
 */

/* 舵机参数宏定义，方便后期微调 */
#define SERVO_MIN_ANGLE   5     // 钳位最小角度
#define SERVO_MAX_ANGLE   175   // 钳位最大角度
#define SERVO_MIN_PULSE   500   // 0度对应的脉宽(us)
#define SERVO_MAX_PULSE   2500  // 180度对应的脉宽(us)
#define SERVO_DEFAULT_ANG 90    // 90度上电瞬间不容易堵转、卡死、发热

/* 通用角度钳位宏 */
#define CLAMP_ANGLE(angle)                                   \
    (((angle) < SERVO_MIN_ANGLE) ? SERVO_MIN_ANGLE :         \
     ((angle) > SERVO_MAX_ANGLE) ? SERVO_MAX_ANGLE :         \
     (angle))

/**
 * @brief  初始化舵机, 启动 TIM PWM 输出。
 */
void Servo_Init(void);

/**
 * @brief  设置舵机角度
 * @param  angle  可传 0 ~ 180，但超出钳位值范围自动钳位
 */
void Servo_SetAngle(int angle);

/**
 * @brief  直接停止 PWM 输出, 立即停止舵机
 */
void Servo_Stop(void);

/**
 * @brief  转到安全角度后，再停止舵机
 * @param  safe_angle  停止前舵机转到的角度 (超出钳位值范围设置默认角度)
 */
void Servo_SafeStop(int safe_angle);

/**
 * @brief 舵机测试函数
 */
void Servo_Test(void);

#endif