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