28#include "ads7952_version.h"
39template <
typename Port>
40concept DeclaresDelayUs =
requires(Port& port) { port.DelayUs(1U); };
44template <
typename Port>
45concept HasDelayUs =
requires { ExactHook<Port, void(uint32_t)
noexcept>::Take(&Port::DelayUs); };
48template <
typename Port>
49concept DeclaresLog =
requires(Port& port) { port.Log(
LogLevel::Info,
""); };
52template <
typename Port>
54 requires { ExactHook<Port, void(
LogLevel,
const char*)
noexcept>::Take(&Port::Log); };
58template <
typename Port>
59void DelayUs(Port& port, uint32_t us)
noexcept {
60 if constexpr (HasDelayUs<Port>) {
63 static_assert(kAlwaysFalse<Port>,
64 "ads7952: the port must implement `void DelayUs(uint32_t us) noexcept`");
69template <
typename Port>
70void Log(Port& port, [[maybe_unused]]
LogLevel level,
71 [[maybe_unused]]
const char* message)
noexcept {
72 if constexpr (HasLog<Port>) {
73 port.Log(level, message);
83[[nodiscard]]
constexpr uint8_t NextInSequence(uint16_t mask, uint8_t channel)
noexcept {
84 const uint32_t from = (
static_cast<uint32_t
>(channel) + 1U) & 0x0FU;
85 const auto rotated = std::rotr(mask,
static_cast<int>(from));
89 const auto step =
static_cast<uint32_t
>(std::countr_zero(rotated));
90 return static_cast<uint8_t
>((from + step) & 0x0FU);
94[[nodiscard]]
constexpr uint8_t CountChannels(uint16_t mask)
noexcept {
95 return static_cast<uint8_t
>(std::popcount(mask));
99[[nodiscard]]
constexpr uint16_t Auto2Mask(uint8_t last)
noexcept {
100 return static_cast<uint16_t
>((uint32_t{2} << (
static_cast<uint32_t
>(last) & 0x0FU)) - 1U);
104static_assert((NextInSequence(0x0FFF_u16, 3_u8) == 4U) &&
105 (NextInSequence(0x0FFF_u16, 11_u8) == 0U));
106static_assert((NextInSequence(0x8001_u16, 15_u8) == 0U) &&
107 (NextInSequence(0x8001_u16, 0_u8) == 15U));
108static_assert((NextInSequence(0x0010_u16, 4_u8) == 4U) && (NextInSequence(0x0000_u16, 7_u8) == 7U));
109static_assert((CountChannels(0xFFFF_u16) == 16U) && (CountChannels(0x00A5_u16) == 4U));
110static_assert((Auto2Mask(0_u8) == 0x0001U) && (Auto2Mask(11_u8) == 0x0FFFU) &&
111 (Auto2Mask(15_u8) == 0xFFFFU));
115[[nodiscard]]
constexpr uint16_t ControlBits(
const Config& config)
noexcept {
116 return static_cast<uint16_t
>(
123[[nodiscard]]
constexpr uint16_t GpioProgramWord(
const Config& config)
noexcept {
126 return static_cast<uint16_t
>(
136[[nodiscard]]
constexpr Config EveryThresholdDiffers(
const Config& config)
noexcept {
139 t.low_code =
static_cast<uint16_t
>(~static_cast<uint32_t>(t.low_code) &
kMaxCode);
140 t.high_code =
static_cast<uint16_t
>(~static_cast<uint32_t>(t.high_code) &
kMaxCode);
151struct IdentityChannels {
156[[nodiscard]]
constexpr IdentityChannels IdentityFor(
Variant variant)
noexcept {
159 return {.first = 2, .second = 1};
161 return {.first = 5, .second = 2};
167 return {.first = 10, .second = 5};
171[[nodiscard]]
constexpr bool IdentityCovers(
Variant variant)
noexcept {
172 const IdentityChannels ids = IdentityFor(variant);
173 const auto channels =
static_cast<uint32_t
>(
ChannelCount(variant));
174 const uint32_t used = (channels > 8U) ? 0x0FU : (channels - 1U);
175 return (ids.first < channels) && (ids.second < channels) &&
176 (((
static_cast<uint32_t
>(ids.first) ^
static_cast<uint32_t
>(ids.second)) & used) == used);
244template <SpiPort Port>
247 !detail::DeclaresDelayUs<Port> || detail::HasDelayUs<Port>,
248 "ads7952: the DelayUs hook must be `void DelayUs(uint32_t us) noexcept`, so that no "
249 "wait is truncated");
250 static_assert(!detail::DeclaresLog<Port> || detail::HasLog<Port>,
251 "ads7952: the optional Log hook must be `void Log(LogLevel, const char* message) "
260 explicit ADS7952(Port& port,
const Config& config = {})
noexcept : bus_(port), config_(config) {}
342 return config_uncertain_;
573 enum class Mode : uint8_t { Unknown, Manual, Auto1, Auto2 };
576 Result<
void> programAll() noexcept;
577 Result<
void> resetChip() noexcept;
578 Result<
void> checkIdentity() noexcept;
579 Result<uint16_t> checkScale() noexcept;
581 Result<
void> writeGpioProgram(const
Config& to) noexcept;
583 Result<
void> writeAlarmGroup(const
Config& from, const
Config& to, uint8_t group) noexcept;
585 Result<
void> programAuto1(uint16_t mask) noexcept;
586 Result<
void> programAuto2(uint8_t last) noexcept;
587 Result<uint16_t> readSelected(uint8_t channel, uint8_t rest) noexcept;
588 Result<
void> park(uint8_t channel, uint8_t rest) noexcept;
589 Result<
void> readPipelined(std::span<const uint8_t> channels, std::span<uint16_t> codes) noexcept;
590 Result<
Bank> scan(Mode mode, uint16_t mask) noexcept;
592 Result<
void> discardStale() noexcept;
593 Result<uint16_t> modeFrame(uint16_t control_bits) noexcept;
594 Result<uint16_t> select(uint8_t channel) noexcept;
595 Result<uint16_t> selectChecked(uint8_t channel) noexcept;
596 [[nodiscard]] uint8_t settledChannel() const noexcept;
597 Error lostTrack(
Error mismatch, uint8_t address) noexcept;
598 Result<uint16_t> frame(uint16_t word) noexcept;
600 static constexpr uint8_t kNotAReset = 0xFFU;
601 [[nodiscard]]
bool validChannel(uint8_t channel) const noexcept {
604 [[nodiscard]]
bool validList(std::span<const uint8_t> channels,
605 std::span<const uint16_t> codes)
const noexcept {
606 if (channels.empty() || (channels.size() >
kMaxChannels) || (codes.size() < channels.size())) {
609 return std::all_of(channels.begin(), channels.end(),
610 [
this](uint8_t channel) { return validChannel(channel); });
612 [[nodiscard]]
static constexpr bool isVerify(
Verify verify)
noexcept {
615 template <
typename T>
616 Result<T> fail(
Error error,
const char* message)
noexcept;
617 Result<void> failedWrite(
Error error,
const char* message)
noexcept;
619 detail::FrameBus<Port> bus_;
621 Mode mode_{Mode::Unknown};
622 uint8_t manual_channel_{0};
624 uint16_t last_reply_{0xFFFF};
625 bool initialized_{
false};
626 bool config_uncertain_{
false};
634#include "../src/ads7952.ipp"
Compile-time helpers of the ADS7952 driver: exact hook matching and enumeration checks.
ADS795x command and reply words: the bit fields of every frame (datasheet SLAS605C,...
The SPI port of the ADS7952 driver: the CRTP base, the SpiPort concept and the 16-bit frame.
Public types of the ADS7952 driver: errors, Result<T>, variants, ranges, GPIO and alarm settings,...
Driver for one ADS7950, ADS7951, ADS7952 or ADS7953 on a platform port.
Definition ads7952.hpp:245
uint32_t ToMicrovolts(uint16_t code) const noexcept
The input voltage a code stands for in the configured range and reference. No I/O.
Definition ads7952.hpp:443
Error CheckScaleCode(uint16_t code) const noexcept
Judge a code of the monitor channel against Config::monitor, with no I/O: use it on every Bank or DMA...
Definition ads7952.hpp:482
Result< void > SetAlarmThresholds(uint8_t channel, AlarmThreshold thresholds) noexcept
Program both alarm thresholds of a channel: the group frame, the low threshold, the high threshold wi...
bool IsInitialized() const noexcept
Definition ads7952.hpp:295
Result< void > ReadChannels(std::span< const uint8_t > channels, std::span< uint16_t > codes) noexcept
One conversion of each listed channel, pipelined in Manual mode (Figure 51): a Manual word per channe...
Result< void > EnsureInitialized() noexcept
Reset the chip, write the configuration and check that an ADS795x answers, once: the only way to init...
uint8_t GetChannelCount() const noexcept
Definition ads7952.hpp:353
ADS7952(const ADS7952 &)=delete
One driver object per chip.
bool IsConfigUncertain() const noexcept
Whether the chip may hold something other than GetConfig(). No I/O.
Definition ads7952.hpp:341
Result< uint16_t > ReadChannel(uint8_t channel) noexcept
One conversion of channel in Manual mode.
void GetConfig() const &&=delete
Not on a temporary driver: the reference would dangle (KB-CPP20-044).
Result< void > SetAuto1Channels(uint16_t mask, Verify verify=Verify::None) noexcept
Program the Auto-1 sequence: two frames (Table 3). In Auto-1 the chip goes on with the next enabled c...
uint32_t ToMicrovolts(const Bank &bank, uint8_t channel) const noexcept
The input voltage of one channel of a scan, in the range that scan was converted in (Bank::range),...
Definition ads7952.hpp:454
ADS7952(Port &port, const Config &config={}) noexcept
Bind the driver to a port and store the configuration. No I/O, cannot fail.
Definition ads7952.hpp:260
Result< Bank > ReadAuto2() noexcept
One pass of the Auto-2 sequence, channel 0 to Config::auto2_last_channel: as ReadAuto1() with the Aut...
Result< void > SetRange(Range range) noexcept
Change the input range: one mode word for the current mode with the new DI06 (Table 1,...
Result< void > SetGpioOutputs(uint8_t levels, Verify verify=Verify::None) noexcept
Drive the GPIO outputs: one mode word with the new DI03:00, then the frame on whose CS falling edge t...
uint16_t GetLastReply() const noexcept
The last reply word the driver received, for logs: 0xFFFF before the first. No I/O.
Definition ads7952.hpp:491
Result< uint8_t > ReadGpio() noexcept
Read the levels of GPIO3:0, inputs and outputs: a mode word with DI04 = 1, then one with DI04 = 0 who...
Result< void > ApplyConfig(const Config &config) noexcept
Replace the configuration.
Result< void > TraceFrames(uint8_t channel, std::span< uint16_t > replies) noexcept
Bring-up trace: select channel in Manual mode (DI11 = 1) and return every reply word unparsed,...
ADS7952 & operator=(const ADS7952 &)=delete
One driver object per chip.
Result< void > Deinitialize() noexcept
Power the chip down and mark the driver uninitialised: one mode word with DI05 = 1,...
Result< void > SetAuto2LastChannel(uint8_t last, Verify verify=Verify::None) noexcept
Program the last channel of the Auto-2 sequence: one frame (Table 6). In Auto-2 the chip starts again...
const Config & GetConfig() const &noexcept
Definition ads7952.hpp:346
Result< Bank > ReadAuto1() noexcept
One pass of the Auto-1 sequence (Config::auto1_channels): the hot path.
Result< uint16_t > CheckScale() noexcept
Prove the scale now: one conversion of the Config::monitor channel, judged by CheckScaleCode()....
constexpr uint16_t kGpio3PowerDown
DI08: GPIO3 is the power-down input.
Definition ads7952_registers.hpp:61
constexpr uint16_t kRangeTwoVref
DI06: 0 to 2 x VREF (Range 2).
Definition ads7952_registers.hpp:50
constexpr uint16_t kGpioProgram
0100: GPIO program register (Table 11).
Definition ads7952_registers.hpp:41
constexpr uint16_t kGpioDirectionMask
DI03:00: 1 = output.
Definition ads7952_registers.hpp:64
constexpr uint32_t kGpioAlarmShift
DI06:04: GPIO0/GPIO1 alarm outputs.
Definition ads7952_registers.hpp:63
constexpr uint16_t kGpioDataMask
DI03:00: GPIO output levels.
Definition ads7952_registers.hpp:53
constexpr uint16_t kGpio2Range
DI07: GPIO2 is the range input.
Definition ads7952_registers.hpp:62
constexpr uint8_t ChannelCount(Variant variant) noexcept
Number of analog inputs of a variant.
Definition ads7952_types.hpp:317
constexpr uint32_t CodeToMicrovolts(uint16_t code, Range range, uint16_t vref_mv) noexcept
Convert a result code to the input voltage it stands for (Table 8: one LSB is full scale / 4096,...
Definition ads7952_types.hpp:653
Range
Input range, DI06 of the mode control word (Tables 1, 2, 5; Table 8).
Definition ads7952_types.hpp:227
Variant
Which 12-bit member of the family is fitted. The chip cannot tell, so it is configured.
Definition ads7952_types.hpp:212
constexpr std::size_t kMaxChannels
Channels of the largest part (ADS7953); arrays indexed by channel have this size.
Definition ads7952_types.hpp:299
constexpr Error CheckScaleCode(const Config &config, uint16_t code) noexcept
Judge one code of the scale monitor's channel. No I/O.
Definition ads7952_types.hpp:504
constexpr uint16_t kMaxCode
Largest result code: 12 bits, straight binary (Table 8).
Definition ads7952_types.hpp:301
Error
Why a call failed. Every call of the driver returns one of these in its Result.
Definition ads7952_types.hpp:38
LogLevel
Severity passed to the optional Log() hook.
Definition ads7952_types.hpp:197
Verify
Extra verification for one call, chosen per call (handbook KB-ARCH-041).
Definition ads7952_types.hpp:256
@ TwoVref
0 to 2 x VREF (Range 2); specified only while 2 x VREF <= +VA (section 7.6).
@ Ads7952
12 channels. The default.
@ Info
Lifecycle events: initialised.
@ None
No extra frame. The default.
@ ReadBack
Read back what the chip took (GPIO levels, the scanned sequence).
The ADS7952 driver: everything it declares lives here; internals in detail.
Definition ads7952.hpp:30
The two alarm thresholds of one channel, in 12-bit result codes. The chip keeps the upper 10 bits and...
Definition ads7952_types.hpp:293
The result of one Auto-1 or Auto-2 scan: one code per channel of the sequence.
Definition ads7952_types.hpp:354
What the driver is told about the chip and the board. Config{} is an ADS7952 in TSSOP left in its res...
Definition ads7952_types.hpp:402
std::array< AlarmThreshold, kMaxChannels > alarms
Definition ads7952_types.hpp:424
uint16_t vref_mv
Definition ads7952_types.hpp:412
Package package
Definition ads7952_types.hpp:404
Variant variant
The fitted part; every channel is checked against it.
Definition ads7952_types.hpp:403
GpioConfig gpio
GPIO program register and output levels.
Definition ads7952_types.hpp:423
Range range
Definition ads7952_types.hpp:408
The GPIO program register and the GPIO output levels. GpioConfig{} is the reset state: every pin an i...
Definition ads7952_types.hpp:280
uint8_t output_mask
Bit n = 1: GPIOn is a general-purpose output (DI03:00).
Definition ads7952_types.hpp:281
uint8_t output_levels
Levels of the output pins, bit n for GPIOn; only output pins.
Definition ads7952_types.hpp:282
bool gpio2_range_input
GPIO2 selects the range (DI07); DI06 is then ignored.
Definition ads7952_types.hpp:284
bool gpio3_power_down_input
GPIO3 is the active-low power-down input (DI08).
Definition ads7952_types.hpp:285
AlarmOutput alarm_output
GPIO0/GPIO1 alarm functions (DI06:04).
Definition ads7952_types.hpp:283
The value of a call, or why there is none.
Definition ads7952_types.hpp:137