Sean Wilson
AdiSense1000_V21 MBED API
Fork of
AdiSense1000
by 
PoC_Team
Diff: inc/adi_sense_1000/adi_sense_1000_api.h
- Revision:
- 11:7215312d26fb
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/inc/adi_sense_1000/adi_sense_1000_api.h Mon Nov 27 12:46:37 2017 +0000
@@ -0,0 +1,407 @@
+/*!
+ ******************************************************************************
+ * @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_1000_API_H__
+#define __ADI_SENSE_1000_API_H__
+
+#include "inc/adi_sense_types.h"
+#include "inc/adi_sense_config_types.h"
+#include "inc/adi_sense_platform.h"
+#include "adi_sense_1000_config.h"
+#include "adi_sense_1000_lut_data.h"
+
+/*! @addtogroup ADI_Sense_Api ADI Sense Host Library API
+ * @{
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/******************************************************************************
+ * ADI Sense 1000 device-specific API function prototypes
+ *
+ * These are supplementary to the general ADI Sense API
+ *****************************************************************************/
+
+/*!
+ * @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_1000_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_1000_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_1000_SetPowerConfig(
+ ADI_SENSE_DEVICE_HANDLE hDevice,
+ ADI_SENSE_1000_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_1000_SetMeasurementConfig(
+ ADI_SENSE_DEVICE_HANDLE hDevice,
+ ADI_SENSE_1000_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_1000_SetDiagnosticsConfig(
+ ADI_SENSE_DEVICE_HANDLE hDevice,
+ ADI_SENSE_1000_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_1000_SetChannelConfig(
+ ADI_SENSE_DEVICE_HANDLE hDevice,
+ ADI_SENSE_1000_CHANNEL_ID eChannelId,
+ ADI_SENSE_1000_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_1000_SetChannelCount(
+ ADI_SENSE_DEVICE_HANDLE hDevice,
+ ADI_SENSE_1000_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_1000_SetChannelThresholdLimits(
+ ADI_SENSE_DEVICE_HANDLE hDevice,
+ ADI_SENSE_1000_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_1000_SetChannelSettlingTime(
+ ADI_SENSE_DEVICE_HANDLE hDevice,
+ ADI_SENSE_1000_CHANNEL_ID eChannelId,
+ uint32_t settlingTime);
+
+/*!
+ * @brief Assemble a list of separate Look-Up Tables into a single buffer
+ *
+ * @param[out] pLutBuffer Pointer to the Look-Up Table data buffer where
+ * the assembled Look-Up Table data will be placed
+ * @param[in] lutBufferSize Allocated size, in bytes, of the output data buffer
+ * @param[in] nNumTables Number of tables to add to the Look-Up Table buffer
+ * @param[in] ppDesc Array of pointers to the table descriptors to be added
+ * @param[in] ppData Array of pointers to the table data to be added
+ *
+ * @return Status
+ * - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details This utiliity function fills the Look-up Table header fields; then
+ * walks through the array of individual table descriptor and data
+ * pointers provided, appending (copying) each one to the Look-Up Table
+ * data buffer. The length and crc16 fields of each table descriptor
+ * will be calculated and filled by this function, but other fields in
+ * the descriptor structure must be filled by the caller beforehand.
+ *
+ * @note The assembled LUT data buffer filled by this function can then be
+ * written to the device memory using @adi_sense_1000_SetLutData.
+ */
+ADI_SENSE_RESULT adi_sense_1000_AssembleLutData(
+ ADI_SENSE_1000_LUT * pLutBuffer,
+ unsigned lutBufferSize,
+ unsigned const nNumTables,
+ ADI_SENSE_1000_LUT_DESCRIPTOR * const ppDesc[],
+ ADI_SENSE_1000_LUT_TABLE_DATA * const ppData[]);
+
+/*!
+ * @brief Write Look-Up Table data to the device memory
+ *
+ * @param[in] hDevice ADI Sense device context handle
+ * @param[out] pLutData Pointer to the Look-Up Table data structure
+ *
+ * @return Status
+ * - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details Validates the 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_1000_SetLutData(
+ ADI_SENSE_DEVICE_HANDLE const hDevice,
+ ADI_SENSE_1000_LUT * const pLutData);
+
+/*!
+ * @brief Write Look-Up Table raw data to the device memory
+ *
+ * @param[in] hDevice ADI Sense device context handle
+ * @param[out] pLutData Pointer to the Look-Up Table raw data structure
+ *
+ * @return Status
+ * - #ADI_SENSE_SUCCESS Call completed successfully.
+ *
+ * @details This can be used instead of @adi_sense_1000_SetLutData for
+ * loading LUT data from the alternative raw data format. See
+ * @adi_sense_1000_SetLutData for more information.
+ *
+ * @note Settings are not applied until adi_sense_ApplyConfigUpdates() is called
+ */
+ADI_SENSE_RESULT adi_sense_1000_SetLutDataRaw(
+ ADI_SENSE_DEVICE_HANDLE const hDevice,
+ ADI_SENSE_1000_LUT_RAW * const pLutData);
+
+/*!
+ * @brief Get the number of samples available when DATAREADY status is asserted.
+ *
+ * @param[in] hDevice ADI Sense device context handle
+ * @param[in] bHealthCheckMode Set true for health-check measurement cycles only.
+ * See @ref adi_sense_StartMeasurement().
+ * @param[out] peOperatingMode Pointer to return the configured operating mode
+ * @param[out] peDataReadMode 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_1000_GetDataReadyModeInfo(
+ ADI_SENSE_DEVICE_HANDLE const hDevice,
+ bool_t const bHealthCheckMode,
+ ADI_SENSE_1000_OPERATING_MODE * const peOperatingMode,
+ ADI_SENSE_1000_DATAREADY_MODE * const peDataReadyMode,
+ uint32_t * const pnSamplesPerDataready,
+ uint32_t * const pnSamplesPerCycle);
+
+/*!
+ * @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_1000_ReadCalTable(
+ ADI_SENSE_DEVICE_HANDLE hDevice,
+ float *buffer,
+ unsigned maxLen,
+ unsigned *dataLen,
+ unsigned *nRows,
+ unsigned *nColumns);
+
+#ifdef __cplusplus
+}
+#endif
+
+/*!
+ * @}
+ */
+
+#endif /* __ADI_SENSE_1000_API_H__ */
+