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     uint32_t                      rawValue;
00176     /*!< The raw (unprocessed) value obtained directly from the measurement
00177      *   channel, if available
00178      */
00179     float32_t                     processedValue;
00180     /*!< The processed value obtained from the measurement channel, as a final
00181      *   measurement value, following calibration and linearisation correction,
00182      *   and conversion into an appropriate unit of measurement.
00183      */
00184 
00185 }   ADMW_DATA_SAMPLE ;
00186 
00187 /*! Measurement mode options for the ADMW device.
00188  *  @ref admw_StartMeasurement
00189  */
00190 typedef enum
00191 {
00192     ADMW_MEASUREMENT_MODE_NORMAL  = 0,
00193     /*!< In this mode, normal measurement cycle(s) are executed and data samples
00194      *   are returned with raw measurement values included. */
00195     ADMW_MEASUREMENT_MODE_OMIT_RAW ,
00196     /*!< In this mode, normal measurement cycle(s) are executed and data samples
00197      *   are returned with raw measurement values omitted for efficiency. */
00198 
00199 }   ADMW_MEASUREMENT_MODE ;
00200 
00201 /*! Identifiers for the user configuration slots in persistent memory. */
00202 typedef enum
00203 {
00204     ADMW_FLASH_CONFIG_1,
00205 
00206 }   ADMW_USER_CONFIG_SLOT ;
00207 
00208 
00209 
00210 typedef struct
00211 {
00212     unsigned nDeviceIndex;
00213     ADMW_SPI_HANDLE  hSpi;
00214     ADMW_GPIO_HANDLE  hGpio;
00215 } ADMW_DEVICE_CONTEXT;
00216 
00217 /******************************************************************************
00218  * ADMW High-Level API function prototypes
00219  *****************************************************************************/
00220 
00221 /*!
00222  * @brief Open ADMW device handle and set up communication interface.
00223  *
00224  * @param[in]  nDeviceIndex    Zero-based index number identifying this device
00225  *                             instance.  Note that this will be used to
00226  *                             retrieve a specific device configuration for
00227  *                             this device (see @ref admw_SetConfig
00228  *                             and @ref ADMW_CONFIG)
00229  * @param[in]  pConnectionInfo Host-specific connection details (e.g. SPI, GPIO)
00230  * @param[out] phDevice        Pointer to return an ADMW device handle
00231  *
00232  * @return Status
00233  *         - #ADMW_SUCCESS Call completed successfully.
00234  *         - #ADMW_NO_MEM  Failed to allocate memory resources.
00235  *         - #ADMW_INVALID_DEVICE_NUM Invalid device index specified
00236  *
00237  * @details Configure and initialise the Log interface and the SPI/GPIO
00238  *          communication interface to the ADISense module.
00239  */
00240 ADMW_RESULT  admw_Open(
00241     unsigned                   const nDeviceIndex,
00242     ADMW_CONNECTION      * const pConnectionInfo,
00243     ADMW_DEVICE_HANDLE  * const phDevice);
00244 
00245 /*!
00246  * @brief Close ADMW device context and free resources.
00247  *
00248  * @param[in] hDevice ADMW device context handle
00249  *
00250  * @return Status
00251  *         - #ADMW_SUCCESS Call completed successfully.
00252  */
00253 ADMW_RESULT  admw_Close(
00254     ADMW_DEVICE_HANDLE    const hDevice);
00255 
00256 /*!
00257  * @brief Get the current state of the specified GPIO input signal.
00258  *
00259  * @param[in]  hDevice    ADMW device context handle
00260  * @param[in]  ePinId     GPIO pin to query
00261  * @param[out] pbAsserted Pointer to return the state of the status signal GPIO pin
00262  *
00263  * @return Status
00264  *         - #ADMW_SUCCESS Call completed successfully.
00265  *         - #ADMW_INVALID_DEVICE_NUM Invalid GPIO pin specified.
00266  *
00267  * @details Sets *pbAsserted to true if the status signal is asserted, or false
00268  *          otherwise.
00269  */
00270 ADMW_RESULT  admw_GetGpioState(
00271     ADMW_DEVICE_HANDLE   const hDevice,
00272     ADMW_GPIO_PIN         const ePinId,
00273     bool                  * const pbAsserted);
00274 
00275 /*!
00276  * @brief Register an application-defined callback function for GPIO interrupts
00277  *
00278  * @param[in] hDevice          ADMW context handle (@ref admw_Open)
00279  * @param[in] ePinId           GPIO pin on which to enable/disable interrupts
00280  * @param[in] callbackFunction Function to be called when an interrupt occurs.
00281  *                             Specify NULL here to disable interrupts.
00282  * @param[in] pCallbackParam   Optional opaque parameter passed to the callback
00283  *
00284  * @return Status
00285  *         - #ADMW_SUCCESS Call completed successfully.
00286  *         - #ADMW_INVALID_DEVICE_NUM Invalid GPIO pin specified.
00287  */
00288 ADMW_RESULT  admw_RegisterGpioCallback(
00289     ADMW_DEVICE_HANDLE          const hDevice,
00290     ADMW_GPIO_PIN                const ePinId,
00291     ADMW_GPIO_CALLBACK           const callbackFunction,
00292     void                           * const pCallbackParam);
00293 
00294 /*!
00295  * @brief Trigger a shut down of the device.
00296  *
00297  * @param[in] hDevice ADMW device context handle
00298  *
00299  * @return Status
00300  *         - #ADMW_SUCCESS Call completed successfully.
00301  *
00302  * @details Instructs the ADMW device to initiate a shut down,
00303  *          typically used to conserve power when the device is not
00304  *          in use.  The device may be restarted by calling
00305  *          @ref admw_Reset().  Note that active configuration
00306  *          settings are not preserved during shutdown and must be
00307  *          reloaded after the device has become ready again.
00308  *
00309  * @note No other command must be running when this is called.
00310  */
00311 ADMW_RESULT  admw_Shutdown(
00312     ADMW_DEVICE_HANDLE    const hDevice);
00313 
00314 /*!
00315  * @brief Reset the ADMW device.
00316  *
00317  * @param[in] hDevice ADMW device context handle
00318  *
00319  * @return Status
00320  *         - #ADMW_SUCCESS Call completed successfully.
00321  *
00322  * @details Trigger a hardware-reset of the ADMW device.
00323  *
00324  * @note The device may require several seconds before it is ready for use
00325  *       again. @ref admw_GetDeviceReadyState may be used to check if
00326  *       the device is ready.
00327  */
00328 ADMW_RESULT  admw_Reset(
00329     ADMW_DEVICE_HANDLE    const hDevice);
00330 
00331 /*!
00332  * @brief Check if the device is ready, following power-up or a reset.
00333  *
00334  * @param[in]  hDevice ADMW device context handle
00335  * @param[out] pbReady Pointer to return true if the device is ready, or false
00336  *                     otherwise
00337  *
00338  * @return Status
00339  *         - #ADMW_SUCCESS Call completed successfully.
00340  *
00341  * @details This function attempts to read a fixed-value device register via
00342  *           the communication interface.
00343  */
00344 ADMW_RESULT  admw_GetDeviceReadyState(
00345     ADMW_DEVICE_HANDLE    const hDevice,
00346     bool                   * const pbReady);
00347 
00348 /*!
00349  * @brief Obtain the product ID from the device.
00350  *
00351  * @param[in]  hDevice    ADMW device context handle
00352  * @param[out] pProductId Pointer to return the product ID value
00353  *
00354  * @return Status
00355  *         - #ADMW_SUCCESS Call completed successfully.
00356  *
00357  * @details Reads the product ID registers on the device and returns the value.
00358  */
00359 ADMW_RESULT  admw_GetProductID(
00360     ADMW_DEVICE_HANDLE    const hDevice,
00361     ADMW_PRODUCT_ID      * const pProductId);
00362 
00363 /*!
00364  * @brief Write full configuration settings to the device registers.
00365  *
00366  * @param[in]  hDevice ADMW device context handle
00367  * @param[out] pConfig Pointer to the configuration data structure
00368  *
00369  * @return Status
00370  *         - #ADMW_SUCCESS Call completed successfully.
00371  *
00372  * @details Translates configuration details provided into device-specific
00373  *          register settings and updates device configuration registers.
00374  *
00375  * @note Settings are not applied until admw_ApplyConfigUpdates() is called
00376  */
00377 ADMW_RESULT  admw_SetConfig(
00378     ADMW_DEVICE_HANDLE   const hDevice,
00379     ADMW_CONFIG         * const pConfig);
00380 
00381 /*!
00382  * @brief Apply the configuration settings currently stored in device registers
00383  *
00384  * @param[in] hDevice ADMW device context handle
00385  *
00386  * @return Status
00387  *         - #ADMW_SUCCESS Call completed successfully.
00388  *
00389  * @details Instructs the ADMW device to reload and apply configuration
00390  *          from the device configuration registers.  Changes to configuration
00391  *          registers are ignored by the device until this function is called.
00392  *
00393  * @note No other command must be running when this is called.
00394  */
00395 ADMW_RESULT  admw_ApplyConfigUpdates(
00396     ADMW_DEVICE_HANDLE    const hDevice);
00397 
00398 /*!
00399  * @brief Store the configuration settings to persistent memory on the device.
00400  *
00401  * @param[in] hDevice ADMW device context handle
00402  * @param[in] eSlotId User configuration slot in persistent memory
00403  *
00404  * @return Status
00405  *         - #ADMW_SUCCESS Call completed successfully.
00406  *
00407  * @details Instructs the ADMW device to save the current contents of its
00408  *          device configuration registers to non-volatile memory.
00409  *
00410  * @note No other command must be running when this is called.
00411  * @note Do not power down the device while this command is running.
00412  */
00413 ADMW_RESULT  admw_SaveConfig(
00414     ADMW_DEVICE_HANDLE    const hDevice,
00415     ADMW_USER_CONFIG_SLOT  const eSlotId);
00416 
00417 /*!
00418  * @brief Restore configuration settings from persistent memory on the device.
00419  *
00420  * @param[in] hDevice ADMW device context handle
00421  * @param[in] eSlotId User configuration slot in persistent memory
00422  *
00423  * @return Status
00424  *         - #ADMW_SUCCESS Call completed successfully.
00425  *
00426  * @details Instructs the ADMW device to restore the contents of its
00427  *          device configuration registers from non-volatile memory.
00428  *
00429  * @note No other command must be running when this is called.
00430  */
00431 ADMW_RESULT  admw_RestoreConfig(
00432     ADMW_DEVICE_HANDLE    const hDevice,
00433     ADMW_USER_CONFIG_SLOT  const eSlotId);
00434 
00435 /*!
00436  * @brief Erases the external flash memory.
00437  *
00438  * @param[in] hDevice ADMW device context handle
00439  *
00440  * @return Status
00441  *         - #ADMW_SUCCESS Call completed successfully.
00442  *
00443  * @details Sends the bulk erase instruction to the external flash
00444  *          device. All stored samples are deleted.
00445  *          It is a blocking operation and takes tens of seconds to
00446  *          complete.
00447  *
00448  * @note No other command must be running when this is called.
00449  */
00450 ADMW_RESULT  admw_EraseExternalFlash(
00451     ADMW_DEVICE_HANDLE    const hDevice);
00452 
00453 /*!
00454  * @brief Gets the number of samples stored in the external flash
00455  *        memory.
00456  *
00457  * @param[in] hDevice ADMW device context handle
00458  * @param[in] pSampleCount Address of the return value.
00459  *
00460  * @return Status
00461  *         - #ADMW_SUCCESS Call completed successfully.
00462  *
00463  * @note No other command must be running when this is called.
00464  */
00465 ADMW_RESULT  admw_GetExternalFlashSampleCount(
00466     ADMW_DEVICE_HANDLE    const hDevice,
00467     uint32_t * nSampleCount);
00468 
00469 // DEBUG - TO BE DELETED
00470 ADMW_RESULT  admw_SetExternalFlashIndex(
00471     ADMW_DEVICE_HANDLE    const hDevice,
00472     uint32_t nStartIndex);
00473 
00474 /*!
00475  * @brief Read measurement samples stored in the the external flash memory.
00476  *
00477  * @param[in]  hDevice          ADMW device context handle
00478  * @param[out] pSamples         Pointer to return a set of requested data
00479  *                              samples.
00480  * @param[in]  nStartIndex      Index of first sample to retrieve.
00481  * @param[in]  nBytesPerSample  The size, in bytes, of each sample.
00482  * @param[in]  nRequested       Number of requested data samples.
00483  * @param[out] pnReturned       Number of valid data samples successfully
00484  *                              retrieved.
00485  *
00486  * @return Status
00487  *         - #ADMW_SUCCESS Call completed successfully.
00488  *
00489  * @details Reads the status registers and extracts the relevant information
00490  *          to return to the caller.
00491  *
00492  */
00493 ADMW_RESULT  admw_GetExternalFlashData(
00494     ADMW_DEVICE_HANDLE    const hDevice,
00495     ADMW_DATA_SAMPLE     * const pSamples,
00496     uint32_t                   const nIndex,
00497     uint32_t                   const nRequested,
00498     uint32_t                 * const pnReturned);
00499 
00500 /*!
00501  * @brief Store the LUT data to 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 save the current contents of its
00509  *          LUT data buffer, set using @ref admw_SetLutData, to
00510  *          non-volatile memory.
00511  *
00512  * @note No other command must be running when this is called.
00513  * @note Do not power down the device while this command is running.
00514  */
00515 ADMW_RESULT  admw_SaveLutData(
00516     ADMW_DEVICE_HANDLE    const hDevice);
00517 
00518 /*!
00519  * @brief Restore LUT data from persistent memory on the device.
00520  *
00521  * @param[in] hDevice ADMW device context handle
00522  *
00523  * @return Status
00524  *         - #ADMW_SUCCESS Call completed successfully.
00525  *
00526  * @details Instructs the ADMW device to restore the contents of its
00527  *          LUT data, previously stored with @ref admw_SaveLutData, from
00528  *          non-volatile memory.
00529  *
00530  * @note No other command must be running when this is called.
00531  */
00532 ADMW_RESULT  admw_RestoreLutData(
00533     ADMW_DEVICE_HANDLE    const hDevice);
00534 
00535 /*!
00536  * @brief Start the measurement cycles on the device.
00537  *
00538  * @param[in] hDevice          ADMW device context handle
00539  * @param[in] eMeasurementMode Allows a choice of special modes for the
00540  *                             measurement.  See @ref ADMW_MEASUREMENT_MODE
00541  *                             for further information.
00542  *
00543  * @return Status
00544  *         - #ADMW_SUCCESS Call completed successfully.
00545  *
00546  * @details Instructs the ADMW device to start executing measurement cycles
00547  *          according to the current applied configuration settings.  The
00548  *          DATAREADY status signal will be asserted whenever new measurement
00549  *          data is published, according to selected settings.
00550  *          Measurement cycles may be stopped by calling @ref
00551  *          admw_StopMeasurement.
00552  *
00553  * @note No other command must be running when this is called.
00554  */
00555 ADMW_RESULT  admw_StartMeasurement(
00556     ADMW_DEVICE_HANDLE    const hDevice,
00557     ADMW_MEASUREMENT_MODE  const eMeasurementMode);
00558 
00559 /*!
00560  * @brief Stop the measurement cycles on the device.
00561  *
00562  * @param[in] hDevice ADMW device context handle
00563  *
00564  * @return Status
00565  *         - #ADMW_SUCCESS Call completed successfully.
00566  *
00567  * @details Instructs the ADMW device to stop executing measurement cycles.
00568  *          The command may be delayed until the current conversion, if any, has
00569  *          been completed and published.
00570  *
00571  * @note To be used only if a measurement command is currently running.
00572  */
00573 ADMW_RESULT  admw_StopMeasurement(
00574     ADMW_DEVICE_HANDLE    const hDevice);
00575 
00576 /*!
00577  * @brief Run built-in diagnostic checks 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 built-in diagnostic
00585  *          tests, on any enabled measurement channels, according to the current
00586  *          applied configuration settings.  Device status registers will be
00587  *          updated to indicate if any errors were detected by the diagnostics.
00588  *
00589  * @note No other command must be running when this is called.
00590  */
00591 ADMW_RESULT  admw_RunDiagnostics(
00592     ADMW_DEVICE_HANDLE    const hDevice);
00593 
00594 /*!
00595  * @brief Run built-in 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 self-calibration
00603  *          routines, on any enabled measurement 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_RunCalibration(
00610     ADMW_DEVICE_HANDLE    const hDevice);
00611 
00612 /*!
00613  * @brief Run built-in digital calibration on the device.
00614  *
00615  * @param[in] hDevice ADMW device context handle
00616  *
00617  * @return Status
00618  *         - #ADMW_SUCCESS Call completed successfully.
00619  *
00620  * @details Instructs the ADMW device to execute its calibration
00621  *          routines, on any enabled digital channels, according to the
00622  *          current applied configuration settings.  Device status registers
00623  *          will be updated to indicate if any errors were detected.
00624  *
00625  * @note No other command must be running when this is called.
00626  */
00627 ADMW_RESULT  admw_RunDigitalCalibration(
00628     ADMW_DEVICE_HANDLE    const hDevice);
00629 
00630 /*!
00631  * @brief Read the current status from the device registers.
00632  *
00633  * @param[in]  hDevice ADMW device context handle
00634  * @param[out] pStatus Pointer to return the status summary obtained from the
00635  *                     device.
00636  *
00637  * @return Status
00638  *         - #ADMW_SUCCESS Call completed successfully.
00639  *
00640  * @details Reads the status registers and extracts the relevant information
00641  *          to return to the caller.
00642  *
00643  * @note This may be called at any time, assuming the device is ready.
00644  */
00645 ADMW_RESULT  admw_GetStatus(
00646     ADMW_DEVICE_HANDLE    const hDevice,
00647     ADMW_STATUS          * const pStatus);
00648 
00649 /*!
00650  * @brief Read measurement data samples from the device registers.
00651  *
00652  * @param[in]  hDevice          ADMW device context handle
00653  * @param[in]  eMeasurementMode Must be set to the same value used for @ref
00654  *                              admw_StartMeasurement().
00655  * @param[out] pSamples         Pointer to return a set of requested data samples.
00656  * @param[in]  nBytesPerSample  The size, in bytes, of each sample.
00657  * @param[in]  nRequested       Number of requested data samples.
00658  * @param[out] pnReturned       Number of valid data samples successfully retrieved.
00659  *
00660  * @return Status
00661  *         - #ADMW_SUCCESS Call completed successfully.
00662  *
00663  * @details Reads the status registers and extracts the relevant information
00664  *          to return to the caller.
00665  *
00666  * @note This is intended to be called only when the DATAREADY status signal
00667  *       is asserted.
00668  */
00669 ADMW_RESULT  admw_GetData(
00670     ADMW_DEVICE_HANDLE    const hDevice,
00671     ADMW_MEASUREMENT_MODE  const eMeasurementMode,
00672     ADMW_DATA_SAMPLE     * const pSamples,
00673     uint8_t                    const nBytesPerSample,
00674     uint32_t                   const nRequested,
00675     uint32_t                 * const pnReturned);
00676 
00677 /*!
00678  * @brief Check if a command is currently running on the device.
00679  *
00680  * @param[in]  hDevice          ADMW device context handle
00681  * @param[out] pbCommandRunning Pointer to return the command running status
00682  *
00683  * @return Status
00684  *         - #ADMW_SUCCESS Call completed successfully.
00685  *
00686  * @details Reads the device status register to check if a command is running.
00687  */
00688 ADMW_RESULT  admw_GetCommandRunningState(
00689     ADMW_DEVICE_HANDLE hDevice,
00690     bool *pbCommandRunning);
00691 
00692 ADMW_RESULT  admw1001_sendRun( ADMW_DEVICE_HANDLE   const hDevice);
00693 ADMW_RESULT  deviceInformation(ADMW_DEVICE_HANDLE hDevice);
00694 
00695 #ifdef __cplusplus
00696 }
00697 #endif
00698 
00699 /*!
00700  * @}
00701  */
00702 
00703 #endif /* _ADMW_API_H__ */