new release

components/buzzer/include/buzzer.h

@@ -1,11 +1,66 @@
+// 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