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