adi_sense_api.h

00001 /*
00002 Copyright 2017 (c) Analog Devices, Inc.
00003 
00004 All rights reserved.
00005 
00006 Redistribution and use in source and binary forms, with or without
00007 modification, are permitted provided that the following conditions are met:
00008   - Redistributions of source code must retain the above copyright
00009     notice, this list of conditions and the following disclaimer.
00010   - Redistributions in binary form must reproduce the above copyright
00011     notice, this list of conditions and the following disclaimer in
00012     the documentation and/or other materials provided with the
00013     distribution.
00014   - Neither the name of Analog Devices, Inc. nor the names of its
00015     contributors may be used to endorse or promote products derived
00016     from this software without specific prior written permission.
00017   - The use of this software may or may not infringe the patent rights
00018     of one or more patent holders. This license does not release you
00019     from the requirement that you obtain separate licenses from these
00020     patent holders to use this software.
00021   - Use of the software either in source or binary form, must be run
00022     on or directly connected to an Analog Devices Inc. component.
00023 
00024 THIS SOFTWARE IS PROVIDED BY ANALOG DEVICES "AS IS" AND ANY EXPRESS OR
00025 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, NON-INFRINGEMENT,
00026 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
00027 IN NO EVENT SHALL ANALOG DEVICES BE LIABLE FOR ANY DIRECT, INDIRECT,
00028 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
00029 LIMITED TO, INTELLECTUAL PROPERTY RIGHTS, PROCUREMENT OF SUBSTITUTE GOODS OR
00030 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00031 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
00032 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
00033 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00034 */
00035 
00036 /*!
00037  ******************************************************************************
00038  * @file:   adi_sense_api.h
00039  * @brief:  ADISENSE Host Library Application Programming Interface (API)
00040  *-----------------------------------------------------------------------------
00041  */
00042 
00043 #ifndef __ADI_SENSE_API_H__
00044 #define __ADI_SENSE_API_H__
00045 
00046 #include "inc/adi_sense_types.h"
00047 #include "inc/adi_sense_config_types.h"
00048 #include "inc/adi_sense_platform.h"
00049 #include "inc/adi_sense_gpio.h"
00050 #include "inc/adi_sense_spi.h"
00051 #include "inc/adi_sense_log.h"
00052 #include "inc/adi_sense_time.h"
00053 
00054 /*! @defgroup ADISENSE_Api ADISENSE Host Library API
00055  *  Host library API common to the ADISENSE product family.
00056  *  @{
00057  */
00058 
00059 #ifdef __cplusplus
00060 extern "C" {
00061 #endif
00062 
00063 /*! The maximum number of channels supported by this API
00064  * @note Specific ADISENSE products may implement a lower number of channels */
00065 #define ADI_SENSE_MAX_CHANNELS 16
00066 
00067 /*! A handle used in all API functions to identify the ADISENSE device. */
00068 typedef void* ADI_SENSE_DEVICE_HANDLE ;
00069 
00070 /*! Supported connection types for communication with the ADISENSE device. */
00071 typedef enum {
00072     ADI_SENSE_CONNECTION_TYPE_SPI  = 1,
00073     /*!< Serial Peripheral Interface (SPI) connection type */
00074 } ADI_SENSE_CONNECTION_TYPE ;
00075 
00076 /*! Connection details for communication with a ADISENSE device instance. */
00077 typedef struct {
00078     ADI_SENSE_CONNECTION_TYPE       type;
00079     /*!< Connection type selection */
00080     ADI_SENSE_PLATFORM_SPI_CONFIG  spi;
00081     /*!< SPI connection parameters, required if SPI connection type is used */
00082     ADI_SENSE_PLATFORM_GPIO_CONFIG gpio;
00083     /*!< GPIO connection parameters, for device reset and status I/O signals */
00084     ADI_SENSE_PLATFORM_LOG_CONFIG  log;
00085     /*!< Log interface connection parameters, for display/routing of log messages */
00086 } ADI_SENSE_CONNECTION ;
00087 
00088 /*! Bit masks (flags) for the different device status indicators. */
00089 typedef enum {
00090     ADI_SENSE_DEVICE_STATUS_BUSY          = (1 << 0),
00091     /*!< Indicates that a command is currently running on the device */
00092     ADI_SENSE_DEVICE_STATUS_DATAREADY     = (1 << 1),
00093     /*!< Indicates the availability of measurement data for retrieval */
00094     ADI_SENSE_DEVICE_STATUS_ERROR         = (1 << 2),
00095     /*!< Indicates that an error condition has been detected by the device */
00096     ADI_SENSE_DEVICE_STATUS_ALERT         = (1 << 3),
00097     /*!< Indicates that an alert condition has been detected by the device */
00098     ADI_SENSE_DEVICE_STATUS_FIFO_ERROR    = (1 << 4),
00099     /*!< Indicates that a FIFO error condition has been detected by the device */
00100     ADI_SENSE_DEVICE_STATUS_CONFIG_ERROR  = (1 << 5),
00101     /*!< Indicates that a configuration error condition has been detected by the device */
00102     ADI_SENSE_DEVICE_STATUS_LUT_ERROR     = (1 << 6),
00103     /*!< Indicates that a look-up table error condition has been detected by the device */
00104     ADI_SENSE_DEVICE_STATUS_EXT_FLASH_ERROR  = (1 << 7),
00105     /*!< Indicates that an external flash memory error condition has been detected by the device */
00106 } ADI_SENSE_DEVICE_STATUS_FLAGS ;
00107 
00108 /*! Bit masks (flags) for the different diagnostics status indicators. */
00109 typedef enum {
00110     ADI_SENSE_DIAGNOSTICS_STATUS_CHECKSUM_ERROR        = (1 << 0),
00111     /*!< Indicates Error on Internal Checksum Calculations */
00112     ADI_SENSE_DIAGNOSTICS_STATUS_COMMS_ERROR           = (1 << 1),
00113     /*!< Indicates Error on Internal Device Communications */
00114     ADI_SENSE_DIAGNOSTICS_STATUS_SUPPLY_MONITOR_ERROR  = (1 << 2),
00115     /*!< Indicates Low Voltage on Internal Supply Voltages */
00116     ADI_SENSE_DIAGNOSTICS_STATUS_SUPPLY_CAP_ERROR      = (1 << 3),
00117     /*!< Indicates Fault on Internal Supply Regulator Capacitor */
00118     ADI_SENSE_DIAGNOSTICS_STATUS_CONVERSION_ERROR      = (1 << 8),
00119     /*!< Indicates Error During Internal ADC Conversions */
00120     ADI_SENSE_DIAGNOSTICS_STATUS_CALIBRATION_ERROR     = (1 << 9),
00121     /*!< Indicates Error During Internal Device Calibrations */
00122 } ADI_SENSE_DIAGNOSTICS_STATUS_FLAGS ;
00123 
00124 /*! Bit masks (flags) for the different channel alert indicators. */
00125 typedef enum {
00126     ADI_SENSE_CHANNEL_ALERT_TIMEOUT           = (1 << 0),
00127     /*!< Indicates timeout condition detected on the channel */
00128     ADI_SENSE_CHANNEL_ALERT_UNDER_RANGE       = (1 << 1),
00129     /*!< Indicates raw sample under valid input range, possibly clamped */
00130     ADI_SENSE_CHANNEL_ALERT_OVER_RANGE        = (1 << 2),
00131     /*!< Indicates raw sample over valid input range, possibly clamped */
00132     ADI_SENSE_CHANNEL_ALERT_LOW_LIMIT         = (1 << 3),
00133     /*!< Indicates measurement result was below configured minimum threshold */
00134     ADI_SENSE_CHANNEL_ALERT_HIGH_LIMIT        = (1 << 4),
00135     /*!< Indicates measurement result was above configured maximum threshold */
00136     ADI_SENSE_CHANNEL_ALERT_SENSOR_OPEN       = (1 << 5),
00137     /*!< Indicates open circuit or mis-wire condition detected on the channel */
00138     ADI_SENSE_CHANNEL_ALERT_REF_DETECT        = (1 << 6),
00139     /*!< Indicates reference-detect error condition detected on the channel */
00140     ADI_SENSE_CHANNEL_ALERT_CONFIG_ERR        = (1 << 7),
00141     /*!< Indicates configuration error condition detected on the channel */
00142     ADI_SENSE_CHANNEL_ALERT_LUT_ERR           = (1 << 8),
00143     /*!< Indicates look-up table error condition detected on the channel */
00144     ADI_SENSE_CHANNEL_ALERT_SENSOR_NOT_READY  = (1 << 9),
00145     /*!< Indicates digital sensor not-ready error condition detected on the channel */
00146     ADI_SENSE_CHANNEL_ALERT_COMP_NOT_READY    = (1 << 10),
00147     /*!< Indicates compensation channel not-ready error condition detected on the channel */
00148     ADI_SENSE_CHANNEL_ALERT_LUT_UNDER_RANGE   = (1 << 13),
00149     /*!< Indicates raw sample was under the available LUT/equation range */
00150     ADI_SENSE_CHANNEL_ALERT_LUT_OVER_RANGE    = (1 << 14),
00151     /*!< Indicates raw sample was over the available LUT/equation range */
00152 } ADI_SENSE_CHANNEL_ALERT_FLAGS ;
00153 
00154 /*! Status details retreived from the ADISENSE device. */
00155 typedef struct {
00156     ADI_SENSE_DEVICE_STATUS_FLAGS       deviceStatus;
00157     /*!< General summary status information from the device  */
00158     ADI_SENSE_DIAGNOSTICS_STATUS_FLAGS  diagnosticsStatus;
00159     /*!< Diagnostic error status information from the device  */
00160     ADI_SENSE_CHANNEL_ALERT_FLAGS       channelAlerts[ADI_SENSE_MAX_CHANNELS];
00161     /*!< Per-channel alert status information from the device  */
00162     uint32_t                           errorCode;
00163     /*!< Code identifying the last error signalled by the device  */
00164     uint32_t                           alertCode;
00165     /*!< Code identifying the last alert signalled by the device  */
00166     uint32_t                           channelAlertCodes[ADI_SENSE_MAX_CHANNELS];
00167     /*!< Per-channel code identifying the last alert signalled for each channel */
00168 } ADI_SENSE_STATUS ;
00169 
00170 /*! Data sample details retreived from the ADISENSE device. */
00171 typedef struct {
00172     ADI_SENSE_DEVICE_STATUS_FLAGS       status;
00173     /*!< Device summary status snapshot when the sample was recorded */
00174     uint32_t                           channelId;
00175     /*!< The measurement channel from which this sample was obtained */
00176     uint32_t                           rawValue;
00177     /*!< The raw (unprocessed) value obtained directly from the measurement
00178      *   channel, if available
00179      */
00180     float32_t                          processedValue;
00181     /*!< The processed value obtained from the measurement channel, as a final
00182      *   measurement value, following calibration and linearisation correction,
00183      *   and conversion into an appropriate unit of measurement.
00184      */
00185 } ADI_SENSE_DATA_SAMPLE ;
00186 
00187 /*! Measurement mode options for the ADISENSE device.
00188  *  @ref adi_sense_StartMeasurement
00189  */
00190 typedef enum {
00191     ADI_SENSE_MEASUREMENT_MODE_HEALTHCHECK  = 1,
00192     /*!< In this mode, a special health-check measurement cycle is executed,
00193      *   carrying out a single conversion per channel with measurement
00194      *   diagnostics enabled, intended for use as a system health check. */
00195     ADI_SENSE_MEASUREMENT_MODE_NORMAL ,
00196     /*!< In this mode, normal measurement cycle(s) are executed and data samples
00197      *   are returned with raw measurement values included. */
00198     ADI_SENSE_MEASUREMENT_MODE_OMIT_RAW ,
00199     /*!< In this mode, normal measurement cycle(s) are executed and data samples
00200      *   are returned with raw measurement values omitted for efficiency. */
00201     ADI_SENSE_MEASUREMENT_MODE_FFT ,
00202     /*!< In this mode, FFT mode measurement cycle(s) are executed and data
00203      *   samples are returned based on FFT-specific configuration parameters. */
00204 } ADI_SENSE_MEASUREMENT_MODE ;
00205 
00206 /*! Identifiers for the user configuration slots in persistent memory. */
00207 typedef enum {
00208     ADI_SENSE_FLASH_CONFIG_1,
00209     ADI_SENSE_FLASH_CONFIG_2,
00210     ADI_SENSE_FLASH_CONFIG_3,
00211     ADI_SENSE_FLASH_CONFIG_4,
00212 } ADI_SENSE_USER_CONFIG_SLOT ;
00213 
00214 
00215 /******************************************************************************
00216  * ADISENSE High-Level API function prototypes
00217  *****************************************************************************/
00218 
00219 /*!
00220  * @brief Open ADISENSE device handle and set up communication interface.
00221  *
00222  * @param[in]  nDeviceIndex    Zero-based index number identifying this device
00223  *                             instance.  Note that this will be used to
00224  *                             retrieve a specific device configuration for
00225  *                             this device (see @ref adi_sense_SetConfig
00226  *                             and @ref ADI_SENSE_CONFIG)
00227  * @param[in]  pConnectionInfo Host-specific connection details (e.g. SPI, GPIO)
00228  * @param[out] phDevice        Pointer to return an ADISENSE device handle
00229  *
00230  * @return Status
00231  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00232  *         - #ADI_SENSE_NO_MEM  Failed to allocate memory resources.
00233  *         - #ADI_SENSE_INVALID_DEVICE_NUM Invalid device index specified
00234  *
00235  * @details Configure and initialise the Log interface and the SPI/GPIO
00236  *          communication interface to the ADISense module.
00237  */
00238 ADI_SENSE_RESULT  adi_sense_Open(
00239     unsigned                   const nDeviceIndex,
00240     ADI_SENSE_CONNECTION      * const pConnectionInfo,
00241     ADI_SENSE_DEVICE_HANDLE  * const phDevice);
00242 
00243 /*!
00244  * @brief Close ADISENSE device context and free resources.
00245  *
00246  * @param[in] hDevice ADISENSE device context handle
00247  *
00248  * @return Status
00249  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00250  */
00251 ADI_SENSE_RESULT  adi_sense_Close(
00252     ADI_SENSE_DEVICE_HANDLE    const hDevice);
00253 
00254 /*!
00255  * @brief Get the current state of the specified GPIO input signal.
00256  *
00257  * @param[in]  hDevice    ADISENSE device context handle
00258  * @param[in]  ePinId     GPIO pin to query
00259  * @param[out] pbAsserted Pointer to return the state of the status signal GPIO pin
00260  *
00261  * @return Status
00262  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00263  *         - #ADI_SENSE_INVALID_DEVICE_NUM Invalid GPIO pin specified.
00264  *
00265  * @details Sets *pbAsserted to true if the status signal is asserted, or false
00266  *          otherwise.
00267  */
00268 ADI_SENSE_RESULT  adi_sense_GetGpioState(
00269     ADI_SENSE_DEVICE_HANDLE   const hDevice,
00270     ADI_SENSE_GPIO_PIN         const ePinId,
00271     bool_t                  * const pbAsserted);
00272 
00273 /*!
00274  * @brief Register an application-defined callback function for GPIO interrupts
00275  *
00276  * @param[in] hDevice          ADISENSE context handle (@ref adi_sense_Open)
00277  * @param[in] ePinId           GPIO pin on which to enable/disable interrupts
00278  * @param[in] callbackFunction Function to be called when an interrupt occurs.
00279  *                             Specify NULL here to disable interrupts.
00280  * @param[in] pCallbackParam   Optional opaque parameter passed to the callback
00281  *
00282  * @return Status
00283  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00284  *         - #ADI_SENSE_INVALID_DEVICE_NUM Invalid GPIO pin specified.
00285  */
00286 ADI_SENSE_RESULT  adi_sense_RegisterGpioCallback(
00287     ADI_SENSE_DEVICE_HANDLE          const hDevice,
00288     ADI_SENSE_GPIO_PIN                const ePinId,
00289     ADI_SENSE_GPIO_CALLBACK           const callbackFunction,
00290     void                           * const pCallbackParam);
00291 
00292 /*!
00293  * @brief Trigger a shut down of the device.
00294  *
00295  * @param[in] hDevice ADISENSE device context handle
00296  *
00297  * @return Status
00298  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00299  *
00300  * @details Instructs the ADISENSE device to initiate a shut down,
00301  *          typically used to conserve power when the device is not
00302  *          in use.  The device may be restarted by calling
00303  *          @ref adi_sense_Reset().  Note that active configuration
00304  *          settings are not preserved during shutdown and must be
00305  *          reloaded after the device has become ready again.
00306  *
00307  * @note No other command must be running when this is called.
00308  */
00309 ADI_SENSE_RESULT  adi_sense_Shutdown(
00310     ADI_SENSE_DEVICE_HANDLE    const hDevice);
00311 
00312 /*!
00313  * @brief Reset the ADISENSE device.
00314  *
00315  * @param[in] hDevice ADISENSE device context handle
00316  *
00317  * @return Status
00318  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00319  *
00320  * @details Trigger a hardware-reset of the ADISENSE device.
00321  *
00322  * @note The device may require several seconds before it is ready for use
00323  *       again. @ref adi_sense_GetDeviceReadyState may be used to check if
00324  *       the device is ready.
00325  */
00326 ADI_SENSE_RESULT  adi_sense_Reset(
00327     ADI_SENSE_DEVICE_HANDLE    const hDevice);
00328 
00329 /*!
00330  * @brief Check if the device is ready, following power-up or a reset.
00331  *
00332  * @param[in]  hDevice ADISENSE device context handle
00333  * @param[out] pbReady Pointer to return true if the device is ready, or false
00334  *                     otherwise
00335  *
00336  * @return Status
00337  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00338  *
00339  * @details This function attempts to read a fixed-value device register via
00340  *           the communication interface.
00341  */
00342 ADI_SENSE_RESULT  adi_sense_GetDeviceReadyState(
00343     ADI_SENSE_DEVICE_HANDLE    const hDevice,
00344     bool_t                   * const pbReady);
00345 
00346 /*!
00347  * @brief Obtain the product ID from the device.
00348  *
00349  * @param[in]  hDevice    ADISENSE device context handle
00350  * @param[out] pProductId Pointer to return the product ID value
00351  *
00352  * @return Status
00353  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00354  *
00355  * @details Reads the product ID registers on the device and returns the value.
00356  */
00357 ADI_SENSE_RESULT  adi_sense_GetProductID(
00358     ADI_SENSE_DEVICE_HANDLE    const hDevice,
00359     ADI_SENSE_PRODUCT_ID      * const pProductId);
00360 
00361 /*!
00362  * @brief Write full configuration settings to the device registers.
00363  *
00364  * @param[in]  hDevice ADISENSE device context handle
00365  * @param[out] pConfig Pointer to the configuration data structure
00366  *
00367  * @return Status
00368  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00369  *
00370  * @details Translates configuration details provided into device-specific
00371  *          register settings and updates device configuration registers.
00372  *
00373  * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
00374  */
00375 ADI_SENSE_RESULT  adi_sense_SetConfig(
00376     ADI_SENSE_DEVICE_HANDLE   const hDevice,
00377     ADI_SENSE_CONFIG         * const pConfig);
00378 
00379 /*!
00380  * @brief Apply the configuration settings currently stored in device registers
00381  *
00382  * @param[in] hDevice ADISENSE device context handle
00383  *
00384  * @return Status
00385  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00386  *
00387  * @details Instructs the ADISENSE device to reload and apply configuration
00388  *          from the device configuration registers.  Changes to configuration
00389  *          registers are ignored by the device until this function is called.
00390  *
00391  * @note No other command must be running when this is called.
00392  */
00393 ADI_SENSE_RESULT  adi_sense_ApplyConfigUpdates(
00394     ADI_SENSE_DEVICE_HANDLE    const hDevice);
00395 
00396 /*!
00397  * @brief Store the configuration settings to persistent memory on the device.
00398  *
00399  * @param[in] hDevice ADISENSE device context handle
00400  * @param[in] eSlotId User configuration slot in persistent memory
00401  *
00402  * @return Status
00403  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00404  *
00405  * @details Instructs the ADISENSE device to save the current contents of its
00406  *          device configuration registers to non-volatile memory.
00407  *
00408  * @note No other command must be running when this is called.
00409  * @note Do not power down the device while this command is running.
00410  */
00411 ADI_SENSE_RESULT  adi_sense_SaveConfig(
00412     ADI_SENSE_DEVICE_HANDLE    const hDevice,
00413     ADI_SENSE_USER_CONFIG_SLOT  const eSlotId);
00414 
00415 /*!
00416  * @brief Restore configuration settings from persistent memory on the device.
00417  *
00418  * @param[in] hDevice ADISENSE device context handle
00419  * @param[in] eSlotId User configuration slot in persistent memory
00420  *
00421  * @return Status
00422  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00423  *
00424  * @details Instructs the ADISENSE device to restore the contents of its
00425  *          device configuration registers from non-volatile memory.
00426  *
00427  * @note No other command must be running when this is called.
00428  */
00429 ADI_SENSE_RESULT  adi_sense_RestoreConfig(
00430     ADI_SENSE_DEVICE_HANDLE    const hDevice,
00431     ADI_SENSE_USER_CONFIG_SLOT  const eSlotId);
00432 
00433 /*!
00434  * @brief Erases the external flash memory.
00435  *
00436  * @param[in] hDevice ADISENSE device context handle
00437  *
00438  * @return Status
00439  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00440  *
00441  * @details Sends the bulk erase instruction to the external flash
00442  *          device. All stored samples are deleted.
00443  *          It is a blocking operation and takes tens of seconds to
00444  *          complete.
00445  *
00446  * @note No other command must be running when this is called.
00447  */
00448 ADI_SENSE_RESULT  adi_sense_EraseExternalFlash(
00449     ADI_SENSE_DEVICE_HANDLE    const hDevice);
00450 
00451 /*!
00452  * @brief Gets the number of samples stored in the external flash
00453  *        memory.
00454  *
00455  * @param[in] hDevice ADISENSE device context handle
00456  * @param[in] pSampleCount Address of the return value.
00457  *
00458  * @return Status
00459  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00460  *
00461  * @note No other command must be running when this is called.
00462  */
00463 ADI_SENSE_RESULT  adi_sense_GetExternalFlashSampleCount(
00464     ADI_SENSE_DEVICE_HANDLE    const hDevice,
00465     uint32_t * nSampleCount);
00466 
00467 // DEBUG - TO BE DELETED
00468 ADI_SENSE_RESULT  adi_sense_SetExternalFlashIndex(
00469     ADI_SENSE_DEVICE_HANDLE    const hDevice,
00470     uint32_t nStartIndex);
00471 
00472 /*!
00473  * @brief Read measurement samples stored in the the external flash memory.
00474  *
00475  * @param[in]  hDevice          ADISENSE device context handle
00476  * @param[out] pSamples         Pointer to return a set of requested data
00477  *                              samples.
00478  * @param[in]  nStartIndex      Index of first sample to retrieve.
00479  * @param[in]  nBytesPerSample  The size, in bytes, of each sample.
00480  * @param[in]  nRequested       Number of requested data samples.
00481  * @param[out] pnReturned       Number of valid data samples successfully
00482  *                              retrieved.
00483  *
00484  * @return Status
00485  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00486  *
00487  * @details Reads the status registers and extracts the relevant information
00488  *          to return to the caller.
00489  *
00490  */
00491 ADI_SENSE_RESULT  adi_sense_GetExternalFlashData(
00492     ADI_SENSE_DEVICE_HANDLE    const hDevice,
00493     ADI_SENSE_DATA_SAMPLE     * const pSamples,
00494     uint32_t                   const nIndex,
00495     uint32_t                   const nRequested,
00496     uint32_t                 * const pnReturned);
00497 
00498 /*!
00499  * @brief Store the LUT data to persistent memory on the device.
00500  *
00501  * @param[in] hDevice ADISENSE device context handle
00502  *
00503  * @return Status
00504  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00505  *
00506  * @details Instructs the ADISENSE device to save the current contents of its
00507  *          LUT data buffer, set using @ref adi_sense_SetLutData, to
00508  *          non-volatile memory.
00509  *
00510  * @note No other command must be running when this is called.
00511  * @note Do not power down the device while this command is running.
00512  */
00513 ADI_SENSE_RESULT  adi_sense_SaveLutData(
00514     ADI_SENSE_DEVICE_HANDLE    const hDevice);
00515 
00516 /*!
00517  * @brief Restore LUT data from persistent memory on the device.
00518  *
00519  * @param[in] hDevice ADISENSE device context handle
00520  *
00521  * @return Status
00522  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00523  *
00524  * @details Instructs the ADISENSE device to restore the contents of its
00525  *          LUT data, previously stored with @ref adi_sense_SaveLutData, from
00526  *          non-volatile memory.
00527  *
00528  * @note No other command must be running when this is called.
00529  */
00530 ADI_SENSE_RESULT  adi_sense_RestoreLutData(
00531     ADI_SENSE_DEVICE_HANDLE    const hDevice);
00532 
00533 /*!
00534  * @brief Start the measurement cycles on the device.
00535  *
00536  * @param[in] hDevice          ADISENSE device context handle
00537  * @param[in] eMeasurementMode Allows a choice of special modes for the
00538  *                             measurement.  See @ref ADI_SENSE_MEASUREMENT_MODE
00539  *                             for further information.
00540  *
00541  * @return Status
00542  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00543  *
00544  * @details Instructs the ADISENSE device to start executing measurement cycles
00545  *          according to the current applied configuration settings.  The
00546  *          DATAREADY status signal will be asserted whenever new measurement
00547  *          data is published, according to selected settings.
00548  *          Measurement cycles may be stopped by calling @ref
00549  *          adi_sense_StopMeasurement.
00550  *
00551  * @note No other command must be running when this is called.
00552  */
00553 ADI_SENSE_RESULT  adi_sense_StartMeasurement(
00554     ADI_SENSE_DEVICE_HANDLE    const hDevice,
00555     ADI_SENSE_MEASUREMENT_MODE  const eMeasurementMode);
00556 
00557 /*!
00558  * @brief Stop the measurement cycles on the device.
00559  *
00560  * @param[in] hDevice ADISENSE device context handle
00561  *
00562  * @return Status
00563  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00564  *
00565  * @details Instructs the ADISENSE device to stop executing measurement cycles.
00566  *          The command may be delayed until the current conversion, if any, has
00567  *          been completed and published.
00568  *
00569  * @note To be used only if a measurement command is currently running.
00570  */
00571 ADI_SENSE_RESULT  adi_sense_StopMeasurement(
00572     ADI_SENSE_DEVICE_HANDLE    const hDevice);
00573 
00574 /*!
00575  * @brief Run built-in diagnostic checks on the device.
00576  *
00577  * @param[in] hDevice ADISENSE device context handle
00578  *
00579  * @return Status
00580  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00581  *
00582  * @details Instructs the ADISENSE device to execute its built-in diagnostic
00583  *          tests, on any enabled measurement channels, according to the current
00584  *          applied configuration settings.  Device status registers will be
00585  *          updated to indicate if any errors were detected by the diagnostics.
00586  *
00587  * @note No other command must be running when this is called.
00588  */
00589 ADI_SENSE_RESULT  adi_sense_RunDiagnostics(
00590     ADI_SENSE_DEVICE_HANDLE    const hDevice);
00591 
00592 /*!
00593  * @brief Run built-in calibration on the device.
00594  *
00595  * @param[in] hDevice ADISENSE device context handle
00596  *
00597  * @return Status
00598  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00599  *
00600  * @details Instructs the ADISENSE device to execute its self-calibration
00601  *          routines, on any enabled measurement channels, according to the
00602  *          current applied configuration settings.  Device status registers
00603  *          will be updated to indicate if any errors were detected.
00604  *
00605  * @note No other command must be running when this is called.
00606  */
00607 ADI_SENSE_RESULT  adi_sense_RunCalibration(
00608     ADI_SENSE_DEVICE_HANDLE    const hDevice);
00609 
00610 /*!
00611  * @brief Run built-in digital calibration on the device.
00612  *
00613  * @param[in] hDevice ADISENSE device context handle
00614  *
00615  * @return Status
00616  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00617  *
00618  * @details Instructs the ADISENSE device to execute its calibration
00619  *          routines, on any enabled digital channels, according to the
00620  *          current applied configuration settings.  Device status registers
00621  *          will be updated to indicate if any errors were detected.
00622  *
00623  * @note No other command must be running when this is called.
00624  */
00625 ADI_SENSE_RESULT  adi_sense_RunDigitalCalibration(
00626     ADI_SENSE_DEVICE_HANDLE    const hDevice);
00627 
00628 /*!
00629  * @brief Read the current status from the device registers.
00630  *
00631  * @param[in]  hDevice ADISENSE device context handle
00632  * @param[out] pStatus Pointer to return the status summary obtained from the
00633  *                     device.
00634  *
00635  * @return Status
00636  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00637  *
00638  * @details Reads the status registers and extracts the relevant information
00639  *          to return to the caller.
00640  *
00641  * @note This may be called at any time, assuming the device is ready.
00642  */
00643 ADI_SENSE_RESULT  adi_sense_GetStatus(
00644     ADI_SENSE_DEVICE_HANDLE    const hDevice,
00645     ADI_SENSE_STATUS          * const pStatus);
00646 
00647 /*!
00648  * @brief Read measurement data samples from the device registers.
00649  *
00650  * @param[in]  hDevice          ADISENSE device context handle
00651  * @param[in]  eMeasurementMode Must be set to the same value used for @ref
00652  *                              adi_sense_StartMeasurement().
00653  * @param[out] pSamples         Pointer to return a set of requested data samples.
00654  * @param[in]  nBytesPerSample  The size, in bytes, of each sample.
00655  * @param[in]  nRequested       Number of requested data samples.
00656  * @param[out] pnReturned       Number of valid data samples successfully retrieved.
00657  *
00658  * @return Status
00659  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00660  *
00661  * @details Reads the status registers and extracts the relevant information
00662  *          to return to the caller.
00663  *
00664  * @note This is intended to be called only when the DATAREADY status signal
00665  *       is asserted.
00666  */
00667 ADI_SENSE_RESULT  adi_sense_GetData(
00668     ADI_SENSE_DEVICE_HANDLE    const hDevice,
00669     ADI_SENSE_MEASUREMENT_MODE  const eMeasurementMode,
00670     ADI_SENSE_DATA_SAMPLE     * const pSamples,
00671     uint8_t                    const nBytesPerSample,
00672     uint32_t                   const nRequested,
00673     uint32_t                 * const pnReturned);
00674 
00675 /*!
00676  * @brief Check if a command is currently running on the device.
00677  *
00678  * @param[in]  hDevice          ADISENSE device context handle
00679  * @param[out] pbCommandRunning Pointer to return the command running status
00680  *
00681  * @return Status
00682  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00683  *
00684  * @details Reads the device status register to check if a command is running.
00685  */
00686 ADI_SENSE_RESULT  adi_sense_GetCommandRunningState(
00687     ADI_SENSE_DEVICE_HANDLE hDevice,
00688     bool_t *pbCommandRunning);
00689 
00690 #ifdef __cplusplus
00691 }
00692 #endif
00693 
00694 /*!
00695  * @}
00696  */
00697 
00698 #endif /* __ADI_SENSE_API_H__ */