HF-ADS7952 Driver 0.1.0-dev
HF-ADS7952 C++ Driver
Loading...
Searching...
No Matches
Core Driver API

High-level class for initialization, conversion, sequencing, and programming. More...

Files

file  ads7952.ipp
 Template implementation for the ADS7952 driver.
 

Classes

class  ads7952::ADS7952< SpiType >
 Main driver class for the ADS7952 ADC. More...
 

Functions

 ads7952::ADS7952< SpiType >::ADS7952 (SpiType &spi, float vref=ADS7952_CFG::DEFAULT_VREF, float va=ADS7952_CFG::DEFAULT_VA, Range initial_range=ADS7952_CFG::DEFAULT_RANGE) noexcept
 Construct a new ADS7952 driver instance.
 
void ads7952::ADS7952< SpiType >::SetVref (float vref) noexcept
 Update the Vref value for voltage calculations.
 
void ads7952::ADS7952< SpiType >::SetVA (float va) noexcept
 Update the VA supply voltage value.
 
bool ads7952::ADS7952< SpiType >::EnsureInitialized (bool force=false) noexcept
 Ensure the driver is initialized — idempotent, safe to call repeatedly.
 
ReadResult ads7952::ADS7952< SpiType >::ReadChannel (uint8_t channel) noexcept
 Read a single ADC channel (switches to Manual mode).
 
ChannelReadings ads7952::ADS7952< SpiType >::ReadAllChannels () noexcept
 Read all channels in the current Auto-1 sequence.
 
float ads7952::ADS7952< SpiType >::CountToVoltage (uint16_t count) const noexcept
 Convert raw count to voltage using the currently active reference.
 
uint16_t ads7952::ADS7952< SpiType >::VoltageToCount (float voltage) const noexcept
 Convert a voltage to a 12-bit ADC count using the active reference.
 
bool ads7952::ADS7952< SpiType >::EnterManualMode (uint8_t channel=0) noexcept
 Enter Manual mode, selecting the given channel for conversion.
 
bool ads7952::ADS7952< SpiType >::EnterAuto1Mode (bool reset_counter=true) noexcept
 Enter Auto-1 mode (sequences through programmed channel mask).
 
bool ads7952::ADS7952< SpiType >::EnterAuto2Mode (bool reset_counter=true) noexcept
 Enter Auto-2 mode (sequences channels 0 through last_channel).
 
bool ads7952::ADS7952< SpiType >::ProgramAuto1Channels (uint16_t channel_mask) noexcept
 Program the Auto-1 channel sequence.
 
bool ads7952::ADS7952< SpiType >::ProgramAuto2LastChannel (uint8_t last_channel) noexcept
 Program the Auto-2 last channel.
 
bool ads7952::ADS7952< SpiType >::ProgramGPIO (const GPIOConfig &config) noexcept
 Program GPIO pin functions, direction, and alarm routing.
 
bool ads7952::ADS7952< SpiType >::ProgramAlarm (uint8_t channel, AlarmBound bound, uint16_t threshold_12bit) noexcept
 Program an alarm threshold for a single channel (count-based).
 
bool ads7952::ADS7952< SpiType >::ProgramAlarmVoltage (uint8_t channel, AlarmBound bound, float voltage) noexcept
 Program an alarm threshold for a single channel (voltage-based).
 
bool ads7952::ADS7952< SpiType >::SetRange (Range range) noexcept
 Set the input voltage range and update active reference.
 
bool ads7952::ADS7952< SpiType >::SetPowerDown (PowerDown pd) noexcept
 Set the power-down mode.
 
void ads7952::ADS7952< SpiType >::SetGPIOOutputs (uint8_t gpio_state) noexcept
 Set GPIO output pin levels (for pins configured as outputs).
 

Detailed Description

High-level class for initialization, conversion, sequencing, and programming.

Function Documentation

◆ ADS7952()

template<typename SpiType >
ads7952::ADS7952< SpiType >::ADS7952 ( SpiType & spi,
float vref = ADS7952_CFG::DEFAULT_VREF,
float va = ADS7952_CFG::DEFAULT_VA,
Range initial_range = ADS7952_CFG::DEFAULT_RANGE )
explicitnoexcept

Construct a new ADS7952 driver instance.

Construct a new ADS7952 driver instance.

Parameters
spiReference to platform-specific SPI interface
vrefREFP pin voltage in volts (default 2.5V for REF5025)
vaVA supply voltage in volts (default 5.0V)
initial_rangeInitial input range to apply for conversions
Parameters
spiReference to platform-specific SPI interface
vrefREFP pin voltage in volts (default 2.5V for REF5025)
vaVA supply voltage in volts (default 5.0V)
initial_rangeInitial input range to apply for conversions

Definition at line 32 of file ads7952.ipp.

◆ CountToVoltage()

template<typename SpiType >
float ads7952::ADS7952< SpiType >::CountToVoltage ( uint16_t count) const
noexcept

Convert raw count to voltage using the currently active reference.

Convert raw count to voltage using the currently active reference.

Parameters
countRaw 12-bit ADC count (0-4095)
Returns
Voltage in volts
Parameters
countRaw 12-bit ADC count (0-4095)
Returns
Voltage in volts

Definition at line 192 of file ads7952.ipp.

References ads7952::reg::MAX_COUNT.

◆ EnsureInitialized()

template<typename SpiType >
bool ads7952::ADS7952< SpiType >::EnsureInitialized ( bool force = false)
noexcept

Ensure the driver is initialized — idempotent, safe to call repeatedly.

Ensure the driver is initialized — idempotent, safe to call repeatedly.

On first call: discards the invalid power-up conversion, programs defaults (Auto-1 channels, Auto-2 last channel), and enters Auto-1 mode. On subsequent calls: returns true immediately without SPI traffic.

Parameters
forceIf true, re-runs the full initialization sequence even if the driver is already initialized. Use after a device reset or power cycle.
Returns
true if the driver is initialized after the call

On first call: discards the invalid power-up conversion, programs defaults (Auto-1 channels, Auto-2 last channel), and enters Auto-1 mode. On subsequent calls: returns true immediately without SPI traffic.

Parameters
forceIf true, re-runs the full initialization sequence even if the driver is already initialized. Use after a device reset or power cycle.
Returns
true if the driver is initialized after the call

Definition at line 63 of file ads7952.ipp.

◆ EnterAuto1Mode()

template<typename SpiType >
bool ads7952::ADS7952< SpiType >::EnterAuto1Mode ( bool reset_counter = true)
noexcept

Enter Auto-1 mode (sequences through programmed channel mask).

Enter Auto-1 mode (sequences through programmed channel mask).

Parameters
reset_countertrue to reset channel counter to start of sequence
Returns
true on success
Parameters
reset_countertrue to reset channel counter to start of sequence
Returns
true on success

Definition at line 224 of file ads7952.ipp.

References ads7952::Auto1, ads7952::reg::Mode::AUTO_1, ads7952::reg::NO_RESET_COUNTER, ads7952::reg::PROGRAM_ENABLE, and ads7952::reg::RESET_COUNTER.

◆ EnterAuto2Mode()

template<typename SpiType >
bool ads7952::ADS7952< SpiType >::EnterAuto2Mode ( bool reset_counter = true)
noexcept

Enter Auto-2 mode (sequences channels 0 through last_channel).

Enter Auto-2 mode (sequences channels 0 through last_channel).

Parameters
reset_countertrue to reset channel counter to channel 0
Returns
true on success
Parameters
reset_countertrue to reset channel counter to channel 0
Returns
true on success

Definition at line 235 of file ads7952.ipp.

References ads7952::Auto2, ads7952::reg::Mode::AUTO_2, ads7952::reg::NO_RESET_COUNTER, ads7952::reg::PROGRAM_ENABLE, and ads7952::reg::RESET_COUNTER.

◆ EnterManualMode()

template<typename SpiType >
bool ads7952::ADS7952< SpiType >::EnterManualMode ( uint8_t channel = 0)
noexcept

Enter Manual mode, selecting the given channel for conversion.

Enter Manual mode, selecting the given channel for conversion.

Parameters
channelChannel to select (0-11, default 0)
Returns
true on success
Parameters
channelChannel to select (0-11, default 0)
Returns
true on success

Definition at line 212 of file ads7952.ipp.

References ads7952::reg::ChannelSelect(), ads7952::reg::Mode::MANUAL, ads7952::Manual, ads7952::reg::NUM_CHANNELS, and ads7952::reg::PROGRAM_ENABLE.

◆ ProgramAlarm()

template<typename SpiType >
bool ads7952::ADS7952< SpiType >::ProgramAlarm ( uint8_t channel,
AlarmBound bound,
uint16_t threshold_12bit )
noexcept

Program an alarm threshold for a single channel (count-based).

Program an alarm threshold for a single channel (count-based).

The 12-bit ADC count (0–4095) is internally truncated to 10 bits for the hardware alarm register (only the top 10 bits are stored).

Parameters
channelChannel number (0–11)
boundLow or High alarm threshold
threshold_12bit12-bit ADC count (0–4095); internally right-shifted by 2 to produce 10-bit hardware threshold
Returns
true on success
adc.ProgramAlarm(0, ads7952::AlarmBound::High, 3000); // Raw count
@ High
High alarm threshold register.

The 12-bit ADC count (0–4095) is internally truncated to 10 bits for the hardware alarm register (only the top 10 bits are stored).

Parameters
channelChannel number (0–11)
boundLow or High alarm threshold
threshold_12bit12-bit ADC count (0–4095); internally right-shifted by 2 to produce 10-bit hardware threshold
Returns
true on success
adc.ProgramAlarm(0, ads7952::AlarmBound::High, 3000); // Raw count

Definition at line 333 of file ads7952.ipp.

References ads7952::reg::Mode::ALARM_GROUP_0, ads7952::reg::Mode::ALARM_GROUP_1, ads7952::reg::Mode::ALARM_GROUP_2, ads7952::reg::Alarm::ChannelInGroup(), ads7952::reg::CHANNELS_PER_ALARM_GROUP, ads7952::reg::Mode::CONTINUE, ads7952::reg::Alarm::EXIT_NEXT_FRAME, ads7952::High, ads7952::reg::Alarm::HIGH_REGISTER, ads7952::reg::NUM_CHANNELS, and ads7952::reg::Alarm::Threshold12To10().

◆ ProgramAlarmVoltage()

template<typename SpiType >
bool ads7952::ADS7952< SpiType >::ProgramAlarmVoltage ( uint8_t channel,
AlarmBound bound,
float voltage )
noexcept

Program an alarm threshold for a single channel (voltage-based).

Program an alarm threshold for a single channel (voltage-based).

Converts the voltage to a 12-bit count using the currently active reference voltage, then programs the hardware alarm register.

Warning
The hardware alarm register stores a raw count, not a voltage. If the range is later changed via SetRange(), the stored count will correspond to a different physical voltage and the alarm will trigger at the wrong level. Re-call ProgramAlarmVoltage() after any SetRange() call to re-synchronize.
Parameters
channelChannel number (0–11)
boundLow or High alarm threshold
voltageThreshold voltage in volts (clamped to valid range)
Returns
true on success
adc.ProgramAlarmVoltage(0, ads7952::AlarmBound::Low, 0.5f);
adc.ProgramAlarmVoltage(0, ads7952::AlarmBound::High, 2.0f);
// After a range change, re-program to restore correct thresholds:
adc.ProgramAlarmVoltage(0, ads7952::AlarmBound::Low, 0.5f); // re-sync
adc.ProgramAlarmVoltage(0, ads7952::AlarmBound::High, 2.0f); // re-sync
@ TwoVref
0 to 2*Vref, clamped to VA (RANGE bit = 1)
@ Low
Low alarm threshold register.

Converts the voltage to a 12-bit count using the currently active reference voltage, then programs the hardware alarm register.

Warning
The hardware alarm register stores a raw count, not a voltage. If the range is later changed via SetRange(), the stored count will correspond to a different physical voltage and the alarm will trigger at the wrong level. Re-call ProgramAlarmVoltage() after any SetRange() call to re-synchronize.
Parameters
channelChannel number (0–11)
boundLow or High alarm threshold
voltageThreshold voltage in volts (clamped to valid range)
Returns
true on success
adc.ProgramAlarmVoltage(0, ads7952::AlarmBound::Low, 0.5f);
adc.ProgramAlarmVoltage(0, ads7952::AlarmBound::High, 2.0f);
// After a range change, re-program to restore correct thresholds:
adc.ProgramAlarmVoltage(0, ads7952::AlarmBound::Low, 0.5f); // re-sync
adc.ProgramAlarmVoltage(0, ads7952::AlarmBound::High, 2.0f); // re-sync

Definition at line 374 of file ads7952.ipp.

References ads7952::VoltageToCount().

◆ ProgramAuto1Channels()

template<typename SpiType >
bool ads7952::ADS7952< SpiType >::ProgramAuto1Channels ( uint16_t channel_mask)
noexcept

Program the Auto-1 channel sequence.

Program the Auto-1 channel sequence.

Bit ordering: bit N enables channel N (bit 0 = CH0, bit 11 = CH11, LSB-first). Only bits [11:0] are used; upper bits are masked off.

Use the ads7952::ChannelMask() helper or predefined constants:

adc.ProgramAuto1Channels(ads7952::ChannelMask(0, 2, 4)); // CH0, CH2, CH4
adc.ProgramAuto1Channels(ads7952::kAllChannels); // All 12
adc.ProgramAuto1Channels(ads7952::kEvenChannels); // Even only
adc.ProgramAuto1Channels(ads7952::ChannelRangeMask(0, 5)); // CH0–CH5
constexpr uint16_t ChannelRangeMask(uint8_t first, uint8_t last) noexcept
Build a contiguous channel range mask from first to last (inclusive).
constexpr uint16_t ChannelMask(Channels... channels) noexcept
Construct a channel enable bitmask from a list of channel numbers.
constexpr uint16_t kAllChannels
CH0–CH11 (all 12)
constexpr uint16_t kEvenChannels
CH0, CH2, CH4, CH6, CH8, CH10.
Parameters
channel_maskBitmask where bit N enables channel N (bits [11:0])
Returns
true on success

Bit ordering: bit N enables channel N (bit 0 = CH0, bit 11 = CH11, LSB-first). Only bits [11:0] are used; upper bits are masked off.

Use the ads7952::ChannelMask() helper or predefined constants:

adc.ProgramAuto1Channels(ads7952::ChannelMask(0, 2, 4)); // CH0, CH2, CH4
adc.ProgramAuto1Channels(ads7952::kAllChannels); // All 12
adc.ProgramAuto1Channels(ads7952::kEvenChannels); // Even only
adc.ProgramAuto1Channels(ads7952::ChannelRangeMask(0, 5)); // CH0–CH5
Parameters
channel_maskBitmask where bit N enables channel N (bits [11:0])
Returns
true on success

Definition at line 250 of file ads7952.ipp.

References ads7952::reg::Mode::AUTO_1_PROG.

◆ ProgramAuto2LastChannel()

template<typename SpiType >
bool ads7952::ADS7952< SpiType >::ProgramAuto2LastChannel ( uint8_t last_channel)
noexcept

Program the Auto-2 last channel.

Program the Auto-2 last channel.

Parameters
last_channelLast channel in sequence (0-11)
Returns
true on success
Parameters
last_channelLast channel in sequence (0-11)
Returns
true on success

Definition at line 268 of file ads7952.ipp.

References ads7952::reg::Auto2LastChannel(), ads7952::reg::Mode::AUTO_2_PROG, and ads7952::reg::NUM_CHANNELS.

◆ ProgramGPIO()

template<typename SpiType >
bool ads7952::ADS7952< SpiType >::ProgramGPIO ( const GPIOConfig & config)
noexcept

Program GPIO pin functions, direction, and alarm routing.

Program GPIO pin functions, direction, and alarm routing.

Configures which GPIO pins act as inputs or outputs, assigns alarm signalling roles to GPIO0/GPIO1, optionally assigns GPIO2/GPIO3 as hardware range/power-down inputs, and optionally resets all device registers. Sends a single GPIO_PROG mode frame.

Parameters
configGPIO configuration structure
Returns
true on success

Configures which GPIO pins act as inputs or outputs, assigns alarm signalling roles to GPIO0/GPIO1, optionally assigns GPIO2/GPIO3 as hardware range/power-down inputs, and optionally resets all device registers. Sends a single GPIO_PROG mode frame.

Parameters
configGPIO configuration structure
Returns
true on success

Definition at line 284 of file ads7952.ipp.

References ads7952::GPIO, ads7952::reg::GPIOProg::GPIO0_HI_ALARM, ads7952::reg::GPIOProg::GPIO0_HI_LO_ALARM, ads7952::GPIO0_HighAlarm, ads7952::GPIO0_HighAndLowAlarm, ads7952::reg::GPIOProg::GPIO1_HI_ALARM, ads7952::GPIO1_HighAlarm, ads7952::reg::GPIOProg::GPIO1_LO_GPIO0_HI_ALARM, ads7952::GPIO1_LowAlarm_GPIO0_HighAlarm, ads7952::reg::GPIOProg::GPIO2_RANGE_IN, ads7952::reg::GPIOProg::GPIO3_PWRDOWN_IN, ads7952::reg::Mode::GPIO_PROG, and ads7952::reg::GPIOProg::RESET_ALL_REGS.

◆ ReadAllChannels()

template<typename SpiType >
ChannelReadings ads7952::ADS7952< SpiType >::ReadAllChannels ( )
noexcept

Read all channels in the current Auto-1 sequence.

Read all channels in the current Auto-1 sequence.

Enters Auto-1 mode with channel counter reset and reads until all programmed channels are received or timeout.

Precondition
EnsureInitialized() has been called successfully.
Returns
ChannelReadings with per-channel counts and voltages

Enters Auto-1 mode with channel counter reset and reads until all programmed channels are received or timeout.

Precondition
EnsureInitialized() has been called successfully.
Returns
ChannelReadings with per-channel counts and voltages

Definition at line 135 of file ads7952.ipp.

References ads7952::Auto1, ads7952::reg::Mode::AUTO_1, ads7952::reg::Mode::CONTINUE, ads7952::ChannelReadings::error, ads7952::reg::Response::GetChannel(), ads7952::reg::Response::GetData(), ads7952::ChannelReadings::MAX_CHANNELS, ads7952::NotInitialized, ads7952::Ok, ads7952::reg::PROGRAM_RETAIN, ADS7952_CFG::READ_ALL_MAX_EXTRA_FRAMES, ads7952::reg::RESET_COUNTER, and ads7952::Timeout.

◆ ReadChannel()

template<typename SpiType >
ReadResult ads7952::ADS7952< SpiType >::ReadChannel ( uint8_t channel)
noexcept

Read a single ADC channel (switches to Manual mode).

Read a single ADC channel (switches to Manual mode).

Precondition
EnsureInitialized() has been called successfully.
Parameters
channelChannel number (0-11)
Returns
ReadResult with count, voltage, channel, and error status
Precondition
EnsureInitialized() has been called successfully.
Parameters
channelChannel number (0-11)
Returns
ReadResult with count, voltage, channel, and error status

Definition at line 101 of file ads7952.ipp.

References ads7952::reg::ChannelSelect(), ads7952::reg::Mode::CONTINUE, ads7952::ReadResult::error, ads7952::reg::Response::GetChannel(), ads7952::reg::Response::GetData(), ads7952::InvalidChannel, ads7952::reg::Mode::MANUAL, ads7952::Manual, ads7952::NotInitialized, ads7952::reg::NUM_CHANNELS, ads7952::Ok, and ads7952::reg::PROGRAM_RETAIN.

◆ SetGPIOOutputs()

template<typename SpiType >
void ads7952::ADS7952< SpiType >::SetGPIOOutputs ( uint8_t gpio_state)
noexcept

Set GPIO output pin levels (for pins configured as outputs).

Set GPIO output pin levels (for pins configured as outputs).

Bit ordering: bit N controls GPIO pin N (bit 0 = GPIO0, bit 3 = GPIO3). 1 = high, 0 = low. Use ads7952::gpio:: constants:

adc.SetGPIOOutputs(ads7952::gpio::kNone); // All low
constexpr uint8_t kGPIO2
Bit 2 — GPIO pin 2.
constexpr uint8_t kNone
No GPIO pins.
constexpr uint8_t kGPIO3
Bit 3 — GPIO pin 3.
Parameters
gpio_stateBits [3:0] — 1 = high, 0 = low per pin

Bit ordering: bit N controls GPIO pin N (bit 0 = GPIO0, bit 3 = GPIO3). 1 = high, 0 = low. Use ads7952::gpio:: constants:

adc.SetGPIOOutputs(ads7952::gpio::kNone); // All low
Parameters
gpio_stateBits [3:0] — 1 = high, 0 = low per pin

Definition at line 414 of file ads7952.ipp.

References ads7952::reg::Mode::CONTINUE.

◆ SetPowerDown()

template<typename SpiType >
bool ads7952::ADS7952< SpiType >::SetPowerDown ( PowerDown pd)
noexcept

Set the power-down mode.

Set the power-down mode.

Parameters
pdNormal or PowerDown
Returns
true on success
Parameters
pdNormal or PowerDown
Returns
true on success

Definition at line 399 of file ads7952.ipp.

References ads7952::reg::Mode::CONTINUE.

◆ SetRange()

template<typename SpiType >
bool ads7952::ADS7952< SpiType >::SetRange ( Range range)
noexcept

Set the input voltage range and update active reference.

Set the input voltage range and update active reference.

Changes the hardware reference voltage used for SAR conversions by sending a CONTINUE frame with the updated range bit. Also updates the internal active_vref_ used by CountToVoltage() and VoltageToCount().

Warning
Alarm thresholds are stored in the hardware as raw counts. Changing the range changes the count produced for any given physical voltage, so existing alarm thresholds will fire at different voltages after a range change. If alarms were programmed using ProgramAlarmVoltage(), re-call it after SetRange() to correct the hardware registers.
Parameters
rangeVref or TwoVref
Returns
true on success

Changes the hardware reference voltage used for SAR conversions by sending a CONTINUE frame with the updated range bit. Also updates the internal active_vref_ used by CountToVoltage() and VoltageToCount().

Warning
Alarm thresholds are stored in the hardware as raw counts. Changing the range changes the count produced for any given physical voltage, so existing alarm thresholds will fire at different voltages after a range change. If alarms were programmed using ProgramAlarmVoltage(), re-call it after SetRange() to correct the hardware registers.
Parameters
rangeVref or TwoVref
Returns
true on success

Definition at line 385 of file ads7952.ipp.

References ads7952::reg::Mode::CONTINUE, and ads7952::TwoVref.

◆ SetVA()

template<typename SpiType >
void ads7952::ADS7952< SpiType >::SetVA ( float va)
noexcept

Update the VA supply voltage value.

Use this for runtime calibration when VA is measured (e.g., via resistor divider on an ADC channel). VA is used for validation and ratiometric sensor calculations.

Parameters
vaNew VA voltage in volts (clamped to 2.7V–5.5V)
Note
Does not send any SPI commands — purely for software calculations.

Definition at line 53 of file ads7952.ipp.

References ADS7952_CFG::MAX_VA, and ADS7952_CFG::MIN_VA.

◆ SetVref()

template<typename SpiType >
void ads7952::ADS7952< SpiType >::SetVref ( float vref)
noexcept

Update the Vref value for voltage calculations.

Use this for runtime calibration when Vref is measured externally. Updates both vref_ and two_vref_ (2×Vref) accordingly.

Parameters
vrefNew Vref voltage in volts (clamped to 1.0V–2.5V)
Note
Does not send any SPI commands — purely for software calculations.

Definition at line 45 of file ads7952.ipp.

References ADS7952_CFG::MAX_VREF, ADS7952_CFG::MIN_VREF, and ads7952::TwoVref.

◆ VoltageToCount()

template<typename SpiType >
uint16_t ads7952::ADS7952< SpiType >::VoltageToCount ( float voltage) const
noexcept

Convert a voltage to a 12-bit ADC count using the active reference.

Convert a voltage to a 12-bit ADC count using the active reference.

Instance version — uses the currently active reference voltage (affected by the Range setting). Result is clamped to 0–4095.

Parameters
voltageTarget voltage in volts
Returns
12-bit ADC count (0–4095)

Instance version — uses the currently active reference voltage (affected by the Range setting). Result is clamped to 0–4095.

Parameters
voltageTarget voltage in volts
Returns
12-bit ADC count (0–4095)

Definition at line 199 of file ads7952.ipp.

References ads7952::reg::MAX_COUNT.