adi_sense_1000_api.h

00001 /*
00002 CONFIDENTIAL AND PROPRIETARY INFORMATION
00003 
00004 Copyright (c) 2018 Emutex Ltd. All rights reserved.
00005 This software and documentation contain confidential and
00006 proprietary information that is the property of
00007 Emutex Ltd. The software and documentation are
00008 furnished under a license agreement and may be used
00009 or copied only in accordance with the terms of the license
00010 agreement. No part of the software and documentation
00011 may be reproduced, transmitted, or translated, in any
00012 form or by any means, electronic, mechanical, manual,
00013 optical, or otherwise, without prior written permission
00014 of Emutex Ltd., or as expressly provided by the license agreement.
00015 Reverse engineering is prohibited, and reproduction,
00016 disclosure or use without specific written authorization
00017 of Emutex Ltd. is strictly forbidden.
00018  */
00019 
00020 /*
00021 Copyright 2017 (c) Analog Devices, Inc.
00022 
00023 All rights reserved.
00024 
00025 Redistribution and use in source and binary forms, with or without
00026 modification, are permitted provided that the following conditions are met:
00027   - Redistributions of source code must retain the above copyright
00028     notice, this list of conditions and the following disclaimer.
00029   - Redistributions in binary form must reproduce the above copyright
00030     notice, this list of conditions and the following disclaimer in
00031     the documentation and/or other materials provided with the
00032     distribution.
00033   - Neither the name of Analog Devices, Inc. nor the names of its
00034     contributors may be used to endorse or promote products derived
00035     from this software without specific prior written permission.
00036   - The use of this software may or may not infringe the patent rights
00037     of one or more patent holders. This license does not release you
00038     from the requirement that you obtain separate licenses from these
00039     patent holders to use this software.
00040   - Use of the software either in source or binary form, must be run
00041     on or directly connected to an Analog Devices Inc. component.
00042 
00043 THIS SOFTWARE IS PROVIDED BY ANALOG DEVICES "AS IS" AND ANY EXPRESS OR
00044 IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, NON-INFRINGEMENT,
00045 MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
00046 IN NO EVENT SHALL ANALOG DEVICES BE LIABLE FOR ANY DIRECT, INDIRECT,
00047 INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
00048 LIMITED TO, INTELLECTUAL PROPERTY RIGHTS, PROCUREMENT OF SUBSTITUTE GOODS OR
00049 SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00050 CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
00051 OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
00052 OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00053 */
00054 
00055 /*!
00056  ******************************************************************************
00057  * @file:   adi_sense_api.h
00058  * @brief:  ADSNS1000 Host Library Application Programming Interface (API)
00059  *-----------------------------------------------------------------------------
00060  */
00061 
00062 #ifndef __ADI_SENSE_1000_API_H__
00063 #define __ADI_SENSE_1000_API_H__
00064 
00065 #include "inc/adi_sense_types.h"
00066 #include "inc/adi_sense_config_types.h"
00067 #include "inc/adi_sense_platform.h"
00068 #include "adi_sense_1000_config.h"
00069 #include "adi_sense_1000_lut_data.h"
00070 
00071 /*! @ingroup ADISENSE_Api */
00072 
00073 /*! @defgroup ADSNS1000_Api ADSNS1000 Host Library API
00074  *  ADSNS1000 device-specific API function prototypes.
00075  *  These are supplementary to the common ADISENSE Host Library API.
00076  *  @{
00077  */
00078 
00079 #ifdef __cplusplus
00080 extern "C" {
00081 #endif
00082 
00083 /*!
00084  * @brief Read one or more device registers at the specified register address.
00085  *
00086  * @param[in]  hDevice    ADISENSE device context handle
00087  * @param[in]  nAddress   Register map address to read from
00088  * @param[out] pData      Pointer to return the register map data
00089  * @param[in]  nLength    Number of bytes of data to read from the register map
00090  *
00091  * @return Status
00092  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00093  *
00094  * @details Provides direct byte-level read access to the device register map.
00095  *          The size and format of the register(s) must be known.
00096  *
00097  * @note Reads from special "keyhole" or "FIFO" registers will be handled
00098  *       according to documentation for those registers.
00099  */
00100 ADI_SENSE_RESULT  adi_sense_1000_ReadRegister(
00101     ADI_SENSE_DEVICE_HANDLE     const hDevice,
00102     uint16_t                   const nAddress,
00103     void                     * const pData,
00104     unsigned                   const nLength);
00105 
00106 /*!
00107  * @brief Write one or more device registers at the specified register address.
00108  *
00109  * @param[in]  hDevice    ADISENSE device context handle
00110  * @param[in]  nAddress   Register map address to read from
00111  * @param[out] pData      Pointer to return the register map data
00112  * @param[in]  nLength    Number of bytes of data to read from the register map
00113  *
00114  * @return Status
00115  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00116  *
00117  * @details Provides direct byte-level write access to the device register map.
00118  *          The size and format of the register(s) must be known.
00119  *
00120  * @note Writes to read-only registers will be ignored by the device.
00121  * @note Writes to special "keyhole" registers will be handled according to
00122  *       documentation for those registers.
00123  */
00124 ADI_SENSE_RESULT  adi_sense_1000_WriteRegister(
00125     ADI_SENSE_DEVICE_HANDLE     const hDevice,
00126     uint16_t                   const nAddress,
00127     void                     * const pData,
00128     unsigned                   const nLength);
00129 
00130 /*!
00131  * @brief Update power configuration settings on the device.
00132  *
00133  * @param[in] hDevice      ADISENSE device context handle
00134  * @param[in] pPowerConfig Power configuration details
00135  *
00136  * @return Status
00137  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00138  *
00139  * @details Translates configuration details provided into device-specific
00140  *          register settings and updates device configuration registers.
00141  *
00142  * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
00143  */
00144 ADI_SENSE_RESULT  adi_sense_1000_SetPowerConfig(
00145     ADI_SENSE_DEVICE_HANDLE  hDevice,
00146     ADI_SENSE_1000_POWER_CONFIG  *pPowerConfig);
00147 
00148 /*!
00149  * @brief Update measurement configuration settings on the device.
00150  *
00151  * @param[in] hDevice            ADISENSE device context handle
00152  * @param[in] pMeasurementConfig Measurement configuration details
00153  *
00154  * @return Status
00155  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00156  *
00157  * @details Translates configuration details provided into device-specific
00158  *          register settings and updates device configuration registers.
00159  *
00160  * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
00161  */
00162 ADI_SENSE_RESULT  adi_sense_1000_SetMeasurementConfig(
00163     ADI_SENSE_DEVICE_HANDLE  hDevice,
00164     ADI_SENSE_1000_MEASUREMENT_CONFIG  *pMeasurementConfig);
00165 
00166 /*!
00167  * @brief Update diagnostics configuration settings on the device.
00168  *
00169  * @param[in] hDevice            ADISENSE device context handle
00170  * @param[in] pDiagnosticsConfig Diagnostics configuration details
00171  *
00172  * @return Status
00173  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00174  *
00175  * @details Translates configuration details provided into device-specific
00176  *          register settings and updates device configuration registers.
00177  *
00178  * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
00179  */
00180 ADI_SENSE_RESULT  adi_sense_1000_SetDiagnosticsConfig(
00181     ADI_SENSE_DEVICE_HANDLE  hDevice,
00182     ADI_SENSE_1000_DIAGNOSTICS_CONFIG  *pDiagnosticsConfig);
00183 
00184 /*!
00185  * @brief Update channel configuration settings for a specific channel.
00186  *
00187  * @param[in] hDevice        ADISENSE device context handle
00188  * @param[in] eChannelId     Selects the channel to be updated
00189  * @param[in] pChannelConfig Channel configuration details
00190  *
00191  * @return Status
00192  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00193  *
00194  * @details Translates configuration details provided into device-specific
00195  *          register settings and updates device configuration registers.
00196  *          Allows individual channel configuration details to be dynamically
00197  *          adjusted without rewriting the full device configuration.
00198  *
00199  * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
00200  */
00201 ADI_SENSE_RESULT  adi_sense_1000_SetChannelConfig(
00202     ADI_SENSE_DEVICE_HANDLE  hDevice,
00203     ADI_SENSE_1000_CHANNEL_ID  eChannelId,
00204     ADI_SENSE_1000_CHANNEL_CONFIG  *pChannelConfig);
00205 
00206 /*!
00207  * @brief Update number of measurements-per-cycle for a specific channel.
00208  *
00209  * @param[in] hDevice               ADISENSE device context handle
00210  * @param[in] eChannelId            Selects the channel to be updated
00211  * @param[in] nMeasurementsPerCycle Specifies the number of measurements to be
00212  *                                  obtained from this channel in each
00213  *                                  measurement cycle.  Set as 0 to disable the
00214  *                                  channel (omit from measurement cycle).
00215  *
00216  * @return Status
00217  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00218  *
00219  * @details Translates configuration details provided into device-specific
00220  *          register settings and updates device configuration registers.
00221  *          Allows individual channels to be dynamically enabled/disabled, and
00222  *          measurements-per-cycle to be adjusted.
00223  *
00224  * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
00225  */
00226 ADI_SENSE_RESULT  adi_sense_1000_SetChannelCount(
00227     ADI_SENSE_DEVICE_HANDLE  hDevice,
00228     ADI_SENSE_1000_CHANNEL_ID  eChannelId,
00229     uint32_t nMeasurementsPerCycle);
00230 
00231 /*!
00232  * @brief Update priority level for a specific channel.
00233  *
00234  * @param[in] hDevice    ADI Sense device context handle
00235  * @param[in] eChannelId Selects the channel to be updated
00236  * @param[in] ePriority  Specifies the channel priority level
00237  *
00238  * @return Status
00239  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00240  *
00241  * @details Translates configuration details provided into device-specific
00242  *          register settings and updates device configuration registers.
00243  *          Allows individual channels to be dynamically re-prioritised.
00244  *
00245  * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
00246  */
00247 ADI_SENSE_RESULT  adi_sense_1000_SetChannelPriority(
00248     ADI_SENSE_DEVICE_HANDLE  hDevice,
00249     ADI_SENSE_1000_CHANNEL_ID  eChannelId,
00250     ADI_SENSE_1000_CHANNEL_PRIORITY  ePriority);
00251 
00252 /*!
00253  * @brief Update the measurement threshold limits for a specified channel.
00254  *
00255  * @param[in] hDevice             ADISENSE device context handle
00256  * @param[in] eChannelId          Selects the channel to be updated
00257  * @param[in] fHighThresholdLimit Optional maximum threshold value for each
00258  *                                processed sample, to be checked prior to
00259  *                                publishing.  A channel ALERT condition is
00260  *                                raised if the processed value is higher than
00261  *                                this threshold.  Set to NaN if not required.
00262  * @param[in] fLowThresholdLimit  Optional minimum threshold value for each
00263  *                                processed sample, to be checked prior to
00264  *                                publishing.  A channel ALERT condition is
00265  *                                raised if the processed value is lower than
00266  *                                this threshold.  Set to NaN if not required.
00267  *
00268  * @return Status
00269  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00270  *
00271  * @details Translates configuration details provided into device-specific
00272  *          register settings and updates device configuration registers.
00273  *          Allows individual channel thresholds to be dynamically adjusted.
00274  *
00275  * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
00276  */
00277 ADI_SENSE_RESULT  adi_sense_1000_SetChannelThresholdLimits(
00278     ADI_SENSE_DEVICE_HANDLE  hDevice,
00279     ADI_SENSE_1000_CHANNEL_ID  eChannelId,
00280     float32_t fHighThresholdLimit,
00281     float32_t fLowThresholdLimit);
00282 
00283 
00284 /*!
00285  * @brief Set a sensor specific parameter for a specified channel.
00286  *
00287  * @param[in] hDevice             ADI Sense device context handle
00288  * @param[in] eChannelId          Selects the channel to be updated
00289  * @param[in] fSensorParam        Sensor specific parameter
00290  *
00291  * @return Status
00292  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00293  *
00294  * @details Translates configuration details provided into device-specific
00295  *          register settings and updates device configuration registers.
00296  *          Allows optional sensor-specific parameter to be specified
00297  *
00298  * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
00299  */
00300 ADI_SENSE_RESULT  adi_sense_1000_SetSensorParameter(
00301      ADI_SENSE_DEVICE_HANDLE  hDevice,
00302      ADI_SENSE_1000_CHANNEL_ID  eChannelId,
00303      float32_t fSensorParam);
00304 /*!
00305  * @brief Update the extra settling time for a specified channel.
00306  *
00307  * @param[in] hDevice       ADISENSE device context handle
00308  * @param[in] eChannelId    Selects the channel to be updated
00309  * @param[in] nSettlingTime A minimum settling time is applied internally for
00310  *                          each channel, based on the sensor type.  However,
00311  *                          additional settling time (microseconds) can
00312  *                          optionally be specified here.  Set to 0 if not
00313  *                          required.
00314  *
00315  * @return Status
00316  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00317  *
00318  * @details Translates configuration details provided into device-specific
00319  *          register settings and updates device configuration registers.
00320  *          Allows individual channel settling times to be dynamically adjusted.
00321  *
00322  * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
00323  */
00324 ADI_SENSE_RESULT  adi_sense_1000_SetChannelSettlingTime(
00325     ADI_SENSE_DEVICE_HANDLE  hDevice,
00326     ADI_SENSE_1000_CHANNEL_ID  eChannelId,
00327     uint32_t nSettlingTime);
00328 
00329 /*!
00330  * @brief Assemble a list of separate Look-Up Tables into a single buffer
00331  *
00332  * @param[out] pLutBuffer    Pointer to the Look-Up Table data buffer where
00333  *                           the assembled Look-Up Table data will be placed
00334  * @param[in] nLutBufferSize Allocated size, in bytes, of the output data buffer
00335  * @param[in] nNumTables     Number of tables to add to the Look-Up Table buffer
00336  * @param[in] ppDesc         Array of pointers to the table descriptors to be added
00337  * @param[in] ppData         Array of pointers to the table data to be added
00338  *
00339  * @return Status
00340  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00341  *
00342  * @details This utiliity function fills the Look-up Table header fields; then
00343  *          walks through the array of individual table descriptor and data
00344  *          pointers provided, appending (copying) each one to the Look-Up Table
00345  *          data buffer. The length and crc16 fields of each table descriptor
00346  *          will be calculated and filled by this function, but other fields in
00347  *          the descriptor structure must be filled by the caller beforehand.
00348  *
00349  * @note    The assembled LUT data buffer filled by this function can then be
00350  *          written to the device memory using @ref adi_sense_1000_SetLutData.
00351  */
00352 ADI_SENSE_RESULT  adi_sense_1000_AssembleLutData(
00353     ADI_SENSE_1000_LUT                  * pLutBuffer,
00354     unsigned                              nLutBufferSize,
00355     unsigned                        const nNumTables,
00356     ADI_SENSE_1000_LUT_DESCRIPTOR * const ppDesc[],
00357     ADI_SENSE_1000_LUT_TABLE_DATA  * const ppData[]);
00358 
00359 /*!
00360  * @brief Write Look-Up Table data to the device memory
00361  *
00362  * @param[in]  hDevice  ADISENSE device context handle
00363  * @param[out] pLutData Pointer to the Look-Up Table data structure
00364  *
00365  * @return Status
00366  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00367  *
00368  * @details Validates the Look-Up Table data format and loads it into
00369  *          device memory via dedicated keyhole registers.
00370  *
00371  * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
00372  */
00373 ADI_SENSE_RESULT  adi_sense_1000_SetLutData(
00374     ADI_SENSE_DEVICE_HANDLE     const hDevice,
00375     ADI_SENSE_1000_LUT       * const pLutData);
00376 
00377 /*!
00378  * @brief Write Look-Up Table raw data to the device memory
00379  *
00380  * @param[in]  hDevice  ADISENSE device context handle
00381  * @param[out] pLutData Pointer to the Look-Up Table raw data structure
00382  *
00383  * @return Status
00384  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00385  *
00386  * @details This can be used instead of @ref adi_sense_1000_SetLutData for
00387  *          loading LUT data from the alternative raw data format.  See
00388  *          @ref adi_sense_1000_SetLutData for more information.
00389  *
00390  * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
00391  */
00392 ADI_SENSE_RESULT  adi_sense_1000_SetLutDataRaw(
00393     ADI_SENSE_DEVICE_HANDLE     const hDevice,
00394     ADI_SENSE_1000_LUT_RAW   * const pLutData);
00395 
00396 /*!
00397  * @brief Get the number of samples available when DATAREADY status is asserted.
00398  *
00399  * @param[in]  hDevice               ADISENSE device context handle
00400  * @param[in]  eMeasurementMode      Must be set to the same value used for @ref
00401  *                                   adi_sense_StartMeasurement().
00402  * @param[out] peOperatingMode       Pointer to return the configured operating mode
00403  * @param[out] peDataReadyMode       Pointer to return the configured data publishing mode
00404  * @param[out] pnSamplesPerDataready Pointer to return the calculated number of samples
00405  *                                   available when DATAREADY is asserted
00406  * @param[out] pnSamplesPerCycle     Pointer to return the calculated number of samples
00407  *                                   produced per measurement cycle
00408  * @param[out] pnBytesPerSample      Pointer to return the size, in bytes, of each sample
00409  *
00410  * @return Status
00411  *         - #ADI_SENSE_SUCCESS Call completed successfully.
00412  *
00413  * @details Examines the current configuration settings in the device registers
00414  *          to calculate the number of samples available whenever the DATAREADY
00415  *          signal is asserted, along with other related information.  This may
00416  *          be used to allocate buffers to store samples and to determine how
00417  *          many samples to retrieve whenever the DATAREADY status is asserted.
00418  */
00419 ADI_SENSE_RESULT  adi_sense_1000_GetDataReadyModeInfo(
00420     ADI_SENSE_DEVICE_HANDLE          const hDevice,
00421     ADI_SENSE_MEASUREMENT_MODE       const eMeasurementMode,
00422     ADI_SENSE_1000_OPERATING_MODE  * const peOperatingMode,
00423     ADI_SENSE_1000_DATAREADY_MODE  * const peDataReadyMode,
00424     uint32_t                      * const pnSamplesPerDataready,
00425     uint32_t                      * const pnSamplesPerCycle,
00426     uint8_t                       * const pnBytesPerSample);
00427 
00428 #ifdef __cplusplus
00429 }
00430 #endif
00431 
00432 /*!
00433  * @}
00434  */
00435 
00436 #endif /* __ADI_SENSE_1000_API_H__ */