|
ADS9324 Driver 0.1.0
API 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. | |
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:
bool GpioSet(CtrlPin, GpioSignal) noexcept drives the RESET pin and the CONVST pulse. Without it Convert() and a hardware reset return Unsupported, and so does single-shot calibration.bool GpioGet(CtrlPin, bool& high) noexcept reads the DRDY/ALARM pin. Without it ReadySource::Pin waits and ReadAlarmPin() return Unsupported.bool CaptureLanes(uint8_t lanes, uint8_t* rx, std::size_t len) noexcept reads data on D7 to D0. Without it frames on D7 to D0 return Unsupported; one lane on SDOUT works.void Log(LogLevel, const char* message) noexcept takes one line per lifecycle event or failure. Without it nothing is logged.void DelayUs(uint32_t us) noexcept is required. A hook declared with the wrong signature is a compile error.
| Port | Your class derived from SpiInterface<Port>. |
|
explicitnoexcept |
Bind the driver to a port and store the configuration. No I/O, cannot fail.
| port | The port; it must outlive the driver. |
| config | What EnsureInitialized() will apply; checked there, before any I/O. |
|
noexcept |
Change the whole configuration. Before the start it is only stored, with no I/O.
| config | Checked with Validate() before any I/O. |
| verify | ReadBack reads every register written and compares (one two-frame read each). |
Ok, InvalidArgument, Unsupported (daisy chain), Refused (powered down), Bus or VerifyFailed. The stored configuration changes only on Ok.
|
noexcept |
Clear the latched flags of a group (DWC_STAT_RST written 1, then 0).
| group | 0 (AIN1 to AIN8) or 1 (AIN9 to AIN16). |
Ok, InvalidArgument, NotInitialized, Refused or Bus.
|
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.
Ok, NotInitialized, Refused (powered down), Unsupported (no GpioSet(); drive CONVST yourself) or Bus.
|
noexcept |
Put the chip in standby and mark the driver uninitialised, even if the write failed.
Ok or Bus; Ok with no I/O on an uninitialised driver.
|
noexcept |
Write ADC_CAL_MODE 0: the calibration values are no longer applied.
Ok, NotInitialized, Refused or Bus.
|
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.
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.
|
inlinenoexcept |
|
inlinenoexcept |
The raw value the last register read returned. No bus traffic.
ReadRegister or a verify read-back received; 0 before any read.
|
noexcept |
The register value the driver believes the chip holds. No I/O.
| bank | The bank. |
| address | The address. |
|
noexcept |
Read DEVICE_ID.
NotInitialized / Bus.
|
noexcept |
Read CALIB_BUSY_FLAG.
NotInitialized, Bus.
|
inlinenoexcept |
EnsureInitialized() and before Deinitialize(). No I/O.
|
inlinenoexcept |
PowerDown() and Wake(). No I/O.
|
noexcept |
Convert(), WaitDataReady() and ReadFrame().
|
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.
Ok; NotInitialized only when no frame was ever sent; Bus, DeviceIdMismatch or UnexpectedReset when the check before the write failed (standby was still written).
|
noexcept |
The level of the DRDY/ALARM pin as asserted or not, with Alarm::active_low applied.
NotInitialized, Unsupported, Bus.
|
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.
NotInitialized, Refused, Unsupported, Bus, UnexpectedReset, DataMismatch (an all-0x00 or all-0xFF frame, unless a test pattern is on).
|
noexcept |
Read one documented register once: bank select, command and data frame.
| bank | The bank. |
| address | A documented address of that bank. |
NotInitialized, InvalidArgument (nothing sent) or Bus.
|
noexcept |
Read the latched window comparator flags of both banks.
NotInitialized, Refused, Bus.
|
noexcept |
Reset the chip and write the stored configuration again.
| kind | Software (SW_RST) or Hardware (a pulse on the RESET pin). |
Ok, NotInitialized, InvalidArgument (kind is not an enumerator), Unsupported (no GpioSet() for Hardware), Bus, Timeout, DeviceIdMismatch.
|
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).
Ok, NotInitialized, Refused (powered down, or a digital filter is on), Unsupported (single shot without GpioSet()), Timeout or Bus.
|
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.
Ok, DataMismatch (a channel returned another value), or the errors of the calls it makes.
|
noexcept |
Change the DRDY/ALARM pin.
| alarm | The new settings. |
| verify | Read back. |
ApplyConfig().
|
noexcept |
Choose the channels in the data frame.
| select | Count and group. |
| verify | Read back. |
ApplyConfig().
|
noexcept |
Change the digital filter.
| filter | The new filter. |
| verify | Read back. |
ApplyConfig(). A changed filter is followed by the SYSREF pulse.
|
noexcept |
Change one channel's input settings (range, type, filter, offset, gain, phase, window).
| channel | 0 (AIN1) to 15 (AIN16). |
| input | The new settings. |
| verify | Read back what was written. |
ApplyConfig(); InvalidArgument for a channel above 15.
|
noexcept |
Change the data interface.
| interface | The new settings. |
| verify | Read back. |
ApplyConfig().
|
noexcept |
Change the reference source (30 ms settle follows).
| source | The source. |
| verify | Read back. |
ApplyConfig().
|
noexcept |
Change the test pattern of one channel group.
| group | 0 (AIN1 to AIN8) or 1 (AIN9 to AIN16). |
| pattern | The pattern. |
| verify | Read back. |
ApplyConfig(); InvalidArgument for a group above 1.
|
noexcept |
Wait until a result is ready: the DRDY/ALARM pin (ReadySource::Pin), or the conversion time.
Ok, NotInitialized, Refused, Unsupported (pin wait without GpioGet(), or the pin is not set to DRDY), Timeout (Sampling::ready_timeout_us) or Bus.
|
noexcept |
Leave standby, wait 30 ms and check that the chip kept its registers.
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.