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