electrical.hpp

Go to the documentation of this file.

/**
 * @file electrical.hpp
 * @brief Electrical description of an analog port — the jack-to-converter circuit
 * @ingroup hal
 *
 * Describes what sits between a jack and the ADC: the voltage span the full
 * code range represents, the converter resolution, and whether the front end
 * inverts. Instances are generated by sloth from the hardware manifests into
 * `sbl::hw::electrical` (config/electrical.hpp); components derive their
 * conditioning from them. Hand-written instances are for tests and one-offs.
 *
 * Codes are right-aligned unsigned counts, 0 .. (2^bits - 1), as the ADC
 * drivers deliver them (STM32H7: RM0433 Rev 8 §25.6.15, right-aligned by default).
 */
 
#ifndef SBL_HW_HAL_ADC_ELECTRICAL_HPP_
#define SBL_HW_HAL_ADC_ELECTRICAL_HPP_
 
#include <cstdint>
 
namespace sbl {
namespace hal {
namespace adc {
 
struct Electrical {
    float lo_v;          ///< Voltage at code 0 (or at full scale, if inverted)
    float hi_v;          ///< Voltage at full scale (or at code 0, if inverted)
    uint8_t bits;        ///< Converter resolution
    bool inverted;       ///< +V at the jack reads as a lower code
 
    constexpr float counts_max() const {
        return static_cast<float>((1u << bits) - 1u);
    }
 
    constexpr float counts_per_volt() const {
        return counts_max() / (hi_v - lo_v);
    }
 
    /// Code for a voltage at the jack, clamped to the converter's rails.
    constexpr uint16_t encode(float volts) const {
        float t = (volts - lo_v) / (hi_v - lo_v);
        if (t < 0.0f) t = 0.0f;
        if (t > 1.0f) t = 1.0f;
        if (inverted) t = 1.0f - t;
        return static_cast<uint16_t>(t * counts_max() + 0.5f);
    }
 
    /// Voltage at the jack for a code.
    constexpr float decode(uint16_t counts) const {
        float t = static_cast<float>(counts) / counts_max();
        if (inverted) t = 1.0f - t;
        return lo_v + t * (hi_v - lo_v);
    }
 
    /// Code that reads as 0 V — the bipolar midpoint. Clamps if 0 V is out of range.
    constexpr uint16_t midpoint() const { return encode(0.0f); }
};
 
} // namespace adc
} // namespace hal
} // namespace sbl
 
#endif // SBL_HW_HAL_ADC_ELECTRICAL_HPP_