// buzzer.h
#pragma once

#include <stdint.h>
#include <stdbool.h>
#include "esp_err.h"
#include "buzzer_events.h"   // para buzzer_pattern_id_t

#ifdef __cplusplus
extern "C" {
#endif

/**
 * @brief Inicializa hardware, fila e task do buzzer; registra event handlers.
 */
void buzzer_init(void);

/**
 * @brief Desinicializa o buzzer (opcional), removendo handlers e task.
 */
void buzzer_deinit(void);

/**
 * @brief Solicita tocar um padrão de buzzer de forma assíncrona.
 * @param id  Enum do padrão (ver buzzer_events.h).
 */
void buzzer_play(buzzer_pattern_id_t id);

/**
 * @brief Interrompe imediatamente qualquer padrão em execução e esvazia a fila.
 */
void buzzer_stop(void);

/**
 * @brief Ativa/Desativa globalmente o buzzer (mute).
 *        Quando desativado, não toca e garante nível/desligado.
 */
void buzzer_set_enabled(bool enabled);

/**
 * @brief Retorna o estado atual de enable/mute do buzzer.
 */
bool buzzer_get_enabled(void);

/**
 * @brief Define quiet hours (janela silenciosa) em minutos desde 00:00.
 * @param enabled     Habilita/desabilita quiet hours.
 * @param start_min   Início (0..1439).
 * @param end_min     Fim (0..1439). Pode cruzar meia-noite.
 */
void buzzer_set_quiet_hours(bool enabled, uint16_t start_min, uint16_t end_min);

/**
 * @brief Ajusta a frequência PWM (somente PASSIVE/LEDC; timer exclusivo recomendado).
 * @return ESP_OK em sucesso; erro se modo inválido ou argumento fora do range.
 */
esp_err_t buzzer_set_frequency(uint32_t hz);

/**
 * @brief Define o duty cycle em porcentagem (0..100) para PASSIVE/LEDC.
 */
void buzzer_set_duty_percent(uint8_t pct);

#ifdef __cplusplus
}
#endif