/******************************************************************************
 * @file    bsp_hw.h
 * @brief   CBC4 板级硬件：上下双电机 / 震动 / LED / 按键 / 充电 / 电量
 * @author  cyWu <1917507415@qq.com>
 * @date    2026.08.25
 * @version V1.6.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 时钟，避免待机空转耗电
 * - V1.6.0, 2026.08.25, cyWu, 去掉停转反接刹车，改自由滑行停止，避免刹车
 *                             电流冲击拉垮供电轨触发 LVD 复位
 ******************************************************************************/

#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_BACKWARD = -1,
    BSP_MOTOR_STOP = 0,
    BSP_MOTOR_FORWARD = 1
} 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  left_dir/right_dir 左右轮方向
 * @param  left_duty/right_duty 左右轮占空比
 * @return 无
 */
void bsp_drive_set(BspMotorDir_t left_dir, uint16_t left_duty,
                   BspMotorDir_t right_dir, uint16_t right_duty);

/** 停止左右轮，四路 PWM 全部清零。 */
void bsp_drive_stop(void);

/**
 * @brief  兼容旧调用；弹力魔盒每个动作一次性更新上下电机四路 PWM
 * @return 无
 */
void bsp_motor_switch_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);

/** @return 1 when TP4056 STDBY is low; otherwise 0. */
uint8_t bsp_stby_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__ */