|
ADS7952 Driver 0.1.0
API 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. | |
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 |
| Port | Your class derived from SpiInterface<Port>. |
|
inlineexplicitnoexcept |
Bind the driver to a port and store the configuration. No I/O, cannot fail.
| port | The port; it must outlive the driver. |
| config | Checked by EnsureInitialized(), before any I/O. |
|
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.
| config | Checked with Validate(). |
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().
|
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.
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).
|
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.
| code | The monitor channel's code, converted in Config::range. |
Ok, RangeMismatch, ScaleMismatch, or InvalidArgument (no monitor).
|
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.
Ok or Bus.
|
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.
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).
|
inlinenoexcept |
|
inlinenoexcept |
|
inlinenoexcept |
The last reply word the driver received, for logs: 0xFFFF before the first. No I/O.
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.
|
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.
|
inlinenoexcept |
EnsureInitialized() and before Deinitialize(). No I/O.
|
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.
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().
|
noexcept |
One pass of the Auto-2 sequence, channel 0 to Config::auto2_last_channel: as ReadAuto1() with the Auto-2 word.
NotInitialized, Bus, DeviceReset or SequenceMismatch (the driver is then uninitialised).
|
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.
| channel | 0 to GetChannelCount() - 1. |
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().
|
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.
| channels | 1 to 16 channels, each below GetChannelCount(); repeats allowed. |
| codes | Where the codes go, in the order of channels; at least as long. |
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.
|
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.
NotInitialized or Bus.
|
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.
| channel | 0 to GetChannelCount() - 1. |
| thresholds | The codes, each 0 to 4095. |
Ok, NotInitialized, InvalidArgument (nothing sent) or Bus.
|
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.
| mask | Bit n for channel n; at least one channel, none above the variant's. |
| verify | Verify::None (the default) or Verify::ReadBack. |
Ok, NotInitialized, InvalidArgument (nothing sent), Bus or WriteMismatch (the driver is then uninitialised: a lost frame and a reset look alike).
|
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().
| last | 0 to GetChannelCount() - 1. |
| verify | Verify::None (the default) or Verify::ReadBack. |
Ok, NotInitialized, InvalidArgument (nothing sent), Bus or WriteMismatch (the driver is then uninitialised).
|
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.
| levels | Bit n for GPIOn; only pins in Config::gpio.output_mask. |
| verify | Verify::None (the default) or Verify::ReadBack. |
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.
|
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.
| range | The new range. |
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.
|
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.
| bank | A result of ReadAuto1() or ReadAuto2(). |
| channel | 0 to 15; a channel the bank does not hold gives 0. |
|
inlinenoexcept |
The input voltage a code stands for in the configured range and reference. No I/O.
| code | 0 to 4095. |
|
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).
| channel | 0 to GetChannelCount() - 1. |
| replies | 1 to kMaxTraceFrames words. |
Ok, NotInitialized, InvalidArgument (nothing sent) or Bus (the words are then 0).