/*
 * @file adc.h
 * @brief ATmega4809 ADC0 driver and engineering-unit conversions.
 *
 * Created: 27.09.2025 05:06:42
 * Author: ThePetrovich
 *
 * Copyright YKSA - Sakha Aerospace Systems, LLC.
 * See the LICENSE file for details.
 *
 * SPDX-License-Identifier: BSD-3-Clause
 */

#ifndef ADC_H_
#define ADC_H_

#include <stdint.h>

/**
 * @brief Enable ADC0 in fast event-driven mode for radiation pulse capture.
 *        ADC0 conversions are started by the detector trigger via EVSYS and
 *        completed by the ADC0_RESRDY ISR.
 */
void adc_enable_fast(void);

/**
 * @brief Restore ADC0 to its default configuration suitable for blocking
 *        analogRead()-style reads of housekeeping channels.
 */
void adc_restore_default(void);

/**
 * @brief Convert a raw ADC reading to temperature in 0.1 °C.
 *        Uses calibration values from @c config when available.
 * @param adc_value Raw ADC reading.
 * @return Temperature in 0.1 °C.
 */
int16_t adc_to_temperature_c(uint16_t adc_value);

/**
 * @brief Convert a raw ADC reading from the V28 feedback divider to mV.
 * @param adc_value Raw ADC reading.
 * @return Voltage at the sensor input in mV.
 */
uint16_t adc_to_voltage_mv(uint16_t adc_value);

/**
 * @brief Block-read an analog pin with software oversampling.
 * @param pin     Analog pin to read.
 * @param samples Sample count (1, 4, 16, or 64).
 * @return Sum of samples right-shifted by log2(samples) to give the average.
 */
uint16_t adc_read_oversampled(uint8_t pin, uint8_t samples);

/**
 * @brief Read the MCU internal temperature sensor (blocking, ~10 ms).
 * @return Temperature in Kelvin.
 */
uint16_t adc_read_tempsense(void);

#endif /* ADC_H_ */