Protocol rework

sbc_fw/adc.h

@@ -1,57 +1,61 @@
 /*
  * @file adc.h
- * @brief
- * 
+ * @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 ADC for fast radiation detection
+ * @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 ADC to default settings
+ * @brief Restore ADC0 to its default configuration suitable for blocking
+ *        analogRead()-style reads of housekeeping channels.
  */
 void adc_restore_default(void);
 
 /**
- * @brief Convert ADC reading to temperature in 0.1°C
- * @param adc_value 12-bit ADC reading
- * @return Temperature in 0.1°C
+ * @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 ADC reading to voltage in mV
- * @param adc_value ADC reading
- * @return Voltage in mV
+ * @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 Read ADC with oversampling
- * @param pin Analog pin to read
- * @param samples Number of samples for oversampling
- * @return Averaged 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 Command to calibrate ADC and read reference values
+ * @brief Read the MCU internal temperature sensor (blocking, ~10 ms).
+ * @return Temperature in Kelvin.
  */
-void adc_cmd_calibrate(void);
+uint16_t adc_read_tempsense(void);
 
-#endif // ADC_H_
+#endif /* ADC_H_ */