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

Driver for one ADS9324 on a platform port. More...

#include <ads9324.hpp>

Public Member Functions

 ADS9324 (Port &port, const Config &config={}) noexcept
 Bind the driver to a port and store the configuration. No I/O, cannot fail.
 
 ADS9324 (const ADS9324 &)=delete
 One driver object per chip.
 
ADS9324 & operator= (const ADS9324 &)=delete
 One driver object per chip.
 
Lifecycle
Result< void > EnsureInitialized () noexcept
 Start the chip, once: the only way to initialise the driver.
 
bool IsInitialized () const noexcept
 
bool IsPoweredDown () const noexcept
 
Result< void > Deinitialize () noexcept
 Put the chip in standby and mark the driver uninitialised, even if the write failed.
 
Result< void > Reset (ResetKind kind) noexcept
 Reset the chip and write the stored configuration again.
 
Result< uint16_t > Identify () noexcept
 Read DEVICE_ID.
 
Configuration
Result< void > ApplyConfig (const Config &config, Verify verify=Verify::None) noexcept
 Change the whole configuration. Before the start it is only stored, with no I/O.
 
const Config & GetConfig () const &noexcept
 
void GetConfig () const &&=delete
 Not on a temporary driver: the reference would dangle (KB-CPP20-044).
 
Result< void > SetInput (uint8_t channel, const Input &input, Verify verify=Verify::None) noexcept
 Change one channel's input settings (range, type, filter, offset, gain, phase, window).
 
Result< void > SetInterface (const Interface &interface, Verify verify=Verify::None) noexcept
 Change the data interface.
 
Result< void > SetFilter (const Filter &filter, Verify verify=Verify::None) noexcept
 Change the digital filter.
 
Result< void > SetChannels (const ChannelSelect &select, Verify verify=Verify::None) noexcept
 Choose the channels in the data frame.
 
Result< void > SetAlarm (const Alarm &alarm, Verify verify=Verify::None) noexcept
 Change the DRDY/ALARM pin.
 
Result< void > SetReference (ReferenceSource source, Verify verify=Verify::None) noexcept
 Change the reference source (30 ms settle follows).
 
Result< void > SetTestPattern (uint8_t group, const TestPattern &pattern, Verify verify=Verify::None) noexcept
 Change the test pattern of one channel group.
 
Conversion and readout
Result< void > Convert () noexcept
 Start one conversion with a pulse on CONVST (high, low, high: the falling edge samples, and the line is high again before DRDY rises). With a FIR filter or an external-clock block average one pulse is not a result: see PulsesPerResult(); MeasureOnce() sends them all.
 
Result< void > WaitDataReady () noexcept
 Wait until a result is ready: the DRDY/ALARM pin (ReadySource::Pin), or the conversion time.
 
Result< Frame > ReadFrame () noexcept
 Read and decode one data frame.
 
Result< Frame > MeasureOnce () noexcept
 Convert(), WaitDataReady() and ReadFrame().
 
Result< bool > ReadAlarmPin () noexcept
 The level of the DRDY/ALARM pin as asserted or not, with Alarm::active_low applied.
 
Window comparator and calibration
Result< WindowFlags > ReadWindowFlags () noexcept
 Read the latched window comparator flags of both banks.
 
Result< void > ClearWindowFlags (uint8_t group) noexcept
 Clear the latched flags of a group (DWC_STAT_RST written 1, then 0).
 
Result< void > RunAdcCalibration () noexcept
 Run the ADC calibration with Config::calibration.
 
Result< void > DisableAdcCalibration () noexcept
 Write ADC_CAL_MODE 0: the calibration values are no longer applied.
 
Result< bool > IsCalibrationBusy () noexcept
 Read CALIB_BUSY_FLAG.
 
Power and diagnostics
Result< void > PowerDown () noexcept
 Enter standby (PDN_CTL.DEVICE_PDN). Other calls return Refused until Wake(). A switch-off is never refused for doubt: after a reset report or a line fault the standby write is still sent, and the error found is returned.
 
Result< void > Wake () noexcept
 Leave standby, wait 30 ms and check that the chip kept its registers.
 
Result< uint16_t > ReadRegister (reg::Bank bank, uint8_t address) noexcept
 Read one documented register once: bank select, command and data frame.
 
uint16_t GetLastRegisterReply () const noexcept
 The raw value the last register read returned. No bus traffic.
 
Result< void > RunDataPathSelfTest () noexcept
 Check the data path with constant test patterns on all 16 channels: every channel must return its own pattern, which also proves the channel-to-register mapping of both banks. The configuration is restored afterwards.
 
uint16_t GetShadow (reg::Bank bank, uint8_t address) const noexcept
 The register value the driver believes the chip holds. No I/O.
 

Detailed Description

template<SpiPort Port>
class ads9324::ADS9324< Port >

Driver for one ADS9324 on a platform port.

Lifecycle: construct with the configuration (no I/O), then EnsureInitialized(), the one way to start (bus up, power-up wait, reset, identity check, configuration), 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.

Configuration is written through a write-through shadow of every register: a call writes only the registers that differ from what the chip holds, and a setter stores the new configuration only after the chip accepted it. Setters take a trailing Verify that reads every register back.

Optional port hooks, found at compile time:

void DelayUs(uint32_t us) noexcept is required. A hook declared with the wrong signature is a compile error.

Template Parameters
PortYour class derived from SpiInterface<Port>.

Constructor & Destructor Documentation

◆ ADS9324()

template<SpiPort Port>
ads9324::ADS9324< Port >::ADS9324 ( Port &  port,
const Config &  config = {} 
)
explicitnoexcept

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

Parameters
portThe port; it must outlive the driver.
configWhat EnsureInitialized() will apply; checked there, before any I/O.

Member Function Documentation

◆ ApplyConfig()

template<SpiPort Port>
Result< void > ads9324::ADS9324< Port >::ApplyConfig ( const Config &  config,
Verify  verify = Verify::None 
)
noexcept

Change the whole configuration. Before the start it is only stored, with no I/O.

Parameters
configChecked with Validate() before any I/O.
verifyReadBack reads every register written and compares (one two-frame read each).
Returns
Ok, InvalidArgument, Unsupported (daisy chain), Refused (powered down), Bus or VerifyFailed. The stored configuration changes only on Ok.

◆ ClearWindowFlags()

template<SpiPort Port>
Result< void > ads9324::ADS9324< Port >::ClearWindowFlags ( uint8_t  group)
noexcept

Clear the latched flags of a group (DWC_STAT_RST written 1, then 0).

Parameters
group0 (AIN1 to AIN8) or 1 (AIN9 to AIN16).
Returns
Ok, InvalidArgument, NotInitialized, Refused or Bus.

◆ Convert()

template<SpiPort Port>
Result< void > ads9324::ADS9324< Port >::Convert ( )
noexcept

Start one conversion with a pulse on CONVST (high, low, high: the falling edge samples, and the line is high again before DRDY rises). With a FIR filter or an external-clock block average one pulse is not a result: see PulsesPerResult(); MeasureOnce() sends them all.

Returns
Ok, NotInitialized, Refused (powered down), Unsupported (no GpioSet(); drive CONVST yourself) or Bus.

◆ Deinitialize()

template<SpiPort Port>
Result< void > ads9324::ADS9324< Port >::Deinitialize ( )
noexcept

Put the chip in standby and mark the driver uninitialised, even if the write failed.

Returns
Ok or Bus; Ok with no I/O on an uninitialised driver.

◆ DisableAdcCalibration()

template<SpiPort Port>
Result< void > ads9324::ADS9324< Port >::DisableAdcCalibration ( )
noexcept

Write ADC_CAL_MODE 0: the calibration values are no longer applied.

Returns
Ok, NotInitialized, Refused or Bus.

◆ EnsureInitialized()

template<SpiPort Port>
Result< void > ads9324::ADS9324< Port >::EnsureInitialized ( )
noexcept

Start the chip, once: the only way to initialise the driver.

Brings the port up, waits the 30 ms power-up time, resets the chip (the RESET pin when Config::hardware_reset is set, else SW_RST), reads DEVICE_ID and BANK_SEL, waits for CALIB_BUSY to clear, clears RESET_DETECT_FLAG, writes the configuration and optionally runs the ADC calibration. 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 (the configuration fails Validate(); no I/O), Unsupported (daisy chain, or a hardware reset without GpioSet()), Bus, Timeout, DeviceIdMismatch, VerifyFailed or the calibration errors.

◆ GetConfig()

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

◆ GetLastRegisterReply()

template<SpiPort Port>
uint16_t ads9324::ADS9324< Port >::GetLastRegisterReply ( ) const
inlinenoexcept

The raw value the last register read returned. No bus traffic.

Returns
The last value ReadRegister or a verify read-back received; 0 before any read.

◆ GetShadow()

template<SpiPort Port>
uint16_t ads9324::ADS9324< Port >::GetShadow ( reg::Bank  bank,
uint8_t  address 
) const
noexcept

The register value the driver believes the chip holds. No I/O.

Parameters
bankThe bank.
addressThe address.
Returns
The shadow value; 0 for an undocumented address.

◆ Identify()

template<SpiPort Port>
Result< uint16_t > ads9324::ADS9324< Port >::Identify ( )
noexcept

Read DEVICE_ID.

Returns
0x0004, or NotInitialized / Bus.

◆ IsCalibrationBusy()

template<SpiPort Port>
Result< bool > ads9324::ADS9324< Port >::IsCalibrationBusy ( )
noexcept

Read CALIB_BUSY_FLAG.

Returns
true while a calibration runs, or NotInitialized, Bus.

◆ IsInitialized()

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

◆ IsPoweredDown()

template<SpiPort Port>
bool ads9324::ADS9324< Port >::IsPoweredDown ( ) const
inlinenoexcept
Returns
true between PowerDown() and Wake(). No I/O.

◆ MeasureOnce()

template<SpiPort Port>
Result< Frame > ads9324::ADS9324< Port >::MeasureOnce ( )
noexcept

Convert(), WaitDataReady() and ReadFrame().

Returns
The frame, or the errors of those calls.

◆ PowerDown()

template<SpiPort Port>
Result< void > ads9324::ADS9324< Port >::PowerDown ( )
noexcept

Enter standby (PDN_CTL.DEVICE_PDN). Other calls return Refused until Wake(). A switch-off is never refused for doubt: after a reset report or a line fault the standby write is still sent, and the error found is returned.

Returns
Ok; NotInitialized only when no frame was ever sent; Bus, DeviceIdMismatch or UnexpectedReset when the check before the write failed (standby was still written).

◆ ReadAlarmPin()

template<SpiPort Port>
Result< bool > ads9324::ADS9324< Port >::ReadAlarmPin ( )
noexcept

The level of the DRDY/ALARM pin as asserted or not, with Alarm::active_low applied.

Returns
true when the pin function is asserted, or NotInitialized, Unsupported, Bus.

◆ ReadFrame()

template<SpiPort Port>
Result< Frame > ads9324::ADS9324< Port >::ReadFrame ( )
noexcept

Read and decode one data frame.

The frame is read on SDOUT (one lane) or on the lanes through CaptureLanes(); the transmit side is all zeros, so no register is written by accident. A DIAG byte with RESET_DETECT_FLAG makes the driver uninitialised and returns UnexpectedReset.

Returns
The frame, or NotInitialized, Refused, Unsupported, Bus, UnexpectedReset, DataMismatch (an all-0x00 or all-0xFF frame, unless a test pattern is on).

◆ ReadRegister()

template<SpiPort Port>
Result< uint16_t > ads9324::ADS9324< Port >::ReadRegister ( reg::Bank  bank,
uint8_t  address 
)
noexcept

Read one documented register once: bank select, command and data frame.

Parameters
bankThe bank.
addressA documented address of that bank.
Returns
The value, or NotInitialized, InvalidArgument (nothing sent) or Bus.

◆ ReadWindowFlags()

template<SpiPort Port>
Result< WindowFlags > ads9324::ADS9324< Port >::ReadWindowFlags ( )
noexcept

Read the latched window comparator flags of both banks.

Returns
The flags per channel, or NotInitialized, Refused, Bus.

◆ Reset()

template<SpiPort Port>
Result< void > ads9324::ADS9324< Port >::Reset ( ResetKind  kind)
noexcept

Reset the chip and write the stored configuration again.

Parameters
kindSoftware (SW_RST) or Hardware (a pulse on the RESET pin).
Returns
Ok, NotInitialized, InvalidArgument (kind is not an enumerator), Unsupported (no GpioSet() for Hardware), Bus, Timeout, DeviceIdMismatch.

◆ RunAdcCalibration()

template<SpiPort Port>
Result< void > ads9324::ADS9324< Port >::RunAdcCalibration ( )
noexcept

Run the ADC calibration with Config::calibration.

Single shot: INT_TRIG_MODE, ADC_CAL_MODE, TRIG 0 to 1 and back, one CONVST pulse ending high, then at most 125 ms plus 25 ms of CALIB_BUSY polling. Continuous: expects a free-running CONVST and waits 100,000 periods. ADC_CAL_MODE stays set afterwards (mode 0 would remove the calibration).

Returns
Ok, NotInitialized, Refused (powered down, or a digital filter is on), Unsupported (single shot without GpioSet()), Timeout or Bus.

◆ RunDataPathSelfTest()

template<SpiPort Port>
Result< void > ads9324::ADS9324< Port >::RunDataPathSelfTest ( )
noexcept

Check the data path with constant test patterns on all 16 channels: every channel must return its own pattern, which also proves the channel-to-register mapping of both banks. The configuration is restored afterwards.

Returns
Ok, DataMismatch (a channel returned another value), or the errors of the calls it makes.

◆ SetAlarm()

template<SpiPort Port>
Result< void > ads9324::ADS9324< Port >::SetAlarm ( const Alarm &  alarm,
Verify  verify = Verify::None 
)
noexcept

Change the DRDY/ALARM pin.

Parameters
alarmThe new settings.
verifyRead back.
Returns
As ApplyConfig().

◆ SetChannels()

template<SpiPort Port>
Result< void > ads9324::ADS9324< Port >::SetChannels ( const ChannelSelect &  select,
Verify  verify = Verify::None 
)
noexcept

Choose the channels in the data frame.

Parameters
selectCount and group.
verifyRead back.
Returns
As ApplyConfig().

◆ SetFilter()

template<SpiPort Port>
Result< void > ads9324::ADS9324< Port >::SetFilter ( const Filter &  filter,
Verify  verify = Verify::None 
)
noexcept

Change the digital filter.

Parameters
filterThe new filter.
verifyRead back.
Returns
As ApplyConfig(). A changed filter is followed by the SYSREF pulse.

◆ SetInput()

template<SpiPort Port>
Result< void > ads9324::ADS9324< Port >::SetInput ( uint8_t  channel,
const Input &  input,
Verify  verify = Verify::None 
)
noexcept

Change one channel's input settings (range, type, filter, offset, gain, phase, window).

Parameters
channel0 (AIN1) to 15 (AIN16).
inputThe new settings.
verifyRead back what was written.
Returns
As ApplyConfig(); InvalidArgument for a channel above 15.

◆ SetInterface()

template<SpiPort Port>
Result< void > ads9324::ADS9324< Port >::SetInterface ( const Interface &  interface,
Verify  verify = Verify::None 
)
noexcept

Change the data interface.

Parameters
interfaceThe new settings.
verifyRead back.
Returns
As ApplyConfig().

◆ SetReference()

template<SpiPort Port>
Result< void > ads9324::ADS9324< Port >::SetReference ( ReferenceSource  source,
Verify  verify = Verify::None 
)
noexcept

Change the reference source (30 ms settle follows).

Parameters
sourceThe source.
verifyRead back.
Returns
As ApplyConfig().

◆ SetTestPattern()

template<SpiPort Port>
Result< void > ads9324::ADS9324< Port >::SetTestPattern ( uint8_t  group,
const TestPattern &  pattern,
Verify  verify = Verify::None 
)
noexcept

Change the test pattern of one channel group.

Parameters
group0 (AIN1 to AIN8) or 1 (AIN9 to AIN16).
patternThe pattern.
verifyRead back.
Returns
As ApplyConfig(); InvalidArgument for a group above 1.

◆ WaitDataReady()

template<SpiPort Port>
Result< void > ads9324::ADS9324< Port >::WaitDataReady ( )
noexcept

Wait until a result is ready: the DRDY/ALARM pin (ReadySource::Pin), or the conversion time.

Returns
Ok, NotInitialized, Refused, Unsupported (pin wait without GpioGet(), or the pin is not set to DRDY), Timeout (Sampling::ready_timeout_us) or Bus.

◆ Wake()

template<SpiPort Port>
Result< void > ads9324::ADS9324< Port >::Wake ( )
noexcept

Leave standby, wait 30 ms and check that the chip kept its registers.

Returns
Ok; UnexpectedReset (RESET_DETECT_FLAG: the registers were lost; the driver is uninitialised); VerifyFailed (GEN_CFG3 differs from the shadow); NotInitialized, Refused (not powered down) or Bus.

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