Diff: inc/adi_sense_api.h

Revision:

7:4dbae381f693

--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/inc/adi_sense_api.h	Fri Oct 20 15:58:01 2017 +0000
@@ -0,0 +1,834 @@
+/*!
+ ******************************************************************************
+ * @file:   adi_sense_api.h
+ * @brief:  ADI Sense Host Library Application Programming Interface (API)
+ *-----------------------------------------------------------------------------
+ */
+
+/*
+Copyright (c) 2017 Emutex Ltd. / Analog Devices, Inc.
+
+All rights reserved.
+
+Redistribution and use in source and binary forms, with or without modification,
+are permitted provided that the following conditions are met:
+  - Redistributions of source code must retain the above copyright notice,
+    this list of conditions and the following disclaimer.
+  - Redistributions in binary form must reproduce the above copyright notice,
+    this list of conditions and the following disclaimer in the documentation
+    and/or other materials provided with the distribution.
+  - Modified versions of the software must be conspicuously marked as such.
+  - This software is licensed solely and exclusively for use with processors
+    manufactured by or for Analog Devices, Inc.
+  - This software may not be combined or merged with other code in any manner
+    that would cause the software to become subject to terms and conditions
+    which differ from those listed here.
+  - Neither the name of Analog Devices, Inc. nor the names of its
+    contributors may be used to endorse or promote products derived
+    from this software without specific prior written permission.
+  - The use of this software may or may not infringe the patent rights of one
+    or more patent holders.  This license does not release you from the
+    requirement that you obtain separate licenses from these patent holders
+    to use this software.
+
+THIS SOFTWARE IS PROVIDED BY ANALOG DEVICES, INC. AND CONTRIBUTORS "AS IS" AND ANY
+EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, NON-INFRINGEMENT,
+TITLE, MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN
+NO EVENT SHALL ANALOG DEVICES, INC. OR CONTRIBUTORS BE LIABLE FOR ANY DIRECT,
+INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, PUNITIVE OR CONSEQUENTIAL DAMAGES
+(INCLUDING, BUT NOT LIMITED TO, DAMAGES ARISING OUT OF CLAIMS OF INTELLECTUAL
+PROPERTY RIGHTS INFRINGEMENT; PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS
+OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY
+THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING
+NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE,
+EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+*/
+
+#ifndef __ADI_SENSE_API_H__
+#define __ADI_SENSE_API_H__
+
+#include "inc/adi_sense_types.h"
+#include "inc/adi_sense_config_types.h"
+#include "inc/adi_sense_dsp_data_types.h"
+#include "inc/adi_sense_platform.h"
+#include "inc/adi_sense_gpio.h"
+#include "inc/adi_sense_spi.h"
+#include "inc/adi_sense_log.h"
+#include "inc/adi_sense_time.h"
+
+/*! @addtogroup ADI_Sense_Api ADI Sense Host Library API
+ *  @{
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*! A handle used in all API functions to identify the ADI Sense device. */
+typedef void* ADI_SENSE_DEVICE_HANDLE;
+
+/*! Supported connection types for communication with the ADI Sense device. */
+typedef enum {
+    ADI_SENSE_CONNECTION_TYPE_SPI = 1,
+    /*!< Serial Peripheral Interface (SPI) connection type */
+} ADI_SENSE_CONNECTION_TYPE;
+
+/*! Connection details for communication with a ADI Sense device instance. */
+typedef struct {
+    ADI_SENSE_CONNECTION_TYPE      type;
+    /*!< Connection type selection */
+    ADI_SENSE_PLATFORM_SPI_CONFIG  spi;
+    /*!< SPI connection parameters, required if SPI connection type is used */
+    ADI_SENSE_PLATFORM_GPIO_CONFIG gpio;
+    /*!< GPIO connection parameters, for device reset and status I/O signals */
+} ADI_SENSE_CONNECTION;
+
+/*! Bit masks (flags) for the different device status indicators. */
+typedef enum {
+    ADI_SENSE_DEVICE_STATUS_BUSY      = (1 << 0),
+    /*!< Indicates that a command is currently running on the device */
+    ADI_SENSE_DEVICE_STATUS_DATAREADY = (1 << 1),
+    /*!< Indicates the availability of measurement data for retrieval */
+    ADI_SENSE_DEVICE_STATUS_ERROR     = (1 << 2),
+    /*!< Indicates that an error condition has been detected by the device */
+    ADI_SENSE_DEVICE_STATUS_ALERT     = (1 << 3),
+    /*!< Indicates that an alert condition has been detected by the device */
+} ADI_SENSE_DEVICE_STATUS_FLAGS;
+
+/*! Bit masks (flags) for the different diagnostics status indicators. */
+typedef enum {
+    ADI_SENSE_DIAGNOSTICS_STATUS_CHECKSUM_ERROR       = (1 << 0),
+    /*!< Indicates Error on Internal Checksum Calculations */
+    ADI_SENSE_DIAGNOSTICS_STATUS_COMMS_ERROR          = (1 << 1),
+    /*!< Indicates Error on Internal Device Communications */
+    ADI_SENSE_DIAGNOSTICS_STATUS_SUPPLY_MONITOR_ERROR = (1 << 2),
+    /*!< Indicates Low Voltage on Internal Supply Voltages */
+    ADI_SENSE_DIAGNOSTICS_STATUS_SUPPLY_CAP_ERROR     = (1 << 3),
+    /*!< Indicates Fault on Internal Supply Regulator Capacitor */
+    ADI_SENSE_DIAGNOSTICS_STATUS_AINM_UV_ERROR        = (1 << 4),
+    /*!< Indicates Under-Voltage Error on Negative Analog Input */
+    ADI_SENSE_DIAGNOSTICS_STATUS_AINM_OV_ERROR        = (1 << 5),
+    /*!< Indicates Over-Voltage Error on Negative Analog Input */
+    ADI_SENSE_DIAGNOSTICS_STATUS_AINP_UV_ERROR        = (1 << 6),
+    /*!< Indicates Under-Voltage Error on Positive Analog Input */
+    ADI_SENSE_DIAGNOSTICS_STATUS_AINP_OV_ERROR        = (1 << 7),
+    /*!< Indicates Over-Voltage Error on Positive Analog Input */
+    ADI_SENSE_DIAGNOSTICS_STATUS_CONVERSION_ERROR     = (1 << 8),
+    /*!< Indicates Error During Internal ADC Conversions */
+    ADI_SENSE_DIAGNOSTICS_STATUS_CALIBRATION_ERROR    = (1 << 9),
+    /*!< Indicates Error During Internal Device Calibrations */
+} ADI_SENSE_DIAGNOSTICS_STATUS_FLAGS;
+
+/*! Bit masks (flags) for the different channel alert indicators. */
+typedef enum {
+    ADI_SENSE_CHANNEL_ALERT_TIMEOUT     = (1 << 0),
+    /*!< Indicates timeout condition detected on the channel */
+    ADI_SENSE_CHANNEL_ALERT_UNDER_RANGE = (1 << 1),
+    /*!< Indicates under-voltage condition detected on the channel */
+    ADI_SENSE_CHANNEL_ALERT_OVER_RANGE  = (1 << 2),
+    /*!< Indicates over-voltage condition detected on the channel */
+    ADI_SENSE_CHANNEL_ALERT_LOW_LIMIT   = (1 << 3),
+    /*!< Indicates measurement result was below configured minimum threshold */
+    ADI_SENSE_CHANNEL_ALERT_HIGH_LIMIT  = (1 << 4),
+    /*!< Indicates measurement result was above configured maximum threshold */
+    ADI_SENSE_CHANNEL_ALERT_SENSOR_OPEN = (1 << 5),
+    /*!< Indicates open circuit or mis-wire condition detected on the channel */
+    ADI_SENSE_CHANNEL_ALERT_REF_DETECT  = (1 << 6),
+    /*!< Indicates reference-detect error condition detected on the channel */
+} ADI_SENSE_CHANNEL_ALERT_FLAGS;
+
+/*! Status details retreived from the ADI Sense device. */
+typedef struct {
+    ADI_SENSE_DEVICE_STATUS_FLAGS      deviceStatus;
+    /*!< General summary status information from the device  */
+    ADI_SENSE_DIAGNOSTICS_STATUS_FLAGS diagnosticsStatus;
+    /*!< Diagnostic error status information from the device  */
+    ADI_SENSE_CHANNEL_ALERT_FLAGS      channelAlerts[ADI_SENSE_MAX_CHANNELS];
+    /*!< Per-channel alert status information from the device  */
+} ADI_SENSE_STATUS;
+
+/*! Data sample details retreived from the ADI Sense device. */
+typedef struct {
+    ADI_SENSE_DEVICE_STATUS_FLAGS      status;
+    /*!< Device summary status snapshot when the sample was recorded */
+    ADI_SENSE_CHANNEL_ID               channelId;
+    /*!< The measurement channel from which this sample was obtained */
+    uint32_t                           rawValue;
+    /*!< The raw (unprocessed) value obtained directly from the measurement
+     *   channel, if available
+     */
+    float32_t                          processedValue;
+    /*!< The processed value obtained from the measurement channel, as a final
+     *   measurement value, following calibration and linearisation correction,
+     *   and conversion into an appropriate unit of measurement.
+     */
+} ADI_SENSE_DATA_SAMPLE;
+
+
+/******************************************************************************
+ * ADI Sense High-Level API function prototypes
+ *****************************************************************************/
+
+/*!
+ * @brief Open ADI Sense device handle and set up communication interface.
+ *
+ * @param[in]  nDeviceIndex    Zero-based index number identifying this device
+ *                             instance.  Note that this will be used to
+ *                             retrieve a specific device configuration for
+ *                             this device (see @ref adi_sense_SetDeviceConfig
+ *                             and @ref ADI_SENSE_CONFIG)
+ * @param[in]  pConnectionInfo Host-specific connection details (e.g. SPI, GPIO)
+ * @param[out] phDevice        Pointer to return an ADI Sense device handle
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *         - #ADI_SENSE_NO_MEM  Failed to allocate memory resources.
+ *         - #ADI_SENSE_INVALID_DEVICE_NUM Invalid device index specified
+ *
+ * @details Configure and initialise the Log interface and the SPI/GPIO
+ *          communication interface to the ADISense module.
+ */
+ADI_SENSE_RESULT adi_sense_Open(
+    unsigned                   const nDeviceIndex,
+    ADI_SENSE_CONNECTION     * const pConnectionInfo,
+    ADI_SENSE_DEVICE_HANDLE  * const phDevice);
+
+/*!
+ * @brief Close ADI Sense device context and free resources.
+ *
+ * @param[in] hDevice ADI Sense device context handle
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ */
+ADI_SENSE_RESULT adi_sense_Close(
+    ADI_SENSE_DEVICE_HANDLE    const hDevice);
+
+/*!
+ * @brief Get the current state of the specified GPIO input signal.
+ *
+ * @param[in]  hDevice ADI Sense device context handle
+ * @param[in]  ePin    GPIO pin to query
+ * @param[out] pbError Pointer to return the state of the status signal GPIO pin
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *         - #ADI_SENSE_INVALID_DEVICE_NUM Invalid GPIO pin specified.
+ *
+ * @details Sets *pbAsserted to true if the status signal is asserted, or false
+ *          otherwise.
+ */
+ADI_SENSE_RESULT adi_sense_GetGpioState(
+    ADI_SENSE_DEVICE_HANDLE   const hDevice,
+    ADI_SENSE_GPIO_PIN        const ePinId,
+    bool_t                  * const pbAsserted);
+
+/*!
+ * @brief Register an application-defined callback function for GPIO interrupts
+ *
+ * @param[in] hDevice          ADI Sense context handle (@ref adi_sense_Open)
+ * @param[in] ePin             GPIO pin on which to enable/disable interrupts
+ * @param[in] callbackFunction Function to be called when an interrupt occurs.
+ *                             Specify NULL here to disable interrupts.
+ * @param[in] pCallbackParam   Optional opaque parameter passed to the callback
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *         - #ADI_SENSE_INVALID_DEVICE_NUM Invalid GPIO pin specified.
+ */
+ADI_SENSE_RESULT adi_sense_RegisterGpioCallback(
+    ADI_SENSE_DEVICE_HANDLE          const hDevice,
+    ADI_SENSE_GPIO_PIN               const ePinId,
+    ADI_SENSE_GPIO_CALLBACK          const callbackFunction,
+    void                           * const pCallbackParam);
+
+/*!
+ * @brief Reset the ADI Sense device.
+ *
+ * @param[in] hDevice ADI Sense device context handle
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Trigger a hardware-reset of the ADI Sense device.
+ *
+ * @note The device may require several seconds before it is ready for use
+ *       again. @ref adi_sense_GetDeviceReadyState may be used to check if
+ *       the device is ready.
+ */
+ADI_SENSE_RESULT adi_sense_Reset(
+    ADI_SENSE_DEVICE_HANDLE    const hDevice);
+
+/*!
+ * @brief Check if the device is ready, following power-up or a reset.
+ *
+ * @param[in]  hDevice ADI Sense device context handle
+ * @param[out] pbReady Pointer to return true if the device is ready, or false
+ *                     otherwise
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details This function attempts to read a fixed-value device register via
+ *           the communication interface.
+ */
+ADI_SENSE_RESULT adi_sense_GetDeviceReadyState(
+    ADI_SENSE_DEVICE_HANDLE    const hDevice,
+    bool_t                   * const pbReady);
+
+/*!
+ * @brief Obtain the product ID from the device.
+ *
+ * @param[in]  hDevice    ADI Sense device context handle
+ * @param[out] pProductId Pointer to return the product ID value
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Reads the product ID registers on the device and returns the value.
+ */
+ADI_SENSE_RESULT adi_sense_GetProductID(
+    ADI_SENSE_DEVICE_HANDLE    const hDevice,
+    ADI_SENSE_PRODUCT_ID     * const pProductId);
+
+/*!
+ * @brief Write full configuration settings to the device registers.
+ *
+ * @param[in]  hDevice ADI Sense device context handle
+ * @param[out] pConfig Pointer to the configuration data structure
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Translates configuration details provided into device-specific
+ *          register settings and updates device configuration registers.
+ *
+ * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
+ */
+ADI_SENSE_RESULT adi_sense_SetDeviceConfig(
+    ADI_SENSE_DEVICE_HANDLE   const hDevice,
+    ADI_SENSE_CONFIG        * const pConfig);
+
+/*!
+ * @brief Write DSP look-up table data to the device memory
+ *
+ * @param[in]  hDevice  ADI Sense device context handle
+ * @param[out] pDspData Pointer to the DSP look-up table data structure
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Validates the DSP look-up table data format and loads it into
+ *          device memory via dedicated keyhole registers.
+ *
+ * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
+ */
+ADI_SENSE_RESULT adi_sense_SetDspData(
+    ADI_SENSE_DEVICE_HANDLE    const hDevice,
+    ADI_SENSE_DSP_LUT_RAW    * const pDspData);
+
+/*!
+ * @brief Apply the configuration settings currently stored in device registers
+ *
+ * @param[in] hDevice ADI Sense device context handle
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Instructs the ADI Sense device to reload and apply configuration
+ *          from the device configuration registers.  Changes to configuration
+ *          registers are ignored by the device until this function is called.
+ *
+ * @note No other command must be running when this is called.
+ */
+ADI_SENSE_RESULT adi_sense_ApplyConfigUpdates(
+    ADI_SENSE_DEVICE_HANDLE    const hDevice);
+
+/*!
+ * @brief Store the configuration settings to persistent memory on the device.
+ *
+ * @param[in] hDevice ADI Sense device context handle
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Instructs the ADI Sense device to save the current contents of its
+ *          device configuration registers to non-volatile memory.
+ *
+ * @note No other command must be running when this is called.
+ * @note Do not power down the device while this command is running.
+ */
+ADI_SENSE_RESULT adi_sense_SaveConfig(
+    ADI_SENSE_DEVICE_HANDLE    const hDevice);
+
+/*!
+ * @brief Restore configuration settings from persistent memory on the device.
+ *
+ * @param[in] hDevice ADI Sense device context handle
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Instructs the ADI Sense device to restore the contents of its
+ *          device configuration registers from non-volatile memory.
+ *
+ * @note No other command must be running when this is called.
+ */
+ADI_SENSE_RESULT adi_sense_RestoreConfig(
+    ADI_SENSE_DEVICE_HANDLE    const hDevice);
+
+/*!
+ * @brief Start the measurement cycles on the device.
+ *
+ * @param[in] hDevice ADI Sense device context handle
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Instructs the ADI Sense device to start executing measurement cycles
+ *          according to the current applied configuration settings.  The
+ *          DATAREADY status signal will be asserted whenever new measurement
+ *          data is published, according to selected settings.
+ *          Measurement cycles may be stopped by calling @ref
+ *          adi_sense_StopMeasurement.
+ *
+ * @note No other command must be running when this is called.
+ */
+ADI_SENSE_RESULT adi_sense_StartMeasurement(
+    ADI_SENSE_DEVICE_HANDLE    const hDevice);
+
+/*!
+ * @brief Stop the measurement cycles on the device.
+ *
+ * @param[in] hDevice ADI Sense device context handle
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Instructs the ADI Sense device to stop executing measurement cycles.
+ *          The command may be delayed until the current conversion, if any, has
+ *          been completed and published.
+ *
+ * @note To be used only if a measurement command is currently running.
+ */
+ADI_SENSE_RESULT adi_sense_StopMeasurement(
+    ADI_SENSE_DEVICE_HANDLE    const hDevice);
+
+/*!
+ * @brief Run built-in diagnostic checks on the device.
+ *
+ * @param[in] hDevice ADI Sense device context handle
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Instructs the ADI Sense device to start executing measurement cycles
+ *          according to the current applied configuration settings.  Device
+ *          status registers will be updated to indicate if any errors were
+ *          detected by the diagnostics checks.
+ *
+ * @note No other command must be running when this is called.
+ */
+ADI_SENSE_RESULT adi_sense_RunDiagnostics(
+    ADI_SENSE_DEVICE_HANDLE    const hDevice);
+
+/*!
+ * @brief Read the current status from the device registers.
+ *
+ * @param[in]  hDevice ADI Sense device context handle
+ * @param[out] pStatus Pointer to return the status summary obtained from the
+ *                     device.
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Reads the status registers and extracts the relevant information
+ *          to return to the caller.
+ *
+ * @note This may be called at any time, assuming the device is ready.
+ */
+ADI_SENSE_RESULT adi_sense_GetStatus(
+    ADI_SENSE_DEVICE_HANDLE    const hDevice,
+    ADI_SENSE_STATUS         * const pStatus);
+
+/*!
+ * @brief Read measurement data samples from the device registers.
+ *
+ * @param[in]  hDevice    ADI Sense device context handle
+ * @param[out] pSamples   Pointer to return a set of requested data samples.
+ * @param[in]  nRequested Number of requested data samples.
+ * @param[out] pnReturned Number of valid data samples successfully retrieved.
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Reads the status registers and extracts the relevant information
+ *          to return to the caller.
+ *
+ * @note This is intended to be called only when the DATAREADY status signal
+ *       is asserted.
+ */
+ADI_SENSE_RESULT adi_sense_GetData(
+    ADI_SENSE_DEVICE_HANDLE    const hDevice,
+    ADI_SENSE_DATA_SAMPLE    * const pSamples,
+    uint32_t                   const nRequested,
+    uint32_t                 * const pnReturned);
+
+/*!
+ * @brief Check if a command is currently running on the device.
+ *
+ * @param[in]  hDevice          ADI Sense device context handle
+ * @param[out] pbCommandRunning Pointer to return the command running status
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Reads the device status register to check if a command is running.
+ */
+ADI_SENSE_RESULT adi_sense_GetCommandRunningState(
+    ADI_SENSE_DEVICE_HANDLE hDevice,
+    bool_t *pbCommandRunning);
+
+/*!
+ * @brief Get the number of samples available when DATAREADY status is asserted.
+ *
+ * @param[in]  hDevice               ADI Sense device context handle
+ * @param[out] peOperatingMode       Pointer to return the configured operating mode
+ * @param[out] peDataPublishMode     Pointer to return the configured data publishing mode
+ * @param[out] pnSamplesPerDataready Pointer to return the calculated number of samples
+ *                                   available when DATAREADY is asserted
+ * @param[out] pnSamplesPerCycle     Pointer to return the calculated number of samples
+ *                                   produced per measurement cycle
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Examines the current configuration settings in the device registers
+ *          to calculate the number of samples available whenever the DATAREADY
+ *          signal is asserted, along with other related information.  This may
+ *          be used to allocate buffers to store samples and to determine how
+ *          many samples to retrieve whenever the DATAREADY status is asserted.
+ */
+ADI_SENSE_RESULT adi_sense_GetDataPublishingInfo(
+    ADI_SENSE_DEVICE_HANDLE       const hDevice,
+    ADI_SENSE_OPERATING_MODE    * const peOperatingMode,
+    ADI_SENSE_DATA_PUBLISH_MODE * const peDataPublishMode,
+    uint32_t                    * const pnSamplesPerDataready,
+    uint32_t                    * const pnSamplesPerCycle);
+
+
+/******************************************************************************
+ * ADI Sense Low-Level API function prototypes
+ *****************************************************************************/
+
+/*!
+ * @brief Read one or more device registers at the specified register address.
+ *
+ * @param[in]  hDevice    ADI Sense device context handle
+ * @param[in]  nAddress   Register map address to read from
+ * @param[out] pData      Pointer to return the register map data
+ * @param[in]  nLength    Number of bytes of data to read from the register map
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Provides direct byte-level read access to the device register map.
+ *          The size and format of the register(s) must be known.
+ *
+ * @note Reads from special "keyhole" or "FIFO" registers will be handled
+ *       according to documentation for those registers.
+ */
+ADI_SENSE_RESULT adi_sense_ReadRegister(
+    ADI_SENSE_DEVICE_HANDLE    const hDevice,
+    uint16_t                   const nAddress,
+    void                     * const pData,
+    unsigned                   const nLength);
+
+/*!
+ * @brief Write one or more device registers at the specified register address.
+ *
+ * @param[in]  hDevice    ADI Sense device context handle
+ * @param[in]  nAddress   Register map address to read from
+ * @param[out] pData      Pointer to return the register map data
+ * @param[in]  nLength    Number of bytes of data to read from the register map
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Provides direct byte-level write access to the device register map.
+ *          The size and format of the register(s) must be known.
+ *
+ * @note Writes to read-only registers will be ignored by the device.
+ * @note Writes to special "keyhole" registers will be handled according to
+ *       documentation for those registers.
+ */
+ADI_SENSE_RESULT adi_sense_WriteRegister(
+    ADI_SENSE_DEVICE_HANDLE    const hDevice,
+    uint16_t                   const nAddress,
+    void                     * const pData,
+    unsigned                   const nLength);
+
+/*!
+ * @brief Update power configuration settings on the device.
+ *
+ * @param[in] hDevice      ADI Sense device context handle
+ * @param[in] pPowerConfig Power configuration details
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Translates configuration details provided into device-specific
+ *          register settings and updates device configuration registers.
+ *
+ * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
+ */
+ADI_SENSE_RESULT adi_sense_SetPowerConfig(
+    ADI_SENSE_DEVICE_HANDLE hDevice,
+    ADI_SENSE_POWER_CONFIG *pPowerConfig);
+
+/*!
+ * @brief Update measurement configuration settings on the device.
+ *
+ * @param[in] hDevice            ADI Sense device context handle
+ * @param[in] pMeasurementConfig Measurement configuration details
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Translates configuration details provided into device-specific
+ *          register settings and updates device configuration registers.
+ *
+ * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
+ */
+ADI_SENSE_RESULT adi_sense_SetMeasurementConfig(
+    ADI_SENSE_DEVICE_HANDLE hDevice,
+    ADI_SENSE_MEASUREMENT_CONFIG *pMeasurementConfig);
+
+/*!
+ * @brief Update diagnostics configuration settings on the device.
+ *
+ * @param[in] hDevice            ADI Sense device context handle
+ * @param[in] pDiagnosticsConfig Diagnostics configuration details
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Translates configuration details provided into device-specific
+ *          register settings and updates device configuration registers.
+ *
+ * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
+ */
+ADI_SENSE_RESULT adi_sense_SetDiagnosticsConfig(
+    ADI_SENSE_DEVICE_HANDLE hDevice,
+    ADI_SENSE_DIAGNOSTICS_CONFIG *pDiagnosticsConfig);
+
+/*!
+ * @brief Update channel configuration settings for a specific channel.
+ *
+ * @param[in] hDevice        ADI Sense device context handle
+ * @param[in] eChannelId     Selects the channel to be updated
+ * @param[in] pChannelConfig Channel configuration details
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Translates configuration details provided into device-specific
+ *          register settings and updates device configuration registers.
+ *          Allows individual channel configuration details to be dynamically
+ *          adjusted without rewriting the full device configuration.
+ *
+ * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
+ */
+ADI_SENSE_RESULT adi_sense_SetChannelConfig(
+    ADI_SENSE_DEVICE_HANDLE hDevice,
+    ADI_SENSE_CHANNEL_ID eChannelId,
+    ADI_SENSE_CHANNEL_CONFIG *pChannelConfig);
+
+/*!
+ * @brief Update number of measurements-per-cycle for a specific channel.
+ *
+ * @param[in] hDevice               ADI Sense device context handle
+ * @param[in] eChannelId            Selects the channel to be updated
+ * @param[in] nMeasurementsPerCycle Specifies the number of measurements to be
+ *                                  obtained from this channel in each
+ *                                  measurement cycle.  Set as 0 to disable the
+ *                                  channel (omit from measurement cycle).
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Translates configuration details provided into device-specific
+ *          register settings and updates device configuration registers.
+ *          Allows individual channels to be dynamically enabled/disabled, and
+ *          measurements-per-cycle to be adjusted.
+ *
+ * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
+ */
+ADI_SENSE_RESULT adi_sense_SetChannelCount(
+    ADI_SENSE_DEVICE_HANDLE hDevice,
+    ADI_SENSE_CHANNEL_ID eChannelId,
+    uint32_t nMeasurementsPerCycle);
+
+/*!
+ * @brief Update the measurement threshold limits for a specified channel.
+ *
+ * @param[in] hDevice            ADI Sense device context handle
+ * @param[in] eChannelId         Selects the channel to be updated
+ * @param[in] highThresholdLimit Optional maximum threshold value for each
+ *                               processed sample, to be checked prior to
+ *                               publishing.  A channel ALERT condition is
+ *                               raised if the processed value is higher than
+ *                               this threshold.  Set to NaN if not required.
+ * @param[in] lowThresholdLimit  Optional minimum threshold value for each
+ *                               processed sample, to be checked prior to
+ *                               publishing.  A channel ALERT condition is
+ *                               raised if the processed value is lower than
+ *                               this threshold.  Set to NaN if not required.
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Translates configuration details provided into device-specific
+ *          register settings and updates device configuration registers.
+ *          Allows individual channel thresholds to be dynamically adjusted.
+ *
+ * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
+ */
+ADI_SENSE_RESULT adi_sense_SetChannelThresholdLimits(
+    ADI_SENSE_DEVICE_HANDLE hDevice,
+    ADI_SENSE_CHANNEL_ID eChannelId,
+    float32_t highThresholdLimit,
+    float32_t lowThresholdLimit);
+
+/*!
+ * @brief Update the extra settling time for a specified channel.
+ *
+ * @param[in] hDevice      ADI Sense device context handle
+ * @param[in] eChannelId   Selects the channel to be updated
+ * @param[in] settlingTime A minimum settling time is applied internally for
+ *                         each channel, based on the sensor type.  However,
+ *                         additional settling time (microseconds) can
+ *                         optionally be specified here.  Set to 0 if not
+ *                         required.
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Translates configuration details provided into device-specific
+ *          register settings and updates device configuration registers.
+ *          Allows individual channel settling times to be dynamically adjusted.
+ *
+ * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
+ */
+ADI_SENSE_RESULT adi_sense_SetChannelSettlingTime(
+    ADI_SENSE_DEVICE_HANDLE hDevice,
+    ADI_SENSE_CHANNEL_ID eChannelId,
+    uint32_t settlingTime);
+
+/*!
+ * @brief Update configuration settings for a specific ADC analog channel.
+ *
+ * @param[in] hDevice           ADI Sense device context handle
+ * @param[in] eChannelId        Selects the channel to be updated
+ * @param[in] pAdcChannelConfig ADC analog channel configuration details
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Translates configuration details provided into device-specific
+ *          register settings and updates device configuration registers.
+ *          Allows individual channel configuration details to be dynamically
+ *          adjusted without rewriting the full device configuration.
+ *
+ * @note Applicable only to ADC analog sensor channels
+ * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
+ */
+ADI_SENSE_RESULT adi_sense_SetAdcChannelConfig(
+    ADI_SENSE_DEVICE_HANDLE hDevice,
+    ADI_SENSE_CHANNEL_ID eChannelId,
+    ADI_SENSE_CHANNEL_CONFIG *pAdcChannelConfig);
+
+/*!
+ * @brief Update configuration settings for a specific I2C digital channel.
+ *
+ * @param[in] hDevice           ADI Sense device context handle
+ * @param[in] eChannelId        Selects the channel to be updated
+ * @param[in] pI2cChannelConfig I2C digital channel configuration details
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Translates configuration details provided into device-specific
+ *          register settings and updates device configuration registers.
+ *          Allows individual channel configuration details to be dynamically
+ *          adjusted without rewriting the full device configuration.
+ *
+ * @note Applicable only to I2C digital sensor channels
+ * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
+ */
+ADI_SENSE_RESULT adi_sense_SetI2cChannelConfig(
+    ADI_SENSE_DEVICE_HANDLE hDevice,
+    ADI_SENSE_CHANNEL_ID eChannelId,
+    ADI_SENSE_I2C_CHANNEL_CONFIG *pI2cChannelConfig);
+
+
+/*!
+ * @brief Update configuration settings for a specific SPI digital channel.
+ *
+ * @param[in] hDevice           ADI Sense device context handle
+ * @param[in] eChannelId        Selects the channel to be updated
+ * @param[in] pSpiChannelConfig SPI digital channel configuration details
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Translates configuration details provided into device-specific
+ *          register settings and updates device configuration registers.
+ *          Allows individual channel configuration details to be dynamically
+ *          adjusted without rewriting the full device configuration.
+ *
+ * @note Applicable only to SPI digital sensor channels
+ * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
+ */
+ADI_SENSE_RESULT adi_sense_SetSpiChannelConfig(
+    ADI_SENSE_DEVICE_HANDLE hDevice,
+    ADI_SENSE_CHANNEL_ID eChannelId,
+    ADI_SENSE_SPI_CHANNEL_CONFIG *pSpiChannelConfig);
+
+/*!
+ * @brief Read the contents of the ADI Sense internal calibration table
+ *
+ * Calibration coefficients/gains/offsets are stored internally in a 2D table of
+ * 32-bit floating point values.  Refer to product documentation for details of
+ * the rows and columns.
+ *
+ * @param[in]  hDevice ADI Sense device context handle
+ * @param[in]  buffer  Pointer to destination buffer for the calibration data
+ * @param[in]  maxLen  The buffer capacity in bytes (e.g. 672 for 56x3 table)
+ * @param[out] dataLen The number of bytes written to the buffer
+ * @param[out] nRows   Pointer to return the number of table rows (e.g. 56)
+ * @param[out] nColums Pointer to return the number of table columns (e.g. 3)
+ *
+ * @return Status
+ *         - #ADI_SENSE_SUCCESS Call completed successfully.
+ *         - #ADI_SENSE_FAILURE
+ *         - #ADI_SENSE_INVALID_OPERATION Invalid register identifier.
+ */
+ADI_SENSE_RESULT adi_sense_ReadCalTable(
+    ADI_SENSE_DEVICE_HANDLE hDevice,
+    float *buffer,
+    unsigned maxLen,
+    unsigned *dataLen,
+    unsigned *nRows,
+    unsigned *nColumns);
+
+#ifdef __cplusplus
+}
+#endif
+
+/*!
+ * @}
+ */
+
+#endif /* __ADI_SENSE_API_H__ */
+