Sean Wilson
AdiSense1000_V21 MBED API
Fork of
AdiSense1000
by 
PoC_Team
Diff: inc/adi_sense_1000/adi_sense_1000_api.h
- Revision:
- 26:12d0204be712
- Child:
- 27:567abf893938
--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/inc/adi_sense_1000/adi_sense_1000_api.h Mon Mar 26 14:50:05 2018 +0000
@@ -0,0 +1,374 @@
+/*!
+ ******************************************************************************
+ * @file: adi_sense_api.h
+ * @brief: ADSNS1000 Host Library Application Programming Interface (API)
+ *-----------------------------------------------------------------------------
+ */
+
+/*
+Copyright 2017 (c) 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.
+ - 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.
+ - Use of the software either in source or binary form, must be run
+ on or directly connected to an Analog Devices Inc. component.
+
+THIS SOFTWARE IS PROVIDED BY ANALOG DEVICES "AS IS" AND ANY EXPRESS OR
+IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, NON-INFRINGEMENT,
+MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED.
+IN NO EVENT SHALL ANALOG DEVICES BE LIABLE FOR ANY DIRECT, INDIRECT,
+INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT
+LIMITED TO, INTELLECTUAL PROPERTY RIGHTS, 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"
+
+/*! @ingroup ADISENSE_Api */
+
+/*! @defgroup ADSNS1000_Api ADSNS1000 Host Library API
+ * ADSNS1000 device-specific API function prototypes.
+ * These are supplementary to the common ADISENSE Host Library API.
+ * @{
+ */
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+/*!
+ * @brief Read one or more device registers at the specified register address.
+ *
+ * @param[in] hDevice ADISENSE 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 ADISENSE 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 ADISENSE 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 ADISENSE 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 ADISENSE 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 ADISENSE 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 ADISENSE 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 ADISENSE device context handle
+ * @param[in] eChannelId Selects the channel to be updated
+ * @param[in] fHighThresholdLimit 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] fLowThresholdLimit 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 fHighThresholdLimit,
+ float32_t fLowThresholdLimit);
+
+/*!
+ * @brief Update the extra settling time for a specified channel.
+ *
+ * @param[in] hDevice ADISENSE device context handle
+ * @param[in] eChannelId Selects the channel to be updated
+ * @param[in] nSettlingTime 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 nSettlingTime);
+
+/*!
+ * @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] nLutBufferSize 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 @ref adi_sense_1000_SetLutData.
+ */
+ADI_SENSE_RESULT adi_sense_1000_AssembleLutData(
+ ADI_SENSE_1000_LUT * pLutBuffer,
+ unsigned nLutBufferSize,
+ 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 ADISENSE 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 ADISENSE 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 @ref adi_sense_1000_SetLutData for
+ * loading LUT data from the alternative raw data format. See
+ * @ref 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 ADISENSE device context handle
+ * @param[in] eMeasurementMode Must be set to the same value used for @ref
+ * adi_sense_StartMeasurement().
+ * @param[out] peOperatingMode Pointer to return the configured operating mode
+ * @param[out] peDataReadyMode 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,
+ ADI_SENSE_MEASUREMENT_MODE const eMeasurementMode,
+ ADI_SENSE_1000_OPERATING_MODE * const peOperatingMode,
+ ADI_SENSE_1000_DATAREADY_MODE * const peDataReadyMode,
+ uint32_t * const pnSamplesPerDataready,
+ uint32_t * const pnSamplesPerCycle);
+
+#ifdef __cplusplus
+}
+#endif
+
+/*!
+ * @}
+ */
+
+#endif /* __ADI_SENSE_1000_API_H__ */
+