tep101.txt

tinyos-2.x.rar

===================================
Analog-to-Digital Converters (ADCs)
===================================

:TEP: 101
:Group: Core Working Group 
:Type: Documentary
:Status: Final
:TinyOS-Version: 2.x
:Author: Jan-Hinrich Hauer, Philip Levis, Vlado Handziski, David Gay

.. Note::

   This memo documents a part of TinyOS for the TinyOS Community, and
   requests discussion and suggestions for improvements.  Distribution
   of this memo is unlimited. This memo is in full compliance with
   [TEP1]_.


Abstract
====================================================================

This TEP proposes a hardware abstraction for analog-to-digital converters (ADCs)
in TinyOS 2.x, which is aligned to the three-layer Hardware Abstraction
Architecture (HAA) specified in [TEP2]_. It describes some design principles and
documents the set of hardware-independent interfaces to an ADC.

1. Introduction
====================================================================

Analog-to-digital converters (ADCs) are devices that convert analog input
signals to discrete digital output signals, typically voltage to a binary
number.  The interested reader can refer to Appendix A for a brief overview of
the ADC hardware on some current TinyOS platforms.  In earlier versions of
TinyOS, the distinction between a sensor and an ADC were blurred: this led
components that had nothing to do with an ADC to still resemble one
programatically, even though the semantics and forms of operation were
completely different.  To compensate for the difference non-ADC sensors
introduced additional interfaces, such as ``ADCError``, that were tightly bound
to sensor acquisition but separate in wiring. The separation between the ADC
and ``ADCError`` interface is bug prone and problematic, as is the equation of
a sensor and an ADC. TinyOS 2.x separates the structure and interfaces of an
ADC from those of sensor drivers (which may be on top of an ADC stack, but
this fact is hidden from higher level components). This TEP presents how TinyOS
2.x structures ADC software. [TEP109]_ (Sensor Boards) shows how a platform can
present actual named sensors. 

As can be seen in Appendix A the ADC hardware used on TinyOS platforms differ
in many respects, which makes it difficult to find a chip independent
representation for an ADC. Even if there were such a representation, the
configuration details of an ADC would still depend on the actual device
producing the input signal (sensor).  Neither a platform independent
application nor the ADC hardware stack itself has access to this information,
as it can only be determined on a platform or sensorboard level. For example,
determining which ADC port a sensor is attached to and how conversion results
need to be interpreted is a platform specific determination. Although the
actual configuration details may be different the procedure of configuring an
ADC can be unified on all ADCs with the help of **hardware independent
interfaces**: in a similar way as the ``Read`` interface definition does not
predefine the type or semantics of the exchanged data (see [TEP114]_), a
configuration interface definition can abstract from the data type and
semantics of the involved configuration settings.  For example, like a
component can provide a ``Read<uint8_t>`` or ``Read<uint16_t>`` interface, it
can also provide a ``AdcConfigure<atm128_adc_config_t>`` or
``AdcConfigure<msp430adc12_channel_config_t>`` interface depending on what ADC
it represents.  This TEP proposes the (typed) ``AdcConfigure`` interface as the
standard interface for configuring an ADC in TinyOS 2.x.

In spite of their hardware differences, one aspect represents a common
denominator of ADCs: they all produce conversion results. To facilitate sensor
software development conversion results are returned by the ADC stack through
the interfaces ``Read``, ``ReadStream`` and ``ReadNow`` (see `2.  Interfaces`_
and [TEP114]_).  Conversion results are returned as uninterpreted values and
translating them to engineering units can only be done with the configuration
knowledge of the respective platform, for example, the reference voltage or the
resistance of a reference resistor in ratiometric measurements.  Translating
uninterpreted values to engineering units may be performed by components
located on top of the ADC stack and is out of the scope of this TEP.

The top layer of abstraction of an ADC - the Hardware Interface Layer (HIL) -
thus provides the interfaces ``Read``, ``ReadNow`` and ``ReadStream`` and uses
the ``AdcConfigure`` interface for hardware configuration (why it **uses** and
does not **provide** ``AdcConfigure`` is explained below).  Since the type and
semantics of the parameters passed through these interfaces is dependent on the
actual ADC implementation, it is only a "weak" HIL (see [TEP2]_).

Following the principles of the HAA [TEP2]_ the Hardware Adaptation Layer (HAL,
which resides below the HIL) of an ADC should expose all the chip-specific
capabilities of the chip.  For example, the ADC12 on the MSP430 MCU supports a
"Repeat-Sequence-of-Channels Mode" and therefore this function should be
accessible on the HAL of the MSP430 ADC12 hardware abstraction.  Other ADCs
might not exhibit such functionality and might therefore - on the level of HAL
- provide only an interface to perform single conversions. Since all ADCs have
the same HIL representation it may be necessary to perform some degree of
software emulation in the HIL implementation.  For example, a ``ReadStream``
command can be emulated by multiple single conversion commands. Below the HAL
resides the Hardware Presentation Layer (HPL), a stateless component that
provides access to the hardware registers (see [TEP2]_). The general structure
(without virtualization) of the ADC stack is as follows ::


        ^                     |
        |                     |
        |                   Read,
  AdcConfigure              ReadNow (+ Resource),
        |                   ReadStream
        |                     |
        |                     V
  +----------------------------------+
  |  Hardware Interface Layer (HIL)  |
  |  (chip-specific implementation)  |
  +----------------------------------+
                   |
                   |
    chip-specific interface(s) + Resource
 (e.g. Msp430Adc12SingleChannel + Resource)
                   |
                   V
  +----------------------------------+
  |  Hardware Adaptation Layer (HAL) |
  |  (chip-specific implementation)  |
  +----------------------------------+
                   |
                   |
         chip-specific interface(s)
             (e.g. HplAdc12)
                   |
                   V
  +----------------------------------+
  | Hardware Presentation Layer (HPL)|
  | (chip-specific implementation)   |
  +----------------------------------+


The rest of this TEP specifies:

* the set of standard TinyOS interfaces for collecting ADC conversion
  results and for configuring an ADC (`2. Interfaces`_)
* guidelines on how an ADC's HAL should expose chip-specific 
  interfaces (`3. HAL guidelines`_)
* what components an ADC's HIL MUST implement (`4. HIL requirements`_)
* guidelines on how the HIL should be implemented 
  (`5. HIL guidelines`_)
* a section pointing to current implementations (`6. Implementation`_)

This TEP ends with appendices documenting, as an example, the ADC implementation
for the TI MSP430 MCU.


2. Interfaces
====================================================================

This TEP proposes the ``AdcConfigure`` interface for ADC hardware configuration
and the ``Read``, ``ReadStream`` and ``ReadNow`` interfaces to acquire
conversion results. The ``Read`` and ``ReadStream`` interfaces are documented
in [TEP114]_ and the ``ReadNow`` interface is documented in this TEP.  A
``Read[Now|Stream]`` interface is always provided in conjunction with a
``AdcConfigure`` interface.

Interface for configuring the ADC hardware
--------------------------------------------------------------------

The ``AdcConfigure`` interface is defined as follows::

  interface AdcConfigure< config_type > 
  {
    async command config_type getConfiguration(); 
  }

This interface is used by the ADC stack to retrieve the hardware configuration
of an ADC HIL client. ``config_type`` is a chip-specific data type (simple or
structured) that contains all information necessary to configure the respective
ADC hardware. For example, on the ADC12 of the MSP430 the ``AdcConfigure``
interface will be instantiated with the ``const msp430adc12_channel_config_t*``
data type. A client MUST always return the same configuration through a
``AdcConfigure`` interface and, if configuration data is passed as a pointer,
the HIL component (see `4. HIL requirements`_) MUST NOT reference it after the
return of the ``getConfiguration()`` command. If a client wants to use the ADC
with different configurations it must provide multiple instances of the
``AdcConfigure`` interface.

Note that the ``AdcConfigure`` interface is **provided** by an ADC HIL client
and it is **used** by the ADC HIL implementation. Therefore an ADC HIL client
cannot initiate the configuration of the ADC hardware itself. Instead it is the
ADC HIL implementation that can "pull" the client's ADC configuration just
before it initates a conversion based on the respective client's configuration.
The rationale is that the ADC HIL implementation does not have to store an ADC
configuration per client - instead the ADC client can, for example, store its
configuration in program memory.

Interfaces for acquiring conversion results
--------------------------------------------------------------------
   
This TEP proposes to adopt the following two source-independent data
collection interfaces from [TEP114]_ for the collection of ADC conversion
results on the level of HIL::

  interface Read< size_type >
  interface ReadStream< size_type >

In addition it proposes the following data collection interface for low-latency
reading of conversion results::