ADS7952 Driver 0.1.0
API reference
Loading...
Searching...
No Matches
Classes | Enumerations | Functions | Variables
Driver types

Errors, results, variants and configuration. More...

Classes

struct  ads7952::Result< T >
 The value of a call, or why there is none. More...
 
struct  ads7952::Result< void >
 The result of a call that returns no value. More...
 
struct  ads7952::GpioConfig
 The GPIO program register and the GPIO output levels. GpioConfig{} is the reset state: every pin an input with no function. More...
 
struct  ads7952::AlarmThreshold
 The two alarm thresholds of one channel, in 12-bit result codes. The chip keeps the upper 10 bits and compares them with the upper 10 bits of each result (Table 13), so the two lowest bits of a threshold are dropped. AlarmThreshold{} is the reset state: no alarm. More...
 
struct  ads7952::Bank
 The result of one Auto-1 or Auto-2 scan: one code per channel of the sequence. More...
 
struct  ads7952::ScaleMonitor
 A channel the board drives with a known voltage, so the driver can prove the scale every code is converted with: the range the chip is really in, and a reference that is present. More...
 
struct  ads7952::Config
 What the driver is told about the chip and the board. Config{} is an ADS7952 in TSSOP left in its reset state (Tables 1 to 13): Range 1, every GPIO an input, every channel in Auto-1, channel 11 the last of Auto-2, no alarm; with a 2.5 V reference and a 5 V analog supply. More...
 

Enumerations

enum class  ads7952::Error : uint8_t {
  ads7952::Error::Ok = 0 , ads7952::Error::NotInitialized = 1 , ads7952::Error::InvalidArgument = 2 , ads7952::Error::Bus = 3 ,
  ads7952::Error::Timeout = 4 , ads7952::Error::DeviceIdMismatch = 5 , ads7952::Error::Crc = 6 , ads7952::Error::Busy = 7 ,
  ads7952::Error::DeviceFault = 8 , ads7952::Error::Unsupported = 9 , ads7952::Error::NoDevice = 16 , ads7952::Error::ChannelMismatch = 17 ,
  ads7952::Error::SequenceMismatch = 18 , ads7952::Error::WriteMismatch = 19 , ads7952::Error::RangeMismatch = 20 , ads7952::Error::ScaleMismatch = 21 ,
  ads7952::Error::DeviceReset = 22
}
 Why a call failed. Every call of the driver returns one of these in its Result. More...
 
enum class  ads7952::LogLevel : uint8_t { ads7952::LogLevel::Error = 0 , ads7952::LogLevel::Warning , ads7952::LogLevel::Info , ads7952::LogLevel::Debug }
 Severity passed to the optional Log() hook. More...
 
enum class  ads7952::Variant : uint8_t { ads7952::Variant::Ads7950 = 0 , ads7952::Variant::Ads7951 = 1 , ads7952::Variant::Ads7952 = 2 , ads7952::Variant::Ads7953 = 3 }
 Which 12-bit member of the family is fitted. The chip cannot tell, so it is configured. More...
 
enum class  ads7952::Package : uint8_t { ads7952::Package::Tssop = 0 , ads7952::Package::Vqfn = 1 }
 The package: the VQFN parts bring out GPIO0 only (section 8.5.2). More...
 
enum class  ads7952::Range : uint8_t { ads7952::Range::Vref = 0 , ads7952::Range::TwoVref = 1 }
 Input range, DI06 of the mode control word (Tables 1, 2, 5; Table 8). More...
 
enum class  ads7952::Verify : uint8_t { ads7952::Verify::None = 0 , ads7952::Verify::ReadBack = 1 }
 Extra verification for one call, chosen per call (handbook KB-ARCH-041). More...
 
enum class  ads7952::AlarmOutput : uint8_t {
  ads7952::AlarmOutput::None = 0 , ads7952::AlarmOutput::Gpio0HighOrLow = 1 , ads7952::AlarmOutput::Gpio0High = 2 , ads7952::AlarmOutput::Gpio1Low = 4 ,
  ads7952::AlarmOutput::Gpio1LowGpio0High = 6
}
 What GPIO0 and GPIO1 do besides general-purpose I/O: DI06:04 of the GPIO program register (Table 11). Alarm outputs are active high. More...
 

Functions

constexpr const char * ads7952::ToString (Error error) noexcept
 The name of an error, for logs.
 
constexpr uint8_t ads7952::ChannelCount (Variant variant) noexcept
 Number of analog inputs of a variant.
 
constexpr uint16_t ads7952::AllChannels (Variant variant) noexcept
 The mask of every channel of a variant: also the reset value of its Auto-1 program register (section 8.4.1).
 
constexpr Error ads7952::ValidateMonitor (const Config &config) noexcept
 Check the scale monitor of a configuration.
 
constexpr Error ads7952::CheckScaleCode (const Config &config, uint16_t code) noexcept
 Judge one code of the scale monitor's channel. No I/O.
 
constexpr Error ads7952::ValidateGpio (const Config &config) noexcept
 Check the GPIO settings of a configuration against its package.
 
constexpr Error ads7952::ValidateAlarms (const Config &config) noexcept
 Check the alarm thresholds of a configuration against its variant.
 
constexpr bool ads7952::ValidSupplies (const Config &config) noexcept
 Check the reference and the analog supply (section 7.3), and Range 2 against them (2 x VREF <= +VA, section 7.6).
 
constexpr bool ads7952::ValidPark (const Config &config) noexcept
 Check Config::park_channel against the variant.
 
constexpr Error ads7952::Validate (const Config &config) noexcept
 Check a configuration without touching the chip.
 
constexpr Config ads7952::ResetConfig (Variant variant) noexcept
 The Config of a variant left in its reset state: Config{} with that variant's Auto-1 mask and Auto-2 last channel.
 
constexpr uint32_t ads7952::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, code 4095 is full scale less one LSB).
 
constexpr const char * ads7952::GetDriverVersion () noexcept
 
constexpr uint32_t ads7952::GetDriverVersionMajor () noexcept
 
constexpr uint32_t ads7952::GetDriverVersionMinor () noexcept
 
constexpr uint32_t ads7952::GetDriverVersionPatch () noexcept
 

Variables

constexpr std::size_t ads7952::kMaxChannels = 16
 Channels of the largest part (ADS7953); arrays indexed by channel have this size.
 
constexpr uint16_t ads7952::kMaxCode = 4095
 Largest result code: 12 bits, straight binary (Table 8).
 
constexpr uint32_t ads7952::kCodesPerFullScale = 4096
 Codes per full scale: one LSB is full scale / 4096 (Table 8).
 
constexpr uint32_t ads7952::kPowerUpUs = 1
 
constexpr std::size_t ads7952::kMaxTraceFrames = 32
 Longest TraceFrames() request, in frames.
 
constexpr std::size_t ads7952::kFrameBytes = 2
 Bytes per transfer: every frame is 16 bits with CS low throughout (section 8.1).
 
constexpr uint8_t ads7952::kNoMonitor = 0xFF
 ScaleMonitor::channel when no channel carries a known voltage: no scale check.
 
constexpr uint8_t ads7952::kNoPark = 0xFF
 Config::park_channel when the chip stays on channel 0 after a read of it: no parking.
 

Detailed Description

Errors, results, variants and configuration.

Enumeration Type Documentation

◆ AlarmOutput

enum class ads7952::AlarmOutput : uint8_t
strong

What GPIO0 and GPIO1 do besides general-purpose I/O: DI06:04 of the GPIO program register (Table 11). Alarm outputs are active high.

Enumerator
None 

000: GPIO0 and GPIO1 are general-purpose I/O. The reset value.

Gpio0HighOrLow 

xx1: GPIO0 is the "high or low" alarm output.

Gpio0High 

010: GPIO0 is the high alarm output.

Gpio1Low 

100: GPIO1 is the low alarm output (TSSOP only).

Gpio1LowGpio0High 

110: GPIO1 the low and GPIO0 the high alarm output (TSSOP only).

◆ Error

enum class ads7952::Error : uint8_t
strong

Why a call failed. Every call of the driver returns one of these in its Result.

Values 0 to 9 are the shared base set; chip-specific values start at 16. The type is [[nodiscard]]: a call whose Error is dropped does not compile quietly (KB-CPP20-037).

Enumerator
Ok 

The call succeeded.

NotInitialized 

EnsureInitialized() has not succeeded, or Deinitialize() ran since.

InvalidArgument 

An argument or a Config field is out of range; nothing was sent.

Bus 

The port's Transfer() (or EnsureInitialized()) returned false.

Timeout 

Not returned by this driver: no call waits for the chip.

DeviceIdMismatch 

At start-up, the replies do not carry the channel addresses the chip must send back (MISO stuck low or carrying a pattern, SDI not reaching the chip, another part on the chip select).

Crc 

Not returned by this driver (the chip sends no CRC).

Busy 

Not returned by this driver (the chip is never busy to a frame).

DeviceFault 

Not returned by this driver (the chip reports no faults).

Unsupported 

A setting the configured part or package lacks (GPIO1 to GPIO3 on the VQFN package), or SetRange() while GPIO2 is the range input.

NoDevice 

At start-up, every reply was 0xFFFF: nothing drives MISO (no chip on the chip select, MISO pulled or floating high).

ChannelMismatch 

A reply that must carry a channel's result carries another address: a frame was lost, the chip was reset, or the bus is broken. The result was not returned.

SequenceMismatch 

The replies of an Auto-1 or Auto-2 scan are not one pass of the programmed sequence: the chip left the mode, lost its program register (a reset or brown-out), or a frame was lost.

WriteMismatch 

Verify::ReadBack found that the chip did not take the setting: the GPIO levels read back differ, or the sequence scanned is not the one just programmed.

RangeMismatch 

The scale monitor (Config::monitor) reads what the other range would give: the chip is not converting in Config::range. GPIO2 is the range input and the board drives it to the other level, or the chip was reset (back to Range 1) and the driver has not seen it.

ScaleMismatch 

The scale monitor reads outside its window in both ranges: the reference is missing, wrong or not yet settled, or the monitor input is not the voltage Config::monitor declares.

DeviceReset 

The chip was reset behind the driver (a brown-out): a reply came from channel 0, the power-on channel (section 8.4.3), where the driver expected another, or the scale monitor found Range 1, the reset value. The registers hold their reset values (no alarm function, no GPIO outputs, the reset alarm thresholds); the driver is uninitialised and EnsureInitialized() programs the chip again.

◆ LogLevel

enum class ads7952::LogLevel : uint8_t
strong

Severity passed to the optional Log() hook.

Enumerator
Error 

A call failed.

Warning 

Something unexpected that the driver recovered from.

Info 

Lifecycle events: initialised.

Debug 

Detail for bring-up.

◆ Package

enum class ads7952::Package : uint8_t
strong

The package: the VQFN parts bring out GPIO0 only (section 8.5.2).

Enumerator
Tssop 

TSSOP (DBT): GPIO0 to GPIO3. The default.

Vqfn 

VQFN (RGE, RHB): GPIO0 only; the driver programs GPIO1 to GPIO3 as outputs, as Table 11 requires.

◆ Range

enum class ads7952::Range : uint8_t
strong

Input range, DI06 of the mode control word (Tables 1, 2, 5; Table 8).

Enumerator
Vref 

0 to VREF (Range 1). The reset value.

TwoVref 

0 to 2 x VREF (Range 2); specified only while 2 x VREF <= +VA (section 7.6).

◆ Variant

enum class ads7952::Variant : uint8_t
strong

Which 12-bit member of the family is fitted. The chip cannot tell, so it is configured.

The four parts share the frame format, the modes and the registers; they differ in the number of channels, which sets the reset value of the Auto-1 mask and the Auto-2 last channel and the number of alarm groups (section 8.4.1, Tables 4 and 12). The 10-bit (ADS7954 to ADS7957) and 8-bit (ADS7958 to ADS7961) parts are not supported.

Enumerator
Ads7950 

4 channels.

Ads7951 

8 channels.

Ads7952 

12 channels. The default.

Ads7953 

16 channels.

◆ Verify

enum class ads7952::Verify : uint8_t
strong

Extra verification for one call, chosen per call (handbook KB-ARCH-041).

The datasheet needs none of it: Verify::None, the default, sends only the frames the chip needs. Verify::ReadBack costs frames on the bus; each call that takes it says how many.

Enumerator
None 

No extra frame. The default.

ReadBack 

Read back what the chip took (GPIO levels, the scanned sequence).

Function Documentation

◆ AllChannels()

constexpr uint16_t ads7952::AllChannels ( Variant  variant)
constexprnoexcept

The mask of every channel of a variant: also the reset value of its Auto-1 program register (section 8.4.1).

Parameters
variantThe part.
Returns
0x000F, 0x00FF, 0x0FFF or 0xFFFF; 0 for a value that is not an enumerator.

◆ ChannelCount()

constexpr uint8_t ads7952::ChannelCount ( Variant  variant)
constexprnoexcept

Number of analog inputs of a variant.

Parameters
variantThe part.
Returns
4, 8, 12 or 16; 0 for a value that is not an enumerator.

◆ CheckScaleCode()

constexpr Error ads7952::CheckScaleCode ( const Config &  config,
uint16_t  code 
)
constexprnoexcept

Judge one code of the scale monitor's channel. No I/O.

Parameters
configThe configuration (its monitor, range and vref_mv).
codeThe monitor channel's code, from any read, Bank or DMA stream converted in config.range.
Returns
Ok; RangeMismatch when the code is what the other range gives; ScaleMismatch when it is in neither window; InvalidArgument with no monitor or an invalid one.

◆ CodeToMicrovolts()

constexpr uint32_t ads7952::CodeToMicrovolts ( uint16_t  code,
Range  range,
uint16_t  vref_mv 
)
constexprnoexcept

Convert a result code to the input voltage it stands for (Table 8: one LSB is full scale / 4096, code 4095 is full scale less one LSB).

Parameters
code0 to 4095.
rangeThe range the conversion was made in.
vref_mvThe reference, in millivolts.
Returns
The input voltage at the bottom of the code's step, in microvolts.

◆ GetDriverVersion()

constexpr const char * ads7952::GetDriverVersion ( )
constexprnoexcept
Returns
The driver version, e.g. "0.1.0", from the generated ads7952_version.h. No I/O.

◆ GetDriverVersionMajor()

constexpr uint32_t ads7952::GetDriverVersionMajor ( )
constexprnoexcept
Returns
The major version. No I/O.

◆ GetDriverVersionMinor()

constexpr uint32_t ads7952::GetDriverVersionMinor ( )
constexprnoexcept
Returns
The minor version. No I/O.

◆ GetDriverVersionPatch()

constexpr uint32_t ads7952::GetDriverVersionPatch ( )
constexprnoexcept
Returns
The patch version. No I/O.

◆ ResetConfig()

constexpr Config ads7952::ResetConfig ( Variant  variant)
constexprnoexcept

The Config of a variant left in its reset state: Config{} with that variant's Auto-1 mask and Auto-2 last channel.

Parameters
variantThe part.
Returns
The configuration.

◆ ToString()

constexpr const char * ads7952::ToString ( Error  error)
constexprnoexcept

The name of an error, for logs.

Parameters
errorThe error.
Returns
A static string such as "Bus"; "Unknown" for a value that is not an enumerator.

◆ Validate()

constexpr Error ads7952::Validate ( const Config &  config)
constexprnoexcept

Check a configuration without touching the chip.

Parameters
configThe configuration.
Returns
Ok; InvalidArgument for a value that is not an enumerator, a voltage outside section 7.3, Range 2 with 2 x VREF above +VA, a channel the variant lacks, a threshold above 4095, a scale monitor ValidateMonitor() refuses, a park channel ValidPark() refuses, or a GPIO setting that contradicts itself; Unsupported for a GPIO the package lacks.

◆ ValidateAlarms()

constexpr Error ads7952::ValidateAlarms ( const Config &  config)
constexprnoexcept

Check the alarm thresholds of a configuration against its variant.

Parameters
configThe configuration.
Returns
Ok, or InvalidArgument for a code above 4095 or a threshold other than the reset value on a channel the variant lacks.

◆ ValidateGpio()

constexpr Error ads7952::ValidateGpio ( const Config &  config)
constexprnoexcept

Check the GPIO settings of a configuration against its package.

Parameters
configThe configuration.
Returns
Ok, InvalidArgument or Unsupported (a pin or function the VQFN package lacks).

◆ ValidateMonitor()

constexpr Error ads7952::ValidateMonitor ( const Config &  config)
constexprnoexcept

Check the scale monitor of a configuration.

Parameters
configThe configuration.
Returns
Ok with no monitor or a usable one; InvalidArgument for a channel the variant lacks, a zero tolerance, a window that touches code 0 or 4095 (a dead or clipped input would pass), or windows of the two ranges that touch (a lost range could pass).

◆ ValidPark()

constexpr bool ads7952::ValidPark ( const Config &  config)
constexprnoexcept

Check Config::park_channel against the variant.

Parameters
configThe configuration.
Returns
true for kNoPark or a channel from 1 to the variant's last.

◆ ValidSupplies()

constexpr bool ads7952::ValidSupplies ( const Config &  config)
constexprnoexcept

Check the reference and the analog supply (section 7.3), and Range 2 against them (2 x VREF <= +VA, section 7.6).

Parameters
configThe configuration.
Returns
true when vref_mv, va_min_mv and range fit together.

Variable Documentation

◆ kPowerUpUs

constexpr uint32_t ads7952::kPowerUpUs = 1
inlineconstexpr

Longest wait after the chip leaves power-down or reset before its first conversion, in microseconds (section 7.6, "Power-up time").