MCP9700 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
mcp9700.hpp
Go to the documentation of this file.
1
13#ifndef MCP9700_HPP
14#define MCP9700_HPP
15
16#include <cstdint>
17#include <limits>
18
20#include "mcp9700_detail.hpp"
21#include "mcp9700_types.hpp"
22#include "mcp9700_version.h"
23
24namespace mcp9700 {
25
26namespace detail {
27
28// Optional hooks: a `Declares*` concept only tests the name, the `Has*` concept
29// the exact signature, `noexcept` and the result type; the driver rejects a
30// hook that is declared but does not match (handbook KB-CPP20-007).
31
34template <typename Port>
35concept DeclaresGpioSet =
36 requires(Port& port) { port.GpioSet(CtrlPin::Enable, GpioSignal::ACTIVE); };
37
39template <typename Port>
40concept HasGpioSet =
41 requires { ExactHook<Port, bool(CtrlPin, GpioSignal) noexcept>::Take(&Port::GpioSet); };
42
44template <typename Port>
45concept DeclaresDelayUs = requires(Port& port) { port.DelayUs(1_u32); };
46
48template <typename Port>
49concept HasDelayUs = requires { ExactHook<Port, void(uint32_t) noexcept>::Take(&Port::DelayUs); };
50
52template <typename Port>
53concept DeclaresLog = requires(Port& port) { port.Log(LogLevel::Info, ""); };
54
57template <typename Port>
58concept HasLog =
59 requires { ExactHook<Port, void(LogLevel, const char*) noexcept>::Take(&Port::Log); };
60
63template <typename Port>
64void DelayUs(Port& port, uint32_t us) noexcept {
65 if constexpr (HasDelayUs<Port>) {
66 port.DelayUs(us);
67 } else {
68 static_assert(kAlwaysFalse<Port>, "mcp9700: the port must implement `void "
69 "DelayUs(uint32_t us) noexcept`");
70 }
71}
72
74template <typename Port>
75void Log([[maybe_unused]] Port& port, [[maybe_unused]] LogLevel level,
76 [[maybe_unused]] const char* message) noexcept {
77 if constexpr (HasLog<Port>) {
78 port.Log(level, message);
79 }
80}
81
83struct Samples {
84 uint64_t sum{0U};
85 uint32_t min{std::numeric_limits<uint32_t>::max()};
86 uint32_t max{0U};
87};
88
90constexpr uint64_t CeilDiv(uint64_t a, uint64_t b) noexcept {
91 return (a + b - 1U) / b;
92}
93
96constexpr uint64_t AdcCodes(const Config& config) noexcept {
97 return uint64_t{1} << (static_cast<uint32_t>(config.adc_resolution_bits) & 0x3FU);
98}
99
106constexpr uint64_t AdcLsbMv(const Config& config) noexcept {
107 const uint64_t lsb = CeilDiv(config.adc_full_scale_mv, AdcCodes(config));
108 return (lsb > 0U) ? lsb : uint64_t{1};
109}
110
120inline Result<Measurement> Evaluate(const Config& config, const VariantSpec& spec,
121 const Samples& samples) noexcept;
122
124constexpr const char* StartupReason(Error error) noexcept {
125 if (error == Error::OutputLow) {
126 return "mcp9700: start-up output too low: unpowered, grounded or wrong "
127 "channel";
128 }
129 if (error == Error::OutputHigh) {
130 return "mcp9700: start-up output too high: shorted to supply or mis-scaled "
131 "ADC";
132 }
133 if (error == Error::Saturated) {
134 return "mcp9700: start-up conversion at the ADC full scale: clipped or "
135 "open input";
136 }
137 return "mcp9700: start-up output unstable: floating or disturbed line";
138}
139
140} // namespace detail
141
168template <AdcPort Port>
169class MCP9700 {
170 static_assert(!detail::DeclaresGpioSet<Port> || detail::HasGpioSet<Port>,
171 "mcp9700: the optional GpioSet hook must be `bool "
172 "GpioSet(CtrlPin, GpioSignal) "
173 "noexcept`, so that a failed pin write is reported");
174 static_assert(!detail::DeclaresDelayUs<Port> || detail::HasDelayUs<Port>,
175 "mcp9700: the DelayUs hook must be `void DelayUs(uint32_t us) "
176 "noexcept`, so that no "
177 "wait is truncated");
178 static_assert(!detail::DeclaresLog<Port> || detail::HasLog<Port>,
179 "mcp9700: the optional Log hook must be `void Log(LogLevel, "
180 "const char* message) "
181 "noexcept`");
182
183public:
191 explicit MCP9700(Port& port, const Config& config = {}) noexcept : port_(port), config_(config) {}
192
194 MCP9700(const MCP9700&) = delete;
196 MCP9700& operator=(const MCP9700&) = delete;
197
213
215 [[nodiscard]] bool IsInitialized() const noexcept {
216 return initialized_;
217 }
218
229
235 Result<void> Sleep() noexcept;
236
250
256 Result<int32_t> ReadTemperatureMilliC() noexcept;
257
263 Result<uint32_t> ReadOutputMv() noexcept;
264
271 Result<uint32_t> ReadRawPortMv() noexcept;
272
276 [[nodiscard]] uint32_t GetLastRawPortMv() const noexcept {
277 return last_raw_mv_;
278 }
279
285 [[nodiscard]] uint32_t ResolutionMilliC() const noexcept;
286
288 [[nodiscard]] const Config& GetConfig() const& noexcept {
289 return config_;
290 }
293 void GetConfig() const&& = delete;
294
300 [[nodiscard]] Result<VariantSpec> GetSpec() const noexcept {
301 return ResolveSpec(config_);
302 }
303
304private:
305 Result<void> initialize() noexcept;
306 Result<void> failStartup(Error reason) noexcept;
307 Result<void> switchOff() noexcept;
308 Result<detail::Samples> collect() noexcept;
309 Result<Measurement> readValidated() noexcept;
310 Result<uint32_t> readOnce() noexcept;
311
312 Port& port_;
313 Config config_{};
314 VariantSpec spec_{};
315 uint32_t last_raw_mv_{0U};
316 bool initialized_{false};
317};
318
321} // namespace mcp9700
322
323// codeql::misra_deviation_next_line(MD-CPP-009)
324#include "../src/mcp9700.ipp" // IWYU pragma: export
325
326#endif // MCP9700_HPP
Driver for one MCP970x analog temperature sensor (or a declared Custom part) on an ADC port.
Definition mcp9700.hpp:169
Result< int32_t > ReadTemperatureMilliC() noexcept
The temperature of ReadMeasurement(), milli-degrees Celsius, after offset_cal_mc.
Result< VariantSpec > GetSpec() const noexcept
The effective variant row (a table row, or the one built from the Custom declaration)....
Definition mcp9700.hpp:300
bool IsInitialized() const noexcept
Definition mcp9700.hpp:215
Result< Measurement > ReadMeasurement() noexcept
The validated reading: discard_conversions dummy conversions, then samples averaged.
const Config & GetConfig() const &noexcept
Definition mcp9700.hpp:288
Result< void > EnsureInitialized() noexcept
Start the sensor, once: the only way to initialise the driver.
uint32_t ResolutionMilliC() const noexcept
One ADC step expressed in milli-degrees at the current slope, rounded up. No I/O.
void GetConfig() const &&=delete
Not on a temporary driver: the reference would dangle (handbook KB-CPP20-044).
Result< uint32_t > ReadRawPortMv() noexcept
One conversion, once: no scaling, no check, no retry (handbook KB-CPP-129). For bring-up.
Result< uint32_t > ReadOutputMv() noexcept
The mean output voltage at VOUT (scaled by the divider), validated like a reading.
Result< void > Deinitialize() noexcept
Mark the driver uninitialised and switch the sensor off when the port has GpioSet(); the next EnsureI...
MCP9700(const MCP9700 &)=delete
One driver object per sensor.
MCP9700 & operator=(const MCP9700 &)=delete
One driver object per sensor.
MCP9700(Port &port, const Config &config={}) noexcept
Bind the driver to a port and store the configuration. No I/O, cannot fail.
Definition mcp9700.hpp:191
uint32_t GetLastRawPortMv() const noexcept
Definition mcp9700.hpp:276
Result< void > Sleep() noexcept
Switch the sensor off; EnsureInitialized() powers it again.
LogLevel
Severity passed to the optional Log() hook.
Definition mcp9700_types.hpp:454
constexpr Result< VariantSpec > ResolveSpec(const Config &config) noexcept
The effective variant row of a configuration: a table row, or the row built from the Custom declarati...
Definition mcp9700_types.hpp:580
Error
Why a call failed. Values 0 to 9 are the shared base set; chip-specific values start at 16.
Definition mcp9700_types.hpp:46
@ Info
Lifecycle events.
@ OutputLow
The output is below the specified range minus the margin.
@ OutputHigh
The output is above the specified range plus the margin.
The ADC port of the MCP970x driver: the CRTP base, its pin enums, the AdcPort concept and the output-...
Compile-time helpers of the MCP9700 driver: typed integer literals, exact hook matching,...
Public types of the MCP970x driver: errors, Result<T>, the variant table, configuration,...
The MCP970x driver: everything it declares lives here; internals in detail.
Definition mcp9700.hpp:24
GpioSignal
Logical level of a control pin; the port maps it to the physical polarity.
Definition mcp9700_adc_interface.hpp:56
@ ACTIVE
The pin function is asserted.
CtrlPin
Control pins the port may drive through the optional GpioSet() hook.
Definition mcp9700_adc_interface.hpp:49
Everything EnsureInitialized() uses. Config{} is an MCP9700 on a 12 bit, 3.3 V ADC.
Definition mcp9700_types.hpp:274
uint32_t adc_full_scale_mv
Largest voltage the port can report, mV.
Definition mcp9700_types.hpp:279
uint8_t adc_resolution_bits
ADC resolution, 8 to 16 bits.
Definition mcp9700_types.hpp:280
The temperature and the voltage behind it, from one validated reading.
Definition mcp9700_types.hpp:447
The value of a call, or why there is none.
Definition mcp9700_types.hpp:112
One row of the variant table: the only place a coefficient, range, supply, accuracy band or package l...
Definition mcp9700_types.hpp:326