[Tinyos Core WG] TEP 101
Vlado Handziski
vlado.handziski at gmail.com
Wed Sep 20 10:00:13 PDT 2006
Skipped content of type multipart/alternative-------------- next part --------------
===================================
Analog-to-Digital Converters (ADCs)
===================================
:TEP: 101
:Group: Core Working Group
:Type: Documentary
:Status: Draft
:TinyOS-Version: 2.x
:Author: Jan-Hinrich Hauer, Philip Levis, Vlado Handziski, David Gay
:Draft-Created: 20-Dec-2004
:Draft-Version: $Revision: 1.1.2.7 $
:Draft-Modified: $Date: 2006/07/14 17:01:14 $
:Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>
.. 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 sensors (which may be on top of an ADC, but this fact is hidden
from higher level components). This TEP presents how TinyOS 2.x structures ADC
software. TEP 109 (Sensor Boards) shows how a platform can present actual named
sensors [TEP109]_.
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 a conversion result is to be
interpreted is a platform-specific determination. However, in a similar way as
the message buffer abstraction ``message_t`` is declared per link layer (see
[TEP111]_), an ADC configuration abstraction can be declared per ADC chip and
still be passed between components using standard TinyOS interfaces. This TEP
proposes the ``AdcConfigure`` interface as the standard interface for
configuring an ADC in TinyOS 2.x. It describes how an ADC configuration
structure is declared per ADC chip and that a **platform** is responsible to
define the configuration for every sensor attached to the ADC.
In spite of their hardware differences, one aspect represents a common
denominator of all ADCs: they produce conversion results. To facilitate sensor
software development conversion results are returned by the ADC hardware stack
using the standard TinyOS interfaces ``Read``, ``ReadNow`` and ``ReadStream``
(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 is
performed by components located on top of the ADC hardware stack and out of the
scope of this TEP.
The top layer of abstraction of an ADC - the Hardware Interface Layer (HIL) -
thus provides the standard TinyOS interfaces ``Read``, ``ReadNow`` and
``ReadStream`` and uses the ``AdcConfigure`` interface for hardware
configuration (why it **uses** and does not **provide** ``AdcConfigure`` is
explained below).
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 thus 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 hardware 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)
|
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``, ``ReadNow`` and ``ReadStream`` interfaces to acquire
conversion results. A ``Read[Now|Stream]`` interface is always provided in
conjunction with an ``AdcConfigure`` interface.
Interface for configuring the ADC hardware
--------------------------------------------------------------------
The ``AdcConfigure`` interface is defined as follows::
interface AdcConfigure<adc_config_t>
{
async command adc_config_t getConfiguration();
}
This interface is used by the ADC implementation to retrieve the desired
hardware configuration of an ADC client. ``adc_config_t`` is instantiated by a
chip-specific structure 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
``msp430adc12_channel_config_t`` structure. A client MUST always return the same
configuration through an ``AdcConfigure`` interface. If a client wants to use
the ADC with different configurations it must provide multiple instances of the
``AdcConfigure`` interface.
Interfaces for acquiring conversion results
--------------------------------------------------------------------
This TEP proposes to adopt the following three generic, source-independent data
collection interfaces from [TEP114]_ for the collection of ADC conversion
results on the level of HIL::
interface Read< size_type >
interface ReadNow< size_type >
interface ReadStream< size_type >
Every data collection interface is associated with an ``AdcConfigure`` interface
(how this association is realized is explained in Section `4. HIL
requirements`_). As the resolution of conversion results is chip-specific, the
``size_type`` parameter reflects an upper bound for the chip-specific resolution
of the conversion results - the actual resolution may be smaller (e.g. uint16_t
for a 12-bit ADC). The above interfaces are specified in [TEP114]_, in the
following their usage is explained with respect to ADCs.
Read
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``Read`` interface can be used to sample an ADC channel and return a single
conversion result as an uninterpreted value. The meaning of the ``Read``
interface is explained in [TEP114]_.
ReadNow
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``ReadNow`` interface is similar to the ``Read`` interface. The difference
is that if a call to ``ReadNow.read()`` succeeds, the ADC starts to sample the
channel immediately (more precisely: when ``SUCCESS`` is returned the hardware
has started the sampling process). Due to its timing constraints the ``ReadNow``
interface is always provided in conjunction with an instance of the ``Resource``
interface (a client must reserve the ADC before the client may call
``ReadNow.read()``). Please refer to [TEP108]_ on how the ``Resource``
interface should be used by a client component.
ReadStream
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The ``ReadStream`` interface can be used to sample an ADC channel multiple times
with a specified sampling period. The meaning of the ``ReadStream`` interface
is explained in [TEP114]_ .
3. HAL guidelines
====================================================================
As explained in `1. Introduction`_ the HAL exposes the full capabilities of the
ADC hardware. Therefore only chip- and platform-dependent clients can wire to
the HAL. Although the HAL is chip-specific, both, in terms of implementation and
representation, its design should follow the guidelines described below to
facilitate the mapping to the HIL representation. Appendix B shows the HAL
signature of the HAL for the MSP430.
Resource reservation
--------------------------------------------------------------------
As the ADC hardware is a shared resource that is usually multiplexed between
several clients some form of access arbitration is necessary. The HAL should
therefore provide a parameterized ``Resource`` interface, instantiate a standard
arbiter component and connect the ``Resource`` interface to the arbiter as
described in [TEP108]_. To ensure fair and uniform arbitration on all platforms
the standard round robin arbiter is recommended. The meaning of resource
arbiters and the ``Resource`` interface is the topic of [TEP108]_.
Configuration and sampling
--------------------------------------------------------------------
As the ADC hardware is a shared resource the HAL should support hardware
configuration and sampling per client (although per-port configuration is
possible, it is not recommended, because it forces all clients to use the same
settings for a given port). Therefore the HAL should provide sampling
interfaces parameterized by a client identifier. An HAL client can use its
instance of the sampling interface to configure the ADC hardware, start the
sampling process and get conversion results. It wires to a sampling interface
using a unique client identifier (this may be hidden by a virtualization
component). All commands and events in the sampling interface should be 'async'
to reflect the potential timing requirements of clients on the level of HAL. An
HAL may provide multiple different parameterized sampling interfaces, depending
on the hardware capabilities. This allows to differentiate/group ADC
functionality, for example single vs. repeated sampling, single channel vs.
multiple channels or low-frequency vs. high-frequency sampling. Every sampling
interface should allow the client to individually configure the ADC hardware,
for example by including the configuration data as parameters in the sampling
commands. However, if configuration data is passed as a pointer, the HAL
component MUST NOT reference it after the return of the respective command.
Appendix B shows the HAL interfaces for the MSP430.
HAL virtualization
--------------------------------------------------------------------
In order to hide wiring complexities and/or export only a subset of all ADC
functions generic ADC wrapper components may be provided on the level of HAL.
Such components can also be used to ensure that a sampling interface is always
provided with a ``Resource`` interface and both are instantiated with the same
client ID if this is required by the HAL implementation.
4. HIL requirements
====================================================================
The following generic components MUST be provided on all platforms that have an
ADC::
AdcReadClient
AdcReadNowClient
AdcReadStreamClient
These components provide virtualized access to the HIL of an ADC. They are
instantiated by an ADC client and provide/use the four interfaces described in
`2. Interfaces`_. An ADC client may instantiate multiple such components. The
following paragraphs describe their signatures. Appendix C shows the
``AdcReadClient`` for the MSP430.
AdcReadClient
--------------------------------------------------------------------
::
generic configuration AdcReadClient() {
provides {
interface Read< size_type >;
}
uses {
interface AdcConfigure< adc_config_t >;
}
}
The ``AdcReadClient`` component provides a ``Read`` interface for acquiring
single conversion results. The associated ADC channel (port) and further
configuration details are returned by the ``AdcConfigure.getConfiguration()``
command. It is the task of the client to wire this interface to a component that
provides the client's ADC configuration. The HAL implementation will use the
``AdcConfigure`` interface to dynamically "pull" the client's ADC settings when
it translates the ``Read.read()`` command to a chip-specific sampling command.
Note that both, ``size_type`` and ``adc_config_t``, are only placeholders and
will be instantiated by the respective HIL implementation (for an example, see
the AdcReadClient for the MSP430 in Appendix C).
AdcReadNowClient
--------------------------------------------------------------------
::
generic configuration AdcReadNowClient() {
provides {
interface Resource;
interface ReadNow< size_type >;
}
uses {
interface AdcConfigure< adc_config_t >;
}
}
The ``AdcReadNowClient`` component provides a ``ReadNow`` interface for
acquiring single conversion results. In contrast to ``Read.read()`` when a call
to ``ReadNow.read()`` succeeds, the ADC starts to sample the channel immediately
(a successful ``Read.read()`` command may not have this implication, see
[TEP114]_ and `2. Interfaces`_). A client MUST reserve the ADC through the
``Resource`` interface before the client may call ``ReadNow.read()``. For more
details on the ``Resource`` interface please refer to [TEP108]_. The associated
ADC channel (port) and further configuration details are returned by the
``AdcConfigure.getConfiguration()`` command. It is the task of the client to
wire this interface to a component that provides the client's ADC configuration.
The HAL implementation will use the ``AdcConfigure`` interface to dynamically
"pull" the client's ADC settings when it translates the ``ReadNow.read()``
command to a chip-specific sampling command. Note that both, ``size_type`` and
``adc_config_t``, are only placeholders and will be instantiated by the
respective HIL implementation (for an example how this is done for the
AdcReadClient see Appendix C).
AdcReadStreamClient
--------------------------------------------------------------------
::
generic configuration AdcReadStreamClient() {
provides {
interface ReadStream< size_type >;
}
uses {
interface AdcConfigure< adc_config_t >;
}
}
The ``AdcReadStreamClient`` component provides a ``ReadStream`` interface for
acquiring multiple conversion results calling a single command. The
``ReadStream`` interface is explained in [TEP114]_ and `2. Interfaces`_. The
``AdcConfigure`` is used in the same way as described in the section on the
``AdcReadClient``. Note that both, ``size_type`` and ``adc_config_t``, are only
placeholders and will be instantiated by the respective HIL implementation (for
an example how this is done for the AdcReadClient see Appendix C).
5. HIL guidelines
====================================================================
The HIL implementation of an ADC stack has two main tasks: it translates a
``Read``, ``ReadNow`` or ``ReadStream`` request to a chip-specific HAL sampling
command and it abstracts from the ``Resource`` interface (the latter only for
the ``AdcReadClient`` and ``AdcReadStreamClient``). The first task is solved
with the help of the ``AdcConfigure`` interface which is used by the HIL
implementation to retrieve a client's ADC configuration. The second task MAY be
performed by the following library components: ``ArbitratedReadC``, and
``ArbitratedReadStreamC`` (in tinyos-2.x/tos/system) - refer to the Atmel Atmega
128 HAL implementation (in tinyos-2.x/tos/chips/atm128/adc), for an example.
Note that since the ``ReadNow`` interface is always provided in conjunction with
a ``Resource`` interface the HIL implementation does not have to perform the ADC
resource reservation for an ``AdcReadNowClient`, but may simply forward an
instance of the ``Resource`` interface from the HAL to the ``AdcReadNowClient``.
The typical sequence of events is as follows: When a client requests data
through the ``Read`` or ``ReadStream`` interface the HIL will request access to
the HAL using the ``Resource`` interface. After the HIL has been granted
access, it will "pull" the client's ADC configuration using the ``AdcConfigure``
interface and translate the client's ``Read`` or ``ReadStream`` command to a
chip-specific HAL command. Once the HIL is signalled the conversion result(s)
from the HAL it releases the ADC through the ``Resource`` interface and signals
the conversion result(s) to its client though the ``Read`` or ``ReadStream``
interface. When a client requests data through the ``ReadNow`` interface the
HIL translates the client's command to the chip-specific HAL command without
using the ``Resource`` interface (it may check ownership of the client through
the ``ArbiterInfo`` interface - this check can also be done in the HAL
implementation). Once the HIL is signalled the conversion result(s) it forwards
it to the respective ``ReadNow`` client.
6. Implementation
====================================================================
The implementation of the ADC12 stack on the MSP430 can be found in
``tinyos-2.x/tos/chips/msp430/adc12``:
* ``HplAdc12P.nc`` is the HPL implementation
* ``Msp430Adc12P.nc`` is the HAL implementation
* ``AdcP.nc`` is the HIL implementation
* ``AdcReadClientC.nc``, ``AdcReadNowClientC.nc`` and
``AdcReadStreamClientC.nc`` provide virtualized access to the HIL
The Atmel Atmega 128 ADC implementation can be found in
``tinyos-2.x/tos/chips/atm128/adc``:
* ``HplAtm128AdcC.nc`` is the HPL implementation
* ``Atm128AdcP.nc`` is the HAL implementation
* ``WireAdcP.nc`` and the library components for arbitrating 'Read',
'ReadNow' and 'ReadStream', ``ArbitratedReadC`` and
``ArbitratedReadStreamC`` (in ``tinyos-2.x/tos/system``), realize
the HAL
* ``AdcReadClientC.nc``, ``AdcReadNowClientC.nc`` and
``AdcReadStreamClientC.nc`` provide access to the ADC on a per-client
basis via the platform-independent interfaces 'Read', 'ReadNow' and
'ReadStream', respectively, and the atmega-specific ADC configuration
interface ``Atm128AdcConfig.nc``
Appendix A: Hardware differences between platforms
====================================================================
The following table compares the characteristics of two microcontrollers
commonly used in TinyOS platforms:
+----------------------+----------------------+---------------------+
| | Atmel Atmega 128 | TI MSP430 ADC12 |
+======================+======================+=====================+
|Resolution | 10-bit | 12-bit |
+----------------------+----------------------+---------------------+
|channels |- 8 multiplexed |- 8 individually |
| | external channels | configurable |
| |- 16 differential | external channels |
| | voltage input |- internal channels |
| | combinations | (AVcc, temperature,|
| |- 2 differential | reference voltages)|
| | inputs with gain | |
| | amplification | |
+----------------------+----------------------+---------------------+
|internal reference | 2.56V | 1.5V or 2.5V |
|voltage | | |
+----------------------+----------------------+---------------------+
|conversion reference |- positive terminal: | individually |
| | AVcc or 2.56V or | selectable per |
| | AREF (external) | channel: |
| |- negative terminal: | |
| | GND |- AVcc and AVss |
| | |- Vref+ and AVss |
| | |- Veref+ and AVss |
| | |- AVcc and (Vref- or |
| | | Veref-) |
| | |- AVref+ and (Vref- |
| | | or Veref-) |
| | |- Veref+ and (Vref- |
| | | or Veref-) |
+----------------------+----------------------+---------------------+
|conversion modes |- single channel |- single conversion |
| | conversion mode | mode |
| |- free running mode |- repeat single |
| | (channels and | conversion mode |
| | reference voltages |- sequence mode |
| | can be switched | (sequence <= 16 |
| | between samples) | channels) |
| | |- repeat sequence |
| | | mode |
+----------------------+----------------------+---------------------+
|conversion clock |clkADC with prescaler |ACLK, MCLK, SMCLK or |
|source | |ADC-oscillator (5MHz)|
| | |with prescaler |
| | |respectively |
+----------------------+----------------------+---------------------+
|sample-hold-time |1.5 clock cycles |selectable values |
| |(fixed) |from 4 to 1024 clock |
| | |cycles |
+----------------------+----------------------+---------------------+
|conversion triggering |by software |by software or timers|
+----------------------+----------------------+---------------------+
|conversion during |yes |yes |
|sleep mode possible | | |
+----------------------+----------------------+---------------------+
|interrupts |after each conversion |after single or |
| | |sequence conversion |
+----------------------+----------------------+---------------------+
Appendix B: an HAL representation: MSP430 ADC12
====================================================================
The following section shows the HAL signature for the ADC12 of the TI MSP430
MCU. It reflects the four MSP430 ADC12 conversion modes as it lets a client
sample an ADC channel once ("Single-channel-single-conversion") or repeatedly
("Repeat-single-channel"), multiple times ("Sequence-of-channels") or multiple
times repeatedly ("Repeat-sequence-of-channels"). In contrast to the single
channel conversion modes the sequence conversion modes trigger a single
interrupt after multiple samples and thus enable high-frequency sampling. The
``DMAExtension`` interface is used to reset the state machine when the DMA is
responsible for data transfer::
configuration Msp430Adc12P
{
provides {
interface Resource[uint8_t id];
interface Msp430Adc12SingleChannel as SingleChannel[uint8_t id];
interface AsyncStdControl as DMAExtension[uint8_t id];
}
}
interface Msp430Adc12SingleChannel
{
async command error_t configureSingle(const msp430adc12_channel_config_t *config);
async command error_t configureSingleRepeat(const msp430adc12_channel_config_t *config, uint16_t jiffies);
async command error_t configureMultiple( const msp430adc12_channel_config_t *config, uint16_t buffer[], uint16_t numSamples, uint16_t jiffies);
async command error_t configureMultipleRepeat(const msp430adc12_channel_config_t *config, uint16_t buffer[], uint8_t numSamples, uint16_t jiffies);
async command error_t getData();
async event error_t singleDataReady(uint16_t data);
async event uint16_t* multipleDataReady(uint16_t buffer[], uint16_t numSamples);
}
Appendix C: an HAL representation: MSP430 ADC12
====================================================================
The signature of the AdcReadClientC component for the MSP430 ADC12 is as
follows::
generic configuration AdcReadClientC() {
provides interface Read<uint16_t>;
uses interface AdcConfigure<msp430adc12_channel_config_t>;
}
.. [TEP1] TEP 1: TEP Structure and Keywords.
.. [TEP2] TEP 2: Hardware Abstraction Architecture.
.. [TEP108] TEP 108: Resource Arbitration.
.. [TEP109] TEP 109: Sensor Boards.
.. [TEP111] TEP 111: message_t
.. [TEP114] TEP 114: SIDs: Source and Sink Independent Drivers.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.millennium.berkeley.edu/pipermail/tinyos-2.0wg/attachments/20060920/6e4b48b9/tep101-0001.html
More information about the Tinyos-2.0wg
mailing list