/**
 * @file buzzer.h
 * @brief 蜂鸣器设备驱动头文件
 * @details 提供蜂鸣器音频播放功能，支持单音符播放和预设音乐播放
 * @author Generated by STM32CubeMX
 * @date 2025年10月23日
 */

#pragma once

#ifdef __cplusplus
extern "C" {
#endif

/* Includes ----------------------------------------------------------------- */
#include "bsp/pwm.h"    // PWM底层硬件抽象层
#include "device.h"     // 设备通用头文件
#include <stddef.h>     // 标准定义
#include <stdint.h>     // 标准整型定义

/* USER INCLUDE BEGIN */

/* USER INCLUDE END */

/* Exported constants ------------------------------------------------------- */

/* USER DEFINE BEGIN */

/* USER DEFINE END */

/* Exported types ----------------------------------------------------------- */

/**
 * @brief 音符枚举类型
 * @details 定义标准十二平均律音符，用于音乐播放
 */
typedef enum {
  NOTE_C = 0,       ///< Do音符
  NOTE_CS = 1,      ///< Do#音符 (升Do)
  NOTE_D = 2,       ///< Re音符
  NOTE_DS = 3,      ///< Re#音符 (升Re)
  NOTE_E = 4,       ///< Mi音符
  NOTE_F = 5,       ///< Fa音符
  NOTE_FS = 6,      ///< Fa#音符 (升Fa)
  NOTE_G = 7,       ///< Sol音符
  NOTE_GS = 8,      ///< Sol#音符 (升Sol)
  NOTE_A = 9,       ///< La音符
  NOTE_AS = 10,     ///< La#音符 (升La)
  NOTE_B = 11,      ///< Si音符
  NOTE_REST = 255   ///< 休止符 (无声音)
} NOTE_t;

/**
 * @brief 音调结构体
 * @details 定义一个完整的音调信息，包括音符、八度和持续时间
 */
typedef struct {
  NOTE_t note;          ///< 音符名称 (使用NOTE_t枚举)
  uint8_t octave;       ///< 八度 (0-8，通常使用3-7)
  uint16_t duration_ms; ///< 持续时间，单位毫秒
} Tone_t;

/**
 * @brief 预设音乐枚举类型
 * @details 定义可播放的预设音乐类型
 */
typedef enum {
  /* USER MUSIC MENU BEGIN */
  MUSIC_RM,     ///< RM战队音乐
  MUSIC_NOKIA,  ///< 诺基亚经典铃声
  /* USER MUSIC MENU END */
} MUSIC_t;

/**
 * @brief 蜂鸣器设备结构体
 * @details 蜂鸣器设备的完整描述，包含设备头信息和PWM通道
 */
typedef struct {
  DEVICE_Header_t header;     ///< 设备通用头信息 (在线状态、时间戳等)
  BSP_PWM_Channel_t channel;  ///< PWM输出通道
} BUZZER_t;

/* USER STRUCT BEGIN */

/* USER STRUCT END */

/* Exported functions prototypes -------------------------------------------- */

/**
 * @brief 初始化蜂鸣器设备
 * @param buzzer 蜂鸣器设备结构体指针
 * @param channel PWM输出通道
 * @return int8_t 返回值：DEVICE_OK(0) 成功，DEVICE_ERR(-1) 失败
 * @note 初始化后蜂鸣器处于停止状态
 */
int8_t BUZZER_Init(BUZZER_t *buzzer, BSP_PWM_Channel_t channel);

/**
 * @brief 启动蜂鸣器播放
 * @param buzzer 蜂鸣器设备结构体指针
 * @return int8_t 返回值：DEVICE_OK(0) 成功，DEVICE_ERR(-1) 失败
 * @note 需要先调用BUZZER_Set设置频率和占空比
 */
int8_t BUZZER_Start(BUZZER_t *buzzer);

/**
 * @brief 停止蜂鸣器播放
 * @param buzzer 蜂鸣器设备结构体指针
 * @return int8_t 返回值：DEVICE_OK(0) 成功，DEVICE_ERR(-1) 失败
 */
int8_t BUZZER_Stop(BUZZER_t *buzzer);

/**
 * @brief 设置蜂鸣器频率和占空比
 * @param buzzer 蜂鸣器设备结构体指针
 * @param freq 频率 (Hz)，通常范围20Hz-20kHz
 * @param duty_cycle 占空比 (0.0-1.0)，影响音量大小
 * @return int8_t 返回值：DEVICE_OK(0) 成功，DEVICE_ERR(-1) 失败
 * @note 设置后需要调用BUZZER_Start才能听到声音
 */
int8_t BUZZER_Set(BUZZER_t *buzzer, float freq, float duty_cycle);

/**
 * @brief 播放预设音乐
 * @param buzzer 蜂鸣器设备结构体指针
 * @param music 音乐类型 (使用MUSIC_t枚举)
 * @return int8_t 返回值：DEVICE_OK(0) 成功，DEVICE_ERR(-1) 失败
 * @note 这是一个阻塞函数，会播放完整首音乐后返回
 */
int8_t BUZZER_PlayMusic(BUZZER_t *buzzer, MUSIC_t music);

/* USER FUNCTION BEGIN */

/* USER FUNCTION END */

#ifdef __cplusplus
}
#endif