File content as of revision 2:2f9f9f7f0243:

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.