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