File content as of revision 7:4dbae381f693:

/*!
 ******************************************************************************
 * @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__ */