Rohan Gurav
/
Sean_AdiSense1000_V21
ADISense1000 Version 2.1 code base
Fork of AdiSense1000_V21 by
Diff: inc/adi_sense_api.h
- Revision:
- 7:4dbae381f693
diff -r ef0331efed74 -r 4dbae381f693 inc/adi_sense_api.h --- /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__ */ +