[Tinyos-beta-commits] CVS: tinyos-1.x/beta/teps/html tep101.html,
1.5, 1.6
Jan-Hinrich Hauer
janhauer at users.sourceforge.net
Tue May 24 19:46:55 PDT 2005
Update of /cvsroot/tinyos/tinyos-1.x/beta/teps/html
In directory sc8-pr-cvs1.sourceforge.net:/tmp/cvs-serv19270/beta/teps/html
Modified Files:
tep101.html
Log Message:
TEP 101 (ADC) basically rewritten.
Index: tep101.html
===================================================================
RCS file: /cvsroot/tinyos/tinyos-1.x/beta/teps/html/tep101.html,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** tep101.html 24 Mar 2005 21:21:41 -0000 1.5
--- tep101.html 25 May 2005 02:46:52 -0000 1.6
***************
*** 6,10 ****
<meta name="generator" content="Docutils 0.3.7: http://docutils.sourceforge.net/" />
<title>Analog-to-Digital Converters (ADCs)</title>
! <meta name="author" content="Jan-Hinrich Hauer, Vlado Handziski, Joe Polastre, Lama Nachman" />
<style type="text/css">
--- 6,10 ----
<meta name="generator" content="Docutils 0.3.7: http://docutils.sourceforge.net/" />
<title>Analog-to-Digital Converters (ADCs)</title>
! <meta name="author" content="Jan-Hinrich Hauer, Philip Levis, Vlado Handziski, David Gay" />
<style type="text/css">
***************
*** 298,302 ****
</tr>
<tr><th class="docinfo-name">Author:</th>
! <td>Jan-Hinrich Hauer, Vlado Handziski, Joe Polastre, Lama Nachman</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">20-Dec-2004</td>
</tr>
--- 298,302 ----
</tr>
<tr><th class="docinfo-name">Author:</th>
! <td>Jan-Hinrich Hauer, Philip Levis, Vlado Handziski, David Gay</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">20-Dec-2004</td>
</tr>
***************
*** 319,333 ****
<h1><a name="abstract">Abstract</a></h1>
<p>This TEP proposes a new hardware abstraction for the analog-to-digital
! converters (ADCs) in TinyOS 1.2. It focuses on aligning the ADC
abstraction with the three-layer Hardware Abstraction Architecture
! (HAA).</p>
</div>
<div class="section" id="introduction">
! <h1><a name="introduction">1. Introduction</a></h1>
! <div class="section" id="internal-adcs">
! <h2><a name="internal-adcs">Internal ADCs</a></h2>
! <p>There are two different internal ADCs in use for the TinyOS platforms:
! The internal ADC of the Atmel Atmega 128 and the ADC12 of TI MSP430.
! Their characteristics are compared in the following table:</p>
<table border="1" class="docutils">
<colgroup>
--- 319,457 ----
<h1><a name="abstract">Abstract</a></h1>
<p>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).</p>
</div>
<div class="section" id="introduction">
! <h1><a name="introduction">Introduction</a></h1>
! <p>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
! <a class="reference" href="#hardware-differences-between-the-current-platforms">Hardware differences between the current platforms</a>). 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.</p>
! <p>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.</p>
! <p>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.</p>
! </div>
! <div class="section" id="overview">
! <h1><a name="overview">Overview</a></h1>
! <p>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.</p>
! <p>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.</p>
! <p>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).</p>
! <p>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.</p>
! <p>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.:</p>
! <pre class="literal-block">
! +-------------+
! | 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) |
! +---------------------+
! </pre>
! </div>
! <div class="section" id="hardware-differences-between-the-current-platforms">
! <h1><a name="hardware-differences-between-the-current-platforms">Hardware differences between the current platforms</a></h1>
! <p>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:</p>
<table border="1" class="docutils">
<colgroup>
***************
*** 454,589 ****
</table>
</div>
- <div class="section" id="external-adcs">
- <h2><a name="external-adcs">External ADCs</a></h2>
- <p>In addition to the above internal ADCs, some of the TinyOS platforms
- use dedicated ADCs like ADS1242, ADS7828, ADS1251, ADS8345, ADS8325,
- ADS1100 (all by TI). They differ in resolution (12-bit to 24 -bit),
- interfaces (SPI, I2C), channel numbers (1 to 8), reference voltages
- and conversion rates. Implementation of the three layers of the HAA
- will be considerably different from internal ADCs, as issues like bus
- arbitration or communication errors have to be taken into
- consideration. Although the particular implementation will vary
- according to chip and platform, each HIL (<a class="reference" href="#hardware-interface-layer-hil">Hardware Interface Layer
- (HIL)</a>) will export the standard <em>ADCSingle</em> and <em>ADCMultiple</em>
- interface, providing a uniform application-level OS service. External
- ADCs will influence the HIL interfaces and the layering in the
- following ways:</p>
- <ul>
- <li><p class="first">An additional command <em>reserveADC</em> will be included in the
- HIL interfaces. This command will guarantee a minimum
- delay between the next invocation of <em>getData</em> and the actual
- sampling of the channel.</p>
- </li>
- <li><p class="first">The HIL will provide a mechanism to signal an error that
- occurred during the sampling process.</p>
- </li>
- <li><p class="first">A more general architectural issue is how to structure the
- communication between the HPL of the external ADC and the HPL
- of the particular bus implementation.
- We propose to deal with bus arbitration and related tasks
- on the level of the HALs. I.e. the HAL_ADC module will wire to
- e.g. HAL_SPI module to perform bus arbitration while HPL_ADC
- will wire to HPL_SPI. HPL_ADC is unaware of bus arbitration
- and will always assume to be owner of the bus. This ensures
- that</p>
- <blockquote>
- <ul class="simple">
- <li>The HPL can be kept stateless.</li>
- <li>The HAL is capable of deciding how long to maintain a certain
- state in bus arbitration. If there is, for example, a request
- for a continuous or sequence conversion the HAL could refrain
- from releasing the bus after each single conversion.</li>
- </ul>
- </blockquote>
- </li>
- </ul>
- </div>
- </div>
- <div class="section" id="architecture">
- <h1><a name="architecture">2. Architecture</a></h1>
- <p>The proposed architecture aligns with the three-layer Hardware
- Abstraction Architecture (HAA).</p>
<div class="section" id="hardware-presentation-layer-hpl">
! <h2><a name="hardware-presentation-layer-hpl">Hardware Presentation Layer (HPL)</a></h2>
<ol class="loweralpha simple">
! <li>Implementation: chip/platform dependent</li>
! <li>Presentation: chip dependent</li>
<li>Stateless</li>
<li>General structure:<ol class="lowerroman">
! <li>StdControl (init, start, stop) for power management to work</li>
<li>get/set commands for the registers that control the hardware</li>
! <li>additional commands for the frequently used operations</li>
<li>commands for enabling/disabling of interrupts</li>
<li>service routines for the ADC interrupt</li>
</ol>
</li>
- <li>The HPL for an external ADC SHOULD follow the general structure
- described above by wiring to the respective hardware module's HPL
- to access the bus and relevant pins (see <a class="reference" href="#external-adcs">External ADCs</a>).</li>
</ol>
</div>
<div class="section" id="hardware-adaptation-layer-hal">
! <h2><a name="hardware-adaptation-layer-hal">Hardware Adaptation Layer (HAL)</a></h2>
! <p>For the HAL presentation, the idea of binding an interface to ADC
! settings is extended. This mechanism was introduced in the
! <tt class="docutils literal"><span class="pre">ADCControl</span></tt> interface, but was only applied to channels. Instead of
! only binding to a channel, all settings supported by the interface
! SHOULD be passed to a <tt class="docutils literal"><span class="pre">bind</span></tt> commandhandler once at initialization.
! For all subsequent calls on the interface instance these settings are
! then valid.</p>
<ol class="loweralpha">
! <li><p class="first">Implementation: chip/platform dependent</p>
</li>
! <li><p class="first">Presentation: chip dependent</p>
</li>
! <li><p class="first">MSP430:</p>
! <p>To offload the interfaces, the four supported conversion modes of the
! MSP430 are separated into two separate interfaces: <em>MSP430ADC12Single</em> and
! <em>MSP430ADC12Multiple</em>, for single and multiple conversions,
! respectively. Both interfaces provide two commands which allow the
! conversion(s) to be performed once or repeatedly. One
! characteristic of the MSP430 ADC12 is the ability to define the
! time interval between subsequent conversions. This is reflected by
! an additional parameter <em>jiffies</em> in the relevant commands of the
! HAL interfaces.</p>
! <p>A new return datatype <tt class="docutils literal"><span class="pre">msp430ADCresult_t</span></tt> is introduced, which
! not only includes MSP430ADC12_FAIL and 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.
! HAL-configuration, interfaces and datatypes are as follows (see
! <a class="reference" href="#implementation">3. Implementation</a> for where to find commented versions).:</p>
<pre class="literal-block">
! configuration MSP430ADC12C
{
! provides interface StdControl;
! provides interface MSP430ADC12Single[uint8_t id];
! provides interface MSP430ADC12Multiple[uint8_t id];
}
!
! interface MSP430ADC12Single
{
! command result_t bind(MSP430ADC12Settings_t settings);
! async command msp430ADCresult_t getData();
! async command msp430ADCresult_t getDataRepeat(uint16_t jiffies);
! async command result_t reserve();
! async command result_t reserveRepeat(uint16_t jiffies);
! async command result_t unreserve();
! async event result_t dataReady(uint16_t data);
}
- interface MSP430ADC12Multiple
- {
- command result_t bind( MSP430ADC12Settings_t settings);
- async command msp430ADCresult_t getData(uint16_t *buf, uint16_t length,
- uint16_t jiffies);
- async command msp430ADCresult_t getDataRepeat(uint16_t *buf, uint8_t length,
- uint16_t jiffies);
- async command result_t reserve(uint16_t *buf, uint16_t length, uint16_t jiffies);
- async command result_t reserveRepeat(uint16_t *buf, uint8_t length, uint16_t jiffies);
- async command result_t unreserve();
- async event uint16_t* dataReady(uint16_t *buf, uint16_t length);
- }
-
typedef struct
{
--- 578,679 ----
</table>
</div>
<div class="section" id="hardware-presentation-layer-hpl">
! <h1><a name="hardware-presentation-layer-hpl">Hardware Presentation Layer (HPL)</a></h1>
! <blockquote>
<ol class="loweralpha simple">
! <li>Implementation: Chip dependent</li>
! <li>Presentation: Chip dependent</li>
<li>Stateless</li>
<li>General structure:<ol class="lowerroman">
! <li>provides StdControl interface if necessary for power management</li>
<li>get/set commands for the registers that control the hardware</li>
! <li>additional commands for frequently used operations</li>
<li>commands for enabling/disabling of interrupts</li>
<li>service routines for the ADC interrupt</li>
</ol>
</li>
</ol>
+ </blockquote>
</div>
<div class="section" id="hardware-adaptation-layer-hal">
! <h1><a name="hardware-adaptation-layer-hal">Hardware Adaptation Layer (HAL)</a></h1>
! <p>As explained in the <a class="reference" href="#overview">Overview</a> 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.</p>
! <div class="section" id="hardware-adaptation-sublayer1-hal1">
! <h2><a name="hardware-adaptation-sublayer1-hal1">Hardware Adaptation SubLayer1 (HAL1)</a></h2>
! <blockquote>
<ol class="loweralpha">
! <li><p class="first">Implementation: Chip dependent</p>
</li>
! <li><p class="first">Presentation: Chip dependent</p>
</li>
! <li><p class="first">Async</p>
! </li>
! <li><p class="first">ADC12 on MSP430</p>
! <blockquote>
! <p>The core configuration of the HAL1 on MSP430 is
! the MSP430ADC12C configuration.:</p>
<pre class="literal-block">
! 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];
}
! </pre>
! <p>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.:</p>
! <pre class="literal-block">
! generic configuration MSP430ADC12Client()
! {
! provides interface Resource;
! provides interface MSP430ADC12SingleChannel;
! } implementation {
! components MSP430ADC12C;
!
! Resource = MSP430ADC12C.Resource[unique(ADC_RESOURCE)];
! MSP430ADC12SingleChannel = MSP430ADC12C.MSP430ADC12SingleChannel[unique(MSP430ADC12_CLIENT)];
! }
! </pre>
! <p>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.</p>
! <p>ii. The MSP430ADC12SingleChannel interface includes four
! <em>getData</em> commands, two events signalling data back and a
! <em>getConfigurationData</em> event.:</p>
! <pre class="literal-block">
! 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
{
***************
*** 596,746 ****
unsigned int inputChannel: 4; // input channel
unsigned int sampleHoldTime: 4; // sample-hold-time
! } MSP430ADC12Settings_t;
!
! typedef union
! {
! uint32_t i;
! MSP430ADC12Settings_t s;
! } MSP430ADC12Settings_ut;
!
! typedef enum
! {
! MSP430ADC12_FAIL = 0,
! MSP430ADC12_SUCCESS = 1,
! MSP430ADC12_QUEUED = 2
! } msp430ADCresult_t;
</pre>
! </li>
! <li><p class="first">Atmega 128:
! To maintain compatibility with the existing code the
! original ADC interface will be provided with one extension,
! a <em>reserveADC</em> command.</p>
! <ol class="lowerroman">
! <li><p class="first">interface Atmega128ADC:</p>
<pre class="literal-block">
! interface Atmega128ADC
{
! async command result_t getData();
! async command result_t getContinuousData();
! async command result_t reserveADC();
! async event result_t dataReady(uint16_t data);
}
- </pre>
- </li>
- <li><p class="first">interface ADCControl:</p>
- <pre class="literal-block">
- /* the original ADCControl interface from tos/interfaces/ */
! command result_t init();
! command result_t setSamplingRate(uint8_t rate);
! command result_t bindPort(uint8_t port, uint8_t adcPort);
</pre>
</li>
</ol>
! </li>
! <li><p class="first">External ADCs:
! The HALs of external ADCs are chip and platform dependent. Their
! interfaces SHOULD be defined with regard to the HIL
! interfaces specified below. As stated above (<a class="reference" href="#external-adcs">External ADCs</a>),
! HALs for external ADCs might also have to deal with bus arbitration
! and related tasks.</p>
! </li>
! </ol>
</div>
! <div class="section" id="hardware-interface-layer-hil">
! <h2><a name="hardware-interface-layer-hil">Hardware Interface Layer (HIL)</a></h2>
! <p>An HIL provides application-level OS services via platform independent
! interfaces. The ADC's HIL interface should abstract from platform
! dependent settings as a platform independent application is not in a
! position to deal with platform dependent settings such as a channel
! number or sample-hold-time. In HIL a translation from a platform
! independent representation of a sensor to platform dependent settings
! for a HAL's <em>bind</em> needs to be performed. Also, the HIL is responsible
! for translating an application request to HAL primitives.</p>
! <p>The current practice of having wrappers represent sensors is
! maintained: A wrapper configuration will provide a <em>StdControl</em>, the
! <em>ADCSingle</em> and the <em>ADCMultiple</em> interface. A wrapper thus
! represents the HIL in the ADC's hardware abstraction, i.e. it sits on
! top of the native HAL component. Its task is to bind to HAL with the
! appropriate settings (typically done in StdControl.init) and to
! forward commands, possibly adding slight changes to translate them to
! the HAL interface. Since an HAL interface is designed with the HIL
! interfaces in mind wrappers will typically be fairly lightweight. An
! example configuration for a temperature sensor wrapper on the msp430
! platform would look like this:</p>
<pre class="literal-block">
! StdControl
! | ADCSingle
! | | ADCMultiple
! | | |
! +------|----|----|------------------------------------------+
! | | | | Temperature |
! | v v v |
! | +--------------------+ MSP430ADC12Single +------------+ |
! | | TemperatureM |-------------------->|MSP430ADC12C| |
! | | | MSP430ADC12Multiple | | |
! | | |-------------------->| | |
! | +--------------------+ +------------+ |
! +-----------------------------------------------------------+
</pre>
! <p>On the level of HIL two interfaces MUST be provided: ADCSingle and
! ADCMultiple. ADCSingle is used for single conversions (once or
! repeated) and ADCMultiple is used for multiple conversions (once or
! repeated).</p>
! <p>Both interfaces must take into account that some (e.g. external ADCs)
! may face errors during the sampling process which can lead to invalid
! results. Therefore events in the ADCSingle and ADCMultiple interfaces
! not only return the conversion result(s) but also additional error
! information contained in a new datatype adcresult_t.</p>
! <p>The returned conversion results are uninterpreted 16-bit values. Note
! that still multiple results can be combined by an application to
! create a mean or median.</p>
! <ol class="loweralpha">
! <li><p class="first">Implementation: platform dependent</p>
</li>
! <li><p class="first">Presentation: application-level OS service (see
! <a class="reference" href="#implementation">3. Implementation</a> for where to find the commented version).:</p>
<pre class="literal-block">
! interface ADCSingle
! {
! async command adcresult_t getData();
! async command adcresult_t getDataContinuous();
! async command adcresult_t reserve();
! async command adcresult_t reserveContinuous();
! async command adcresult_t unreserve();
! async event result_t dataReady(adcresult result, uint16_t data);
}
! interface ADCMultiple
! {
! async command adcresult_t getData(uint16_t *buf, uint16_t length);
! async command adcresult_t getDataContinuous(uint16_t *buf, uint16_t length);
! async command adcresult_t reserve(uint16_t *buf, uint16_t length);
! async command adcresult_t reserveContinuous(uint16_t *buf, uint16_t length);
! async command adcresult_t unreserve();
! async event uint16_t* dataReady(adcresult result, uint16_t *buf, uint16_t length);
}
</pre>
</li>
</ol>
</div>
</div>
<div class="section" id="implementation">
! <h1><a name="implementation">3. Implementation</a></h1>
! <p>The ADCSingle and ADCMultiple interfaces and ADCHIL.h (containing the
! definition of adcresult_t) can be found in tos/interfaces. Interfaces
! relating to msp430 are in tos/platform/msp430. The HAL implementation
! of the msp430 as well as wrappers (HIL) for internal temperature and
! internal voltage of the msp430 can also be found in
! tos/platform/msp430. A test application for the msp430 platform is
! tinyos-1.x/contrib/eyes/apps/TestADC.</p>
</div>
<div class="section" id="author-s-address">
<h1><a name="author-s-address">4. Author's Address</a></h1>
<div class="line-block">
! <div class="line">Jan Hauer <hauer at tkn.tu-berlin.de>,</div>
! <div class="line">Vlado Handziski <handzisk at tkn.tu-berlin.de>,</div>
! <div class="line">Joe Polastre <polastre at cs.berkeley.edu>,</div>
! <div class="line">Lama Nachman <lama.nachman at intel.com></div>
</div>
</div>
--- 686,913 ----
unsigned int inputChannel: 4; // input channel
unsigned int sampleHoldTime: 4; // sample-hold-time
! } msp430adc12_channel_config_t;
</pre>
! <p>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.</p>
! <p>The <em>getData</em> 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 <em>jiffies</em> in the relevant commands. A datatype
! <tt class="docutils literal"><span class="pre">msp430adc12_result_t</span></tt> 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.</p>
! <ol class="loweralpha simple" start="5">
! <li>The ADC on ATmega128:</li>
! </ol>
! <p>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):</p>
<pre class="literal-block">
! 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);
! }
</pre>
+ <p>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.</p>
+ </blockquote>
</li>
</ol>
! </blockquote>
</div>
! <div class="section" id="hardware-adaptation-sublayer2-hal2">
! <h2><a name="hardware-adaptation-sublayer2-hal2">Hardware Adaptation SubLayer2 (HAL2)</a></h2>
! <blockquote>
! <ol class="loweralpha">
! <li><p class="first">Presentation: Chip independent, platform dependent</p>
! <blockquote>
! <p>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.:</p>
<pre class="literal-block">
! 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
! }
</pre>
! <p>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.</p>
! </blockquote>
</li>
! <li><p class="first">Implementation: Chip dependent</p>
! <blockquote>
! <p>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.</p>
! <ol class="lowerroman simple">
! <li>MSP430</li>
! </ol>
! <p>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:</p>
<pre class="literal-block">
! /* 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;
}
</pre>
+ <p>The MSP430ADC12ChannelConfigM module SHOULD be placed in the
+ according platform or sensorboard directory and it MUST
+ implement the interface "MSP430ADC12ChannelConfig".:</p>
+ <pre class="literal-block">
+ interface MSP430ADC12ChannelConfig {
+ async event msp430adc12_channel_config_t getConfigurationData(uint8_t channel);
+ }
+ </pre>
+ <p>ADCM MAY signal the <em>getConfigurationData()</em> 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.</p>
+ <p>ii. For the ADC on the ATmega128 in the current implementation
+ a port number exhaustively defines all relevant settings.</p>
+ </blockquote>
</li>
</ol>
+ </blockquote>
</div>
</div>
+ <div class="section" id="services">
+ <h1><a name="services">Services</a></h1>
+ <p>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.</p>
+ </div>
+ <div class="section" id="hardware-interface-layer-hil">
+ <h1><a name="hardware-interface-layer-hil">Hardware Interface Layer (HIL)</a></h1>
+ <p>The ADC hardware stack itself does not include an HIL for reasons
+ mentioned in the <a class="reference" href="#introduction">Introduction</a>. Instead named sensor wrappers
+ provide platform independent access to the ADC which is covered in TEP
+ 109 (Sensorboards).</p>
+ </div>
<div class="section" id="implementation">
! <h1><a name="implementation">Implementation</a></h1>
! <p>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.</p>
</div>
<div class="section" id="author-s-address">
<h1><a name="author-s-address">4. Author's Address</a></h1>
<div class="line-block">
! <div class="line">Jan Hauer / Vlado Handziski</div>
! <div class="line">Sekr FT5</div>
! <div class="line">Einsteinufer 25</div>
! <div class="line">10587 Berlin</div>
! <div class="line">GERMANY</div>
! <div class="line"><br /></div>
! <div class="line">email - <a class="reference" href="mailto:hauer@tkn.tu-berlin.de">hauer@tkn.tu-berlin.de</a>, <a class="reference" href="mailto:handzisk@tkn.tu-berlin.de">handzisk@tkn.tu-berlin.de</a></div>
! <div class="line"><br /></div>
! <div class="line"><br /></div>
! <div class="line">Philip Levis</div>
! <div class="line">467 Soda Hall</div>
! <div class="line">UC Berkeley</div>
! <div class="line">Berkeley, CA 94720</div>
! <div class="line"><br /></div>
! <div class="line">phone - +1 510 290 5283</div>
! <div class="line"><br /></div>
! <div class="line">email - <a class="reference" href="mailto:pal@cs.berkeley.edu">pal@cs.berkeley.edu</a></div>
! <div class="line"><br /></div>
! <div class="line"><br /></div>
! <div class="line">David Gay</div>
! <div class="line">2150 Shattuck Ave, Suite 1300</div>
! <div class="line">Intel Research</div>
! <div class="line">Berkeley, CA 94704</div>
! <div class="line"><br /></div>
! <div class="line">phone - +1 510 495 3055</div>
! <div class="line"><br /></div>
! <div class="line">email - <a class="reference" href="mailto:david.e.gay@intel.com">david.e.gay@intel.com</a></div>
</div>
</div>
More information about the Tinyos-beta-commits
mailing list