driver.hpp

Go to the documentation of this file.

/**
 * @file driver.hpp
 * @brief ADC driver interface - canonical types for MCU driver implementations
 * @ingroup hal
 *
 * This header provides everything an ADC driver needs:
 * - AdcHandle: Channel reference with peripheral and channel number
 * - SampleTime: Sampling duration configuration
 *
 * ## Low-Level Driver Interface
 *
 * Drivers implement the following static interface:
 *
 *   // Initialize the ADC peripheral
 *   static void init();
 *
 *   // Configure channel for conversion
 *   static void configure_channel(const sbl::AdcHandle& handle,
 *                                 sbl::adc::SampleTime sample_time);
 *
 *   // Start single conversion
 *   static void start_conversion(const sbl::AdcHandle& handle);
 *
 *   // Check if conversion is complete
 *   static bool is_conversion_complete();
 *
 *   // Read raw conversion result
 *   static uint16_t read_raw();
 *
 *   // Get ADC resolution (compile-time constant)
 *   static constexpr uint8_t resolution_bits();
 *
 * ## Convenience Helpers
 *
 * The core library provides convenience functions that compose the
 * low-level primitives:
 *
 *   // Single blocking read
 *   uint16_t value = sbl::adc::read<sbl::driver::Adc>(handle);
 *
 * Usage in driver:
 *   #include <sbl/hal/adc/driver.hpp>
 *   using sbl::adc::SampleTime;
 */
 
#ifndef SBL_HAL_ADC_DRIVER_HPP_
#define SBL_HAL_ADC_DRIVER_HPP_
 
#include "handle.hpp"
#include "types.hpp"
 
namespace sbl {
 
// Convenience namespace alias for drivers
// Maps sbl::core::hal::adc -> sbl::adc for cleaner code
namespace adc {
    using SampleTime = sbl::core::hal::adc::SampleTime;
    using Resolution = sbl::core::hal::adc::Resolution;
 
    /**
     * @brief Blocking single-channel ADC read
     *
     * Convenience function that composes low-level driver primitives.
     * Configures the channel, starts conversion, waits for completion,
     * and returns the raw value.
     *
     * @tparam Driver ADC driver type (e.g., sbl::driver::Adc)
     * @param handle ADC channel handle from hardware config
     * @param sample_time Sampling duration (default: Medium)
     * @return Raw ADC value (resolution depends on driver)
     *
     * Example:
     *   auto value = sbl::adc::read<sbl::driver::Adc>(sbl::hw::adc::knob1);
     */
    template<typename Driver>
    inline uint16_t read(const AdcHandle& handle,
                         SampleTime sample_time = SampleTime::Medium) {
        Driver::configure_channel(handle, sample_time);
        Driver::start_conversion(handle);
        while (!Driver::is_conversion_complete()) {
            // Busy wait - suitable for polling mode
        }
        return Driver::read_raw();
    }
 
    /**
     * @brief Convert raw ADC value to voltage (millivolts)
     *
     * @tparam Driver ADC driver type for resolution info
     * @param raw_value Raw ADC reading
     * @param vref_mv Reference voltage in millivolts (default: 3300mV)
     * @return Voltage in millivolts
     */
    template<typename Driver>
    inline uint32_t to_millivolts(uint16_t raw_value, uint32_t vref_mv = 3300) {
        constexpr uint32_t max_value = (1u << Driver::resolution_bits()) - 1;
        return (static_cast<uint32_t>(raw_value) * vref_mv) / max_value;
    }
 
} // namespace adc
 
} // namespace sbl
 
#endif // SBL_HAL_ADC_DRIVER_HPP_