new buzzer component

components/auth/include/auth.h

@@ -8,74 +8,105 @@
 extern "C" {
 #endif
 
-/// Tamanho máximo de uma tag RFID (incluindo '\0')
-#define AUTH_TAG_MAX_LEN 20
+/// Maximum length of an RFID tag (including null terminator)
+#define AUTH_TAG_MAX_LEN 30
 
-/// Estrutura de evento emitida após leitura de uma tag
+/// Event structure emitted after a tag is read
 typedef struct {
-    char tag[AUTH_TAG_MAX_LEN];  ///< Tag lida
-    bool authorized;             ///< true se a tag for reconhecida como válida
+    char tag[AUTH_TAG_MAX_LEN];  ///< The tag that was read
+    bool authorized;             ///< true if the tag is valid
 } auth_event_t;
 
 /**
- * @brief Inicializa o sistema de autenticação.
+ * @brief Initializes the authentication system.
  * 
- * - Carrega a configuração (enabled) da NVS
- * - Inicia o leitor Wiegand
- * - Emite evento AUTH_EVENT_INIT com estado atual
+ * - Loads configuration (enabled/disabled) from NVS
+ * - Starts the Wiegand reader
+ * - Emits AUTH_EVENT_INIT with current status
  */
 void auth_init(void);
 
 /**
- * @brief Ativa ou desativa o uso de autenticação via RFID.
+ * @brief Enables or disables RFID-based authentication.
  * 
- * Esta configuração é persistida em NVS. Se desativado, o sistema
- * considerará todas as autorizações como aceitas.
+ * This setting is persisted in NVS. If disabled,
+ * all tags will be treated as authorized.
  *
- * @param value true para ativar, false para desativar
+ * @param value true to enable authentication, false to disable
  */
 void auth_set_enabled(bool value);
 
 /**
- * @brief Verifica se o sistema de autenticação está habilitado.
+ * @brief Checks whether authentication is currently enabled.
+ *
+ * @return true if enabled, false if disabled
  */
 bool auth_is_enabled(void);
 
 /**
- * @brief Adiciona uma nova tag RFID à lista de autorizadas.
+ * @brief Adds a new RFID tag to the authorized list.
  *
- * @param tag String da tag (máx AUTH_TAG_MAX_LEN-1)
- * @return true se a tag foi adicionada, false se já existia ou inválida
+ * @param tag The RFID tag (max AUTH_TAG_MAX_LEN-1 characters)
+ * @return true if the tag was added successfully,
+ *         false if it already exists or is invalid
  */
 bool auth_add_tag(const char *tag);
 
 /**
- * @brief Remove uma tag previamente cadastrada.
+ * @brief Removes an existing RFID tag from the authorized list.
  *
- * @param tag String da tag
- * @return true se foi removida, false se não encontrada
+ * @param tag The tag to remove
+ * @return true if the tag was removed, false if not found
  */
 bool auth_remove_tag(const char *tag);
 
 /**
- * @brief Verifica se uma tag já está registrada como válida.
+ * @brief Checks whether a tag is already registered.
+ *
+ * @param tag The tag to check
+ * @return true if the tag exists, false otherwise
  */
 bool auth_tag_exists(const char *tag);
 
 /**
- * @brief Lista todas as tags válidas atualmente registradas (via logs).
+ * @brief Logs all currently registered tags via ESP logging.
  */
 void auth_list_tags(void);
 
 /**
- * @brief Processa uma tag RFID lida (chamada normalmente pelo leitor).
+ * @brief Processes a read RFID tag.
  *
- * - Verifica validade
- * - Emite evento AUTH_EVENT_TAG_PROCESSED
- * - Inicia timer de expiração se autorizada
+ * - Checks whether it's authorized
+ * - Emits AUTH_EVENT_TAG_PROCESSED event
+ * - Starts expiration timer if authorized
+ *
+ * @param tag The tag that was read
  */
 void auth_process_tag(const char *tag);
 
+/**
+ * @brief Enables registration mode for the next tag read.
+ *
+ * When registration mode is active, the next tag read
+ * will be added to the authorized list automatically.
+ * Mode is deactivated after one tag is registered.
+ */
+void auth_wait_for_tag_registration(void);
+
+/**
+ * @brief Returns the total number of registered tags.
+ *
+ * @return Number of valid tags
+ */
+int auth_get_tag_count(void);
+
+/**
+ * @brief Returns the tag string at the given index.
+ *
+ * @param index The index (0 ≤ index < auth_get_tag_count())
+ * @return Pointer to the tag string, or NULL if index is invalid
+ */
+const char *auth_get_tag_by_index(int index);
 
 #ifdef __cplusplus
 }