/**
 * @file    buzzer.h
 * @brief   无源蜂鸣器控制 (LEDC PWM 音调)
 *
 * 硬件建议 (无源蜂鸣器电流较大, 建议用 NPN 三极管驱动):
 *   ESP32 GPIO ──[1kΩ]── S8050 基极
 *   蜂鸣器 +  → 5V (或 3.3V)
 *   蜂鸣器 −  → 三极管集电极
 *   三极管发射极 → GND
 *   (磁式蜂鸣器可在两端并联 1N4148 续流二极管)
 */

#ifndef BUZZER_H
#define BUZZER_H

#include <stdint.h>

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief  初始化无源蜂鸣器 (LEDC 独立定时器/通道)
 * @param  gpio  GPIO 引脚号, 如 GPIO_NUM_13
 */
void buzzer_init(int gpio);

/**
 * @brief  开始发声
 * @param  freq_hz  频率 (Hz), 常用 2000~4000
 */
void buzzer_on(uint32_t freq_hz);

/**
 * @brief  停止发声 (静音)
 */
void buzzer_off(void);

/**
 * @brief  设置音调频率 (不改变发声状态)
 */
void buzzer_set_freq(uint32_t freq_hz);

/**
 * @brief  阻塞式响一声 (需在任务中调用)
 * @param  freq_hz       频率 (Hz)
 * @param  duration_ms   时长 (ms)
 */
void buzzer_beep(uint32_t freq_hz, uint32_t duration_ms);

/**
 * @brief  阻塞式响两声 (确认提示音)
 */
void buzzer_beep_twice(uint32_t freq_hz, uint32_t duration_ms);

/**
 * @brief  阻塞式急促响三声 (执行完成提示音)
 */
void buzzer_beep_triple(uint32_t freq_hz, uint32_t duration_ms);

#ifdef __cplusplus
}
#endif

#endif /* BUZZER_H */