Diff: doc/key_topics.md

Revision:

23:2adb6216b001

Parent:

22:374234219d96

Child:

24:5a2272a25ff1

--- a/doc/key_topics.md	Mon Jan 08 16:57:46 2018 +0000
+++ /dev/null	Thu Jan 01 00:00:00 1970 +0000
@@ -1,437 +0,0 @@
-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.
-