![](/media/cache/group/default_image.jpg.50x50_q85.jpg)
(working) Use this code for calibrating the Load cells.
Fork of ADISense1000_Example_FW by
Diff: doc/key_topics.md
- Revision:
- 0:76fed7dd9235
--- /dev/null Thu Jan 01 00:00:00 1970 +0000 +++ b/doc/key_topics.md Thu Jan 25 16:00:23 2018 +0000 @@ -0,0 +1,437 @@ +Key Topics +========== + +[TOC] + +# Register Interface {#registerinterface} +The ADI Sense module provides a register-style interface for the purpose +of exchanging configuration, status, and data with the host application +processor. + +## Overview {#registerinterface_overview} +The registers can be divided broadly into the following categories: +* Command input register + - This special register is used to issue commands to the module. + - New commands are typically ignored until the running command + has completed (as indicated via the Status registers) +* Configuration input registers + - Configuration registers are used to specify configuration parameters + for use by the module, typically specifying details such as operating + mode, sensor information, limits, and many other options. + - Changes to configuration input registers are typically ignored until a + command is issued to "apply" the configuration on the device. +* Status output registers + - Status information is provided by the module via these read-only registers + - Dedicated output signals (e.g. ERROR and ALERT) may be linked with this + status information + - The host application processor may acknowledge and reset/clear the status + indicators by reading the relevant status registers. The status indicators + will be set again if the underlying condition is subsequently detected again +* Data output registers + - Measurement data samples produced by the module are typically accessed via + a FIFO-style register which may be read repeatedly until all available data + has been consumed. + - Data samples are provided in a pre-determined format according to the + measurement mode, and typically comprise a processed measurement value, + status flags, measurement channel identifier and, optionally, the raw + (unprocessed) data sample retrieved from the sensor input channel. +* Keyhole access registers + - Access to large internal memory regions within the module is typically + provided via an pair of "keyhole" registers, consisting of an address + register and a data register. An address (i.e. an starting offset within + the region) must first be written to the address register, then the + companion data register may be accessed repeatedly to read/write data to + the corresponding region. The address is automatically incremented with + each access to the data register, so that data can be transferred in a + single burst for efficiency. + +# Configuration {#configuration} +The ADI Sense module is a flexible measurement processor which must be +configured via the [register interface](@ref #registerinterface) before it +can be used to acquire data from its external sensor inputs. + +## Overview {#configuration_overview} +A configuration consists of the following elements: +* Global configuration register settings, such as: + - Operating modes + - Power configuration + - Measurement cycle timing + - External reference values +* Channel-specific register settings, such as: + - measurement count + - connected sensor type + - sensor configuration details + - settling time + - filter options + - threshold limits + - calibration adjustments +* Optional user-defined analog sensor linearisation data + - used to compensate for inherent non-linear characteristics of analog sensors + - supplied via a Look-Up Table data structure with a specific format + - allows the user to leverage the data acquisition and processing features + of the ADI Sense module for use with non-standard or unsupported sensors + +## Configuration data structure {#configuration_data} +Although the module can be configured and managed directly via the +[register interface](@ref #registerinterface), the ADI Sense Host Library +provides a level of abstraction above this which allows a more simplified +programming paradigm for the device. + +A single C-language configuration data structure can be used to define all +configuration values for the ADI Sense module. This can be passed to the +relevant ADI Sense Host Library API functions, which will do the work of +translating the configuration details into the appropriate register values +and sending them to the module via its host communication interface. + +The [examples](doc/examples.md) provided with the ADI Sense Host Library +demonstrate this configuration method. Individual configurations are stored +and compiled as .c files, and a configuration may be selected and loaded by +the application code. Note that only the essential configuration fields are +filled, depending on the specific sensor configuration and operating mode +required. + +## Loading and Applying a configuration {#configuration_loading} +Configuration data must first be loaded via the @ref adi_sense_SetConfig API +function - which updates the registers on the module according to the supplied +configuration details - and then applied by calling the @ref +adi_sense_ApplyConfigUpdates function which issues a special command to instruct +the module to apply the new configuration. If user-defined linearisation data +is also required, this must also be loaded via the @ref +adi_sense_1000_SetLutData function _before_ applying the new configuration. + +To avoid loading the configuration details to the module every time it is +powered on, it is possible to save it to non-volatile memory on the module +using @ref adi_sense_SaveConfig and @ref adi_sense_SaveLutData. The saved +configuration is automatically restored by default when the module is +subsequently reset or powered on, and can also be reloaded on demand if required +using the @ref adi_sense_RestoreConfig and @ref adi_sense_RestoreLutData +functions. Note that, in all cases, @ref adi_sense_ApplyConfigUpdates _must_ +be called to instruct the module to apply the configuration before will be used. + +Once a valid configuration has been loaded and applied, the user may issue +commands to the module to initiate measurement cycles, internal calibration, or +diagnostic routines (all of which depend on a valid configuration being applied +in advance). + +## Configuration errors {#configuration_errors} +Attempts to load invalid configuration details will be flagged via the relevant +status registers and signals. After calling @ref adi_sense_ApplyConfigUpdates, +it is advisable to check the status of the module by calling @ref +adi_sense_GetStatus and examining the relevant status information returned from +the module. Subsequent commands issued to the module may not execute correctly +in the presence of unresolved configuration errors. + +# Measurement Cycles {#measurementcycles} +## Overview {#measurementcycles_overview} +Conversions are carried out sequentially across each of the enabled channels in +a predictable pattern which has a defined order and user-specified number of +conversions per channel. This is typically referred to as the _Measurement +Sequence_. + +A _Measurement Cycle_ essentially consists of a single _Measurement Sequence_ +which may be repeated at specified time intervals. + +The configuration parameters required to define the Measurement Cycle and +Sequence are as follows: +* Cycle interval time (specified in microseconds/milliseconds/seconds) +* For each enabled sensor input channel: + - Number of conversions-per-cycle + - Extra settling time (specified in microseconds) + +In addition to the cycle time, the following operating modes dictate when and +how many cycles should be executed: +* **Single-Cycle Mode** + - Executes a single Measurement Cycle and stops +* **Continuous Mode** + - Executes Measurement Cycles continuously until stopped by the host + application processor +* **Multi-Cycle Mode** + - Executes a specified number (burst) of Measurement Cycles and stores the + results in a buffer for retrieval by the host. + - Repeats this indefinitely at specified intervals (multi-cycle burst + interval) until stopped by the host application processor. + +## Executing Measurement Cycles {#measurementcycles_executing} +Once a valid configuration is loaded (see @ref #configuration), +Measurement Cycles are initiated by the host application processor via @ref +adi_sense_StartMeasurement, and may be stopped if necessary via @ref +adi_sense_StopMeasurement. These functions issue the relevant commands to the +ADI Sense module via its dedicate command register. + +Certain auxiliary tasks may also be carried out internally by the module on a +per-cycle basis, such as Calibration and Diagnostics. These are discussed in +in later sections below. + +## Sequence Order {#measurementcycles_sequence} +The sequence is constructed according to which channels are enabled and how many +measurements must be performed per channel. The arrangement is similar to +round-robin scheduling - a measurement is carried out on each enabled channel, in +ascending channel order, and then the loop is repeated until the requested number +of measurements on each channel has been satisfied. + +For example, lets say channels [0, 3, 4, 5] are enabled, with measurementsPerCycle +set as follows: + +channelId | measurementsPerCycle +--------- | -------------------- + CJC_1 | 4 + SENSOR_0 | 2 + I2C_1 | 3 + SPI_0 | 1 + +The length of the sequence would be 10 measurements in total, and the order in +which the channel measurements appear in the sequence would look like this: + +| **CJC_1** | **SENSOR_0** | **I2C_1** | **SPI_0** | **CJC_1** | **SENSOR_0** | **I2C_1** | **CJC_1** | **I2C_1** | **CJC_1** | + +When measurement data samples are retrieved from the ADI Sense by the host +application, this is the order in which those data samples will appear. + +The ADI Sense 1000 provides up to 13 measurement channels, and allows a maximum +measurementsPerCycle of 128, so a single cycle can produce a maximum of 1664 +measurements. In other words, the maximum length of the sequence is 1664. + +## Sequence Timing {#measurementcycles_timing} +The timing of each measurement within the sequence depends on a number of factors: +* **Settling time** + - A settling time is applied when switching between each channel (unless only + a single channel in the sequence), particularly to allow the analog + front-end circuit to stabilise before a conversion is performed. + - Each channel is subject to a minimum settling time (e.g. 500 microseconds) + - Additional settling time can be configured per-channel if required + - As the analog sensor channels are multi-plexed into a single physical input + channel, with different front-end circuit configurations for each, the + settling and conversion of the analog channels must be done one-at-a-time in + series. Their settling time starts only when the channel is reached in the + sequence. + - Digital sensors operate independently, and so are activated in parallel to + other sensors. Consequently, their settling time may start at the start of + a cycle, or immediately after a previous conversion result has been obtained + from the sensor. +* **Conversion time** + - Once the settling time has passed, a conversion is initiated to obtain a raw + measurement value from the sensor input. + - The time required for the conversion may be influenced by factors such as + filter configuration (in the case of analog channels) or specific digital + sensor performance characteristics and configuration options. +* **Processing time** + - Once the raw conversion result is obtained, it is subjected to further + processing to apply correction for non-linear sensors, calibration + adjustments, and conversion into standard measurement units + - The processing time varies depending on the sensor type and correction + algorithms to be applied, but a standard budget of processing time (e.g. + 500 microseconds) is allocated to each channel to produce consistent and + predictable time separation between the measurement results. + +So, to summarise, the distinct phases for each measurement on each channel +typically look like this: + +**settling** > **conversion** > **processing** > **publishing** + +Taking the sequence example in the previous section, let's assume a base +settling time (_Ts_) and processing time (_Tp_) of 500 microseconds for each channel +and the following variable timing parameters _Te_ and _Tc_ (in units of microseconds): + +channelId | extraSettlingTime (_Te_) | conversionTime (_Tc_) | sum (_Ts_ + _Te_ + _Tc_ + _Tp_) | measurementsPerCycle | total +--------- | ------------------------ | --------------------- | ------------------------------- | -------------------- | ----- + CJC_1 | 4000 | 50000 | 55000 | 4 | 220000 + SENSOR_0 | 1000 | 50000 | 52000 | 2 | 104000 + I2C_1 | 20000 | 1000 | 22000 | 3 | 66000 + SPI_0 | 0 | 800 | 1800 | 1 | 1800 + +To clarify: _Te_ above comes directly from the channel configuration. _Tc_, however, +is dictated by the sensor and its configuration. + +The minimum time required for the cycle to complete is, in the above example, +391800 microseconds. + +If the selected operating mode is Continuous or Multi-Cycle mode, the +configuration must also specify the interval between successive cycles +(cycleInterval). If this is less than the actual time required to +complete the cycle, the next cycle will start immediately after the +completion of the previous one; if it is more, there will be a delay +until the next cycle is started. + +## Measurement Results storage and retrieval {#measurementcycles_publishing} +As part of module configuration, a data-ready mode must be selected to decide +how measurements results are made available and retained for consuming by the +host application processor: + +* **Per-Conversion** + - In this mode, each measurement result (a.k.a. data sample) is made available + as soon as it is ready. + - Only a single result is stored, and it is overwritten when the next + measurement result becomes ready. Only the latest result is retained. + - The host application processor must, therefore, consume each single + measurement result (by reading the DATA_FIFO register) as soon as the + result becomes available. +* **Per-Cycle** + - In this mode, the measurement results from a full cycle (10 data samples, + in the example above) are made available only when the measurement cycle is + complete. + - The results are overwritten when the next measurement cycle (if any) + is completed. + - The host application processor must consume the measurement results in a + batch as soon as they become available. +* **Per-Multicycle-Burst** + - In this mode, the measurement results from a burst of measurement cycles + are made available only when thise measurement cycles are completed. + - The results are overwritten when the next burst of measurement cycles + are completed. + - The host application processor must consume the measurement results in a + batch as soon as they become available. + - Note that this data-ready mode is only available when the Multi-Cycle + operating mode is also selected. + +When new measurement results are ready for retrieval, the DRDY output signal +is asserted. The host application may check this signal continuously, or attach +an interrupt notification to this signal, to ensure that measurement results are +retrieved in a timely fashion before they are subsequently overwritten by the +next conversion/cycle. Alternatively, the host application may also read the +STATUS register to check the DRDY status indicator. + +The ADI Sense Host Library API provides the following functions which are +relevant for data retrieval: +* @ref adi_sense_RegisterGpioCallback for recieving DRDY interrupt notifications +* @ref adi_sense_GetGpioState for polling the state of the DRDY signal +* @ref adi_sense_GetStatus for reading the module status registers +* @ref adi_sense_GetData for retrieveing the measurement results from the module + +The @ref adi_sense_1000_GetDataReadyModeInfo API function, specific to the ADI +Sense 1000, is also useful for obtaining information on the number of +measurement results to expect when the DRDY indicator is asserted, based on the +operating and data-ready mode configuration settings currently set in the module +registers. + +# Calibration {#calibration} +The ADI Sense module incorporates a number of calibration measures to ensure +the accuracy of measurement results, described in the following sections. These +mostly pertain to the analog measurement channels, but some provisions are also +included for calibration of digital sensors. + +## Factory calibration {#calibration_factory} +Calibration is performed during factory production for error introduced by +components (e.g. resistors, switches) present on the signal paths of the +module's analog front-end. Calibration offset and gain values are calculated +and stored in non-volatile memory within the module as part of the production +process. These are applied automatically without intervention from the host +application. + +## Internal auto-calibration {#calibration_internal} +The high-accuracy ADC incorporated within the ADI Sense module includes +internal calibration functions to assist in removing offset or gain errors +internal to that ADC. As this is a time-consuming process, it is invoked +only in the following circumstances: +* The host application issues a self-calibration command (@ref + adi_sense_RunCalibration) +* The host application updates the module configuration and the module + determines, based on the configuration changes, that re-calibration is + required. In this case, the calibration is carried out at the point + where the new configuration settings are applied (@ref + adi_sense_ApplyConfigUpdates) + +In all cases, a valid configuration must be set and it used as part of the +calibration process. External sensors and reference circuits must be +connected for calibration to work correctly. + +## User calibration {#calibration_user} +Additional gain and offset correction parameters may be specified per-channel as +part of the module configuration. These are applied as a final step to each +measurement result from the channel during the final stages of processing before +the data sample is made available to the host processor. + +# Diagnostics {#diagnostics} +The ADC within the ADI Sense module includes a range of sophisticated diagnostic +features to automatically detect error conditions such as under-/over-voltage on +analog input signals, supply voltage errors, reference detection errors and more. +These are enabled by default and, if triggered, will result in an ERROR or ALERT +signal being asserted by the module. Diagnostic status can be queried via the +module status registers (@ref adi_sense_GetStatus). + +Additional diagnostic tests may be executed by the module to detect additional +error conditions such as a disconnected or mis-wired sensor. These tests are +typically time-consuming, and so are carried out only if selected by the user: +* Sensor diagnostics may be requested by executing a dedicated diagnostics + command (@ref adi_sense_RunDiagnostics) +* Sensor diagnostics may be optionally executed at the start of each measurement + cycle, at a frequency determined by the user through the configuration + parameters (see @ref ADI_SENSE_1000_DIAGNOSTICS_CONFIG) + +# Sensor Linearisation {#linearisation} +Analog sensors typically produce an output which is not completely linear or +directly proportional with respect to their input. Different sensor types +generally have different linearity characteristics, each requiring different +correction methods or coefficients for accurate translation of the sensor output +back to the corresponding input. Typical methods include use of linearisation +formulae (e.g. polynomial equations with variable coefficients), or tables of +sample input values and their corresponding outputs which can be used with +interpolation to perform the translation. + +The ADI Sense module performs linearisation and calibration correction of the +analog sensor measurements, and incorporates the linearisation functions +complete with coefficients or translation tables for a range of supported sensor +types. On the ADI Sense 1000, for example, measurement results from any +[sensor types](@ref ADI_SENSE_1000_ADC_SENSOR_TYPE) named with the +"_L1" suffix or with a specific sensor model name (e.g. @ref +ADI_SENSE_1000_ADC_SENSOR_VOLTAGE_PRESSURE_AMPHENOL_NPA300X) will be +automatically linearised using built-in linearisation functions and coefficients +or translation tables. + +It is also possible to have ADI Sense perform linearisation on other sensor +types. A range of [sensor type IDs](@ref ADI_SENSE_1000_ADC_SENSOR_TYPE) named +with an "_L2" suffix are reserved for this purpose. By specifying one of these +sensor types, and by providing the necessary linearisation information for that +sensor type as part of a "look-up table" data structure loaded via the @ref +adi_sense_1000_SetLutData API function, the ADI Sense module can be extended to +work with sensor variants which require a different linearisation what is +already provided through built-in methods. Linearisation data may be provided +in the form of a coefficient list for a polynomial equation, or as a +translation table, depending on what is most appropriate for that sensor. + +Translation tables can be expressed in a number of formats, such as 1- or +2-Dimensional tables, with equally- or non-equally-spaced vectors. 2-D tables +are used where the sensor output is affected by both the sensor input and +another factor such as the operating temperature of the sensor itself. If the +sensor output values can be captured for an equally-spaced set of input values +(i.e. values separated by a constant increment, such as 3,6,9,12,etc.), the +equally-spaced table formats allow for a more compact represenation as only the +ouput values need to be listed individually. + +Multiple coefficient lists can be specified for a given sensor type, along with +an applicable range of input values, as it may be necessary to apply different +equations depending on the input range. For example, RTD sensors feature a +different linearity curve for input ranges above/below 0 degrees Celsius. + +The ADI Sense 1000 allows a flexible look-up table (LUT) data structure up to a +[maximum size](@ref ADI_SENSE_LUT_MAX_SIZE) to be loaded by the user for use +with custom "L2" sensor types. The LUT data structure format, defined as @ref +ADI_SENSE_1000_LUT, allows for a variable set of tables of different formats +to be included as part of the overall data structure. Each table is preceeded +by a descriptor which specifies the format of the following table. A single +top-level header at the start of the LUT specifies how many tables are contained +within. The LUT structure basically looks like this: + + |---------------------| + | top-level header | + |---------------------| + | table #0 descriptor | + | table #0 data | + |---------------------| + | table #1 descriptor | + | table #1 data | + |---------------------| + ~~~ + |---------------------| + | table #N descriptor | + | table #N data | + |---------------------| + +To cater for this flexibility, the data structure definition is inherently +complex. To absorb some of this complexity, a supplementary API function named +@ref adi_sense_1000_AssembleLutData is provided. By providing a list of +pointers to descriptors and data elements for each table to be included in the +LUT structure, along with buffer of allocated memory, this function constructs +the top-level header and appends each table and also fills some fields within +the table descriptors (e.g. length, CRC). Please refer to the "user_lut_data" +application example for an illustration of how this function can be used. +