/******************************************************************************
 * @file    bsp_hw.h
 * @brief   CBC2 板级硬件：电机 / LED / 按键 / 充电 / 电量
 * @author  cyWu <1917507415@qq.com>
 * @date    2026.08.24
 * @version V1.5.0
 * @history
 * - V1.0.0, 2026.08.21, cyWu, 首次发布
 * - V1.1.0, 2026.08.24, cyWu, 停转改为反转刹车；去掉未贴件限位
 * - V1.3.0, 2026.08.24, cyWu, 电机改 MCPWM 50% 占空比降速
 * - V1.4.0, 2026.08.24, cyWu, 增加按占空比驱动，供玩法变速
 * - V1.5.0, 2026.08.25, cyWu, 空闲关闭 MCPWM 时钟，避免待机空转耗电
 ******************************************************************************/

#ifndef __BSP_HW_H__
#define __BSP_HW_H__

#include <stdint.h>
#include "board_pin.h"

typedef enum {
    BSP_HW_OK = 0,
    BSP_HW_ERR_PARAM,
    BSP_HW_ERR_NOT_INIT
} BspHw_Ret_t;

typedef enum {
    BSP_MOTOR_STOP = 0,    /**< 滑行停（INA/INB 都低） */
    BSP_MOTOR_IN,          /**< 收绳（顺时针，见 BOARD_MOTOR_IN_INA_HIGH） */
    BSP_MOTOR_OUT          /**< 放绳 */
} BspMotorDir_t;

/**
 * @brief  初始化 GPIO / 充电 ADC
 * @return BSP_HW_OK=成功
 */
BspHw_Ret_t bsp_hw_init(void);

/**
 * @brief  查询是否已初始化
 * @return BSP_HW_OK=已初始化，BSP_HW_ERR_NOT_INIT=未初始化
 */
BspHw_Ret_t bsp_hw_get_status(void);

/**
 * @brief  红灯开关
 * @param  on 1=亮，0=灭
 * @return 无
 */
void bsp_led_red_set(uint8_t on);

/**
 * @brief  绿灯开关
 * @param  on 1=亮，0=灭
 * @return 无
 */
void bsp_led_green_set(uint8_t on);

/**
 * @brief  红绿灯全灭
 * @return 无
 */
void bsp_led_all_off(void);

/**
 * @brief   设置电机方向。STOP 时若正在转，先反转刹车再滑行
 * @note    占空比用 BOARD_MOTOR_PWM_DUTY（手动点动）
 * @param  dir 收绳 / 放绳 / 停转
 * @return 无
 */
void bsp_motor_set(BspMotorDir_t dir);

/**
 * @brief  设置电机方向与 PWM 占空比
 * @param  dir  收绳 / 放绳 / 停转
 * @param  duty 占空比 0~10000（0%~100%）；STOP 时忽略
 * @return 无
 */
void bsp_motor_set_pwm(BspMotorDir_t dir, uint16_t duty);

/**
 * @brief  推进换向死区与停转反转刹车，按真实毫秒计时
 * @return 无
 */
void bsp_motor_brake_tick(void);

/**
 * @brief  电机是否还在转或刹车
 * @return 1=忙碌，0=已停且 PWM 已关
 */
uint8_t bsp_motor_is_busy(void);

/**
 * @brief  读取按键
 * @return 1=按下，0=未按下
 */
uint8_t bsp_key_is_pressed(void);

/**
 * @brief  读取 ME4054 CHG：充电中为低
 * @return 1=充电中，0=未充电
 */
uint8_t bsp_chg_is_low(void);

/**
 * @brief  读取电池电压
 * @return 电池电压，单位 mV
 */
uint16_t bsp_vbat_mv(void);

/**
 * @brief  读取 5V 口电压，用于判断 USB
 * @return VPWR 电压，单位 mV
 */
uint16_t bsp_vpwr_mv(void);

/**
 * @brief  USB 是否在位（以 ADC 为主，比较器为辅）
 * @return 1=插入，0=未插入
 */
uint8_t  bsp_vpwr_is_online(void);

/**
 * @brief  轻睡前关掉空闲电机 PWM（电机忙碌时不关）
 * @return 无
 */
void bsp_hw_sleep_pwm_off(void);

/**
 * @brief  进深睡前把电机 PWM 关掉并拉低，灯全灭
 * @return 无
 */
void bsp_hw_enter_sleep_io(void);

#endif /* __BSP_HW_H__ */