admw1001_api.h

00001 /*
00002 Copyright 2019 (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:   admw_1001_api.h
00039  * @brief:  ADMW1001 Host Library Application Programming Interface (API)
00040  *-----------------------------------------------------------------------------
00041  */
00042 
00043 #ifndef __ADMW1001_API_H__
00044 #define __ADMW1001_API_H__
00045 
00046 #include "inc/admw_types.h"
00047 #include "inc/admw_config_types.h"
00048 #include "inc/admw_platform.h"
00049 #include "inc/admw1001/admw1001_config.h"
00050 #include "inc/admw1001/admw1001_lut_data.h"
00051 
00052 /*! @ingroup ADMW_Api */
00053 
00054 /*! @defgroup ADMW1001_Api ADMW1001 Host Library API
00055  *  ADMW1001 device-specific API function prototypes.
00056  *  These are supplementary to the common ADMW Host Library API.
00057  *  @{
00058  */
00059 
00060 #ifdef __cplusplus
00061 extern "C" {
00062 #endif
00063 
00064 /*!
00065  * @brief Read one or more device registers at the specified register address.
00066  *
00067  * @param[in]  hDevice    ADMW1001 device context handle
00068  * @param[in]  nAddress   Register map address to read from
00069  * @param[out] pData      Pointer to return the register map data
00070  * @param[in]  nLength    Number of bytes of data to read from the register map
00071  *
00072  * @return Status
00073  *         - #ADMW_SUCCESS Call completed successfully.
00074  *
00075  * @details Provides direct byte-level read access to the device register map.
00076  *          The size and format of the register(s) must be known.
00077  *
00078  * @note Reads from special "keyhole" or "FIFO" registers will be handled
00079  *       according to documentation for those registers.
00080  */
00081 ADMW_RESULT  admw1001_ReadRegister(
00082     ADMW_DEVICE_HANDLE   const hDevice,
00083     uint16_t            const nAddress,
00084     void                *const pData,
00085     unsigned            const nLength);
00086 /*!
00087  * @brief Read one or more device registers at the specified debug register address.
00088  *
00089  * @param[in]  hDevice    ADMW1001 device context handle
00090  * @param[in]  nAddress   Register map address to read from
00091  * @param[out] pData      Pointer to return the register map data
00092  * @param[in]  nLength    Number of bytes of data to read from the register map
00093  *
00094  * @return Status
00095  *         - #ADMW_SUCCESS Call completed successfully.
00096  *
00097  * @details Provides direct byte-level read access to the device register map.
00098  *          The size and format of the register(s) must be known.
00099  *
00100  * @note Reads from special "keyhole" or "FIFO" registers will be handled
00101  *       according to documentation for those registers.
00102  */
00103 ADMW_RESULT  admw1001_Read_Debug_Register(
00104     ADMW_DEVICE_HANDLE   const hDevice,
00105     uint16_t            const nAddress,
00106     void                *const pData,
00107     unsigned            const nLength);
00108 
00109 /*!
00110  * @brief Write one or more device registers at the specified register address.
00111  *
00112  * @param[in]  hDevice    ADMW1001 device context handle
00113  * @param[in]  nAddress   Register map address to read from
00114  * @param[out] pData      Pointer to return the register map data
00115  * @param[in]  nLength    Number of bytes of data to read from the register map
00116  *
00117  * @return Status
00118  *         - #ADMW_SUCCESS Call completed successfully.
00119  *
00120  * @details Provides direct byte-level write access to the device register map.
00121  *          The size and format of the register(s) must be known.
00122  *
00123  * @note Writes to read-only registers will be ignored by the device.
00124  * @note Writes to special "keyhole" registers will be handled according to
00125  *       documentation for those registers.
00126  */
00127 ADMW_RESULT  admw1001_WriteRegister(
00128     ADMW_DEVICE_HANDLE   const hDevice,
00129     uint16_t            const nAddress,
00130     void                *const pData,
00131     unsigned            const nLength);
00132 
00133 /*!
00134  * @brief Write one or more device registers at the specified debug register address.
00135  *
00136  * @param[in]  hDevice    ADMW1001 device context handle
00137  * @param[in]  nAddress   Register map address to read from
00138  * @param[out] pData      Pointer to return the register map data
00139  * @param[in]  nLength    Number of bytes of data to read from the register map
00140  *
00141  * @return Status
00142  *         - #ADMW_SUCCESS Call completed successfully.
00143  *
00144  * @details Provides direct byte-level write access to the device register map.
00145  *          The size and format of the register(s) must be known.
00146  *
00147  */
00148 ADMW_RESULT  admw1001_Write_Debug_Register(
00149     ADMW_DEVICE_HANDLE   const hDevice,
00150     uint16_t            const nAddress,
00151     void                *const pData,
00152     unsigned            const nLength);
00153 /*
00154  * @brief Update power configuration settings on the device.
00155  *
00156  * @param[in] hDevice      ADMW1001 device context handle
00157  * @param[in] pPowerConfig Power configuration details
00158  *
00159  * @return Status
00160  *         - #ADMW_SUCCESS Call completed successfully.
00161  *
00162  * @details Translates configuration details provided into device-specific
00163  *          register settings and updates device configuration registers.
00164  *
00165  * @note Settings are not applied until admw_ApplyConfigUpdates() is called
00166  */
00167 ADMW_RESULT  admw1001_SetPowerConfig(
00168     ADMW_DEVICE_HANDLE       hDevice,
00169     ADMW1001_POWER_CONFIG    *pPowerConfig);
00170 
00171 /*!
00172  * @brief Update measurement configuration settings on the device.
00173  *
00174  * @param[in] hDevice            ADMW1001 device context handle
00175  * @param[in] pMeasurementConfig Measurement configuration details
00176  *
00177  * @return Status
00178  *         - #ADMW_SUCCESS Call completed successfully.
00179  *
00180  * @details Translates configuration details provided into device-specific
00181  *          register settings and updates device configuration registers.
00182  *
00183  * @note Settings are not applied until admw_ApplyConfigUpdates() is called
00184  */
00185 ADMW_RESULT  admw1001_SetMeasurementConfig(
00186     ADMW_DEVICE_HANDLE           hDevice,
00187     ADMW1001_MEASUREMENT_CONFIG  *pMeasurementConfig);
00188 
00189 /*!
00190  * @brief Update diagnostics configuration settings on the device.
00191  *
00192  * @param[in] hDevice            ADMW1001 device context handle
00193  * @param[in] pDiagnosticsConfig Diagnostics configuration details
00194  *
00195  * @return Status
00196  *         - #ADMW_SUCCESS Call completed successfully.
00197  *
00198  * @details Translates configuration details provided into device-specific
00199  *          register settings and updates device configuration registers.
00200  *
00201  * @note Settings are not applied until admw_ApplyConfigUpdates() is called
00202  */
00203 ADMW_RESULT  admw1001_SetDiagnosticsConfig(
00204     ADMW_DEVICE_HANDLE           hDevice,
00205     ADMW1001_DIAGNOSTICS_CONFIG  *pDiagnosticsConfig);
00206 
00207 /*!
00208  * @brief Update channel configuration settings for a specific channel.
00209  *
00210  * @param[in] hDevice        ADMW1001 device context handle
00211  * @param[in] eChannelId     Selects the channel to be updated
00212  * @param[in] pChannelConfig Channel configuration details
00213  *
00214  * @return Status
00215  *         - #ADMW_SUCCESS Call completed successfully.
00216  *
00217  * @details Translates configuration details provided into device-specific
00218  *          register settings and updates device configuration registers.
00219  *          Allows individual channel configuration details to be dynamically
00220  *          adjusted without rewriting the full device configuration.
00221  *
00222  * @note Settings are not applied until admw_ApplyConfigUpdates() is called
00223  */
00224 ADMW_RESULT  admw1001_SetChannelConfig(
00225     ADMW_DEVICE_HANDLE       hDevice,
00226     ADMW1001_CH_ID           eChannelId,
00227     ADMW1001_CHANNEL_CONFIG  *pChannelConfig);
00228 
00229 /*!
00230  * @brief Update number of measurements-per-cycle for a specific channel.
00231  *
00232  * @param[in] hDevice               ADMW1001 device context handle
00233  * @param[in] eChannelId            Selects the channel to be updated
00234  * @param[in] nMeasurementsPerCycle Specifies the number of measurements to be
00235  *                                  obtained from this channel in each
00236  *                                  measurement cycle.  Set as 0 to disable the
00237  *                                  channel (omit from measurement cycle).
00238  *
00239  * @return Status
00240  *         - #ADMW_SUCCESS Call completed successfully.
00241  *
00242  * @details Translates configuration details provided into device-specific
00243  *          register settings and updates device configuration registers.
00244  *          Allows individual channels to be dynamically enabled/disabled, and
00245  *          measurements-per-cycle to be adjusted.
00246  *
00247  * @note Settings are not applied until admw_ApplyConfigUpdates() is called
00248  */
00249 ADMW_RESULT  admw1001_SetChannelCount(
00250     ADMW_DEVICE_HANDLE   hDevice,
00251     ADMW1001_CH_ID  eChannelId,
00252     uint32_t            nMeasurementsPerCycle);
00253 
00254 /*!
00255  * @brief Update priority level for a specific channel.
00256  *
00257  * @param[in] hDevice    ADMW1001 device context handle
00258  * @param[in] eChannelId Selects the channel to be updated
00259  * @param[in] ePriority  Specifies the channel priority level
00260  *
00261  * @return Status
00262  *         - #ADMW_SUCCESS Call completed successfully.
00263  *
00264  * @details Translates configuration details provided into device-specific
00265  *          register settings and updates device configuration registers.
00266  *          Allows individual channels to be dynamically re-prioritised.
00267  *
00268  * @note Settings are not applied until admw_ApplyConfigUpdates() is called
00269  */
00270 ADMW_RESULT  admw1001_SetChannelPriority(
00271     ADMW_DEVICE_HANDLE           hDevice,
00272     ADMW1001_CH_ID       eChannelId,
00273     ADMW1001_CHANNEL_PRIORITY    ePriority);
00274 
00275 /*!
00276  * @brief Update the measurement threshold limits for a specified channel.
00277  *
00278  * @param[in] hDevice             ADMW1001 device context handle
00279  * @param[in] eChannelId          Selects the channel to be updated
00280  * @param[in] fHighThresholdLimit Optional maximum threshold value for each
00281  *                                processed sample, to be checked prior to
00282  *                                publishing.  A channel ALERT condition is
00283  *                                raised if the processed value is higher than
00284  *                                this threshold.  Set to NaN if not required.
00285  * @param[in] fLowThresholdLimit  Optional minimum threshold value for each
00286  *                                processed sample, to be checked prior to
00287  *                                publishing.  A channel ALERT condition is
00288  *                                raised if the processed value is lower than
00289  *                                this threshold.  Set to NaN if not required.
00290  *
00291  * @return Status
00292  *         - #ADMW_SUCCESS Call completed successfully.
00293  *
00294  * @details Translates configuration details provided into device-specific
00295  *          register settings and updates device configuration registers.
00296  *          Allows individual channel thresholds to be dynamically adjusted.
00297  *
00298  * @note Settings are not applied until admw_ApplyConfigUpdates() is called
00299  */
00300 ADMW_RESULT  admw1001_SetChannelThresholdLimits(
00301     ADMW_DEVICE_HANDLE       hDevice,
00302     ADMW1001_CH_ID   eChannelId,
00303     float32_t               fHighThresholdLimit,
00304     float32_t               fLowThresholdLimit);
00305 
00306 
00307 /*!
00308  * @brief Set a sensor specific parameter for a specified channel.
00309  *
00310  * @param[in] hDevice             ADMW1001 device context handle
00311  * @param[in] eChannelId          Selects the channel to be updated
00312  * @param[in] fSensorParam        Sensor specific parameter
00313  *
00314  * @return Status
00315  *         - #ADMW_SUCCESS Call completed successfully.
00316  *
00317  * @details Translates configuration details provided into device-specific
00318  *          register settings and updates device configuration registers.
00319  *          Allows optional sensor-specific parameter to be specified
00320  *
00321  * @note Settings are not applied until admw_ApplyConfigUpdates() is called
00322  */
00323 ADMW_RESULT  admw1001_SetSensorParameter(
00324      ADMW_DEVICE_HANDLE      hDevice,
00325      ADMW1001_CH_ID      eChannelId,
00326      float32_t              fSensorParam);
00327 /*!
00328  * @brief Update the extra settling time for a specified channel.
00329  *
00330  * @param[in] hDevice       ADMW1001 device context handle
00331  * @param[in] eChannelId    Selects the channel to be updated
00332  * @param[in] nSettlingTime A minimum settling time is applied internally for
00333  *                          each channel, based on the sensor type.  However,
00334  *                          additional settling time (microseconds) can
00335  *                          optionally be specified here.  Set to 0 if not
00336  *                          required.
00337  *
00338  * @return Status
00339  *         - #ADMW_SUCCESS Call completed successfully.
00340  *
00341  * @details Translates configuration details provided into device-specific
00342  *          register settings and updates device configuration registers.
00343  *          Allows individual channel settling times to be dynamically adjusted.
00344  *
00345  * @note Settings are not applied until admw_ApplyConfigUpdates() is called
00346  */
00347 ADMW_RESULT  admw1001_SetChannelSettlingTime(
00348     ADMW_DEVICE_HANDLE   hDevice,
00349     ADMW1001_CH_ID  eChannelId,
00350     uint32_t            nSettlingTime);
00351 
00352 #ifdef __V2_3_CFG_FMT__
00353 /*!
00354  * @brief Enable access to advanced sensor configuration options.
00355  *
00356  * @param[in] hDevice       ADMW1001 device context handle
00357  * @param[in] key           Key to unlock advanced access
00358  *
00359  * @return Status
00360  *         - #ADMW_SUCCESS Call completed successfully.
00361  *
00362  * @details When the correct access key is provided, access to advanced sensor
00363  *          configuration options and use of advanced sensor types is enabled.
00364  *
00365  * @note Settings are not applied until admw_ApplyConfigUpdates() is called
00366  */
00367 ADMW_RESULT  admw1001_SetAdvancedAccess(
00368     ADMW_DEVICE_HANDLE               hDevice,
00369     ADMW1001_ADVANCED_ACCESS_KEY    key);
00370 #endif
00371 
00372 /*!
00373  * @brief Assemble a list of separate Look-Up Tables into a single buffer
00374  *
00375  * @param[out] pLutBuffer    Pointer to the Look-Up Table data buffer where
00376  *                           the assembled Look-Up Table data will be placed
00377  * @param[in] nLutBufferSize Allocated size, in bytes, of the output data buffer
00378  * @param[in] nNumTables     Number of tables to add to the Look-Up Table buffer
00379  * @param[in] ppDesc         Array of pointers to the table descriptors to be added
00380  * @param[in] ppData         Array of pointers to the table data to be added
00381  *
00382  * @return Status
00383  *         - #ADMW_SUCCESS Call completed successfully.
00384  *
00385  * @details This utiliity function fills the Look-up Table header fields; then
00386  *          walks through the array of individual table descriptor and data
00387  *          pointers provided, appending (copying) each one to the Look-Up Table
00388  *          data buffer. The length and crc16 fields of each table descriptor
00389  *          will be calculated and filled by this function, but other fields in
00390  *          the descriptor structure must be filled by the caller beforehand.
00391  *
00392  * @note    The assembled LUT data buffer filled by this function can then be
00393  *          written to the device memory using @ref admw1001_SetLutData.
00394  */
00395 ADMW_RESULT  admw1001_AssembleLutData(
00396     ADMW1001_LUT            *pLutBuffer,
00397     unsigned                nLutBufferSize,
00398     unsigned                const nNumTables,
00399     ADMW1001_LUT_DESCRIPTOR *const ppDesc[],
00400     ADMW1001_LUT_TABLE_DATA  *const ppData[]);
00401 
00402 /*!
00403  * @brief Write Look-Up Table data to the device memory
00404  *
00405  * @param[in]  hDevice  ADMW1001 device context handle
00406  * @param[out] pLutData Pointer to the Look-Up Table data structure
00407  *
00408  * @return Status
00409  *         - #ADMW_SUCCESS Call completed successfully.
00410  *
00411  * @details Validates the Look-Up Table data format and loads it into
00412  *          device memory via dedicated keyhole registers.
00413  *
00414  * @note Settings are not applied until admw_ApplyConfigUpdates() is called
00415  */
00416 ADMW_RESULT  admw1001_SetLutData(
00417     ADMW_DEVICE_HANDLE   hDevice,
00418     ADMW1001_LUT        *const pLutData);
00419 
00420 /*!
00421  * @brief Write Look-Up Table raw data to the device memory
00422  *
00423  * @param[in]  hDevice  ADMW device context handle
00424  * @param[out] pLutData Pointer to the Look-Up Table raw data structure
00425  *
00426  * @return Status
00427  *         - #ADMW_SUCCESS Call completed successfully.
00428  *
00429  * @details This can be used instead of @ref admw1001_SetLutData for
00430  *          loading LUT data from the alternative raw data format.  See
00431  *          @ref admw1001_SetLutData for more information.
00432  *
00433  * @note Settings are not applied until admw_ApplyConfigUpdates() is called
00434  */
00435 ADMW_RESULT  admw1001_SetLutDataRaw(
00436     ADMW_DEVICE_HANDLE   hDevice,
00437     ADMW1001_LUT_RAW    *const pLutData);
00438 
00439 /*!
00440  * @brief Get the number of samples available when DATAREADY status is asserted.
00441  *
00442  * @param[in]  hDevice               ADMW device context handle
00443  * @param[in]  eMeasurementMode      Must be set to the same value used for @ref
00444  *                                   admw_StartMeasurement().
00445  * @param[out] peOperatingMode       Pointer to return the configured operating mode
00446  * @param[out] peDataReadyMode       Pointer to return the configured data publishing mode
00447  * @param[out] pnSamplesPerDataready Pointer to return the calculated number of samples
00448  *                                   available when DATAREADY is asserted
00449  * @param[out] pnSamplesPerCycle     Pointer to return the calculated number of samples
00450  *                                   produced per measurement cycle
00451  * @param[out] pnBytesPerSample      Pointer to return the size, in bytes, of each sample
00452  *
00453  * @return Status
00454  *         - #ADMW_SUCCESS Call completed successfully.
00455  *
00456  * @details Examines the current configuration settings in the device registers
00457  *          to calculate the number of samples available whenever the DATAREADY
00458  *          signal is asserted, along with other related information.  This may
00459  *          be used to allocate buffers to store samples and to determine how
00460  *          many samples to retrieve whenever the DATAREADY status is asserted.
00461  */
00462 ADMW_RESULT  admw1001_GetDataReadyModeInfo(
00463     ADMW_DEVICE_HANDLE       const hDevice,
00464     ADMW_MEASUREMENT_MODE    const eMeasurementMode,
00465     ADMW1001_OPERATING_MODE  *const peOperatingMode,
00466     ADMW1001_DATAREADY_MODE  *const peDataReadyMode,
00467     uint32_t                *const pnSamplesPerDataready,
00468     uint32_t                *const pnSamplesPerCycle,
00469     uint8_t                 *const pnBytesPerSample);
00470 
00471 #ifdef __cplusplus
00472 }
00473 #endif
00474 
00475 /*!
00476  * @}
00477  */
00478 
00479 #endif /* __ADMW1001_API_H__ */