/*******************************************************************************
 * @file    full_agc.h
 * @brief   Automatic Gain Control (AGC) header for NIRS measurement system
 * @author  Charles KWON <charleskwon@medithings.co.kr>
 * @version V2.0.0
 * @date    2025-12-31
 *
 * Copyright (c) 2025 Medithings Inc.
 * All rights reserved.
 *
 * This header defines the interface for the AGC module which automatically
 * calibrates photodetector gain for each LED-PD pair in the NIRS system.
 ******************************************************************************/

#ifndef _FULL_AGC_H__
#define _FULL_AGC_H__

/*============================================================================*/
/* Includes - Charles KWON                                                    */
/*============================================================================*/
#include "sdk_common.h"

/*============================================================================*/
/* Configuration Constants - Charles KWON                                     */
/*============================================================================*/

/**
 * @brief Number of photodetectors in the system
 * - Charles KWON
 *
 * Used to determine iteration count for AGC scanning
 */
#define PD_NO   1

/*============================================================================*/
/* AGC Control Functions - Charles KWON                                       */
/*============================================================================*/

/**
 * @brief Initialize and start AGC sequence for current phase
 * - Charles KWON
 *
 * Configures LED/PD lists based on which phase is active (A or B).
 * Must be called after setting full_agc_a_start or full_agc_b_start.
 */
void full_agc_start(void);

/**
 * @brief Terminate AGC sequence and perform cleanup
 * - Charles KWON
 *
 * Stops all AGC timers, uninitializes SAADC, restores HW I2C mode,
 * turns off all LEDs/PDs, and clears the processing flag.
 */
void full_agc_end(void);

/*============================================================================*/
/* SAADC Functions - Charles KWON                                             */
/*============================================================================*/

/**
 * @brief Initialize SAADC for AGC voltage measurement
 * - Charles KWON
 *
 * Configures single-ended ADC on AIN6 (FSA5157P6X analog switch output)
 * with double-buffering for continuous sampling during AGC.
 */
void full_agc_adc_init(void);

/**
 * @brief Uninitialize SAADC after AGC completion
 * - Charles KWON
 *
 * Releases SAADC resources for use by other modules.
 */
void full_agc_uninit(void);

/*============================================================================*/
/* AGC Loop Timer Functions - Charles KWON                                    */
/*============================================================================*/

/**
 * @brief AGC measurement loop timer callback
 * - Charles KWON
 *
 * Periodically called to drive the AGC state machine.
 * Each call advances the measurement sequence by one step.
 *
 * @param[in] p_context Unused timer context parameter
 */
void full_agc_loop(void * p_context);

/**
 * @brief Start AGC measurement loop timer
 * - Charles KWON
 *
 * Begins periodic timer that drives the AGC state machine.
 */
void full_agc_timer_start(void);

/**
 * @brief Stop AGC measurement loop timer
 * - Charles KWON
 */
void full_agc_timer_stop(void);

/**
 * @brief Initialize AGC loop timer
 * - Charles KWON
 *
 * Creates the repeating timer used for AGC measurement sequencing.
 * Must be called during system initialization before starting AGC.
 */
void full_agc_timer_init(void);

/*============================================================================*/
/* AGC Entry Point - Charles KWON                                             */
/*============================================================================*/

/**
 * @brief Start full AGC measurement sequence
 * - Charles KWON
 *
 * Main entry point for AGC calibration. This function:
 * 1. Initializes AGC state variables
 * 2. Stops battery monitoring timer
 * 3. Configures Part A LED/PD lists
 * 4. Initializes SAADC
 * 5. Starts AGC loop timer
 *
 * AGC automatically transitions from Part A to Part B and
 * stores results in EEPROM upon completion.
 */
void full_agc_mesurement_start(void);

/*============================================================================*/
/* AGC Data Transmission Functions - Charles KWON                             */
/*============================================================================*/

/**
 * @brief AGC data transmission timer callback
 * - Charles KWON
 *
 * Handles sequenced transmission of AGC calibration results over BLE.
 * Data is sent in chunks to comply with BLE packet size limits.
 *
 * @param[in] p_context Unused timer context parameter
 */
void full_agc_send_loop(void * p_context);

/**
 * @brief Start AGC data transmission timer
 * - Charles KWON
 */
void full_agc_send_timer_start(void);

/**
 * @brief Stop AGC data transmission timer
 * - Charles KWON
 */
void full_agc_send_timer_stop(void);

/**
 * @brief Initialize AGC send timer
 * - Charles KWON
 *
 * Creates the single-shot timer used for sequenced BLE transmission.
 * Must be called during system initialization.
 */
void full_agc_send_timer_init(void);

#endif /* _FULL_AGC_H__ */