admw_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_api.h
00039  * @brief:  ADMW Host Library Application Programming Interface (API)
00040  *-----------------------------------------------------------------------------
00041  */
00042 
00043 #ifndef _ADMW_API_H__
00044 #define _ADMW_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/admw_gpio.h"
00050 #include "inc/admw_spi.h"
00051 #include "inc/admw_log.h"
00052 #include "inc/admw_time.h"
00053 
00054 /*! @defgroup ADMW_Api ADMW Host Library API
00055  *  Host library API common to the ADMW 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 ADMW products may implement a lower number of channels */
00065 #define ADMW_MAX_CHANNELS 16
00066 
00067 /*! A handle used in all API functions to identify the ADMW device. */
00068 
00069 typedef void* ADMW_DEVICE_HANDLE ;
00070 
00071 #define ADMW_FORMATTED_VERSION_SIZE     11u
00072 #define ADMW_VERSION_REG_VAL_SIZE       4u
00073 #define ADMW1001_FIRMWARE_VERSION_DEFAULT "00.00.0000"
00074 #define SPI_BUFFER_SIZE                        100u
00075 
00076 #define SFL_READ_STATUS_HDR_SIZE               14u
00077 
00078 #define SFL_READ_STATUS_RESPONSE_SIZE          42u
00079 
00080 /*! Supported connection types for communication with the ADMW device. */
00081 typedef enum {
00082     ADMW_CONNECTION_TYPE_SPI  = 1,
00083     /*!< Serial Peripheral Interface (SPI) connection type */
00084 } ADMW_CONNECTION_TYPE ;
00085 
00086 /*! Connection details for communication with a ADMW device instance. */
00087 typedef struct {
00088     ADMW_CONNECTION_TYPE       type;
00089     /*!< Connection type selection */
00090     ADMW_PLATFORM_SPI_CONFIG  spi;
00091     /*!< SPI connection parameters, required if SPI connection type is used */
00092     ADMW_PLATFORM_GPIO_CONFIG gpio;
00093     /*!< GPIO connection parameters, for device reset and status I/O signals */
00094     ADMW_PLATFORM_LOG_CONFIG  log;
00095     /*!< Log interface connection parameters, for display/routing of log messages */
00096 } ADMW_CONNECTION ;
00097 
00098 /*! Bit masks (flags) for the different device status indicators. */
00099 typedef enum {
00100     ADMW_DEVICE_STATUS_BUSY          = (1 << 0),
00101     /*!< Indicates that a command is currently running on the device */
00102     ADMW_DEVICE_STATUS_DATAREADY     = (1 << 1),
00103     /*!< Indicates the availability of measurement data for retrieval */
00104     ADMW_DEVICE_STATUS_ERROR         = (1 << 2),
00105     /*!< Indicates that an error condition has been detected by the device */
00106     ADMW_DEVICE_STATUS_ALERT         = (1 << 3),
00107     /*!< Indicates that an alert condition has been detected by the device */
00108     ADMW_DEVICE_STATUS_FIFO_ERROR    = (1 << 4),
00109     /*!< Indicates that a FIFO error condition has been detected by the device */
00110     ADMW_DEVICE_STATUS_CONFIG_ERROR  = (1 << 5),
00111     /*!< Indicates that a configuration error condition has been detected by the device */
00112     ADMW_DEVICE_STATUS_LUT_ERROR     = (1 << 6),
00113     /*!< Indicates that a look-up table error condition has been detected by the device */
00114 } ADMW_DEVICE_STATUS_FLAGS ;
00115 
00116 /*! Bit masks (flags) for the different diagnostics status indicators. */
00117 typedef enum {
00118     ADMW_DIAGNOSTICS_STATUS_CHECKSUM_ERROR        = (1 << 0),
00119     /*!< Indicates Error on Internal Checksum Calculations */
00120     ADMW_DIAGNOSTICS_STATUS_CONVERSION_ERROR      = (1 << 8),
00121     /*!< Indicates Error During Internal ADC Conversions */
00122     ADMW_DIAGNOSTICS_STATUS_CALIBRATION_ERROR     = (1 << 9),
00123     /*!< Indicates Error During Internal Device Calibrations */
00124 } ADMW_DIAGNOSTICS_STATUS_FLAGS ;
00125 
00126 /*! Bit masks (flags) for the different channel alert indicators. */
00127 typedef enum {
00128     ADMW_CHANNEL_ALERT_TIMEOUT           = (1 << 0),
00129     /*!< Indicates timeout condition detected on the channel */
00130     ADMW_CHANNEL_ALERT_UNDER_RANGE       = (1 << 1),
00131     /*!< Indicates raw sample under valid input range, possibly clamped */
00132     ADMW_CHANNEL_ALERT_OVER_RANGE        = (1 << 2),
00133     /*!< Indicates raw sample over valid input range, possibly clamped */
00134     ADMW_CHANNEL_ALERT_LOW_LIMIT         = (1 << 3),
00135     /*!< Indicates measurement result was below configured minimum threshold */
00136     ADMW_CHANNEL_ALERT_HIGH_LIMIT        = (1 << 4),
00137     /*!< Indicates measurement result was above configured maximum threshold */
00138     ADMW_CHANNEL_ALERT_SENSOR_OPEN       = (1 << 5),
00139     /*!< Indicates open circuit or mis-wire condition detected on the channel */
00140     ADMW_CHANNEL_ALERT_REF_DETECT        = (1 << 6),
00141     /*!< Indicates reference-detect error condition detected on the channel */
00142     ADMW_CHANNEL_ALERT_CONFIG_ERR        = (1 << 7),
00143     /*!< Indicates configuration error condition detected on the channel */
00144     ADMW_CHANNEL_ALERT_LUT_ERR           = (1 << 8),
00145     /*!< Indicates look-up table error condition detected on the channel */
00146     ADMW_CHANNEL_ALERT_SENSOR_NOT_READY  = (1 << 9),
00147     /*!< Indicates digital sensor not-ready error condition detected on the channel */
00148     ADMW_CHANNEL_ALERT_COMP_NOT_READY    = (1 << 10),
00149     /*!< Indicates compensation channel not-ready error condition detected on the channel */
00150     ADMW_CHANNEL_ALERT_LUT_UNDER_RANGE   = (1 << 13),
00151     /*!< Indicates raw sample was under the available LUT/equation range */
00152     ADMW_CHANNEL_ALERT_LUT_OVER_RANGE    = (1 << 14),
00153     /*!< Indicates raw sample was over the available LUT/equation range */
00154 } ADMW_CHANNEL_ALERT_FLAGS ;
00155 
00156 /*! Status details retreived from the ADMW device. */
00157 typedef struct {
00158     ADMW_DEVICE_STATUS_FLAGS       deviceStatus;
00159     /*!< General summary status information from the device  */
00160     ADMW_DIAGNOSTICS_STATUS_FLAGS  diagnosticsStatus;
00161     /*!< Diagnostic error status information from the device  */
00162     ADMW_CHANNEL_ALERT_FLAGS       channelAlerts[ADMW_MAX_CHANNELS];
00163     /*!< Per-channel alert status information from the device  */
00164     uint32_t                           errorCode;
00165     /*!< Code identifying the last error signalled by the device  */
00166     uint32_t                           alertCode;
00167     /*!< Code identifying the last alert signalled by the device  */
00168     uint32_t                           debugCode;
00169     /*!< Supplementary code related to the last error/alert  */
00170     uint32_t                           channelAlertCodes[ADMW_MAX_CHANNELS];
00171     /*!< Per-channel code identifying the last alert signalled for each channel */
00172 } ADMW_STATUS ;
00173 
00174 /*! Data sample details retreived from the ADMW device. */
00175 typedef struct {
00176     ADMW_DEVICE_STATUS_FLAGS       status;
00177     /*!< Device summary status snapshot when the sample was recorded */
00178     uint32_t                           channelId;
00179     /*!< The measurement channel from which this sample was obtained */
00180     uint32_t                           rawValue;
00181     /*!< The raw (unprocessed) value obtained directly from the measurement
00182      *   channel, if available
00183      */
00184     float32_t                          processedValue;
00185     /*!< The processed value obtained from the measurement channel, as a final
00186      *   measurement value, following calibration and linearisation correction,
00187      *   and conversion into an appropriate unit of measurement.
00188      */
00189 } ADMW_DATA_SAMPLE ;
00190 
00191 /*! Measurement mode options for the ADMW device.
00192  *  @ref admw_StartMeasurement
00193  */
00194 typedef enum {
00195     ADMW_MEASUREMENT_MODE_NORMAL  = 0,
00196     /*!< In this mode, normal measurement cycle(s) are executed and data samples
00197      *   are returned with raw measurement values included. */
00198     ADMW_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 } ADMW_MEASUREMENT_MODE ;
00202 
00203 /*! Identifiers for the user configuration slots in persistent memory. */
00204 typedef enum {
00205     ADMW_FLASH_CONFIG_1,
00206 } ADMW_USER_CONFIG_SLOT ;
00207 
00208 
00209 /******************************************************************************
00210  * ADMW High-Level API function prototypes
00211  *****************************************************************************/
00212 
00213 /*!
00214  * @brief Open ADMW device handle and set up communication interface.
00215  *
00216  * @param[in]  nDeviceIndex    Zero-based index number identifying this device
00217  *                             instance.  Note that this will be used to
00218  *                             retrieve a specific device configuration for
00219  *                             this device (see @ref admw_SetConfig
00220  *                             and @ref ADMW_CONFIG)
00221  * @param[in]  pConnectionInfo Host-specific connection details (e.g. SPI, GPIO)
00222  * @param[out] phDevice        Pointer to return an ADMW device handle
00223  *
00224  * @return Status
00225  *         - #ADMW_SUCCESS Call completed successfully.
00226  *         - #ADMW_NO_MEM  Failed to allocate memory resources.
00227  *         - #ADMW_INVALID_DEVICE_NUM Invalid device index specified
00228  *
00229  * @details Configure and initialise the Log interface and the SPI/GPIO
00230  *          communication interface to the ADMW1001 module.
00231  */
00232 ADMW_RESULT  admw_Open(
00233     unsigned                   const nDeviceIndex,
00234     ADMW_CONNECTION      * const pConnectionInfo,
00235     ADMW_DEVICE_HANDLE  * const phDevice);
00236 
00237 /*!
00238  * @brief Close ADMW device context and free resources.
00239  *
00240  * @param[in] hDevice ADMW device context handle
00241  *
00242  * @return Status
00243  *         - #ADMW_SUCCESS Call completed successfully.
00244  */
00245 ADMW_RESULT  admw_Close(
00246     ADMW_DEVICE_HANDLE    const hDevice);
00247 
00248 /*!
00249  * @brief Get the current state of the specified GPIO input signal.
00250  *
00251  * @param[in]  hDevice    ADMW device context handle
00252  * @param[in]  ePinId     GPIO pin to query
00253  * @param[out] pbAsserted Pointer to return the state of the status signal GPIO pin
00254  *
00255  * @return Status
00256  *         - #ADMW_SUCCESS Call completed successfully.
00257  *         - #ADMW_INVALID_DEVICE_NUM Invalid GPIO pin specified.
00258  *
00259  * @details Sets *pbAsserted to true if the status signal is asserted, or false
00260  *          otherwise.
00261  */
00262 ADMW_RESULT  admw_GetGpioState(
00263     ADMW_DEVICE_HANDLE   const hDevice,
00264     ADMW_GPIO_PIN         const ePinId,
00265     bool                  * const pbAsserted);
00266 
00267 /*!
00268  * @brief Register an application-defined callback function for GPIO interrupts
00269  *
00270  * @param[in] hDevice          ADMW context handle (@ref admw_Open)
00271  * @param[in] ePinId           GPIO pin on which to enable/disable interrupts
00272  * @param[in] callbackFunction Function to be called when an interrupt occurs.
00273  *                             Specify NULL here to disable interrupts.
00274  * @param[in] pCallbackParam   Optional opaque parameter passed to the callback
00275  *
00276  * @return Status
00277  *         - #ADMW_SUCCESS Call completed successfully.
00278  *         - #ADMW_INVALID_DEVICE_NUM Invalid GPIO pin specified.
00279  */
00280 ADMW_RESULT  admw_RegisterGpioCallback(
00281     ADMW_DEVICE_HANDLE          const hDevice,
00282     ADMW_GPIO_PIN                const ePinId,
00283     ADMW_GPIO_CALLBACK           const callbackFunction,
00284     void                           * const pCallbackParam);
00285 
00286 /*!
00287  * @brief Trigger a shut down of the device.
00288  *
00289  * @param[in] hDevice ADMW device context handle
00290  *
00291  * @return Status
00292  *         - #ADMW_SUCCESS Call completed successfully.
00293  *
00294  * @details Instructs the ADMW device to initiate a shut down,
00295  *          typically used to conserve power when the device is not
00296  *          in use.  The device may be restarted by calling
00297  *          @ref admw_Reset().  Note that active configuration
00298  *          settings are not preserved during shutdown and must be
00299  *          reloaded after the device has become ready again.
00300  *
00301  * @note No other command must be running when this is called.
00302  */
00303 ADMW_RESULT  admw_Shutdown(
00304     ADMW_DEVICE_HANDLE    const hDevice);
00305 
00306 /*!
00307  * @brief Reset the ADMW device.
00308  *
00309  * @param[in] hDevice ADMW device context handle
00310  *
00311  * @return Status
00312  *         - #ADMW_SUCCESS Call completed successfully.
00313  *
00314  * @details Trigger a hardware-reset of the ADMW device.
00315  *
00316  * @note The device may require several seconds before it is ready for use
00317  *       again. @ref admw_GetDeviceReadyState may be used to check if
00318  *       the device is ready.
00319  */
00320 ADMW_RESULT  admw_Reset(
00321     ADMW_DEVICE_HANDLE    const hDevice);
00322 
00323 /*!
00324  * @brief Check if the device is ready, following power-up or a reset.
00325  *
00326  * @param[in]  hDevice ADMW device context handle
00327  * @param[out] pbReady Pointer to return true if the device is ready, or false
00328  *                     otherwise
00329  *
00330  * @return Status
00331  *         - #ADMW_SUCCESS Call completed successfully.
00332  *
00333  * @details This function attempts to read a fixed-value device register via
00334  *           the communication interface.
00335  */
00336 ADMW_RESULT  admw_GetDeviceReadyState(
00337     ADMW_DEVICE_HANDLE    const hDevice,
00338     bool                   * const pbReady);
00339 
00340 /*!
00341  * @brief Obtain the product ID from the device.
00342  *
00343  * @param[in]  hDevice    ADMW device context handle
00344  * @param[out] pProductId Pointer to return the product ID value
00345  *
00346  * @return Status
00347  *         - #ADMW_SUCCESS Call completed successfully.
00348  *
00349  * @details Reads the product ID registers on the device and returns the value.
00350  */
00351 ADMW_RESULT  admw_GetProductID(
00352     ADMW_DEVICE_HANDLE    const hDevice,
00353     ADMW_PRODUCT_ID      * const pProductId);
00354 
00355 /*!
00356  * @brief Write full configuration settings to the device registers.
00357  *
00358  * @param[in]  hDevice ADMW device context handle
00359  * @param[out] pConfig Pointer to the configuration data structure
00360  *
00361  * @return Status
00362  *         - #ADMW_SUCCESS Call completed successfully.
00363  *
00364  * @details Translates configuration details provided into device-specific
00365  *          register settings and updates device configuration registers.
00366  *
00367  * @note Settings are not applied until admw_ApplyConfigUpdates() is called
00368  */
00369 ADMW_RESULT  admw_SetConfig(
00370     ADMW_DEVICE_HANDLE   const hDevice,
00371     ADMW_CONFIG         * const pConfig);
00372 
00373 /*!
00374  * @brief Apply the configuration settings currently stored in device registers
00375  *
00376  * @param[in] hDevice ADMW device context handle
00377  *
00378  * @return Status
00379  *         - #ADMW_SUCCESS Call completed successfully.
00380  *
00381  * @details Instructs the ADMW device to reload and apply configuration
00382  *          from the device configuration registers.  Changes to configuration
00383  *          registers are ignored by the device until this function is called.
00384  *
00385  * @note No other command must be running when this is called.
00386  */
00387 ADMW_RESULT  admw_ApplyConfigUpdates(
00388     ADMW_DEVICE_HANDLE    const hDevice);
00389 
00390 /*!
00391  * @brief Store the configuration settings to persistent memory on the device.
00392  *
00393  * @param[in] hDevice ADMW device context handle
00394  * @param[in] eSlotId User configuration slot in persistent memory
00395  *
00396  * @return Status
00397  *         - #ADMW_SUCCESS Call completed successfully.
00398  *
00399  * @details Instructs the ADMW device to save the current contents of its
00400  *          device configuration registers to non-volatile memory.
00401  *
00402  * @note No other command must be running when this is called.
00403  * @note Do not power down the device while this command is running.
00404  */
00405 ADMW_RESULT  admw_SaveConfig(
00406     ADMW_DEVICE_HANDLE    const hDevice,
00407     ADMW_USER_CONFIG_SLOT  const eSlotId);
00408 
00409 /*!
00410  * @brief Restore configuration settings from persistent memory on the device.
00411  *
00412  * @param[in] hDevice ADMW device context handle
00413  * @param[in] eSlotId User configuration slot in persistent memory
00414  *
00415  * @return Status
00416  *         - #ADMW_SUCCESS Call completed successfully.
00417  *
00418  * @details Instructs the ADMW device to restore the contents of its
00419  *          device configuration registers from non-volatile memory.
00420  *
00421  * @note No other command must be running when this is called.
00422  */
00423 ADMW_RESULT  admw_RestoreConfig(
00424     ADMW_DEVICE_HANDLE    const hDevice,
00425     ADMW_USER_CONFIG_SLOT  const eSlotId);
00426 
00427 /*!
00428  * @brief Erases the external flash memory.
00429  *
00430  * @param[in] hDevice ADMW device context handle
00431  *
00432  * @return Status
00433  *         - #ADMW_SUCCESS Call completed successfully.
00434  *
00435  * @details Sends the bulk erase instruction to the external flash
00436  *          device. All stored samples are deleted.
00437  *          It is a blocking operation and takes tens of seconds to
00438  *          complete.
00439  *
00440  * @note No other command must be running when this is called.
00441  */
00442 ADMW_RESULT  admw_EraseExternalFlash(
00443     ADMW_DEVICE_HANDLE    const hDevice);
00444 
00445 /*!
00446  * @brief Gets the number of samples stored in the external flash
00447  *        memory.
00448  *
00449  * @param[in] hDevice ADMW device context handle
00450  * @param[in] pSampleCount Address of the return value.
00451  *
00452  * @return Status
00453  *         - #ADMW_SUCCESS Call completed successfully.
00454  *
00455  * @note No other command must be running when this is called.
00456  */
00457 ADMW_RESULT  admw_GetExternalFlashSampleCount(
00458     ADMW_DEVICE_HANDLE    const hDevice,
00459     uint32_t * nSampleCount);
00460 
00461 // DEBUG - TO BE DELETED
00462 ADMW_RESULT  admw_SetExternalFlashIndex(
00463     ADMW_DEVICE_HANDLE    const hDevice,
00464     uint32_t nStartIndex);
00465 
00466 /*!
00467  * @brief Read measurement samples stored in the the external flash memory.
00468  *
00469  * @param[in]  hDevice          ADMW device context handle
00470  * @param[out] pSamples         Pointer to return a set of requested data
00471  *                              samples.
00472  * @param[in]  nStartIndex      Index of first sample to retrieve.
00473  * @param[in]  nBytesPerSample  The size, in bytes, of each sample.
00474  * @param[in]  nRequested       Number of requested data samples.
00475  * @param[out] pnReturned       Number of valid data samples successfully
00476  *                              retrieved.
00477  *
00478  * @return Status
00479  *         - #ADMW_SUCCESS Call completed successfully.
00480  *
00481  * @details Reads the status registers and extracts the relevant information
00482  *          to return to the caller.
00483  *
00484  */
00485 ADMW_RESULT  admw_GetExternalFlashData(
00486     ADMW_DEVICE_HANDLE    const hDevice,
00487     ADMW_DATA_SAMPLE     * const pSamples,
00488     uint32_t                   const nIndex,
00489     uint32_t                   const nRequested,
00490     uint32_t                 * const pnReturned);
00491 
00492 /*!
00493  * @brief Store the LUT data to persistent memory on the device.
00494  *
00495  * @param[in] hDevice ADMW device context handle
00496  *
00497  * @return Status
00498  *         - #ADMW_SUCCESS Call completed successfully.
00499  *
00500  * @details Instructs the ADMW device to save the current contents of its
00501  *          LUT data buffer, set using @ref admw_SetLutData, to
00502  *          non-volatile memory.
00503  *
00504  * @note No other command must be running when this is called.
00505  * @note Do not power down the device while this command is running.
00506  */
00507 ADMW_RESULT  admw_SaveLutData(
00508     ADMW_DEVICE_HANDLE    const hDevice);
00509 
00510 /*!
00511  * @brief Restore LUT data from persistent memory on the device.
00512  *
00513  * @param[in] hDevice ADMW device context handle
00514  *
00515  * @return Status
00516  *         - #ADMW_SUCCESS Call completed successfully.
00517  *
00518  * @details Instructs the ADMW device to restore the contents of its
00519  *          LUT data, previously stored with @ref admw_SaveLutData, from
00520  *          non-volatile memory.
00521  *
00522  * @note No other command must be running when this is called.
00523  */
00524 ADMW_RESULT  admw_RestoreLutData(
00525     ADMW_DEVICE_HANDLE    const hDevice);
00526 
00527 /*!
00528  * @brief Start the measurement cycles on the device.
00529  *
00530  * @param[in] hDevice          ADMW device context handle
00531  * @param[in] eMeasurementMode Allows a choice of special modes for the
00532  *                             measurement.  See @ref ADMW_MEASUREMENT_MODE
00533  *                             for further information.
00534  *
00535  * @return Status
00536  *         - #ADMW_SUCCESS Call completed successfully.
00537  *
00538  * @details Instructs the ADMW device to start executing measurement cycles
00539  *          according to the current applied configuration settings.  The
00540  *          DATAREADY status signal will be asserted whenever new measurement
00541  *          data is published, according to selected settings.
00542  *          Measurement cycles may be stopped by calling @ref
00543  *          admw_StopMeasurement.
00544  *
00545  * @note No other command must be running when this is called.
00546  */
00547 ADMW_RESULT  admw_StartMeasurement(
00548     ADMW_DEVICE_HANDLE    const hDevice,
00549     ADMW_MEASUREMENT_MODE  const eMeasurementMode);
00550 
00551 /*!
00552  * @brief Stop the measurement cycles on the device.
00553  *
00554  * @param[in] hDevice ADMW device context handle
00555  *
00556  * @return Status
00557  *         - #ADMW_SUCCESS Call completed successfully.
00558  *
00559  * @details Instructs the ADMW device to stop executing measurement cycles.
00560  *          The command may be delayed until the current conversion, if any, has
00561  *          been completed and published.
00562  *
00563  * @note To be used only if a measurement command is currently running.
00564  */
00565 ADMW_RESULT  admw_StopMeasurement(
00566     ADMW_DEVICE_HANDLE    const hDevice);
00567 
00568 /*!
00569  * @brief Run built-in diagnostic checks on the device.
00570  *
00571  * @param[in] hDevice ADMW device context handle
00572  *
00573  * @return Status
00574  *         - #ADMW_SUCCESS Call completed successfully.
00575  *
00576  * @details Instructs the ADMW device to execute its built-in diagnostic
00577  *          tests, on any enabled measurement channels, according to the current
00578  *          applied configuration settings.  Device status registers will be
00579  *          updated to indicate if any errors were detected by the diagnostics.
00580  *
00581  * @note No other command must be running when this is called.
00582  */
00583 ADMW_RESULT  admw_RunDiagnostics(
00584     ADMW_DEVICE_HANDLE    const hDevice);
00585 
00586 /*!
00587  * @brief Run built-in calibration on the device.
00588  *
00589  * @param[in] hDevice ADMW device context handle
00590  *
00591  * @return Status
00592  *         - #ADMW_SUCCESS Call completed successfully.
00593  *
00594  * @details Instructs the ADMW device to execute its self-calibration
00595  *          routines, on any enabled measurement channels, according to the
00596  *          current applied configuration settings.  Device status registers
00597  *          will be updated to indicate if any errors were detected.
00598  *
00599  * @note No other command must be running when this is called.
00600  */
00601 ADMW_RESULT  admw_RunCalibration(
00602     ADMW_DEVICE_HANDLE    const hDevice);
00603 
00604 /*!
00605  * @brief Run built-in digital calibration on the device.
00606  *
00607  * @param[in] hDevice ADMW device context handle
00608  *
00609  * @return Status
00610  *         - #ADMW_SUCCESS Call completed successfully.
00611  *
00612  * @details Instructs the ADMW device to execute its calibration
00613  *          routines, on any enabled digital channels, according to the
00614  *          current applied configuration settings.  Device status registers
00615  *          will be updated to indicate if any errors were detected.
00616  *
00617  * @note No other command must be running when this is called.
00618  */
00619 ADMW_RESULT  admw_RunDigitalCalibration(
00620     ADMW_DEVICE_HANDLE    const hDevice);
00621 
00622 /*!
00623  * @brief Read the current status from the device registers.
00624  *
00625  * @param[in]  hDevice ADMW device context handle
00626  * @param[out] pStatus Pointer to return the status summary obtained from the
00627  *                     device.
00628  *
00629  * @return Status
00630  *         - #ADMW_SUCCESS Call completed successfully.
00631  *
00632  * @details Reads the status registers and extracts the relevant information
00633  *          to return to the caller.
00634  *
00635  * @note This may be called at any time, assuming the device is ready.
00636  */
00637 ADMW_RESULT  admw_GetStatus(
00638     ADMW_DEVICE_HANDLE    const hDevice,
00639     ADMW_STATUS          * const pStatus);
00640 
00641 /*!
00642  * @brief Read measurement data samples from the device registers.
00643  *
00644  * @param[in]  hDevice          ADMW device context handle
00645  * @param[in]  eMeasurementMode Must be set to the same value used for @ref
00646  *                              admw_StartMeasurement().
00647  * @param[out] pSamples         Pointer to return a set of requested data samples.
00648  * @param[in]  nBytesPerSample  The size, in bytes, of each sample.
00649  * @param[in]  nRequested       Number of requested data samples.
00650  * @param[out] pnReturned       Number of valid data samples successfully retrieved.
00651  *
00652  * @return Status
00653  *         - #ADMW_SUCCESS Call completed successfully.
00654  *
00655  * @details Reads the status registers and extracts the relevant information
00656  *          to return to the caller.
00657  *
00658  * @note This is intended to be called only when the DATAREADY status signal
00659  *       is asserted.
00660  */
00661 ADMW_RESULT  admw_GetData(
00662     ADMW_DEVICE_HANDLE    const hDevice,
00663     ADMW_MEASUREMENT_MODE  const eMeasurementMode,
00664     ADMW_DATA_SAMPLE     * const pSamples,
00665     uint8_t                    const nBytesPerSample,
00666     uint32_t                   const nRequested,
00667     uint32_t                 * const pnReturned);
00668 
00669 /*!
00670  * @brief Check if a command is currently running on the device.
00671  *
00672  * @param[in]  hDevice          ADMW device context handle
00673  * @param[out] pbCommandRunning Pointer to return the command running status
00674  *
00675  * @return Status
00676  *         - #ADMW_SUCCESS Call completed successfully.
00677  *
00678  * @details Reads the device status register to check if a command is running.
00679  */
00680 ADMW_RESULT  admw_GetCommandRunningState(
00681     ADMW_DEVICE_HANDLE hDevice,
00682     bool *pbCommandRunning);
00683 
00684 ADMW_RESULT  deviceInformation(ADMW_DEVICE_HANDLE hDevice);
00685 #ifdef __cplusplus
00686 }
00687 #endif
00688 
00689 /*!
00690  * @}
00691  */
00692 
00693 #endif /* _ADMW_API_H__ */