adc.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Chris Leishman
 
#pragma once
 
#include <idfxx/error>
#include <idfxx/gpio>
 
#include <chrono>
#include <cstddef>
#include <cstdint>
#include <electro/electro>
#include <frequency/frequency>
#include <memory>
#include <optional>
#include <span>
#include <vector>
 
namespace idfxx::adc {
 
enum class attenuation : uint8_t {
    db_0,   
    db_2_5, 
    db_6,   
    db_12,  
};
 
struct divider_ratio {
    int num = 1; 
    int den = 1; 
 
    [[nodiscard]] constexpr bool operator==(const divider_ratio&) const noexcept = default;
};
 
class input {
public:
    struct config {
        idfxx::gpio pin = gpio::nc();                      
        enum attenuation attenuation = attenuation::db_12; 
        divider_ratio divider{};
 
        [[nodiscard]] constexpr bool operator==(const config&) const noexcept = default;
    };
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit input(config config);
#endif
 
    [[nodiscard]] static result<input> make(config config);
 
    ~input();
 
    input(const input&) = delete;
    input& operator=(const input&) = delete;
    input(input&& other) noexcept;
    input& operator=(input&& other) noexcept;
 
    [[nodiscard]] idfxx::gpio pin() const noexcept;
 
    [[nodiscard]] enum attenuation attenuation() const noexcept;
 
    [[nodiscard]] divider_ratio divider() const noexcept;
 
    [[nodiscard]] bool calibrated() const noexcept;
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] int read_raw() { return unwrap(try_read_raw()); }
 
    [[nodiscard]] electro::millivolts read_voltage() { return unwrap(try_read_voltage()); }
#endif
 
    [[nodiscard]] result<int> try_read_raw();
 
    [[nodiscard]] result<electro::millivolts> try_read_voltage();
 
private:
    struct state;
    explicit input(std::unique_ptr<state> s) noexcept;
 
    std::unique_ptr<state> _state;
};
 
class sampler {
public:
    struct config {
        std::vector<idfxx::gpio> pins{};
        enum attenuation attenuation = attenuation::db_12;
        freq::hertz sample_rate{20'000};
        size_t frame_samples = 256;
        size_t buffer_samples = 1024;
 
        [[nodiscard]] bool operator==(const config&) const noexcept = default;
    };
 
    struct sample {
        idfxx::gpio pin = gpio::nc(); 
        int raw = 0;                  
 
        [[nodiscard]] constexpr bool operator==(const sample&) const noexcept = default;
    };
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit sampler(config config);
#endif
 
    [[nodiscard]] static result<sampler> make(config config);
 
    ~sampler();
 
    sampler(const sampler&) = delete;
    sampler& operator=(const sampler&) = delete;
    sampler(sampler&& other) noexcept;
    sampler& operator=(sampler&& other) noexcept;
 
    [[nodiscard]] std::span<const idfxx::gpio> pins() const noexcept;
 
    [[nodiscard]] enum attenuation attenuation() const noexcept;
 
    [[nodiscard]] freq::hertz sample_rate() const noexcept;
 
    [[nodiscard]] bool running() const noexcept;
 
    [[nodiscard]] bool calibrated() const noexcept;
 
    [[nodiscard]] size_t overruns() const noexcept;
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void start() { unwrap(try_start()); }
 
    void stop() { unwrap(try_stop()); }
#endif
 
    [[nodiscard]] result<void> try_start();
 
    result<void> try_stop();
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] size_t read(std::span<sample> out) { return unwrap(try_read(out)); }
 
    template<typename Rep, typename Period>
    [[nodiscard]] size_t read(std::span<sample> out, const std::chrono::duration<Rep, Period>& timeout) {
        return unwrap(try_read(out, timeout));
    }
 
    [[nodiscard]] size_t read(std::span<electro::millivolts> out) { return unwrap(try_read(out)); }
 
    template<typename Rep, typename Period>
    [[nodiscard]] size_t read(std::span<electro::millivolts> out, const std::chrono::duration<Rep, Period>& timeout) {
        return unwrap(try_read(out, timeout));
    }
#endif
 
    [[nodiscard]] result<size_t> try_read(std::span<sample> out) { return _try_read(out, std::nullopt); }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<size_t> try_read(std::span<sample> out, const std::chrono::duration<Rep, Period>& timeout) {
        return _try_read(out, std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
    [[nodiscard]] result<size_t> try_read(std::span<electro::millivolts> out) {
        return _read_voltage(out, std::nullopt);
    }
 
    template<typename Rep, typename Period>
    [[nodiscard]] result<size_t>
    try_read(std::span<electro::millivolts> out, const std::chrono::duration<Rep, Period>& timeout) {
        return _read_voltage(out, std::chrono::ceil<std::chrono::milliseconds>(timeout));
    }
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] electro::millivolts to_voltage(const sample& s) const { return unwrap(try_to_voltage(s)); }
 
    [[nodiscard]] electro::millivolts to_voltage(int raw) const { return unwrap(try_to_voltage(raw)); }
 
    void to_voltage(std::span<const sample> in, std::span<electro::millivolts> out) const {
        unwrap(try_to_voltage(in, out));
    }
#endif
 
    [[nodiscard]] result<electro::millivolts> try_to_voltage(const sample& s) const;
 
    [[nodiscard]] result<electro::millivolts> try_to_voltage(int raw) const;
 
    [[nodiscard]] result<void> try_to_voltage(std::span<const sample> in, std::span<electro::millivolts> out) const;
 
private:
    struct state;
    explicit sampler(std::unique_ptr<state> s) noexcept;
    // A nullopt timeout means wait forever.
    [[nodiscard]] result<size_t> _try_read(std::span<sample> out, std::optional<std::chrono::milliseconds> timeout);
    [[nodiscard]] result<size_t>
    _read_voltage(std::span<electro::millivolts> out, std::optional<std::chrono::milliseconds> timeout);
 
    std::unique_ptr<state> _state;
};
 
 
} // namespace idfxx::adc