Rohan Gurav
ADISense1000 Version 2.1 code base
Fork of
AdiSense1000_V21
by 
Sean Wilson
doc/key_topics.md@19:a6d4bdcffb84, 2018-01-08 (annotated)
- Committer:
- kevin1990
- Date:
- Mon Jan 08 16:32:34 2018 +0000
- Revision:
- 19:a6d4bdcffb84
v1.0_RC4 Release
Who changed what in which revision?
| User | Revision | Line number | New contents of line |
|---|---|---|---|
| kevin1990 | 19:a6d4bdcffb84 | 1 | Key Topics |
| kevin1990 | 19:a6d4bdcffb84 | 2 | ========== |
| kevin1990 | 19:a6d4bdcffb84 | 3 | |
| kevin1990 | 19:a6d4bdcffb84 | 4 | [TOC] |
| kevin1990 | 19:a6d4bdcffb84 | 5 | |
| kevin1990 | 19:a6d4bdcffb84 | 6 | # Register Interface {#registerinterface} |
| kevin1990 | 19:a6d4bdcffb84 | 7 | The ADI Sense module provides a register-style interface for the purpose |
| kevin1990 | 19:a6d4bdcffb84 | 8 | of exchanging configuration, status, and data with the host application |
| kevin1990 | 19:a6d4bdcffb84 | 9 | processor. |
| kevin1990 | 19:a6d4bdcffb84 | 10 | |
| kevin1990 | 19:a6d4bdcffb84 | 11 | ## Overview {#registerinterface_overview} |
| kevin1990 | 19:a6d4bdcffb84 | 12 | The registers can be divided broadly into the following categories: |
| kevin1990 | 19:a6d4bdcffb84 | 13 | * Command input register |
| kevin1990 | 19:a6d4bdcffb84 | 14 | - This special register is used to issue commands to the module. |
| kevin1990 | 19:a6d4bdcffb84 | 15 | - New commands are typically ignored until the running command |
| kevin1990 | 19:a6d4bdcffb84 | 16 | has completed (as indicated via the Status registers) |
| kevin1990 | 19:a6d4bdcffb84 | 17 | * Configuration input registers |
| kevin1990 | 19:a6d4bdcffb84 | 18 | - Configuration registers are used to specify configuration parameters |
| kevin1990 | 19:a6d4bdcffb84 | 19 | for use by the module, typically specifying details such as operating |
| kevin1990 | 19:a6d4bdcffb84 | 20 | mode, sensor information, limits, and many other options. |
| kevin1990 | 19:a6d4bdcffb84 | 21 | - Changes to configuration input registers are typically ignored until a |
| kevin1990 | 19:a6d4bdcffb84 | 22 | command is issued to "apply" the configuration on the device. |
| kevin1990 | 19:a6d4bdcffb84 | 23 | * Status output registers |
| kevin1990 | 19:a6d4bdcffb84 | 24 | - Status information is provided by the module via these read-only registers |
| kevin1990 | 19:a6d4bdcffb84 | 25 | - Dedicated output signals (e.g. ERROR and ALERT) may be linked with this |
| kevin1990 | 19:a6d4bdcffb84 | 26 | status information |
| kevin1990 | 19:a6d4bdcffb84 | 27 | - The host application processor may acknowledge and reset/clear the status |
| kevin1990 | 19:a6d4bdcffb84 | 28 | indicators by reading the relevant status registers. The status indicators |
| kevin1990 | 19:a6d4bdcffb84 | 29 | will be set again if the underlying condition is subsequently detected again |
| kevin1990 | 19:a6d4bdcffb84 | 30 | * Data output registers |
| kevin1990 | 19:a6d4bdcffb84 | 31 | - Measurement data samples produced by the module are typically accessed via |
| kevin1990 | 19:a6d4bdcffb84 | 32 | a FIFO-style register which may be read repeatedly until all available data |
| kevin1990 | 19:a6d4bdcffb84 | 33 | has been consumed. |
| kevin1990 | 19:a6d4bdcffb84 | 34 | - Data samples are provided in a pre-determined format according to the |
| kevin1990 | 19:a6d4bdcffb84 | 35 | measurement mode, and typically comprise a processed measurement value, |
| kevin1990 | 19:a6d4bdcffb84 | 36 | status flags, measurement channel identifier and, optionally, the raw |
| kevin1990 | 19:a6d4bdcffb84 | 37 | (unprocessed) data sample retrieved from the sensor input channel. |
| kevin1990 | 19:a6d4bdcffb84 | 38 | * Keyhole access registers |
| kevin1990 | 19:a6d4bdcffb84 | 39 | - Access to large internal memory regions within the module is typically |
| kevin1990 | 19:a6d4bdcffb84 | 40 | provided via an pair of "keyhole" registers, consisting of an address |
| kevin1990 | 19:a6d4bdcffb84 | 41 | register and a data register. An address (i.e. an starting offset within |
| kevin1990 | 19:a6d4bdcffb84 | 42 | the region) must first be written to the address register, then the |
| kevin1990 | 19:a6d4bdcffb84 | 43 | companion data register may be accessed repeatedly to read/write data to |
| kevin1990 | 19:a6d4bdcffb84 | 44 | the corresponding region. The address is automatically incremented with |
| kevin1990 | 19:a6d4bdcffb84 | 45 | each access to the data register, so that data can be transferred in a |
| kevin1990 | 19:a6d4bdcffb84 | 46 | single burst for efficiency. |
| kevin1990 | 19:a6d4bdcffb84 | 47 | |
| kevin1990 | 19:a6d4bdcffb84 | 48 | # Configuration {#configuration} |
| kevin1990 | 19:a6d4bdcffb84 | 49 | The ADI Sense module is a flexible measurement processor which must be |
| kevin1990 | 19:a6d4bdcffb84 | 50 | configured via the [register interface](@ref #registerinterface) before it |
| kevin1990 | 19:a6d4bdcffb84 | 51 | can be used to acquire data from its external sensor inputs. |
| kevin1990 | 19:a6d4bdcffb84 | 52 | |
| kevin1990 | 19:a6d4bdcffb84 | 53 | ## Overview {#configuration_overview} |
| kevin1990 | 19:a6d4bdcffb84 | 54 | A configuration consists of the following elements: |
| kevin1990 | 19:a6d4bdcffb84 | 55 | * Global configuration register settings, such as: |
| kevin1990 | 19:a6d4bdcffb84 | 56 | - Operating modes |
| kevin1990 | 19:a6d4bdcffb84 | 57 | - Power configuration |
| kevin1990 | 19:a6d4bdcffb84 | 58 | - Measurement cycle timing |
| kevin1990 | 19:a6d4bdcffb84 | 59 | - External reference values |
| kevin1990 | 19:a6d4bdcffb84 | 60 | * Channel-specific register settings, such as: |
| kevin1990 | 19:a6d4bdcffb84 | 61 | - measurement count |
| kevin1990 | 19:a6d4bdcffb84 | 62 | - connected sensor type |
| kevin1990 | 19:a6d4bdcffb84 | 63 | - sensor configuration details |
| kevin1990 | 19:a6d4bdcffb84 | 64 | - settling time |
| kevin1990 | 19:a6d4bdcffb84 | 65 | - filter options |
| kevin1990 | 19:a6d4bdcffb84 | 66 | - threshold limits |
| kevin1990 | 19:a6d4bdcffb84 | 67 | - calibration adjustments |
| kevin1990 | 19:a6d4bdcffb84 | 68 | * Optional user-defined analog sensor linearisation data |
| kevin1990 | 19:a6d4bdcffb84 | 69 | - used to compensate for inherent non-linear characteristics of analog sensors |
| kevin1990 | 19:a6d4bdcffb84 | 70 | - supplied via a Look-Up Table data structure with a specific format |
| kevin1990 | 19:a6d4bdcffb84 | 71 | - allows the user to leverage the data acquisition and processing features |
| kevin1990 | 19:a6d4bdcffb84 | 72 | of the ADI Sense module for use with non-standard or unsupported sensors |
| kevin1990 | 19:a6d4bdcffb84 | 73 | |
| kevin1990 | 19:a6d4bdcffb84 | 74 | ## Configuration data structure {#configuration_data} |
| kevin1990 | 19:a6d4bdcffb84 | 75 | Although the module can be configured and managed directly via the |
| kevin1990 | 19:a6d4bdcffb84 | 76 | [register interface](@ref #registerinterface), the ADI Sense Host Library |
| kevin1990 | 19:a6d4bdcffb84 | 77 | provides a level of abstraction above this which allows a more simplified |
| kevin1990 | 19:a6d4bdcffb84 | 78 | programming paradigm for the device. |
| kevin1990 | 19:a6d4bdcffb84 | 79 | |
| kevin1990 | 19:a6d4bdcffb84 | 80 | A single C-language configuration data structure can be used to define all |
| kevin1990 | 19:a6d4bdcffb84 | 81 | configuration values for the ADI Sense module. This can be passed to the |
| kevin1990 | 19:a6d4bdcffb84 | 82 | relevant ADI Sense Host Library API functions, which will do the work of |
| kevin1990 | 19:a6d4bdcffb84 | 83 | translating the configuration details into the appropriate register values |
| kevin1990 | 19:a6d4bdcffb84 | 84 | and sending them to the module via its host communication interface. |
| kevin1990 | 19:a6d4bdcffb84 | 85 | |
| kevin1990 | 19:a6d4bdcffb84 | 86 | The [examples](doc/examples.md) provided with the ADI Sense Host Library |
| kevin1990 | 19:a6d4bdcffb84 | 87 | demonstrate this configuration method. Individual configurations are stored |
| kevin1990 | 19:a6d4bdcffb84 | 88 | and compiled as .c files, and a configuration may be selected and loaded by |
| kevin1990 | 19:a6d4bdcffb84 | 89 | the application code. Note that only the essential configuration fields are |
| kevin1990 | 19:a6d4bdcffb84 | 90 | filled, depending on the specific sensor configuration and operating mode |
| kevin1990 | 19:a6d4bdcffb84 | 91 | required. |
| kevin1990 | 19:a6d4bdcffb84 | 92 | |
| kevin1990 | 19:a6d4bdcffb84 | 93 | ## Loading and Applying a configuration {#configuration_loading} |
| kevin1990 | 19:a6d4bdcffb84 | 94 | Configuration data must first be loaded via the @ref adi_sense_SetConfig API |
| kevin1990 | 19:a6d4bdcffb84 | 95 | function - which updates the registers on the module according to the supplied |
| kevin1990 | 19:a6d4bdcffb84 | 96 | configuration details - and then applied by calling the @ref |
| kevin1990 | 19:a6d4bdcffb84 | 97 | adi_sense_ApplyConfigUpdates function which issues a special command to instruct |
| kevin1990 | 19:a6d4bdcffb84 | 98 | the module to apply the new configuration. If user-defined linearisation data |
| kevin1990 | 19:a6d4bdcffb84 | 99 | is also required, this must also be loaded via the @ref |
| kevin1990 | 19:a6d4bdcffb84 | 100 | adi_sense_1000_SetLutData function _before_ applying the new configuration. |
| kevin1990 | 19:a6d4bdcffb84 | 101 | |
| kevin1990 | 19:a6d4bdcffb84 | 102 | To avoid loading the configuration details to the module every time it is |
| kevin1990 | 19:a6d4bdcffb84 | 103 | powered on, it is possible to save it to non-volatile memory on the module |
| kevin1990 | 19:a6d4bdcffb84 | 104 | using @ref adi_sense_SaveConfig and @ref adi_sense_SaveLutData. The saved |
| kevin1990 | 19:a6d4bdcffb84 | 105 | configuration is automatically restored by default when the module is |
| kevin1990 | 19:a6d4bdcffb84 | 106 | subsequently reset or powered on, and can also be reloaded on demand if required |
| kevin1990 | 19:a6d4bdcffb84 | 107 | using the @ref adi_sense_RestoreConfig and @ref adi_sense_RestoreLutData |
| kevin1990 | 19:a6d4bdcffb84 | 108 | functions. Note that, in all cases, @ref adi_sense_ApplyConfigUpdates _must_ |
| kevin1990 | 19:a6d4bdcffb84 | 109 | be called to instruct the module to apply the configuration before will be used. |
| kevin1990 | 19:a6d4bdcffb84 | 110 | |
| kevin1990 | 19:a6d4bdcffb84 | 111 | Once a valid configuration has been loaded and applied, the user may issue |
| kevin1990 | 19:a6d4bdcffb84 | 112 | commands to the module to initiate measurement cycles, internal calibration, or |
| kevin1990 | 19:a6d4bdcffb84 | 113 | diagnostic routines (all of which depend on a valid configuration being applied |
| kevin1990 | 19:a6d4bdcffb84 | 114 | in advance). |
| kevin1990 | 19:a6d4bdcffb84 | 115 | |
| kevin1990 | 19:a6d4bdcffb84 | 116 | ## Configuration errors {#configuration_errors} |
| kevin1990 | 19:a6d4bdcffb84 | 117 | Attempts to load invalid configuration details will be flagged via the relevant |
| kevin1990 | 19:a6d4bdcffb84 | 118 | status registers and signals. After calling @ref adi_sense_ApplyConfigUpdates, |
| kevin1990 | 19:a6d4bdcffb84 | 119 | it is advisable to check the status of the module by calling @ref |
| kevin1990 | 19:a6d4bdcffb84 | 120 | adi_sense_GetStatus and examining the relevant status information returned from |
| kevin1990 | 19:a6d4bdcffb84 | 121 | the module. Subsequent commands issued to the module may not execute correctly |
| kevin1990 | 19:a6d4bdcffb84 | 122 | in the presence of unresolved configuration errors. |
| kevin1990 | 19:a6d4bdcffb84 | 123 | |
| kevin1990 | 19:a6d4bdcffb84 | 124 | # Measurement Cycles {#measurementcycles} |
| kevin1990 | 19:a6d4bdcffb84 | 125 | ## Overview {#measurementcycles_overview} |
| kevin1990 | 19:a6d4bdcffb84 | 126 | Conversions are carried out sequentially across each of the enabled channels in |
| kevin1990 | 19:a6d4bdcffb84 | 127 | a predictable pattern which has a defined order and user-specified number of |
| kevin1990 | 19:a6d4bdcffb84 | 128 | conversions per channel. This is typically referred to as the _Measurement |
| kevin1990 | 19:a6d4bdcffb84 | 129 | Sequence_. |
| kevin1990 | 19:a6d4bdcffb84 | 130 | |
| kevin1990 | 19:a6d4bdcffb84 | 131 | A _Measurement Cycle_ essentially consists of a single _Measurement Sequence_ |
| kevin1990 | 19:a6d4bdcffb84 | 132 | which may be repeated at specified time intervals. |
| kevin1990 | 19:a6d4bdcffb84 | 133 | |
| kevin1990 | 19:a6d4bdcffb84 | 134 | The configuration parameters required to define the Measurement Cycle and |
| kevin1990 | 19:a6d4bdcffb84 | 135 | Sequence are as follows: |
| kevin1990 | 19:a6d4bdcffb84 | 136 | * Cycle interval time (specified in microseconds/milliseconds/seconds) |
| kevin1990 | 19:a6d4bdcffb84 | 137 | * For each enabled sensor input channel: |
| kevin1990 | 19:a6d4bdcffb84 | 138 | - Number of conversions-per-cycle |
| kevin1990 | 19:a6d4bdcffb84 | 139 | - Extra settling time (specified in microseconds) |
| kevin1990 | 19:a6d4bdcffb84 | 140 | |
| kevin1990 | 19:a6d4bdcffb84 | 141 | In addition to the cycle time, the following operating modes dictate when and |
| kevin1990 | 19:a6d4bdcffb84 | 142 | how many cycles should be executed: |
| kevin1990 | 19:a6d4bdcffb84 | 143 | * **Single-Cycle Mode** |
| kevin1990 | 19:a6d4bdcffb84 | 144 | - Executes a single Measurement Cycle and stops |
| kevin1990 | 19:a6d4bdcffb84 | 145 | * **Continuous Mode** |
| kevin1990 | 19:a6d4bdcffb84 | 146 | - Executes Measurement Cycles continuously until stopped by the host |
| kevin1990 | 19:a6d4bdcffb84 | 147 | application processor |
| kevin1990 | 19:a6d4bdcffb84 | 148 | * **Multi-Cycle Mode** |
| kevin1990 | 19:a6d4bdcffb84 | 149 | - Executes a specified number (burst) of Measurement Cycles and stores the |
| kevin1990 | 19:a6d4bdcffb84 | 150 | results in a buffer for retrieval by the host. |
| kevin1990 | 19:a6d4bdcffb84 | 151 | - Repeats this indefinitely at specified intervals (multi-cycle burst |
| kevin1990 | 19:a6d4bdcffb84 | 152 | interval) until stopped by the host application processor. |
| kevin1990 | 19:a6d4bdcffb84 | 153 | |
| kevin1990 | 19:a6d4bdcffb84 | 154 | ## Executing Measurement Cycles {#measurementcycles_executing} |
| kevin1990 | 19:a6d4bdcffb84 | 155 | Once a valid configuration is loaded (see @ref #configuration), |
| kevin1990 | 19:a6d4bdcffb84 | 156 | Measurement Cycles are initiated by the host application processor via @ref |
| kevin1990 | 19:a6d4bdcffb84 | 157 | adi_sense_StartMeasurement, and may be stopped if necessary via @ref |
| kevin1990 | 19:a6d4bdcffb84 | 158 | adi_sense_StopMeasurement. These functions issue the relevant commands to the |
| kevin1990 | 19:a6d4bdcffb84 | 159 | ADI Sense module via its dedicate command register. |
| kevin1990 | 19:a6d4bdcffb84 | 160 | |
| kevin1990 | 19:a6d4bdcffb84 | 161 | Certain auxiliary tasks may also be carried out internally by the module on a |
| kevin1990 | 19:a6d4bdcffb84 | 162 | per-cycle basis, such as Calibration and Diagnostics. These are discussed in |
| kevin1990 | 19:a6d4bdcffb84 | 163 | in later sections below. |
| kevin1990 | 19:a6d4bdcffb84 | 164 | |
| kevin1990 | 19:a6d4bdcffb84 | 165 | ## Sequence Order {#measurementcycles_sequence} |
| kevin1990 | 19:a6d4bdcffb84 | 166 | The sequence is constructed according to which channels are enabled and how many |
| kevin1990 | 19:a6d4bdcffb84 | 167 | measurements must be performed per channel. The arrangement is similar to |
| kevin1990 | 19:a6d4bdcffb84 | 168 | round-robin scheduling - a measurement is carried out on each enabled channel, in |
| kevin1990 | 19:a6d4bdcffb84 | 169 | ascending channel order, and then the loop is repeated until the requested number |
| kevin1990 | 19:a6d4bdcffb84 | 170 | of measurements on each channel has been satisfied. |
| kevin1990 | 19:a6d4bdcffb84 | 171 | |
| kevin1990 | 19:a6d4bdcffb84 | 172 | For example, lets say channels [0, 3, 4, 5] are enabled, with measurementsPerCycle |
| kevin1990 | 19:a6d4bdcffb84 | 173 | set as follows: |
| kevin1990 | 19:a6d4bdcffb84 | 174 | |
| kevin1990 | 19:a6d4bdcffb84 | 175 | channelId | measurementsPerCycle |
| kevin1990 | 19:a6d4bdcffb84 | 176 | --------- | -------------------- |
| kevin1990 | 19:a6d4bdcffb84 | 177 | CJC_1 | 4 |
| kevin1990 | 19:a6d4bdcffb84 | 178 | SENSOR_0 | 2 |
| kevin1990 | 19:a6d4bdcffb84 | 179 | I2C_1 | 3 |
| kevin1990 | 19:a6d4bdcffb84 | 180 | SPI_0 | 1 |
| kevin1990 | 19:a6d4bdcffb84 | 181 | |
| kevin1990 | 19:a6d4bdcffb84 | 182 | The length of the sequence would be 10 measurements in total, and the order in |
| kevin1990 | 19:a6d4bdcffb84 | 183 | which the channel measurements appear in the sequence would look like this: |
| kevin1990 | 19:a6d4bdcffb84 | 184 | |
| kevin1990 | 19:a6d4bdcffb84 | 185 | | **CJC_1** | **SENSOR_0** | **I2C_1** | **SPI_0** | **CJC_1** | **SENSOR_0** | **I2C_1** | **CJC_1** | **I2C_1** | **CJC_1** | |
| kevin1990 | 19:a6d4bdcffb84 | 186 | |
| kevin1990 | 19:a6d4bdcffb84 | 187 | When measurement data samples are retrieved from the ADI Sense by the host |
| kevin1990 | 19:a6d4bdcffb84 | 188 | application, this is the order in which those data samples will appear. |
| kevin1990 | 19:a6d4bdcffb84 | 189 | |
| kevin1990 | 19:a6d4bdcffb84 | 190 | The ADI Sense 1000 provides up to 13 measurement channels, and allows a maximum |
| kevin1990 | 19:a6d4bdcffb84 | 191 | measurementsPerCycle of 128, so a single cycle can produce a maximum of 1664 |
| kevin1990 | 19:a6d4bdcffb84 | 192 | measurements. In other words, the maximum length of the sequence is 1664. |
| kevin1990 | 19:a6d4bdcffb84 | 193 | |
| kevin1990 | 19:a6d4bdcffb84 | 194 | ## Sequence Timing {#measurementcycles_timing} |
| kevin1990 | 19:a6d4bdcffb84 | 195 | The timing of each measurement within the sequence depends on a number of factors: |
| kevin1990 | 19:a6d4bdcffb84 | 196 | * **Settling time** |
| kevin1990 | 19:a6d4bdcffb84 | 197 | - A settling time is applied when switching between each channel (unless only |
| kevin1990 | 19:a6d4bdcffb84 | 198 | a single channel in the sequence), particularly to allow the analog |
| kevin1990 | 19:a6d4bdcffb84 | 199 | front-end circuit to stabilise before a conversion is performed. |
| kevin1990 | 19:a6d4bdcffb84 | 200 | - Each channel is subject to a minimum settling time (e.g. 500 microseconds) |
| kevin1990 | 19:a6d4bdcffb84 | 201 | - Additional settling time can be configured per-channel if required |
| kevin1990 | 19:a6d4bdcffb84 | 202 | - As the analog sensor channels are multi-plexed into a single physical input |
| kevin1990 | 19:a6d4bdcffb84 | 203 | channel, with different front-end circuit configurations for each, the |
| kevin1990 | 19:a6d4bdcffb84 | 204 | settling and conversion of the analog channels must be done one-at-a-time in |
| kevin1990 | 19:a6d4bdcffb84 | 205 | series. Their settling time starts only when the channel is reached in the |
| kevin1990 | 19:a6d4bdcffb84 | 206 | sequence. |
| kevin1990 | 19:a6d4bdcffb84 | 207 | - Digital sensors operate independently, and so are activated in parallel to |
| kevin1990 | 19:a6d4bdcffb84 | 208 | other sensors. Consequently, their settling time may start at the start of |
| kevin1990 | 19:a6d4bdcffb84 | 209 | a cycle, or immediately after a previous conversion result has been obtained |
| kevin1990 | 19:a6d4bdcffb84 | 210 | from the sensor. |
| kevin1990 | 19:a6d4bdcffb84 | 211 | * **Conversion time** |
| kevin1990 | 19:a6d4bdcffb84 | 212 | - Once the settling time has passed, a conversion is initiated to obtain a raw |
| kevin1990 | 19:a6d4bdcffb84 | 213 | measurement value from the sensor input. |
| kevin1990 | 19:a6d4bdcffb84 | 214 | - The time required for the conversion may be influenced by factors such as |
| kevin1990 | 19:a6d4bdcffb84 | 215 | filter configuration (in the case of analog channels) or specific digital |
| kevin1990 | 19:a6d4bdcffb84 | 216 | sensor performance characteristics and configuration options. |
| kevin1990 | 19:a6d4bdcffb84 | 217 | * **Processing time** |
| kevin1990 | 19:a6d4bdcffb84 | 218 | - Once the raw conversion result is obtained, it is subjected to further |
| kevin1990 | 19:a6d4bdcffb84 | 219 | processing to apply correction for non-linear sensors, calibration |
| kevin1990 | 19:a6d4bdcffb84 | 220 | adjustments, and conversion into standard measurement units |
| kevin1990 | 19:a6d4bdcffb84 | 221 | - The processing time varies depending on the sensor type and correction |
| kevin1990 | 19:a6d4bdcffb84 | 222 | algorithms to be applied, but a standard budget of processing time (e.g. |
| kevin1990 | 19:a6d4bdcffb84 | 223 | 500 microseconds) is allocated to each channel to produce consistent and |
| kevin1990 | 19:a6d4bdcffb84 | 224 | predictable time separation between the measurement results. |
| kevin1990 | 19:a6d4bdcffb84 | 225 | |
| kevin1990 | 19:a6d4bdcffb84 | 226 | So, to summarise, the distinct phases for each measurement on each channel |
| kevin1990 | 19:a6d4bdcffb84 | 227 | typically look like this: |
| kevin1990 | 19:a6d4bdcffb84 | 228 | |
| kevin1990 | 19:a6d4bdcffb84 | 229 | **settling** > **conversion** > **processing** > **publishing** |
| kevin1990 | 19:a6d4bdcffb84 | 230 | |
| kevin1990 | 19:a6d4bdcffb84 | 231 | Taking the sequence example in the previous section, let's assume a base |
| kevin1990 | 19:a6d4bdcffb84 | 232 | settling time (_Ts_) and processing time (_Tp_) of 500 microseconds for each channel |
| kevin1990 | 19:a6d4bdcffb84 | 233 | and the following variable timing parameters _Te_ and _Tc_ (in units of microseconds): |
| kevin1990 | 19:a6d4bdcffb84 | 234 | |
| kevin1990 | 19:a6d4bdcffb84 | 235 | channelId | extraSettlingTime (_Te_) | conversionTime (_Tc_) | sum (_Ts_ + _Te_ + _Tc_ + _Tp_) | measurementsPerCycle | total |
| kevin1990 | 19:a6d4bdcffb84 | 236 | --------- | ------------------------ | --------------------- | ------------------------------- | -------------------- | ----- |
| kevin1990 | 19:a6d4bdcffb84 | 237 | CJC_1 | 4000 | 50000 | 55000 | 4 | 220000 |
| kevin1990 | 19:a6d4bdcffb84 | 238 | SENSOR_0 | 1000 | 50000 | 52000 | 2 | 104000 |
| kevin1990 | 19:a6d4bdcffb84 | 239 | I2C_1 | 20000 | 1000 | 22000 | 3 | 66000 |
| kevin1990 | 19:a6d4bdcffb84 | 240 | SPI_0 | 0 | 800 | 1800 | 1 | 1800 |
| kevin1990 | 19:a6d4bdcffb84 | 241 | |
| kevin1990 | 19:a6d4bdcffb84 | 242 | To clarify: _Te_ above comes directly from the channel configuration. _Tc_, however, |
| kevin1990 | 19:a6d4bdcffb84 | 243 | is dictated by the sensor and its configuration. |
| kevin1990 | 19:a6d4bdcffb84 | 244 | |
| kevin1990 | 19:a6d4bdcffb84 | 245 | The minimum time required for the cycle to complete is, in the above example, |
| kevin1990 | 19:a6d4bdcffb84 | 246 | 391800 microseconds. |
| kevin1990 | 19:a6d4bdcffb84 | 247 | |
| kevin1990 | 19:a6d4bdcffb84 | 248 | If the selected operating mode is Continuous or Multi-Cycle mode, the |
| kevin1990 | 19:a6d4bdcffb84 | 249 | configuration must also specify the interval between successive cycles |
| kevin1990 | 19:a6d4bdcffb84 | 250 | (cycleInterval). If this is less than the actual time required to |
| kevin1990 | 19:a6d4bdcffb84 | 251 | complete the cycle, the next cycle will start immediately after the |
| kevin1990 | 19:a6d4bdcffb84 | 252 | completion of the previous one; if it is more, there will be a delay |
| kevin1990 | 19:a6d4bdcffb84 | 253 | until the next cycle is started. |
| kevin1990 | 19:a6d4bdcffb84 | 254 | |
| kevin1990 | 19:a6d4bdcffb84 | 255 | ## Measurement Results storage and retrieval {#measurementcycles_publishing} |
| kevin1990 | 19:a6d4bdcffb84 | 256 | As part of module configuration, a data-ready mode must be selected to decide |
| kevin1990 | 19:a6d4bdcffb84 | 257 | how measurements results are made available and retained for consuming by the |
| kevin1990 | 19:a6d4bdcffb84 | 258 | host application processor: |
| kevin1990 | 19:a6d4bdcffb84 | 259 | |
| kevin1990 | 19:a6d4bdcffb84 | 260 | * **Per-Conversion** |
| kevin1990 | 19:a6d4bdcffb84 | 261 | - In this mode, each measurement result (a.k.a. data sample) is made available |
| kevin1990 | 19:a6d4bdcffb84 | 262 | as soon as it is ready. |
| kevin1990 | 19:a6d4bdcffb84 | 263 | - Only a single result is stored, and it is overwritten when the next |
| kevin1990 | 19:a6d4bdcffb84 | 264 | measurement result becomes ready. Only the latest result is retained. |
| kevin1990 | 19:a6d4bdcffb84 | 265 | - The host application processor must, therefore, consume each single |
| kevin1990 | 19:a6d4bdcffb84 | 266 | measurement result (by reading the DATA_FIFO register) as soon as the |
| kevin1990 | 19:a6d4bdcffb84 | 267 | result becomes available. |
| kevin1990 | 19:a6d4bdcffb84 | 268 | * **Per-Cycle** |
| kevin1990 | 19:a6d4bdcffb84 | 269 | - In this mode, the measurement results from a full cycle (10 data samples, |
| kevin1990 | 19:a6d4bdcffb84 | 270 | in the example above) are made available only when the measurement cycle is |
| kevin1990 | 19:a6d4bdcffb84 | 271 | complete. |
| kevin1990 | 19:a6d4bdcffb84 | 272 | - The results are overwritten when the next measurement cycle (if any) |
| kevin1990 | 19:a6d4bdcffb84 | 273 | is completed. |
| kevin1990 | 19:a6d4bdcffb84 | 274 | - The host application processor must consume the measurement results in a |
| kevin1990 | 19:a6d4bdcffb84 | 275 | batch as soon as they become available. |
| kevin1990 | 19:a6d4bdcffb84 | 276 | * **Per-Multicycle-Burst** |
| kevin1990 | 19:a6d4bdcffb84 | 277 | - In this mode, the measurement results from a burst of measurement cycles |
| kevin1990 | 19:a6d4bdcffb84 | 278 | are made available only when thise measurement cycles are completed. |
| kevin1990 | 19:a6d4bdcffb84 | 279 | - The results are overwritten when the next burst of measurement cycles |
| kevin1990 | 19:a6d4bdcffb84 | 280 | are completed. |
| kevin1990 | 19:a6d4bdcffb84 | 281 | - The host application processor must consume the measurement results in a |
| kevin1990 | 19:a6d4bdcffb84 | 282 | batch as soon as they become available. |
| kevin1990 | 19:a6d4bdcffb84 | 283 | - Note that this data-ready mode is only available when the Multi-Cycle |
| kevin1990 | 19:a6d4bdcffb84 | 284 | operating mode is also selected. |
| kevin1990 | 19:a6d4bdcffb84 | 285 | |
| kevin1990 | 19:a6d4bdcffb84 | 286 | When new measurement results are ready for retrieval, the DRDY output signal |
| kevin1990 | 19:a6d4bdcffb84 | 287 | is asserted. The host application may check this signal continuously, or attach |
| kevin1990 | 19:a6d4bdcffb84 | 288 | an interrupt notification to this signal, to ensure that measurement results are |
| kevin1990 | 19:a6d4bdcffb84 | 289 | retrieved in a timely fashion before they are subsequently overwritten by the |
| kevin1990 | 19:a6d4bdcffb84 | 290 | next conversion/cycle. Alternatively, the host application may also read the |
| kevin1990 | 19:a6d4bdcffb84 | 291 | STATUS register to check the DRDY status indicator. |
| kevin1990 | 19:a6d4bdcffb84 | 292 | |
| kevin1990 | 19:a6d4bdcffb84 | 293 | The ADI Sense Host Library API provides the following functions which are |
| kevin1990 | 19:a6d4bdcffb84 | 294 | relevant for data retrieval: |
| kevin1990 | 19:a6d4bdcffb84 | 295 | * @ref adi_sense_RegisterGpioCallback for recieving DRDY interrupt notifications |
| kevin1990 | 19:a6d4bdcffb84 | 296 | * @ref adi_sense_GetGpioState for polling the state of the DRDY signal |
| kevin1990 | 19:a6d4bdcffb84 | 297 | * @ref adi_sense_GetStatus for reading the module status registers |
| kevin1990 | 19:a6d4bdcffb84 | 298 | * @ref adi_sense_GetData for retrieveing the measurement results from the module |
| kevin1990 | 19:a6d4bdcffb84 | 299 | |
| kevin1990 | 19:a6d4bdcffb84 | 300 | The @ref adi_sense_1000_GetDataReadyModeInfo API function, specific to the ADI |
| kevin1990 | 19:a6d4bdcffb84 | 301 | Sense 1000, is also useful for obtaining information on the number of |
| kevin1990 | 19:a6d4bdcffb84 | 302 | measurement results to expect when the DRDY indicator is asserted, based on the |
| kevin1990 | 19:a6d4bdcffb84 | 303 | operating and data-ready mode configuration settings currently set in the module |
| kevin1990 | 19:a6d4bdcffb84 | 304 | registers. |
| kevin1990 | 19:a6d4bdcffb84 | 305 | |
| kevin1990 | 19:a6d4bdcffb84 | 306 | # Calibration {#calibration} |
| kevin1990 | 19:a6d4bdcffb84 | 307 | The ADI Sense module incorporates a number of calibration measures to ensure |
| kevin1990 | 19:a6d4bdcffb84 | 308 | the accuracy of measurement results, described in the following sections. These |
| kevin1990 | 19:a6d4bdcffb84 | 309 | mostly pertain to the analog measurement channels, but some provisions are also |
| kevin1990 | 19:a6d4bdcffb84 | 310 | included for calibration of digital sensors. |
| kevin1990 | 19:a6d4bdcffb84 | 311 | |
| kevin1990 | 19:a6d4bdcffb84 | 312 | ## Factory calibration {#calibration_factory} |
| kevin1990 | 19:a6d4bdcffb84 | 313 | Calibration is performed during factory production for error introduced by |
| kevin1990 | 19:a6d4bdcffb84 | 314 | components (e.g. resistors, switches) present on the signal paths of the |
| kevin1990 | 19:a6d4bdcffb84 | 315 | module's analog front-end. Calibration offset and gain values are calculated |
| kevin1990 | 19:a6d4bdcffb84 | 316 | and stored in non-volatile memory within the module as part of the production |
| kevin1990 | 19:a6d4bdcffb84 | 317 | process. These are applied automatically without intervention from the host |
| kevin1990 | 19:a6d4bdcffb84 | 318 | application. |
| kevin1990 | 19:a6d4bdcffb84 | 319 | |
| kevin1990 | 19:a6d4bdcffb84 | 320 | ## Internal auto-calibration {#calibration_internal} |
| kevin1990 | 19:a6d4bdcffb84 | 321 | The high-accuracy ADC incorporated within the ADI Sense module includes |
| kevin1990 | 19:a6d4bdcffb84 | 322 | internal calibration functions to assist in removing offset or gain errors |
| kevin1990 | 19:a6d4bdcffb84 | 323 | internal to that ADC. As this is a time-consuming process, it is invoked |
| kevin1990 | 19:a6d4bdcffb84 | 324 | only in the following circumstances: |
| kevin1990 | 19:a6d4bdcffb84 | 325 | * The host application issues a self-calibration command (@ref |
| kevin1990 | 19:a6d4bdcffb84 | 326 | adi_sense_RunCalibration) |
| kevin1990 | 19:a6d4bdcffb84 | 327 | * The host application updates the module configuration and the module |
| kevin1990 | 19:a6d4bdcffb84 | 328 | determines, based on the configuration changes, that re-calibration is |
| kevin1990 | 19:a6d4bdcffb84 | 329 | required. In this case, the calibration is carried out at the point |
| kevin1990 | 19:a6d4bdcffb84 | 330 | where the new configuration settings are applied (@ref |
| kevin1990 | 19:a6d4bdcffb84 | 331 | adi_sense_ApplyConfigUpdates) |
| kevin1990 | 19:a6d4bdcffb84 | 332 | |
| kevin1990 | 19:a6d4bdcffb84 | 333 | In all cases, a valid configuration must be set and it used as part of the |
| kevin1990 | 19:a6d4bdcffb84 | 334 | calibration process. External sensors and reference circuits must be |
| kevin1990 | 19:a6d4bdcffb84 | 335 | connected for calibration to work correctly. |
| kevin1990 | 19:a6d4bdcffb84 | 336 | |
| kevin1990 | 19:a6d4bdcffb84 | 337 | ## User calibration {#calibration_user} |
| kevin1990 | 19:a6d4bdcffb84 | 338 | Additional gain and offset correction parameters may be specified per-channel as |
| kevin1990 | 19:a6d4bdcffb84 | 339 | part of the module configuration. These are applied as a final step to each |
| kevin1990 | 19:a6d4bdcffb84 | 340 | measurement result from the channel during the final stages of processing before |
| kevin1990 | 19:a6d4bdcffb84 | 341 | the data sample is made available to the host processor. |
| kevin1990 | 19:a6d4bdcffb84 | 342 | |
| kevin1990 | 19:a6d4bdcffb84 | 343 | # Diagnostics {#diagnostics} |
| kevin1990 | 19:a6d4bdcffb84 | 344 | The ADC within the ADI Sense module includes a range of sophisticated diagnostic |
| kevin1990 | 19:a6d4bdcffb84 | 345 | features to automatically detect error conditions such as under-/over-voltage on |
| kevin1990 | 19:a6d4bdcffb84 | 346 | analog input signals, supply voltage errors, reference detection errors and more. |
| kevin1990 | 19:a6d4bdcffb84 | 347 | These are enabled by default and, if triggered, will result in an ERROR or ALERT |
| kevin1990 | 19:a6d4bdcffb84 | 348 | signal being asserted by the module. Diagnostic status can be queried via the |
| kevin1990 | 19:a6d4bdcffb84 | 349 | module status registers (@ref adi_sense_GetStatus). |
| kevin1990 | 19:a6d4bdcffb84 | 350 | |
| kevin1990 | 19:a6d4bdcffb84 | 351 | Additional diagnostic tests may be executed by the module to detect additional |
| kevin1990 | 19:a6d4bdcffb84 | 352 | error conditions such as a disconnected or mis-wired sensor. These tests are |
| kevin1990 | 19:a6d4bdcffb84 | 353 | typically time-consuming, and so are carried out only if selected by the user: |
| kevin1990 | 19:a6d4bdcffb84 | 354 | * Sensor diagnostics may be requested by executing a dedicated diagnostics |
| kevin1990 | 19:a6d4bdcffb84 | 355 | command (@ref adi_sense_RunDiagnostics) |
| kevin1990 | 19:a6d4bdcffb84 | 356 | * Sensor diagnostics may be optionally executed at the start of each measurement |
| kevin1990 | 19:a6d4bdcffb84 | 357 | cycle, at a frequency determined by the user through the configuration |
| kevin1990 | 19:a6d4bdcffb84 | 358 | parameters (see @ref ADI_SENSE_1000_DIAGNOSTICS_CONFIG) |
| kevin1990 | 19:a6d4bdcffb84 | 359 | |
| kevin1990 | 19:a6d4bdcffb84 | 360 | # Sensor Linearisation {#linearisation} |
| kevin1990 | 19:a6d4bdcffb84 | 361 | Analog sensors typically produce an output which is not completely linear or |
| kevin1990 | 19:a6d4bdcffb84 | 362 | directly proportional with respect to their input. Different sensor types |
| kevin1990 | 19:a6d4bdcffb84 | 363 | generally have different linearity characteristics, each requiring different |
| kevin1990 | 19:a6d4bdcffb84 | 364 | correction methods or coefficients for accurate translation of the sensor output |
| kevin1990 | 19:a6d4bdcffb84 | 365 | back to the corresponding input. Typical methods include use of linearisation |
| kevin1990 | 19:a6d4bdcffb84 | 366 | formulae (e.g. polynomial equations with variable coefficients), or tables of |
| kevin1990 | 19:a6d4bdcffb84 | 367 | sample input values and their corresponding outputs which can be used with |
| kevin1990 | 19:a6d4bdcffb84 | 368 | interpolation to perform the translation. |
| kevin1990 | 19:a6d4bdcffb84 | 369 | |
| kevin1990 | 19:a6d4bdcffb84 | 370 | The ADI Sense module performs linearisation and calibration correction of the |
| kevin1990 | 19:a6d4bdcffb84 | 371 | analog sensor measurements, and incorporates the linearisation functions |
| kevin1990 | 19:a6d4bdcffb84 | 372 | complete with coefficients or translation tables for a range of supported sensor |
| kevin1990 | 19:a6d4bdcffb84 | 373 | types. On the ADI Sense 1000, for example, measurement results from any |
| kevin1990 | 19:a6d4bdcffb84 | 374 | [sensor types](@ref ADI_SENSE_1000_ADC_SENSOR_TYPE) named with the |
| kevin1990 | 19:a6d4bdcffb84 | 375 | "_L1" suffix or with a specific sensor model name (e.g. @ref |
| kevin1990 | 19:a6d4bdcffb84 | 376 | ADI_SENSE_1000_ADC_SENSOR_VOLTAGE_PRESSURE_AMPHENOL_NPA300X) will be |
| kevin1990 | 19:a6d4bdcffb84 | 377 | automatically linearised using built-in linearisation functions and coefficients |
| kevin1990 | 19:a6d4bdcffb84 | 378 | or translation tables. |
| kevin1990 | 19:a6d4bdcffb84 | 379 | |
| kevin1990 | 19:a6d4bdcffb84 | 380 | It is also possible to have ADI Sense perform linearisation on other sensor |
| kevin1990 | 19:a6d4bdcffb84 | 381 | types. A range of [sensor type IDs](@ref ADI_SENSE_1000_ADC_SENSOR_TYPE) named |
| kevin1990 | 19:a6d4bdcffb84 | 382 | with an "_L2" suffix are reserved for this purpose. By specifying one of these |
| kevin1990 | 19:a6d4bdcffb84 | 383 | sensor types, and by providing the necessary linearisation information for that |
| kevin1990 | 19:a6d4bdcffb84 | 384 | sensor type as part of a "look-up table" data structure loaded via the @ref |
| kevin1990 | 19:a6d4bdcffb84 | 385 | adi_sense_1000_SetLutData API function, the ADI Sense module can be extended to |
| kevin1990 | 19:a6d4bdcffb84 | 386 | work with sensor variants which require a different linearisation what is |
| kevin1990 | 19:a6d4bdcffb84 | 387 | already provided through built-in methods. Linearisation data may be provided |
| kevin1990 | 19:a6d4bdcffb84 | 388 | in the form of a coefficient list for a polynomial equation, or as a |
| kevin1990 | 19:a6d4bdcffb84 | 389 | translation table, depending on what is most appropriate for that sensor. |
| kevin1990 | 19:a6d4bdcffb84 | 390 | |
| kevin1990 | 19:a6d4bdcffb84 | 391 | Translation tables can be expressed in a number of formats, such as 1- or |
| kevin1990 | 19:a6d4bdcffb84 | 392 | 2-Dimensional tables, with equally- or non-equally-spaced vectors. 2-D tables |
| kevin1990 | 19:a6d4bdcffb84 | 393 | are used where the sensor output is affected by both the sensor input and |
| kevin1990 | 19:a6d4bdcffb84 | 394 | another factor such as the operating temperature of the sensor itself. If the |
| kevin1990 | 19:a6d4bdcffb84 | 395 | sensor output values can be captured for an equally-spaced set of input values |
| kevin1990 | 19:a6d4bdcffb84 | 396 | (i.e. values separated by a constant increment, such as 3,6,9,12,etc.), the |
| kevin1990 | 19:a6d4bdcffb84 | 397 | equally-spaced table formats allow for a more compact represenation as only the |
| kevin1990 | 19:a6d4bdcffb84 | 398 | ouput values need to be listed individually. |
| kevin1990 | 19:a6d4bdcffb84 | 399 | |
| kevin1990 | 19:a6d4bdcffb84 | 400 | Multiple coefficient lists can be specified for a given sensor type, along with |
| kevin1990 | 19:a6d4bdcffb84 | 401 | an applicable range of input values, as it may be necessary to apply different |
| kevin1990 | 19:a6d4bdcffb84 | 402 | equations depending on the input range. For example, RTD sensors feature a |
| kevin1990 | 19:a6d4bdcffb84 | 403 | different linearity curve for input ranges above/below 0 degrees Celsius. |
| kevin1990 | 19:a6d4bdcffb84 | 404 | |
| kevin1990 | 19:a6d4bdcffb84 | 405 | The ADI Sense 1000 allows a flexible look-up table (LUT) data structure up to a |
| kevin1990 | 19:a6d4bdcffb84 | 406 | [maximum size](@ref ADI_SENSE_LUT_MAX_SIZE) to be loaded by the user for use |
| kevin1990 | 19:a6d4bdcffb84 | 407 | with custom "L2" sensor types. The LUT data structure format, defined as @ref |
| kevin1990 | 19:a6d4bdcffb84 | 408 | ADI_SENSE_1000_LUT, allows for a variable set of tables of different formats |
| kevin1990 | 19:a6d4bdcffb84 | 409 | to be included as part of the overall data structure. Each table is preceeded |
| kevin1990 | 19:a6d4bdcffb84 | 410 | by a descriptor which specifies the format of the following table. A single |
| kevin1990 | 19:a6d4bdcffb84 | 411 | top-level header at the start of the LUT specifies how many tables are contained |
| kevin1990 | 19:a6d4bdcffb84 | 412 | within. The LUT structure basically looks like this: |
| kevin1990 | 19:a6d4bdcffb84 | 413 | |
| kevin1990 | 19:a6d4bdcffb84 | 414 | |---------------------| |
| kevin1990 | 19:a6d4bdcffb84 | 415 | | top-level header | |
| kevin1990 | 19:a6d4bdcffb84 | 416 | |---------------------| |
| kevin1990 | 19:a6d4bdcffb84 | 417 | | table #0 descriptor | |
| kevin1990 | 19:a6d4bdcffb84 | 418 | | table #0 data | |
| kevin1990 | 19:a6d4bdcffb84 | 419 | |---------------------| |
| kevin1990 | 19:a6d4bdcffb84 | 420 | | table #1 descriptor | |
| kevin1990 | 19:a6d4bdcffb84 | 421 | | table #1 data | |
| kevin1990 | 19:a6d4bdcffb84 | 422 | |---------------------| |
| kevin1990 | 19:a6d4bdcffb84 | 423 | ~~~ |
| kevin1990 | 19:a6d4bdcffb84 | 424 | |---------------------| |
| kevin1990 | 19:a6d4bdcffb84 | 425 | | table #N descriptor | |
| kevin1990 | 19:a6d4bdcffb84 | 426 | | table #N data | |
| kevin1990 | 19:a6d4bdcffb84 | 427 | |---------------------| |
| kevin1990 | 19:a6d4bdcffb84 | 428 | |
| kevin1990 | 19:a6d4bdcffb84 | 429 | To cater for this flexibility, the data structure definition is inherently |
| kevin1990 | 19:a6d4bdcffb84 | 430 | complex. To absorb some of this complexity, a supplementary API function named |
| kevin1990 | 19:a6d4bdcffb84 | 431 | @ref adi_sense_1000_AssembleLutData is provided. By providing a list of |
| kevin1990 | 19:a6d4bdcffb84 | 432 | pointers to descriptors and data elements for each table to be included in the |
| kevin1990 | 19:a6d4bdcffb84 | 433 | LUT structure, along with buffer of allocated memory, this function constructs |
| kevin1990 | 19:a6d4bdcffb84 | 434 | the top-level header and appends each table and also fills some fields within |
| kevin1990 | 19:a6d4bdcffb84 | 435 | the table descriptors (e.g. length, CRC). Please refer to the "user_lut_data" |
| kevin1990 | 19:a6d4bdcffb84 | 436 | application example for an illustration of how this function can be used. |
| kevin1990 | 19:a6d4bdcffb84 | 437 |