[Tinyos-host-mote-wg] [Tinyos-2.0wg] TEP 101 (ADC) committed
Jan Hauer
hauer at tkn.tu-berlin.de
Tue May 24 20:03:54 PDT 2005
After some elaborate discussion in the subgroup, the ADC TEP 101 has
been updated with some major changes. I committed it to CVS, it is also
attached here for convenience.
Major changes:
- The ADC abstraction itself does not include an HIL, instead the HIL
is composed of named sensor components discussed in TEP 109 (Sensorboards).
- The ADC stack consists of two HALs, a "traditional" HAL1 and a HAL2
which provides chip independent but platform dependent access to the ADC.
- The ADC stack uses standard TinyOS resource management modules, such
as AcquireDataRoundRobinM, to arbitrate access. Sensor wrappers can sit
on top of them.
- Platform dependent applications (or wrappers that don't incorporate an
arbitration service) can wire to HAL1, platform independent applications
wire to sensor wrappers.
Everyone is welcome to comment.
Jan
-------------- next part --------------
An HTML attachment was scrubbed...
URL: http://mail.millennium.berkeley.edu/pipermail/tinyos-host-mote-wg/attachments/20050524/b7a53316/tep101-0001.html
-------------- 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.6 $
:Draft-Modified: $Date: 2005/05/25 02:46:52 $
: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
TEP 1.
Abstract
====================================================================
This TEP proposes a new hardware abstraction for the analog-to-digital
converters (ADCs) in TinyOS 2.x. It focuses on aligning the ADC
abstraction with the three-layer Hardware Abstraction Architecture
(HAA) described in TEP 2. The ADC abstraction itself does not include
an HIL, but the platform independent representation is discussed in
TEP 109 (Sensorboards).
Introduction
====================================================================
Analog-to-digital converters (ADCs) are devices that convert analog
input signals to discrete digital output signals, typically voltage to
a digital number. The ADCs used in TinyOS differ in many respects (see
`Hardware differences between the current platforms`_). This makes it
difficult to find a chip independent representation for ADCs. Even if
there was such a representation, the configuration details of an ADC
would still depend on the actual device (sensor) producing the input
signal. Neither a platform independent application nor the ADC
hardware stack itself has access to this information. It can only be
determined on a platform or sensorboard level, e.g. which ADC port a
certain sensor is attached to and how a conversion result needs to be
interpreted. Thus there is no platform independent (HIL)
representation of an ADC in TinyOS.
Instead, on top of the ADC hardware abstraction a further abstraction
concept is required to use ADCs in a platform independent way. This
concept is described in TEP 109 (Sensorboards): Named sensor
components, called sensor wrappers, provide platform independent
access to sensors by providing standard TinyOS interfaces.
In order to facilitate the writing of sensor wrappers and allow them
to incorporate certain services (e.g. access to the ADC on a round
robin basis), the ADC hardware stack will include as its top layer a
second, chip independent (but still platform dependent) HAL. The
following section gives an overview of the involved components.
Afterwards each layer is discussed in detail.
Overview
====================================================================
The ADC hardware abstraction ends with a platform dependent HAL. But
it is designed with regard to the sensor abstraction in TEP 109, which
covers the definition and implementation of HIL sensor components.
This overview shows how they match up by describing the integrated
component graph in a top-down fashion.
The highest layer of abstraction, the HIL, will be composed of named
sensor components (sensor wrappers) that provide interfaces only for
acquiring the corresponding data. TEP 109 covers the definition and
implementation of these HIL sensor components. However, many sensors
sit on top of a shared hardware ADC.
As the ADC hardware will usually be multiplexed between several client
applications, access to it needs to be arbitrated. The ADC stack uses
standard TinyOS resource management modules, such as
AcquireDataRoundRobinM, to arbitrate access. These generic arbitration
modules use parameterized AcquireData[Now] (and Resource) interfaces.
An ADC hardware stack that supports arbitration of its input channels
therefore incorporates a layer providing these interfaces for standard
arbiter components to use. The parameter to such a parameterized
interface defines the sensor or, more precisely, the ADC input
channel. An input channel is the most natural representation on this
level of abstraction, because a common denominator of all ADCs is that
they sample an input channel and produce conversion results. Thus one
level of abstraction of the ADC is a parameterized AcquireData
interface, where the parameter defines the ADC input channel to be
sampled. This level of abstraction, however, is not a HIL
representation, because choosing an input channel is a platform or
sensorboard specific decision (as a platform independent application
would not know which channel to choose). Instead, this layer provides
a platform dependent HAL interface. It is important to note that the
implementation of this HAL is, however, chip dependent and platform
independent, while the instantiation is performed on a platform level
(for an example, see below).
There is also need for an HAL in the 'traditional' sense of the
Hardware Abstraction Architecture (HAA): An HAL that offers access to
all the chip specific capabilities via a chip specific interface.
Below this HAL the lowest layer is, as usual, composed of the HPL.
An example for a component stack of a platform independent application
wiring to a sensor wrapper on the 'eyes' platform (using the MSP430)
is shown in the following figure.::
+-------------+
| Platform |
APPLICATION: | independent | location: e.g. tinyos-2.x/apps/TestADC
| Application |
+-------------+
^
|
AcquireData
|
+----------------+
| DemoSensorRRC |
HIL: | (instantiating | location: tinyos-2.x/tos/platforms/eyes
| ADCChannelC) |
+----------------+
^
|
AcquireData[]
|
+----------------------------+
| ADCChannelArbiterC |
Service: | (instantiating | location: tinyos-2.x/tos/lib/adc
| AcquireDataNowRoundRobinM) |
+----------------------------+
^
|
AcquireData[]
|
+---------------------+
| ADCC |
HAL2: | (MSP430 specific | location: tinyos-2.x/tos/chips/msp430
| implementation and |
| representation) |
+---------------------+
^
|
MSP430ADC12SingleChannel[]
|
+---------------------+
| MSP430ADC12C |
HAL1: | (MSP430 specific | location: tinyos-2.x/tos/chips/msp430
| implementation and |
| representation) |
+---------------------+
^
|
MSP430ADC12HPL
|
+---------------------+
| MSP430ADC12HPLC |
HPL: | (MSP430 specific | location: tinyos-2.x/tos/chips/msp430
| implementation and |
| representation) |
+---------------------+
Hardware differences between the current platforms
====================================================================
Currently two different on-chip ADCs are in use for TinyOS, the ADC of
the Atmel ATmega 128 and the ADC12 of TI MSP430. Their
characteristics are compared in the following table:
+----------------------+----------------------+---------------------+
| | 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 |
| | (repeated single | conversion mode |
| | channel conversion) |- sequence mode |
| | | (sequence <= 16 |
| | | 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 |
+----------------------+----------------------+---------------------+
Hardware Presentation Layer (HPL)
====================================================================
a. Implementation: Chip dependent
b. Presentation: Chip dependent
c. Stateless
d. General structure:
i. provides StdControl interface if necessary for power management
ii. get/set commands for the registers that control the hardware
iii. additional commands for frequently used operations
iv. commands for enabling/disabling of interrupts
v. service routines for the ADC interrupt
Hardware Adaptation Layer (HAL)
====================================================================
As explained in the `Overview`_ the HAL consists of two sublayers. To
differentiate the two Hardware Adaptation 'sub'Layers they are called
HAL2 (for the HAL providing a parameterized AcquireData[Now]
interface) and HAL1 (for the 'traditional' HAL). In the hardware stack
for the ADC the HAL1 resides below HAL2, i.e. HAL2 uses the primitives
of HAL1. Only chip dependent application may wire to HAL1 or HAL2 i.e.
platform independent applications MUST NOT wire to HAL1 or HAL2.
Hardware Adaptation SubLayer1 (HAL1)
--------------------------------------------------------------------
a. Implementation: Chip dependent
b. Presentation: Chip dependent
c. Async
d. ADC12 on MSP430
The core configuration of the HAL1 on MSP430 is
the MSP430ADC12C configuration.::
configuration MSP430ADC12C
{
//provides interface Init;
//provides interface StdControl;
provides interface Resource[uint8_t client];
provides interface MSP430ADC12SingleChannel as SingleChannel[uint8_t id];
provides interface MSP430ADC12SingleChannel as SingleChannelADCC[uint8_t id];
}
MSP430ADC12C provides two parameterized
MSP430ADC12SingleChannel interfaces. "SingleChannel" is
provided to chip dependent applications, "SingleChannelADCC" is
reserved for the ADCC component (see 'Hardware Adaptation
SubLayer2 (HAL2)'_). An application SHOULD NOT directly wire
to the MSP430ADC12C, but to an instantiation of the following
generic configuration.::
generic configuration MSP430ADC12Client()
{
provides interface Resource;
provides interface MSP430ADC12SingleChannel;
} implementation {
components MSP430ADC12C;
Resource = MSP430ADC12C.Resource[unique(ADC_RESOURCE)];
MSP430ADC12SingleChannel = MSP430ADC12C.MSP430ADC12SingleChannel[unique(MSP430ADC12_CLIENT)];
}
i. The Resource interface is specified in TEP 108. Before a
call to any command of the MSP430ADC12SingleChannel interface
can succeed, the ADC12 MUST be reserved via the Resource
interface. After an application has performed all desired
operations on the ADC12, it then MUST release the ADC12 via the
Resource interface. In the meantime the ADC12 will be blocked
for all other requests, therefore an application SHOULD
minimize this reservation period. Every application MUST
conform to this policy. The HAL1 will NOT check at runtime
whether a data request maps to the application that has
reserved the ADC.
ii. The MSP430ADC12SingleChannel interface includes four
*getData* commands, two events signalling data back and a
*getConfigurationData* event.::
interface MSP430ADC12SingleChannel
{
async event msp430adc12_channel_config_t getConfigurationData();
async command msp430adc12_result_t getDataSingle();
async command msp430adc12_result_t getDataSingleRepeat(uint16_t jiffies);
async command msp430adc12_result_t getDataMultiple(uint16_t *buf,
uint16_t length, uint16_t jiffies);
async command msp430adc12_result_t getDataMultipleRepeat(uint16_t *buf,
uint8_t length, uint16_t jiffies);
async event result_t dataSingleReady(uint16_t data);
async event uint16_t* dataMultipleReady(uint16_t *buf, uint16_t length);
}
typedef struct
{
unsigned int refVolt2_5: 1; // reference voltage level
unsigned int clockSourceSHT: 2; // clock source sample-hold-time
unsigned int clockSourceSAMPCON: 2; // clock source sampcon signal
unsigned int clockDivSAMPCON: 2; // clock divider sampcon
unsigned int referenceVoltage: 3; // reference voltage
unsigned int clockDivSHT: 3; // clock divider sample-hold-time
unsigned int inputChannel: 4; // input channel
unsigned int sampleHoldTime: 4; // sample-hold-time
} msp430adc12_channel_config_t;
An application needs to implement an event handler for the
MSP430ADC12SingleChannel.getConfigurationData() event. This event
handler MUST return the configuration data for the channel
the application wants to sample. The event MAY be signalled
multiple times by HAL1 and the application MUST always return
the same configuration data.
This approach (in contrast to a command) has the
advantage that HAL1 does not need to maintain a table
of configuration data in RAM. Instead configuration data is
retrieved from the application at runtime whenever needed.
The application SHOULD keep configuration data in program
memory (flash), not in RAM.
The *getData* commands use the four different conversion modes
of the ADC12: A single channel converted once or repeatedly or
a sequence of channels converted once or repeatedly. The
sequence-of-channel mode is used to perform high-frequency
sampling of around 70kSPS (kilo samples per second) on a single
channel. The MSP430 ADC12 allows to define a sampling period
for subsequent conversions. This is reflected by an additional
parameter *jiffies* in the relevant commands. A datatype
``msp430adc12_result_t`` is used, which not only includes
MSP430ADC12_SUCCESS but also MSP430ADC12_QUEUED to queue
commands. This is necessary to deal with a possible 17ms delay
when starting the internal reference voltage generator.
e. The ADC on ATmega128:
In the current implementation on the Atmel an ADC channel is
exhaustively defined by the port numer, i.e. there is no bind
mechanism (e.g. like for the MSP430)::
configuration HALADCC
{
provides {
interface Init;
interface StdControl;
interface Resource[uint8_t client];
interface ATm128ADC[uint8_t port];
}
}
interface ATm128ADC
{
async command error_t getData();
async command error_t getContinuousData();
async event error_t dataReady(uint16_t data);
}
The Resource interface is specified in TEP 108. Before any call
on the ATm128ADC interface can succeed, the ADC MUST be
reserved via the Resource interface. After an application has
performed all desired operations on the ADC, it then MUST
release the ADC via the Resource interface. In the meantime
the ADC will be blocked for all other request, therefore an
application SHOULD minimize this reservation period.
Hardware Adaptation SubLayer2 (HAL2)
--------------------------------------------------------------------
a. Presentation: Chip independent, platform dependent
The common denominator of all ADCs is that they sample an input
channel and produce conversion results. An abstraction of the
ADC that satisfies both, is a parameterized AcquireData
interface, where the parameter defines the ADC channel (i.e. port)
to be sampled. An HAL2 MUST provide the following
interfaces.::
configuration ADCC {
provides {
interface Init;
interface StdControl;
interface Resource[uint8_t client];
interface AcquireData[uint8_t port];
interface AcquireDataNow[uint8_t port];
interface AcquireDataBuffered[uint8_t port];
}
} implementation {
// chip dependent
}
The name of a HAL2 configuration is chip specific (it can be,
but doesn't have to be "ADCC"). An HAL2 module will perform a
mapping of the chip specific HAL1 interfaces to the above shown
standard TinyOS interfaces. Note that, although the provided
interfaces are standard TinyOS interfaces, the fact that they
are parameterized by a port identifier makes the HAL2
representation platform dependent. Platform independent
applications SHOULD NOT wire to HAL2.
b. Implementation: Chip dependent
The HAL2 representation allows access to an ADC on a port
basis. For ADCs that require more detailed configuration
information than the port number an additional
mechanism is required for the HAL2 implementation to
determine what the actual chip-specific settings for a given
ADC port are. For example, the HAL2 module of the
ADC12 on MSP430 needs to know the exact configuration settings
ADC channel (port) in order to successfully call the
for a given MSP430ADC12SingleChannel.bind() command. What these
settings are can only be determined on a platform or sensorboard
level and not within the ADC hardware stack itself. The mapping of
a channel number to its settings must be well-defined for all
relevant ADCs.
i. MSP430
Each platform or sensorboard that allows access to the
ADC12 via ADCC MUST provide a module
"MSP430ADC12ChannelConfigM.nc", because in its implementation
ADCC wires to MSP430ADC12ChannelConfigM::
/* HAL2 component for ADC12 of MSP430 */
configuration ADCC {
provides {
interface Init;
interface StdControl;
interface Resource[uint8_t client];
interface AcquireData[uint8_t port];
interface AcquireDataNow[uint8_t port];
interface AcquireDataBuffered[uint8_t port];
}
}
}
implementation {
components ADCM, MSP430ADC12ChannelConfigM, MSP430ADC12C;
Init = MSP430ADC12C;
StdControl = MSP430ADC12C;
Resource = MSP430ADC12C;
AcquireData = ADCM;
AcquireDataNow = ADCM;
AcquireDataBuffered = ADCM;
ADCM.SingleChannel -> MSP430ADC12C.SingleChannelADCC;
ADCM.MSP430ADC12ChannelConfig -> MSP430ADC12ChannelConfigM;
}
The MSP430ADC12ChannelConfigM module SHOULD be placed in the
according platform or sensorboard directory and it MUST
implement the interface "MSP430ADC12ChannelConfig".::
interface MSP430ADC12ChannelConfig {
async event msp430adc12_channel_config_t getConfigurationData(uint8_t channel);
}
ADCM MAY signal the *getConfigurationData()* event for channels
0-7 and MSP430ADC12ChannelConfigM MUST return the corresponding
configuration data for the platform or sensorboard. The event
MAY be signalled multiple times and MSP430ADC12ChannelConfigM
MUST always return the same configuration data.
ii. For the ADC on the ATmega128 in the current implementation
a port number exhaustively defines all relevant settings.
Services
====================================================================
As the ADC hardware will usually be multiplexed between several client
applications, access to it needs to be arbitrated. Arbitration of the
HAL2 is performed by channel arbiter components, e.g.
ADCChannelArbiterC or ADCNowChannelArbiterC, located in
tinyos-2.x/tos/lib/adc. These arbiters SHOULD NOT be wired to
directly. Instead generic wrapper components, e.g. ADCChannelC or
ADCNowChannelC, SHOULD be used. This guarantees correct wiring between
arbiters and HAL2. The generic wrapper components will be instantiated
by sensor wrapper components, i.e. per platform. Platform independent
applications SHOULD NOT instantiate these themselves.
Hardware Interface Layer (HIL)
====================================================================
The ADC hardware stack itself does not include an HIL for reasons
mentioned in the `Introduction`_. Instead named sensor wrappers
provide platform independent access to the ADC which is covered in TEP
109 (Sensorboards).
Implementation
====================================================================
See the tinyos-2.x/tos/ tree. Interfaces are in interfaces/ and HPL,
HAL1 and HAL2 components in chips/. Arbitration service components are
in lib/adc.
4. Author's Address
====================================================================
| Jan Hauer / Vlado Handziski
| Sekr FT5
| Einsteinufer 25
| 10587 Berlin
| GERMANY
|
| email - hauer at tkn.tu-berlin.de, handzisk at tkn.tu-berlin.de
|
|
| Philip Levis
| 467 Soda Hall
| UC Berkeley
| Berkeley, CA 94720
|
| phone - +1 510 290 5283
|
| email - pal at cs.berkeley.edu
|
|
| David Gay
| 2150 Shattuck Ave, Suite 1300
| Intel Research
| Berkeley, CA 94704
|
| phone - +1 510 495 3055
|
| email - david.e.gay at intel.com
-------------- next part --------------
_______________________________________________
Tinyos-2.0wg mailing list
Tinyos-2.0wg at Mail.Millennium.Berkeley.EDU
https://mail.millennium.berkeley.edu/cgi-bin/mailman/listinfo/tinyos-2.0wg
More information about the Tinyos-host-mote-wg
mailing list