/**
 * @file battery_monitor.h
 * @brief Header file for the battery monitoring module.
 *
 * This module provides functions to initialize, start, and retrieve
 * battery voltage measurements and percentage calculations.
 */

#ifndef BATTERY_MONITOR_H__
#define BATTERY_MONITOR_H__

#include <stdint.h>
#include <stdbool.h>

/**
 * @brief Starts periodic battery voltage measurements.
 *
 * This function initiates a timer that triggers ADC measurements
 * periodically. After a predefined number of samples are collected,
 * they are averaged, converted to a percentage, and reported via the
 * registered callback.
 *
 * @return 0 on success, a negative errno code on failure.
 */
int battery_monitor_start_periodic_measurement(void);

/**
 * @brief Retrieves the last calculated battery percentage.
 *
 * This function returns the most recently calculated battery percentage.
 * If no measurements have been completed yet, it will return 0.
 *
 * @return The last known battery percentage (0-100).
 */
uint8_t battery_monitor_get_percentage(void);

/**
 * @brief Checks if the battery is currently charging.
 *
 * This function reads the GPIO pin configured for charge detection
 * and returns true if the battery is charging, false otherwise.
 *
 * @return true if the battery is charging, false if not.
 */
bool batt_get_charge_status(void);

/**
 * @brief Initializes the battery monitoring module.
 *
 * This function sets up the ADC peripheral and configures the necessary
 * channels for battery voltage measurement. It also registers the
 * callback function for reporting battery percentage.
 *
 * @param callback A pointer to the function that will be called when
 * a new battery percentage is available.
 * @return 0 on success, a negative errno code on failure.
 */
int battery_monitor_init(void);

#endif /* BATTERY_MONITOR_H__ */