ds18x20.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 <idfxx/onewire>
 
#include <array>
#include <cstdint>
#include <span>
#include <string>
#include <thermo/thermo>
#include <vector>
 
namespace idfxx::ds18x20 {
 
enum class family : uint8_t {
    ds18s20 = 0x10,  
    ds1822 = 0x22,   
    ds18b20 = 0x28,  
    max31850 = 0x3B, 
};
 
enum class resolution : uint8_t {
    bits_9 = 0x1F,  
    bits_10 = 0x3F, 
    bits_11 = 0x5F, 
    bits_12 = 0x7F, 
};
 
class device;
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
[[nodiscard]] inline std::vector<device> scan_devices(idfxx::gpio pin, size_t max_devices = 8);
 
[[nodiscard]] inline std::vector<thermo::millicelsius> measure_and_read_multi(std::span<const device> devices);
#endif
 
[[nodiscard]] result<std::vector<device>> try_scan_devices(idfxx::gpio pin, size_t max_devices = 8);
 
[[nodiscard]] result<std::vector<thermo::millicelsius>> try_measure_and_read_multi(std::span<const device> devices);
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
inline std::vector<device> scan_devices(idfxx::gpio pin, size_t max_devices) {
    return unwrap(try_scan_devices(pin, max_devices));
}
 
inline std::vector<thermo::millicelsius> measure_and_read_multi(std::span<const device> devices) {
    return unwrap(try_measure_and_read_multi(devices));
}
#endif
 
class device {
public:
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit device(idfxx::gpio pin, onewire::address addr = onewire::address::any());
#endif
 
    [[nodiscard]] static result<device> make(idfxx::gpio pin, onewire::address addr = onewire::address::any());
 
    // Copyable and movable
    device(const device&) = default;
    device(device&&) = default;
    device& operator=(const device&) = default;
    device& operator=(device&&) = default;
 
    [[nodiscard]] constexpr bool operator==(const device&) const noexcept = default;
 
    [[nodiscard]] constexpr idfxx::gpio pin() const { return _pin; }
 
    [[nodiscard]] constexpr onewire::address addr() const { return _addr; }
 
    // Temperature measurement
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void measure(bool wait = true) { unwrap(try_measure(wait)); }
 
    [[nodiscard]] thermo::millicelsius read_temperature() const { return unwrap(try_read_temperature()); }
 
    [[nodiscard]] thermo::millicelsius measure_and_read() { return unwrap(try_measure_and_read()); }
#endif
 
    [[nodiscard]] result<void> try_measure(bool wait = true);
 
    [[nodiscard]] result<thermo::millicelsius> try_read_temperature() const;
 
    [[nodiscard]] result<thermo::millicelsius> try_measure_and_read();
 
    // Resolution configuration
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    void set_resolution(resolution res) { unwrap(try_set_resolution(res)); }
 
    [[nodiscard]] resolution get_resolution() const { return unwrap(try_get_resolution()); }
#endif
 
    [[nodiscard]] result<void> try_set_resolution(resolution res);
 
    [[nodiscard]] result<resolution> try_get_resolution() const;
 
    // Low-level scratchpad access
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] std::array<uint8_t, 9> read_scratchpad() const { return unwrap(try_read_scratchpad()); }
 
    void write_scratchpad(std::span<const uint8_t, 3> data) { unwrap(try_write_scratchpad(data)); }
 
    void copy_scratchpad() { unwrap(try_copy_scratchpad()); }
#endif
 
    [[nodiscard]] result<std::array<uint8_t, 9>> try_read_scratchpad() const;
 
    [[nodiscard]] result<void> try_write_scratchpad(std::span<const uint8_t, 3> data);
 
    [[nodiscard]] result<void> try_copy_scratchpad();
 
private:
    friend result<std::vector<device>> try_scan_devices(idfxx::gpio pin, size_t max_devices);
 
    struct validated {};
    device(idfxx::gpio pin, onewire::address addr, validated)
        : _pin(pin)
        , _addr(addr) {}
    idfxx::gpio _pin;
    onewire::address _addr;
};
 
 
} // namespace idfxx::ds18x20
 
namespace idfxx {
 
[[nodiscard]] inline std::string to_string(ds18x20::family f) {
    switch (f) {
    case ds18x20::family::ds18s20:
        return "DS18S20";
    case ds18x20::family::ds1822:
        return "DS1822";
    case ds18x20::family::ds18b20:
        return "DS18B20";
    case ds18x20::family::max31850:
        return "MAX31850";
    default: {
        static constexpr char hex[] = "0123456789ABCDEF";
        auto v = static_cast<uint8_t>(std::to_underlying(f));
        return std::string("unknown(0x") + hex[v >> 4] + hex[v & 0xF] + ')';
    }
    }
}
 
[[nodiscard]] inline std::string to_string(ds18x20::resolution r) {
    switch (r) {
    case ds18x20::resolution::bits_9:
        return "9-bit";
    case ds18x20::resolution::bits_10:
        return "10-bit";
    case ds18x20::resolution::bits_11:
        return "11-bit";
    case ds18x20::resolution::bits_12:
        return "12-bit";
    default: {
        static constexpr char hex[] = "0123456789ABCDEF";
        auto v = static_cast<uint8_t>(std::to_underlying(r));
        return std::string("unknown(0x") + hex[v >> 4] + hex[v & 0xF] + ')';
    }
    }
}
 
} // namespace idfxx
 
#include "sdkconfig.h"
#ifdef CONFIG_IDFXX_STD_FORMAT
#include <algorithm>
#include <format>
namespace std {
template<>
struct formatter<idfxx::ds18x20::family> {
    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
 
    template<typename FormatContext>
    auto format(idfxx::ds18x20::family f, FormatContext& ctx) const {
        auto s = idfxx::to_string(f);
        return std::copy(s.begin(), s.end(), ctx.out());
    }
};
 
template<>
struct formatter<idfxx::ds18x20::resolution> {
    constexpr auto parse(format_parse_context& ctx) { return ctx.begin(); }
 
    template<typename FormatContext>
    auto format(idfxx::ds18x20::resolution r, FormatContext& ctx) const {
        auto s = idfxx::to_string(r);
        return std::copy(s.begin(), s.end(), ctx.out());
    }
};
} // namespace std
#endif // CONFIG_IDFXX_STD_FORMAT