API guide¶
The driver's API by task, with code that compiles: initialise, measure, set a range, watch a window, calibrate, handle errors and go to standby.
Datasheet sections this page relies on
From Texas Instruments SBASB22 -:
- ADC transfer function and output codes: 7.3.5 ADC Transfer Function, p. 27
- ADC gain and offset error calibration: 7.3.10 ADC Gain and Offset Error Calibration, p. 32
- Digital filters and the system phase calibration: 7.3.11 Digital Filter; 7.3.11.1 System Phase Calibration, p. 34
- Digital window comparator: 7.3.12 Digital Window Comparator, p. 39
- Alarm modes and the DRDY/ALARM pin: 7.3.13 Alarm Modes, Table 7-10, p. 41
- Test patterns: 7.3.14.5 Test Patterns for Data Interface, Table 7-14, p. 47
- Normal operation and standby: 7.4.2 Normal Operation; 7.4.3 Standby Mode, p. 49
All of them, with the driver API for each: Datasheet map.
The shape of the API¶
| Group | Calls |
|---|---|
| Lifecycle | EnsureInitialized(), IsInitialized(), Deinitialize(), Reset(), Identify() |
| Configuration | ApplyConfig(), GetConfig(), SetInput(), SetInterface(), SetFilter(), SetChannels(), SetAlarm(), SetReference(), SetTestPattern() |
| Measurement | Convert(), WaitDataReady(), ReadFrame(), MeasureOnce(), ReadAlarmPin() |
| Window comparator | ReadWindowFlags(), ClearWindowFlags() |
| Calibration | RunAdcCalibration(), DisableAdcCalibration(), IsCalibrationBusy() |
| Power | PowerDown(), Wake(), IsPoweredDown() |
| Diagnostics | ReadRegister(), GetShadow(), RunDataPathSelfTest() |
| Pure helpers | Validate(), RangeMillivolts(), CodeToMicrovolts(), OutputRateHz(), ads9324::GetDriverVersion() |
Every call that touches the chip returns Result<T>: check ok() (or the bool conversion) and read value, or
read error. Result is [[nodiscard]], so an unchecked call is a compiler warning. Channels are counted from 0:
channel 0 is AIN1 and channel 15 is AIN16.
Initialise¶
ads9324::Error BringUp(Adc& adc) {
// The one entry point: starts the chip on the first call, then returns Ok
// with no I/O. After a failure the next call starts again from the beginning.
const auto r = adc.EnsureInitialized();
if (!r) {
std::printf("ADS9324 init: %s\n", ads9324::ToString(r.error));
}
return r.error;
}
The constructor stores the port and the configuration (Config{} unless you pass one) and does no I/O.
EnsureInitialized() is the one way to start the chip. Its first call brings the bus up, waits the power-up time,
resets the chip (RESET when Config::hardware_reset is set, otherwise SW_RST), checks DEVICE_ID, clears the reset
flag and writes the configuration.
Once it has succeeded, EnsureInitialized() returns Ok at once with no I/O, so a caller (or a handler that owns
the driver) can call it before every use. After a failure the driver stays uninitialised and the next call starts
again from the beginning. No other call starts the chip: before EnsureInitialized() succeeds every read and write
returns NotInitialized and sends nothing. ApplyConfig() before the start only stores the configuration for the
first EnsureInitialized().
Measure¶
ads9324::Result<int32_t> MeasureAin5(Adc& adc) {
// CONVST pulse, wait for the result, read and decode one frame (needs
// GpioSet() for CONVST).
const auto frame = adc.MeasureOnce();
if (!frame) {
return ads9324::Result<int32_t>::Failure(frame.error);
}
return ads9324::Result<int32_t>::Success(frame.value.microvolts[4]); // AIN5, in microvolts
}
MeasureOnce() is Convert(), WaitDataReady() and ReadFrame() in one call. Convert() pulses CONVST (high,
then low, then high again: the falling edge samples all 16 channels together, and the line is high when the result
arrives). MeasureOnce() repeats the pulse as often as one result needs (PulsesPerResult()).
WaitDataReady() waits for the DRDY pin when Sampling::ready is ReadySource::Pin and the port has
GpioGet(), otherwise the conversion time. ReadFrame() clocks the frame out and decodes it into a Frame:
Frame field |
Meaning |
|---|---|
codes[n] |
The signed 16-bit code of channel n (0 for a channel that is not in the frame) |
microvolts[n] |
The input voltage of channel n, from the code and the channel's range, in integer microvolts |
raw[n], low_byte[n] |
The wire value after derandomizing, and the extra byte of a 24-bit word |
present_mask, clipped_mask |
Bit n: channel n is in the frame, or sits at a code limit |
diag, window_alert, reset_detected |
The DIAG byte, when Interface::append_diag or randomize adds it |
Drive CONVST yourself¶
A port without GpioSet() for CONVST, or a design where a timer or a PWM channel clocks CONVST, calls ReadFrame()
after each conversion instead of MeasureOnce(); the driver then never touches CONVST, except that
RunAdcCalibration() and a filter change need pulses and return Unsupported without the hook. Set
Sampling::convst_hz to the rate your timer runs, so the timed waits and the output-rate helpers match.
With a block-average filter on the external clock, or a FIR filter, one Convert() is one CONVST pulse, but the
chip produces a result only after the block (PulsesPerResult(Filter) pulses); pulse CONVST that many times (a
free-running timer does this) before ReadFrame(). MeasureOnce() does it for you. Limitations
lists this.
Set a range¶
ads9324::Error UseTenVoltRange(Adc& adc) {
ads9324::Input in =
adc.GetConfig().inputs[8]; // AIN9: the register layout is mirrored, the driver knows
in.range = ads9324::InputRange::V10; // +-10 V full scale
in.bandwidth = ads9324::Bandwidth::Wide; // 280 kHz to 350 kHz low-pass
return adc.SetInput(8, in).error; // only the registers that change are written
}
SetInput() takes a channel and an Input: range (±2.5 V, ±5 V, ±6.25 V, ±10 V, ±12.5 V), type (differential,
single-ended, single-ended open-wire safe), bandwidth, common-mode correction, offset, gain, phase delay and the
window. The registers of the AIN9 to AIN16 bank are in reverse order; SetInput(8, ...) writes AIN9's registers.
A call writes only what changed and stores the input only after the chip accepted it. The offset and gain
correction helpers OffsetCorrectionFor() and GainCorrectionFor() turn a measured error into the register
values.
Watch a window¶
ads9324::Error WatchAin3(Adc& adc) {
ads9324::Input in = adc.GetConfig().inputs[2];
in.window =
ads9324::Window{true, 40, -40, 2}; // alert outside -40..+40 on the top byte, hysteresis 2
if (auto r = adc.SetInput(2, in); !r) {
return r.error;
}
ads9324::Alarm alarm = adc.GetConfig().alarm;
alarm.function = ads9324::AlarmFunction::WindowAlert; // DRDY/ALARM now shows
// the window alert
return adc.SetAlarm(alarm).error;
}
ads9324::Error AcknowledgeAlerts(Adc& adc) {
const auto flags = adc.ReadWindowFlags(); // which channels went high (bit n =
// AIN n+1) or low
if (!flags) {
return flags.error;
}
std::printf("high 0x%04X low 0x%04X\n", static_cast<unsigned>(flags.value.high),
static_cast<unsigned>(flags.value.low));
const auto a = adc.ClearWindowFlags(0); // AIN1 to AIN8
return a ? adc.ClearWindowFlags(1).error : a.error; // AIN9 to AIN16
}
The window comparator compares the top byte of each code with a high and a low threshold, with hysteresis. The
driver writes the thresholds before it enables the window, so no false alert appears between the two writes. With
AlarmFunction::WindowAlert the DRDY/ALARM pin shows the alert (ReadAlarmPin() reads it, with active_low
applied); the flags per channel are latched until ClearWindowFlags() clears a group. Alarm::pulse makes the pin
a pulse instead of a level (window alert only); AlarmFunction::OrMasked needs or_mask_acknowledged, because the
sense of the source mask is not verified (Limitations).
Choose a filter¶
ads9324::Error AverageSixteen(Adc& adc) {
ads9324::Filter f{};
f.kind = ads9324::FilterKind::MovingAverage;
f.length = ads9324::AverageLength::X16;
return adc.SetFilter(f).error; // the driver pulses SYSREF after the write, as the chip needs
}
One digital filter at a time: block average, moving average or a FIR filter (FIR1 to FIR5 and FIR7). The driver
pulses SYSREF (CONVST low, high, low) after a filter write, as the chip requires; that needs GpioSet() for
CONVST. A filter and the ADC calibration exclude each other: switch the filter off first.
Calibrate¶
ads9324::Error Calibrate(Adc& adc) {
// Needs no digital filter. Single shot: about 125 ms, then the chip keeps the
// result.
return adc.RunAdcCalibration()
.error; // Refused when a filter is on, Timeout when CALIB_BUSY stays set
}
RunAdcCalibration() removes the converter's own offset and gain error (Config::calibration chooses which, and
whether CONVST runs single-shot or free). It waits for CALIB_BUSY with a bound of 150 ms. The chip keeps the
result as long as ADC_CAL_MODE stays set, so the driver leaves it set; DisableAdcCalibration() removes the
correction.
Check the data path¶
RunDataPathSelfTest() writes a different constant test pattern to every channel, reads a frame and compares
each channel with its own pattern, then restores the configuration. It proves the data lanes, the word format and
the channel-to-register mapping of both banks on your board, and returns DataMismatch when a channel returns
another's value. Run it once at bring-up.
Handle errors¶
const char* Describe(ads9324::Error e) {
switch (e) {
case ads9324::Error::Bus:
case ads9324::Error::DeviceIdMismatch:
return "check the SPI wiring, the mode and the chip select";
case ads9324::Error::UnexpectedReset:
return "the chip lost its configuration: call EnsureInitialized() again";
case ads9324::Error::DataMismatch:
return "all zeros or all ones on the data line: check SDOUT and the "
"supplies";
case ads9324::Error::Refused:
return "the chip is in standby or a filter is on: Wake(), or SetFilter() "
"with None first";
default:
return ads9324::ToString(e);
}
}
| Signal | Meaning | What to do |
|---|---|---|
Error::Bus |
The port failed a transfer or the bus bring-up | Check the port and the wiring; retry, or Reset(Software), or Deinitialize() and EnsureInitialized() |
Error::Timeout |
A reset, the DRDY pin or a calibration did not finish | Check the supplies, the reference and CONVST; raise Sampling::ready_timeout_us |
Error::DataMismatch |
The frame is all zeros or all ones | Check SDOUT and the supplies; RunDataPathSelfTest() |
Error::UnexpectedReset |
The chip reset behind the driver's back | EnsureInitialized() writes the configuration again |
Error::VerifyFailed |
A read-back differs from what was written | Lower the clock; check the supplies |
Error::Refused |
Standby, or a calibration with a filter on | Wake(), or switch the filter off |
Error::Unsupported |
A hook the call needs is absent, or the daisy chain was requested | Add the hook; the daisy chain is out of scope |
Every value, with the calls that return it, is on the Contract page.
ads9324::ToString() names an error for a log.
Diagnostics¶
For bring-up and fault finding, the driver keeps what it believes the chip holds and offers one raw access (handbook KB-CPP-119, KB-CPP-129):
| Call | I/O | What it gives |
|---|---|---|
ReadRegister(bank, address) |
bank select, command and data frame, no retry | The raw 16 bits of one documented register |
GetLastRegisterReply() |
none | The raw value the last ReadRegister returned |
GetShadow(bank, address) |
none | The value the driver believes the chip holds |
Verify::ReadBack (a trailing argument of every setter) |
one two-frame read per register written | VerifyFailed when a register differs |
Standby¶
void Standby(Adc& adc) {
if (auto r = adc.PowerDown(); !r) {
std::printf("ADS9324 standby failed: %s\n", ads9324::ToString(r.error));
return;
}
// ... later ...
const auto w = adc.Wake(); // waits 30 ms and checks that the registers survived
if (w.error == ads9324::Error::UnexpectedReset) {
(void)adc.EnsureInitialized(); // they did not: start again
}
}
PowerDown() writes the standby bit; until Wake() every other call returns Refused. Wake() waits 30 ms and
checks that the chip kept its registers (GEN_CFG3 against the shadow and the reset flag). Deinitialize() is the
standby write plus NotInitialized afterwards: Deinitialize() then EnsureInitialized() is also the recovery
after a fault.
Next: Configuration.