ADS7952 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Public Member Functions | List of all members
ads7952::ADS7952< Port > Class Template Reference

Driver for one ADS7950, ADS7951, ADS7952 or ADS7953 on a platform port. More...

#include <ads7952.hpp>

Public Member Functions

 ADS7952 (Port &port, const Config &config={}) noexcept
 Bind the driver to a port and store the configuration. No I/O, cannot fail.
 
 ADS7952 (const ADS7952 &)=delete
 One driver object per chip.
 
ADS7952 & operator= (const ADS7952 &)=delete
 One driver object per chip.
 
Lifecycle
Result< void > EnsureInitialized () noexcept
 Reset the chip, write the configuration and check that an ADS795x answers, once: the only way to initialise the driver.
 
bool IsInitialized () const noexcept
 
Result< void > Deinitialize () noexcept
 Power the chip down and mark the driver uninitialised: one mode word with DI05 = 1, then the frame at whose end the chip powers down (section 8.3.2).
 
Result< void > ApplyConfig (const Config &config) noexcept
 Replace the configuration.
 
bool IsConfigUncertain () const noexcept
 Whether the chip may hold something other than GetConfig(). No I/O.
 
const Config & GetConfig () const &noexcept
 
void GetConfig () const &&=delete
 Not on a temporary driver: the reference would dangle (KB-CPP20-044).
 
uint8_t GetChannelCount () const noexcept
 
Conversions
Result< uint16_t > ReadChannel (uint8_t channel) noexcept
 One conversion of channel in Manual mode.
 
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 channel, then two frames; the result of each channel arrives two frames after its select. channels.size() + 2 frames. Every reply's address must be the channel it stands for.
 
Result< Bank > ReadAuto1 () noexcept
 One pass of the Auto-1 sequence (Config::auto1_channels): the hot path.
 
Result< Bank > ReadAuto2 () noexcept
 One pass of the Auto-2 sequence, channel 0 to Config::auto2_last_channel: as ReadAuto1() with the Auto-2 word.
 
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, the select frame's included; the other frames are "continue" words: replies.size() frames. The address nibble of replies[2] onwards should be channel; a nibble that never follows the select means SDI does not reach the chip. A single shot with no retry and no check of the replies (handbook KB-CPP-129); its one side effect is that the chip is left in Manual mode on channel, as after ReadChannel(channel).
 
uint32_t ToMicrovolts (uint16_t code) const noexcept
 The input voltage a code stands for in the configured range and reference. No I/O.
 
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), not the range configured now. No I/O.
 
Result< uint16_t > CheckScale () noexcept
 Prove the scale now: one conversion of the Config::monitor channel, judged by CheckScaleCode(). An explicit, opt-in call: nothing on the conversion path runs it.
 
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-decoded word that holds the monitor channel.
 
uint16_t GetLastReply () const noexcept
 The last reply word the driver received, for logs: 0xFFFF before the first. No I/O.
 
Settings
Result< void > SetRange (Range range) noexcept
 Change the input range: one mode word for the current mode with the new DI06 (Table 1, 2, 5). Results clocked out from the second frame after it use the new range; the conversion calls skip the one in between by themselves.
 
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 channel of the new mask.
 
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 at channel 0. Verify::ReadBack adds one scan, as for SetAuto1Channels().
 
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 with the exit bit, and one frame to leave the sequence (Table 13). 4 frames. The chip keeps the upper 10 bits of each code. There is no way to read them back.
 
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 the chip drives them (section 8.5.2). 2 frames; the pins show the levels when it returns.
 
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 whose reply carries them in DO15:12 (Tables 1, 2, 5). 2 frames.
 

Detailed Description

template<SpiPort Port>
class ads7952::ADS7952< Port >

Driver for one ADS7950, ADS7951, ADS7952 or ADS7953 on a platform port.

Lifecycle: construct with the configuration (no I/O), then EnsureInitialized(), the one way to start (bus up, reset, configuration written, identity check), use, optionally Deinitialize(). Every call that touches the chip returns Error::NotInitialized until EnsureInitialized() has succeeded; no call starts the chip as a side effect.

The frame pipeline. A channel chosen in frame N is acquired in frame N + 1 and its result comes back in frame N + 2 (Figures 51, 53, 56); a range written in frame N applies from the result of frame N + 2 as well. The driver keeps track of what the chip is doing (mode, channel, replies still in flight), so a call sends only the frames it needs, and it checks the channel address of every reply it returns: a result is never attributed to the wrong channel.

A reset behind the driver's back (a brown-out) puts every register back to its reset value (section 8.4.3, Table 11, section 8.5.3) and makes the next conversion invalid (section 7.6); the chip has no flag for it. The driver checks the address of every reply it can predict, the ones a new select discards included, and a reply from channel 0 (the power-on channel) where it expects another is DeviceReset. After it, and after any ChannelMismatch or SequenceMismatch, the driver is uninitialised (fail-safe): EnsureInitialized() resets and programs the chip in the datasheet order and discards the invalid first conversion. A reset at any moment the chip rests on channel 0 in Manual mode (after a read of channel 0, a list ending with it, in any mix of reads) shows in no reply, and the results right after a reset (the invalid conversion, one in Range 1) can be returned before it is seen. Mitigations: the opt-in Config::park_channel, and ApplyConfig(), which writes every register whatever the driver's copy says (docs/limitations.md).

Call Frames
ReadChannel(ch) 1 when ch is the selected Manual channel, 2 right after SetRange(), 3 otherwise; with Config::park_channel, ReadChannel(0) one more (4 when repeated)
ReadChannels(list) list length + 2
ReadAuto1(), ReadAuto2() k (the channels of the sequence) while the sequence runs, k + 1 right after SetRange() or a new sequence, k + 2 when it has to be entered
SetRange() 1
SetAuto1Channels() 2 (Verify::ReadBack: and one scan)
SetAuto2LastChannel() 1 (Verify::ReadBack: and one scan)
SetAlarmThresholds() 4
SetGpioOutputs() 2 (Verify::ReadBack: 3)
ReadGpio() 2
EnsureInitialized() 13, plus 3 to 10 per alarm group that is not at its reset value, plus 3 with a Config::monitor
ApplyConfig() (running) 6 + 10 per alarm group: 16 (ADS7950), 26, 36 (ADS7952), 46 (ADS7953)
CheckScale() as ReadChannel() of the monitor channel: 1 to 3
CheckScaleCode(), ToMicrovolts() 0
Deinitialize() 2

Optional port hooks, found at compile time:

Hook Used for Without it
void Log(LogLevel, const char* message) noexcept One line per lifecycle event or failure Nothing is logged
Template Parameters
PortYour class derived from SpiInterface<Port>.

Constructor & Destructor Documentation

◆ ADS7952()

template<SpiPort Port>
ads7952::ADS7952< Port >::ADS7952 ( Port &  port,
const Config &  config = {} 
)
inlineexplicitnoexcept

Bind the driver to a port and store the configuration. No I/O, cannot fail.

Parameters
portThe port; it must outlive the driver.
configChecked by EnsureInitialized(), before any I/O.

Member Function Documentation

◆ ApplyConfig()

template<SpiPort Port>
Result< void > ads7952::ADS7952< Port >::ApplyConfig ( const Config &  config)
noexcept

Replace the configuration.

Before the start it only stores it, with no I/O. On a running driver it writes every register, changed or not, in the order of section 8.4.3: the GPIO program register, the Auto-1 and Auto-2 program registers, every alarm threshold of every group (Table 13), then a mode word with the range and the GPIO levels and the frame on which the outputs change. The driver's copy is never trusted, because no register can be read back and a reset while the chip converts channel 0 shows in no reply: ApplyConfig(GetConfig()) puts the whole configuration back. 6 + 10 frames per alarm group (36 on the ADS7952). vref_mv and va_min_mv are never sent.

Parameters
configChecked with Validate().
Returns
Ok, InvalidArgument (it fails Validate(), or it changes the variant or package of a running driver; nothing sent), Unsupported, or Bus. After Bus the stored configuration is unchanged and the chip may hold part of the new one: restart with Deinitialize() and EnsureInitialized().

◆ CheckScale()

template<SpiPort Port>
Result< uint16_t > ads7952::ADS7952< Port >::CheckScale ( )
noexcept

Prove the scale now: one conversion of the Config::monitor channel, judged by CheckScaleCode(). An explicit, opt-in call: nothing on the conversion path runs it.

Costs what ReadChannel() of that channel costs (1 to 3 frames) and leaves the chip in Manual mode on it, so the next ReadAuto1() enters Auto-1 again (two frames). Its select carries the range, so it proves that the chip takes the range the driver sends and that the reference is there; a range lost during a long Auto-1 run shows in the scan itself: check the monitor's code of each Bank with CheckScaleCode(), which costs no frame.

Returns
The monitor's code; or NotInitialized, InvalidArgument (no monitor; nothing sent), Bus, ChannelMismatch, RangeMismatch, ScaleMismatch or DeviceReset (a reply from channel 0 out of turn, or Range 1 where the driver sends Range 2: the reset value of DI06). After any of these but Bus the driver is uninitialised (fail-safe).

◆ CheckScaleCode()

template<SpiPort Port>
Error ads7952::ADS7952< Port >::CheckScaleCode ( uint16_t  code) const
inlinenoexcept

Judge a code of the monitor channel against Config::monitor, with no I/O: use it on every Bank or DMA-decoded word that holds the monitor channel.

Parameters
codeThe monitor channel's code, converted in Config::range.
Returns
Ok, RangeMismatch, ScaleMismatch, or InvalidArgument (no monitor).

◆ Deinitialize()

template<SpiPort Port>
Result< void > ads7952::ADS7952< Port >::Deinitialize ( )
noexcept

Power the chip down and mark the driver uninitialised: one mode word with DI05 = 1, then the frame at whose end the chip powers down (section 8.3.2).

The driver is uninitialised afterwards even if a frame failed; the next EnsureInitialized() resets and checks the chip again, which is also how a handler recovers after a fault. On an uninitialised driver it does nothing and returns Ok.

Returns
Ok or Bus.

◆ EnsureInitialized()

template<SpiPort Port>
Result< void > ads7952::ADS7952< Port >::EnsureInitialized ( )
noexcept

Reset the chip, write the configuration and check that an ADS795x answers, once: the only way to initialise the driver.

In order: Validate() the configuration (no I/O), bring the bus up, end any program sequence an earlier failure left open (two frames), reset every register (the GPIO program frame with DI09 = 1, then the frame in which the chip resets itself, then kPowerUpUs), write the GPIO, Auto-1 and Auto-2 program registers and every alarm group that differs from its reset value, then the identity check: in Manual mode, select a channel, keep it one frame, select a second one whose address differs in every bit (10 and 5 on the ADS7952), and demand that the replies two frames after each carry exactly those addresses. A MISO line stuck low or high, a fixed reply pattern, a loop-back and an SDI line that does not reach the chip (whatever mode the chip was left in) all fail it. With a Config::monitor, last, the scale check: one conversion of the monitor channel must fall in its window (CheckScaleCode()), which proves the range and the reference before any result is returned. The chip is left in Manual mode. After it succeeds, later calls return Ok at once with no I/O; after it fails, the next call starts again from the beginning.

Returns
Ok, InvalidArgument or Unsupported (the configuration fails Validate(); no I/O), Bus, NoDevice (every identity reply 0xFFFF), DeviceIdMismatch, or RangeMismatch or ScaleMismatch (the scale check).

◆ GetChannelCount()

template<SpiPort Port>
uint8_t ads7952::ADS7952< Port >::GetChannelCount ( ) const
inlinenoexcept
Returns
The number of analog inputs of the configured variant. No I/O.

◆ GetConfig()

template<SpiPort Port>
const Config & ads7952::ADS7952< Port >::GetConfig ( ) const &
inlinenoexcept
Returns
The configuration last applied or stored. No I/O.

◆ GetLastReply()

template<SpiPort Port>
uint16_t ads7952::ADS7952< Port >::GetLastReply ( ) const
inlinenoexcept

The last reply word the driver received, for logs: 0xFFFF before the first. No I/O.

Returns
After a failed EnsureInitialized(), 0xFFFF means MISO floats high, 0x0000 MISO is stuck low; an address nibble of 0 with any code means the chip did not get the select.

◆ IsConfigUncertain()

template<SpiPort Port>
bool ads7952::ADS7952< Port >::IsConfigUncertain ( ) const
inlinenoexcept

Whether the chip may hold something other than GetConfig(). No I/O.

True after a setter or ApplyConfig() failed with Bus, or a Verify::ReadBack did not confirm a write (the frame may have reached the chip and taken effect: a range, GPIO levels, a sequence, alarm thresholds), until every register is written again: ApplyConfig(GetConfig()) on the running driver, or Deinitialize() then EnsureInitialized() (on a running driver EnsureInitialized() alone does nothing and leaves it set). GetConfig() then shows the values last written successfully, never the ones of the failed write.

Returns
true while the driver's copy is not known to be the chip's state.

◆ IsInitialized()

template<SpiPort Port>
bool ads7952::ADS7952< Port >::IsInitialized ( ) const
inlinenoexcept
Returns
true after a successful EnsureInitialized() and before Deinitialize(). No I/O.

◆ ReadAuto1()

template<SpiPort Port>
Result< Bank > ads7952::ADS7952< Port >::ReadAuto1 ( )
noexcept

One pass of the Auto-1 sequence (Config::auto1_channels): the hot path.

While the chip runs the sequence (after a previous ReadAuto1()), k frames for k channels, each the Auto-1 word with DI11 = 1 and DI10 = 0 (the range and GPIO levels again, no restart): the chip steps through the sequence by itself and every reply is a result. Unlike a "continue" word, it puts the range back and, after a reset, makes the chip enter Auto-1 with the reset sequence, so even a sequence of channel 0 alone shows the reset within a few passes. Right after SetRange() or SetAuto1Channels(), k + 1; otherwise the Auto-1 word that enters the mode and restarts the sequence (with the range and the GPIO levels) and one frame in flight come first, k + 2. The k replies must be the k channels of the sequence, each once, in the chip's ascending, wrapping order; the pass may start at any channel.

Returns
The bank, or NotInitialized, Bus, DeviceReset (a reply from channel 0 out of turn: the chip is back in Manual mode on channel 0) or SequenceMismatch (the chip left Auto-1 or lost its mask). After either of the last two the driver is uninitialised: call EnsureInitialized().

◆ ReadAuto2()

template<SpiPort Port>
Result< Bank > ads7952::ADS7952< Port >::ReadAuto2 ( )
noexcept

One pass of the Auto-2 sequence, channel 0 to Config::auto2_last_channel: as ReadAuto1() with the Auto-2 word.

Returns
The bank, or NotInitialized, Bus, DeviceReset or SequenceMismatch (the driver is then uninitialised).

◆ ReadChannel()

template<SpiPort Port>
Result< uint16_t > ads7952::ADS7952< Port >::ReadChannel ( uint8_t  channel)
noexcept

One conversion of channel in Manual mode.

When the chip already converts channel in Manual mode (after a ReadChannel() of the same channel, or a ReadChannels() that ended with it), one frame; right after SetRange(), two (the first reply was converted in the old range); otherwise three: the Manual word that selects channel (with the range and the GPIO levels, DI11 = 1), the frame that acquires it, and the one that returns it. The frame that returns the result is the Manual word for channel again, so every read sends the channel and the range a reset would have changed (section 8.4.3). The reply's address must be channel; after a select from a settled channel the two replies discarded must carry that channel.

Parameters
channel0 to GetChannelCount() - 1.
Returns
The 12-bit code, or NotInitialized, InvalidArgument (nothing sent), Bus, DeviceReset (a reply came from channel 0, the power-on channel) or ChannelMismatch (another address). After either of the last two the driver is uninitialised: call EnsureInitialized().

◆ ReadChannels()

template<SpiPort Port>
Result< void > ads7952::ADS7952< Port >::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 channel, then two frames; the result of each channel arrives two frames after its select. channels.size() + 2 frames. Every reply's address must be the channel it stands for.

Parameters
channels1 to 16 channels, each below GetChannelCount(); repeats allowed.
codesWhere the codes go, in the order of channels; at least as long.
Returns
Ok, NotInitialized, InvalidArgument (nothing sent, codes untouched), Bus, DeviceReset or ChannelMismatch (the driver is then uninitialised; the two first replies, from before the first select, must carry a settled Manual channel). After a failure past the argument checks the codes are 0.

◆ ReadGpio()

template<SpiPort Port>
Result< uint8_t > ads7952::ADS7952< Port >::ReadGpio ( )
noexcept

Read the levels of GPIO3:0, inputs and outputs: a mode word with DI04 = 1, then one with DI04 = 0 whose reply carries them in DO15:12 (Tables 1, 2, 5). 2 frames.

Returns
Bit n for GPIOn (GPIO0 only on VQFN), or NotInitialized or Bus.

◆ SetAlarmThresholds()

template<SpiPort Port>
Result< void > ads7952::ADS7952< Port >::SetAlarmThresholds ( uint8_t  channel,
AlarmThreshold  thresholds 
)
noexcept

Program both alarm thresholds of a channel: the group frame, the low threshold, the high threshold with the exit bit, and one frame to leave the sequence (Table 13). 4 frames. The chip keeps the upper 10 bits of each code. There is no way to read them back.

Parameters
channel0 to GetChannelCount() - 1.
thresholdsThe codes, each 0 to 4095.
Returns
Ok, NotInitialized, InvalidArgument (nothing sent) or Bus.

◆ SetAuto1Channels()

template<SpiPort Port>
Result< void > ads7952::ADS7952< Port >::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 channel of the new mask.

With Verify::ReadBack, a scan follows (as ReadAuto1(), k + 1 or k + 2 frames) whose addresses must be the new sequence; it leaves the sequence running, so the next ReadAuto1() costs k frames.

Parameters
maskBit n for channel n; at least one channel, none above the variant's.
verifyVerify::None (the default) or Verify::ReadBack.
Returns
Ok, NotInitialized, InvalidArgument (nothing sent), Bus or WriteMismatch (the driver is then uninitialised: a lost frame and a reset look alike).

◆ SetAuto2LastChannel()

template<SpiPort Port>
Result< void > ads7952::ADS7952< Port >::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 at channel 0. Verify::ReadBack adds one scan, as for SetAuto1Channels().

Parameters
last0 to GetChannelCount() - 1.
verifyVerify::None (the default) or Verify::ReadBack.
Returns
Ok, NotInitialized, InvalidArgument (nothing sent), Bus or WriteMismatch (the driver is then uninitialised).

◆ SetGpioOutputs()

template<SpiPort Port>
Result< void > ads7952::ADS7952< Port >::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 the chip drives them (section 8.5.2). 2 frames; the pins show the levels when it returns.

With Verify::ReadBack the second frame is a mode word that asks for the GPIO levels (DI04) and a third returns them in DO15:12, after the pins changed; they must equal levels on every output pin (WriteMismatch). 3 frames. It catches a lost frame and a pin held by the board.

Parameters
levelsBit n for GPIOn; only pins in Config::gpio.output_mask.
verifyVerify::None (the default) or Verify::ReadBack.
Returns
Ok, NotInitialized, InvalidArgument (nothing sent), Bus or WriteMismatch. Once the first frame went out the chip holds the levels and GetConfig() shows them, whatever comes after.

◆ SetRange()

template<SpiPort Port>
Result< void > ads7952::ADS7952< Port >::SetRange ( Range  range)
noexcept

Change the input range: one mode word for the current mode with the new DI06 (Table 1, 2, 5). Results clocked out from the second frame after it use the new range; the conversion calls skip the one in between by themselves.

Parameters
rangeThe new range.
Returns
Ok, NotInitialized, InvalidArgument (not an enumerator, Range 2 with 2 x VREF above va_min_mv, or a Config::monitor that does not fit the new range; nothing sent), Unsupported (GPIO2 is the range input; nothing sent) or Bus.

◆ ToMicrovolts() [1/2]

template<SpiPort Port>
uint32_t ads7952::ADS7952< Port >::ToMicrovolts ( const Bank &  bank,
uint8_t  channel 
) const
inlinenoexcept

The input voltage of one channel of a scan, in the range that scan was converted in (Bank::range), not the range configured now. No I/O.

Parameters
bankA result of ReadAuto1() or ReadAuto2().
channel0 to 15; a channel the bank does not hold gives 0.
Returns
Microvolts at the bottom of the code's step.

◆ ToMicrovolts() [2/2]

template<SpiPort Port>
uint32_t ads7952::ADS7952< Port >::ToMicrovolts ( uint16_t  code) const
inlinenoexcept

The input voltage a code stands for in the configured range and reference. No I/O.

Parameters
code0 to 4095.
Returns
Microvolts at the bottom of the code's step (one LSB is full scale / 4096).

◆ TraceFrames()

template<SpiPort Port>
Result< void > ads7952::ADS7952< Port >::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, the select frame's included; the other frames are "continue" words: replies.size() frames. The address nibble of replies[2] onwards should be channel; a nibble that never follows the select means SDI does not reach the chip. A single shot with no retry and no check of the replies (handbook KB-CPP-129); its one side effect is that the chip is left in Manual mode on channel, as after ReadChannel(channel).

Parameters
channel0 to GetChannelCount() - 1.
replies1 to kMaxTraceFrames words.
Returns
Ok, NotInitialized, InvalidArgument (nothing sent) or Bus (the words are then 0).

The documentation for this class was generated from the following file: