<html xmlns="http://www.w3.org/1999/xhtml" xml:lang="en" lang="en">
<head>
<meta http-equiv="Content-Type" content="text/html; charset=utf-8" />
-<meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
+<meta name="generator" content="Docutils 0.5: 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">
<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>
-<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1.2.9</td>
+<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1.2.10</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-10-12</td>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-11-07</td>
</tr>
<tr class="field"><th class="docinfo-name">Draft-Discuss:</th><td class="field-body">TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu></td>
</tr>
<h1><a id="abstract" name="abstract">Abstract</a></h1>
<p>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
+Architecture (HAA) specified in <a class="citation-reference" href="#tep2" id="id2" name="id2">[TEP2]</a>. It describes some design principles and
documents the set of hardware-independent interfaces to an ADC.</p>
</div>
<div class="section">
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 <tt class="docutils literal"><span class="pre">ADCError</span></tt>, that were tightly bound
-to sensor acquisition but separate in wiring. The separation between the ADC and
-<tt class="docutils literal"><span class="pre">ADCError</span></tt> 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 <a class="citation-reference" href="#tep109" id="id2" name="id2">[TEP109]</a>.</p>
+to sensor acquisition but separate in wiring. The separation between the ADC
+and <tt class="docutils literal"><span class="pre">ADCError</span></tt> 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. <a class="citation-reference" href="#tep109" id="id3" name="id3">[TEP109]</a> (Sensor Boards) shows how a platform can
+present actual named sensors.</p>
<p>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
actual configuration details may be different the procedure of configuring an
ADC can be unified on all ADCs with the help of <strong>hardware independent
interfaces</strong>: in a similar way as the <tt class="docutils literal"><span class="pre">Read</span></tt> interface definition does not
-predefine the type or semantics of the exchanged data (see <a class="citation-reference" href="#tep114" id="id3" name="id3">[TEP114]</a>), a
+predefine the type or semantics of the exchanged data (see <a class="citation-reference" href="#tep114" id="id4" name="id4">[TEP114]</a>), 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 <tt class="docutils literal"><span class="pre">Read<uint8_t></span></tt> or <tt class="docutils literal"><span class="pre">Read<uint16_t></span></tt> interface
-depending on the data it can offer, a component can also use a
-<tt class="docutils literal"><span class="pre">AdcConfigure<atm128_adc_config_t></span></tt> or
+component can provide a <tt class="docutils literal"><span class="pre">Read<uint8_t></span></tt> or <tt class="docutils literal"><span class="pre">Read<uint16_t></span></tt> interface, it
+can also provide a <tt class="docutils literal"><span class="pre">AdcConfigure<atm128_adc_config_t></span></tt> or
<tt class="docutils literal"><span class="pre">AdcConfigure<msp430adc12_channel_config_t></span></tt> interface depending on what ADC
it represents. This TEP proposes the (typed) <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface as the
standard interface for configuring an ADC in TinyOS 2.x.</p>
<p>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 <tt class="docutils literal"><span class="pre">Read</span></tt>, <tt class="docutils literal"><span class="pre">ReadNow</span></tt> and <tt class="docutils literal"><span class="pre">ReadStream</span></tt>
-(see <a class="reference" href="#interfaces">2. Interfaces</a> and <a class="citation-reference" href="#tep114" id="id4" name="id4">[TEP114]</a>). 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.</p>
+denominator of ADCs: they all produce conversion results. To facilitate sensor
+software development conversion results are returned by the ADC stack through
+the interfaces <tt class="docutils literal"><span class="pre">Read</span></tt>, <tt class="docutils literal"><span class="pre">ReadStream</span></tt> and <tt class="docutils literal"><span class="pre">ReadNow</span></tt> (see <a class="reference" href="#interfaces">2. Interfaces</a>
+and <a class="citation-reference" href="#tep114" id="id5" name="id5">[TEP114]</a>). 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.</p>
<p>The top layer of abstraction of an ADC - the Hardware Interface Layer (HIL) -
-thus provides the standard TinyOS interfaces <tt class="docutils literal"><span class="pre">Read</span></tt>, <tt class="docutils literal"><span class="pre">ReadNow</span></tt> and
-<tt class="docutils literal"><span class="pre">ReadStream</span></tt> and uses the <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface for hardware
-configuration (why it <strong>uses</strong> and does not <strong>provide</strong> <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> 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 <a class="citation-reference" href="#tep2" id="id5" name="id5">[TEP2]</a>).</p>
-<p>Following the principles of the HAA <a class="citation-reference" href="#tep2" id="id6" name="id6">[TEP2]</a> the Hardware Adaptation Layer (HAL,
+thus provides the interfaces <tt class="docutils literal"><span class="pre">Read</span></tt>, <tt class="docutils literal"><span class="pre">ReadNow</span></tt> and <tt class="docutils literal"><span class="pre">ReadStream</span></tt> and uses
+the <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface for hardware configuration (why it <strong>uses</strong> and
+does not <strong>provide</strong> <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> 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 <a class="citation-reference" href="#tep2" id="id6" name="id6">[TEP2]</a>).</p>
+<p>Following the principles of the HAA <a class="citation-reference" href="#tep2" id="id7" name="id7">[TEP2]</a> 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 <strong>MSP430 ADC12</strong> hardware abstraction. Other ADCs
+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
+the same HIL representation it may be necessary to perform some degree of
software emulation in the HIL implementation. For example, a <tt class="docutils literal"><span class="pre">ReadStream</span></tt>
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 <a class="citation-reference" href="#tep2" id="id7" name="id7">[TEP2]</a>). The general structure
-(without virtualization) of the ADC hardware stack is as follows</p>
+provides access to the hardware registers (see <a class="citation-reference" href="#tep2" id="id8" name="id8">[TEP2]</a>). The general structure
+(without virtualization) of the ADC stack is as follows</p>
<pre class="literal-block">
^ |
| |
<div class="section">
<h1><a id="interfaces" name="interfaces">2. Interfaces</a></h1>
<p>This TEP proposes the <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface for ADC hardware configuration
-and the <tt class="docutils literal"><span class="pre">Read</span></tt>, <tt class="docutils literal"><span class="pre">ReadNow</span></tt> and <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interfaces to acquire
-conversion results. A <tt class="docutils literal"><span class="pre">Read[Now|Stream]</span></tt> interface is always provided in
-conjunction with a <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface.</p>
+and the <tt class="docutils literal"><span class="pre">Read</span></tt>, <tt class="docutils literal"><span class="pre">ReadStream</span></tt> and <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interfaces to acquire
+conversion results. The <tt class="docutils literal"><span class="pre">Read</span></tt> and <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interfaces are documented
+in <a class="citation-reference" href="#tep114" id="id9" name="id9">[TEP114]</a> and the <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interface is documented in this TEP. A
+<tt class="docutils literal"><span class="pre">Read[Now|Stream]</span></tt> interface is always provided in conjunction with a
+<tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface.</p>
<div class="section">
<h2><a id="interface-for-configuring-the-adc-hardware" name="interface-for-configuring-the-adc-hardware">Interface for configuring the ADC hardware</a></h2>
<p>The <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface is defined as follows:</p>
async command config_type getConfiguration();
}
</pre>
-<p>This interface is used by the ADC implementation to retrieve the hardware
-configuration of an ADC client. <tt class="docutils literal"><span class="pre">config_type</span></tt> 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
-<tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface will be instantiated with the <tt class="docutils literal"><span class="pre">const</span>
-<span class="pre">msp430adc12_channel_config_t*</span></tt> data type. A client MUST always return the same
-configuration through a <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface and, if configuration data
-is passed as a pointer, the HIL component (see <a class="reference" href="#hil-requirements">4. HIL requirements</a>) MUST NOT
-reference it after the return of the <tt class="docutils literal"><span class="pre">getConfiguration()</span></tt> command. If a
-client wants to use the ADC with different configurations it must provide
-multiple instances of the <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface.</p>
+<p>This interface is used by the ADC stack to retrieve the hardware configuration
+of an ADC HIL client. <tt class="docutils literal"><span class="pre">config_type</span></tt> 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 <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt>
+interface will be instantiated with the <tt class="docutils literal"><span class="pre">const</span> <span class="pre">msp430adc12_channel_config_t*</span></tt>
+data type. A client MUST always return the same configuration through a
+<tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface and, if configuration data is passed as a pointer,
+the HIL component (see <a class="reference" href="#hil-requirements">4. HIL requirements</a>) MUST NOT reference it after the
+return of the <tt class="docutils literal"><span class="pre">getConfiguration()</span></tt> command. If a client wants to use the ADC
+with different configurations it must provide multiple instances of the
+<tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface.</p>
+<p>Note that the <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface is <strong>provided</strong> by an ADC HIL client
+and it is <strong>used</strong> 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.</p>
</div>
<div class="section">
<h2><a id="interfaces-for-acquiring-conversion-results" name="interfaces-for-acquiring-conversion-results">Interfaces for acquiring conversion results</a></h2>
-<p>This TEP proposes to adopt the following three generic, source-independent data
-collection interfaces from <a class="citation-reference" href="#tep114" id="id8" name="id8">[TEP114]</a> for the collection of ADC conversion
+<p>This TEP proposes to adopt the following two source-independent data
+collection interfaces from <a class="citation-reference" href="#tep114" id="id10" name="id10">[TEP114]</a> for the collection of ADC conversion
results on the level of HIL:</p>
<pre class="literal-block">
interface Read< size_type >
-interface ReadNow< size_type >
interface ReadStream< size_type >
</pre>
+<p>In addition it proposes the following data collection interface for low-latency
+reading of conversion results:</p>
+<pre class="literal-block">
+interface ReadNow< size_type >
+</pre>
<p>Every data collection interface is associated with an <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt>
interface (how this association is realized is explained in Section <a class="reference" href="#hil-requirements">4. HIL
requirements</a>). As the resolution of conversion results is chip-specific, the
<tt class="docutils literal"><span class="pre">size_type</span></tt> 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
-<a class="citation-reference" href="#tep114" id="id9" name="id9">[TEP114]</a>, in the following their usage is explained with respect to ADCs.</p>
+(e.g. uint16_t for a 12-bit ADC).</p>
<div class="section">
<h3><a id="read" name="read">Read</a></h3>
-<p>The <tt class="docutils literal"><span class="pre">Read</span></tt> interface can be used to sample an ADC channel and return a single
-conversion result as an uninterpreted value. The meaning of the <tt class="docutils literal"><span class="pre">Read</span></tt>
-interface is explained in <a class="citation-reference" href="#tep114" id="id10" name="id10">[TEP114]</a>.</p>
+<p>The <tt class="docutils literal"><span class="pre">Read</span></tt> interface can be used to sample an ADC channel once and return a
+single conversion result as an uninterpreted value. The <tt class="docutils literal"><span class="pre">Read</span></tt> interface is
+documented in <a class="citation-reference" href="#tep114" id="id11" name="id11">[TEP114]</a>.</p>
</div>
<div class="section">
-<h3><a id="readnow" name="readnow">ReadNow</a></h3>
-<p>The <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interface is similar to the <tt class="docutils literal"><span class="pre">Read</span></tt> interface. The difference
-is that if a call to <tt class="docutils literal"><span class="pre">ReadNow.read()</span></tt> succeeds, the ADC starts to sample the
-channel immediately (precisely: when <tt class="docutils literal"><span class="pre">SUCCESS</span></tt> is returned the hardware has
-started the sampling process). Due to its timing constraints the <tt class="docutils literal"><span class="pre">ReadNow</span></tt>
-interface is always provided in conjunction with an instance of the
-<tt class="docutils literal"><span class="pre">Resource</span></tt> interface (a client must reserve the ADC before the client may
-call <tt class="docutils literal"><span class="pre">ReadNow.read()</span></tt>). Please refer to <a class="citation-reference" href="#tep108" id="id11" name="id11">[TEP108]</a> on how the <tt class="docutils literal"><span class="pre">Resource</span></tt>
-interface should be used by a client component.</p>
+<h3><a id="readstream" name="readstream">ReadStream</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface can be used to sample an ADC channel multiple
+times with a specified sampling period. The <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface is
+documented in <a class="citation-reference" href="#tep114" id="id12" name="id12">[TEP114]</a> .</p>
</div>
<div class="section">
-<h3><a id="readstream" name="readstream">ReadStream</a></h3>
-<p>The <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface can be used to sample an ADC channel multiple times
-with a specified sampling period. The meaning of the <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface
-is explained in <a class="citation-reference" href="#tep114" id="id12" name="id12">[TEP114]</a> .</p>
+<h3><a id="readnow" name="readnow">ReadNow</a></h3>
+<p>The <tt class="docutils literal"><span class="pre">ReadNow</span></tt> interface is intended for split-phase low-latency
+reading of small values:</p>
+<pre class="literal-block">
+interface ReadNow<val_t>
+{
+ async command error_t read();
+ async event void readDone( error_t result, val_t val );
+}
+</pre>
+<p>This interface is similar to the <tt class="docutils literal"><span class="pre">Read</span></tt> interface, but works in asynchronous
+context. A successful call to <tt class="docutils literal"><span class="pre">ReadNow.read()</span></tt> means that the ADC hardware
+has started the sampling process and that <tt class="docutils literal"><span class="pre">ReadNow.readDone()</span></tt> will be
+signalled once it has finished (note that the asynchronous
+<tt class="docutils literal"><span class="pre">ReadNow.readDone()</span></tt> might be signalled even before the call to
+<tt class="docutils literal"><span class="pre">ReadNow.read()</span></tt> has returned). Due to its timing constraints the
+<tt class="docutils literal"><span class="pre">ReadNow</span></tt> interface is always provided in conjunction with an instance of the
+<tt class="docutils literal"><span class="pre">Resource</span></tt> interface and a client must reserve the ADC through the
+<tt class="docutils literal"><span class="pre">Resource</span></tt> interface before the client may call <tt class="docutils literal"><span class="pre">ReadNow.read()</span></tt>. Please
+refer to <a class="citation-reference" href="#tep108" id="id13" name="id13">[TEP108]</a> on how the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface should be used by a client
+component.</p>
</div>
</div>
</div>
<p>As explained in <a class="reference" href="#introduction">1. Introduction</a> 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
-signature of the HAL for the MSP430.</p>
+and representation, its design should follow the guidelines described in this
+section to facilitate the mapping to the HIL representation. Appendix B shows
+the signature of the HAL for the MSP430.</p>
<div class="section">
<h2><a id="resource-reservation" name="resource-reservation">Resource reservation</a></h2>
<p>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 <tt class="docutils literal"><span class="pre">Resource</span></tt> interface, instantiate a
standard arbiter component and connect the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface to the
-arbiter as described in <a class="citation-reference" href="#tep108" id="id13" name="id13">[TEP108]</a>. To ensure fair and uniform arbitration on
+arbiter as described in <a class="citation-reference" href="#tep108" id="id14" name="id14">[TEP108]</a>. To ensure fair and uniform arbitration on
all platforms the standard round robin arbiter is recommended. Resource
-arbiters and the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface are the topic of <a class="citation-reference" href="#tep108" id="id14" name="id14">[TEP108]</a>.</p>
+arbiters and the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface are the topic of <a class="citation-reference" href="#tep108" id="id15" name="id15">[TEP108]</a>.</p>
</div>
<div class="section">
<h2><a id="configuration-and-sampling" name="configuration-and-sampling">Configuration and sampling</a></h2>
acquiring single conversion results. In contrast to <tt class="docutils literal"><span class="pre">Read.read()</span></tt> when a call
to <tt class="docutils literal"><span class="pre">ReadNow.read()</span></tt> succeeds, the ADC starts to sample the channel
immediately (a successful <tt class="docutils literal"><span class="pre">Read.read()</span></tt> command may not have this
-implication, see <a class="citation-reference" href="#tep114" id="id1
5" name="id15">[TEP114]</a> and <a class="reference" href="#interfaces">2. Interfaces</a>). A client MUST reserve the ADC
+implication, see <a class="citation-reference" href="#tep114" id="id1
6" name="id16">[TEP114]</a> and <a class="reference" href="#interfaces">2. Interfaces</a>). A client MUST reserve the ADC
through the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface before the client may call
-<tt class="docutils literal"><span class="pre">ReadNow.read()</span></tt> and it must release the ADC through the <tt class="docutils literal"><span class="pre">Resource</span></tt>
-interface when it no longer needs to access it (for more details on the
-<tt class="docutils literal"><span class="pre">Resource</span></tt> interface please refer to <a class="citation-reference" href="#tep108" id="id16" name="id16">[TEP108]</a>). The associated ADC channel
-(port) and further configuration details are returned by the
+<tt class="docutils literal"><span class="pre">ReadNow.read()</span></tt> and it MUST release the ADC through the <tt class="docutils literal"><span class="pre">Resource</span></tt>
+interface when it no longer needs to access it (for more details on how to use
+the <tt class="docutils literal"><span class="pre">Resource</span></tt> interface please refer to <a class="citation-reference" href="#tep108" id="id17" name="id17">[TEP108]</a>). The associated ADC
+channel (port) and further configuration details are returned by the
<tt class="docutils literal"><span class="pre">AdcConfigure.getConfiguration()</span></tt> command. It is the task of the client to
wire this interface to a component that provides the client's ADC
configuration. The HIL implementation will use the <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface
</pre>
<p>The <tt class="docutils literal"><span class="pre">AdcReadStreamClientC</span></tt> component provides a <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface for
acquiring multiple conversion results at once. The <tt class="docutils literal"><span class="pre">ReadStream</span></tt> interface is
-explained in <a class="citation-reference" href="#tep114" id="id1
7" name="id17">[TEP114]</a> and <a class="reference" href="#interfaces">2. Interfaces</a>. The <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface is
+explained in <a class="citation-reference" href="#tep114" id="id1
8" name="id18">[TEP114]</a> and <a class="reference" href="#interfaces">2. Interfaces</a>. The <tt class="docutils literal"><span class="pre">AdcConfigure</span></tt> interface is
used in the same way as described in the section on the <tt class="docutils literal"><span class="pre">AdcReadClientC</span></tt>.
Note that both, <tt class="docutils literal"><span class="pre">size_type</span></tt> and <tt class="docutils literal"><span class="pre">config_type</span></tt>, are only placeholders and
will be instantiated by the respective HIL implementation (for an example how
</div>
<div class="section">
<h1><a id="implementation" name="implementation">6. Implementation</a></h1>
+<div class="section">
+<h2><a id="testadc-application" name="testadc-application">TestAdc application</a></h2>
+<p>An ADC HIL test application can be found in <tt class="docutils literal"><span class="pre">tinyos-2.x/apps/tests/TestAdc</span></tt>.
+Note that this application instantiates generic DemoSensorC, DemoSensorStreamC
+and DemoSensorNowC components (see <a class="citation-reference" href="#tep114" id="id19" name="id19">[TEP114]</a>) and assumes that these components
+are actually wired to an ADC HIL. Please refer to
+<tt class="docutils literal"><span class="pre">tinyos-2.x/apps/tests/TestAdc/README.txt</span></tt> for more information.</p>
+</div>
+<div class="section">
+<h2><a id="haa-on-the-msp430-and-atmega-128" name="haa-on-the-msp430-and-atmega-128">HAA on the MSP430 and Atmega 128</a></h2>
<p>The implementation of the ADC12 stack on the MSP430 can be found in
<tt class="docutils literal"><span class="pre">tinyos-2.x/tos/chips/msp430/adc12</span></tt>:</p>
<blockquote>
<ul class="simple">
<li><tt class="docutils literal"><span class="pre">HplAtm128AdcC.nc</span></tt> is the HPL implementation</li>
<li><tt class="docutils literal"><span class="pre">Atm128AdcP.nc</span></tt> is the HAL implementation</li>
-<li><tt class="docutils literal"><span class="pre">WireAdcP.nc</span></tt> and the library components for arbitrating 'Read',
-'ReadNow' and 'ReadStream', <tt class="docutils literal"><span class="pre">ArbitratedReadC</span></tt> and
+<li><tt class="docutils literal"><span class="pre">AdcP.nc</span></tt>, <tt class="docutils literal"><span class="pre">WireAdcP.nc</span></tt> and the library components for arbitrating
+'Read', 'ReadNow' and 'ReadStream', <tt class="docutils literal"><span class="pre">ArbitratedReadC</span></tt> and
<tt class="docutils literal"><span class="pre">ArbitratedReadStreamC</span></tt> (in <tt class="docutils literal"><span class="pre">tinyos-2.x/tos/system</span></tt>), realize
-the HAL</li>
+the HIL</li>
<li><tt class="docutils literal"><span class="pre">AdcReadClientC.nc</span></tt>, <tt class="docutils literal"><span class="pre">AdcReadNowClientC.nc</span></tt> and
<tt class="docutils literal"><span class="pre">AdcReadStreamClientC.nc</span></tt> provide virtualized access to the HIL</li>
</ul>
</blockquote>
</div>
+</div>
<div class="section">
<h1><a id="appendix-a-hardware-differences-between-platforms" name="appendix-a-hardware-differences-between-platforms">Appendix A: Hardware differences between platforms</a></h1>
<p>The following table compares the characteristics of two microcontrollers
async event uint16_t* multipleDataReady(uint16_t buffer[], uint16_t numSamples);
}
-typedef struct {
+typedef struct
+{
unsigned int inch: 4; // input channel
unsigned int sref: 3; // reference voltage
unsigned int ref2_5v: 1; // reference voltage level
<table class="docutils citation" frame="void" id="tep2" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<tr><td class="label"><a name="tep2">[TEP2]</a></td><td><em>(<a class="fn-backref" href="#id5">1</a>, <a class="fn-backref" href="#id6">2</a>, <a class="fn-backref" href="#id7">3</a>)</em> TEP 2: Hardware Abstraction Architecture.</td></tr>
+<tr><td class="label"><a name="tep2">[TEP2]</a></td><td><em>(<a class="fn-backref" href="#id2">1</a>, <a class="fn-backref" href="#id6">2</a>, <a class="fn-backref" href="#id7">3</a>, <a class="fn-backref" href="#id8">4</a>)</em> TEP 2: Hardware Abstraction Architecture.</td></tr>
</tbody>
</table>
<table class="docutils citation" frame="void" id="tep108" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<tr><td class="label"><a name="tep108">[TEP108]</a></td><td><em>(<a class="fn-backref" href="#id11">1</a>, <a class="fn-backref" href="#id13">2</a>, <a class="fn-backref" href="#id14">3</a>, <a class="fn-backref" href="#id16">4</a>)</em> TEP 108: Resource Arbitration.</td></tr>
+<tr><td class="label"><a name="tep108">[TEP108]</a></td><td><em>(<a class="fn-backref" href="#id13">1</a>, <a class="fn-backref" href="#id14">2</a>, <a class="fn-backref" href="#id15">3</a>, <a class="fn-backref" href="#id17">4</a>)</em> TEP 108: Resource Arbitration.</td></tr>
</tbody>
</table>
<table class="docutils citation" frame="void" id="tep109" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<tr><td class="label"><a class="fn-backref" href="#id2" name="tep109">[TEP109]</a></td><td>TEP 109: Sensor Boards.</td></tr>
+<tr><td class="label"><a class="fn-backref" href="#id3" name="tep109">[TEP109]</a></td><td>TEP 109: Sensor Boards.</td></tr>
</tbody>
</table>
<table class="docutils citation" frame="void" id="tep114" rules="none">
<colgroup><col class="label" /><col /></colgroup>
<tbody valign="top">
-<tr><td class="label"><a name="tep114">[TEP114]</a></td><td><em>(<a class="fn-backref" href="#id3">1</a>, <a class="fn-backref" href="#id4">2</a>, <a class="fn-backref" href="#id8">3</a>, <a class="fn-backref" href="#id9">4</a>, <a class="fn-backref" href="#id10">5</a>, <a class="fn-backref" href="#id12">6</a>, <a class="fn-backref" href="#id15">7</a>, <a class="fn-backref" href="#id17">8</a>)</em> TEP 114: SIDs: Source and Sink Independent Drivers.</td></tr>
+<tr><td class="label"><a name="tep114">[TEP114]</a></td><td><em>(<a class="fn-backref" href="#id4">1</a>, <a class="fn-backref" href="#id5">2</a>, <a class="fn-backref" href="#id9">3</a>, <a class="fn-backref" href="#id10">4</a>, <a class="fn-backref" href="#id11">5</a>, <a class="fn-backref" href="#id12">6</a>, <a class="fn-backref" href="#id16">7</a>, <a class="fn-backref" href="#id18">8</a>, <a class="fn-backref" href="#id19">9</a>)</em> TEP 114: SIDs: Source and Sink Independent Drivers.</td></tr>
</tbody>
</table>
</div>
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
+Architecture (HAA) specified in [TEP2]_. It describes some design principles and
documents the set of hardware-independent interfaces to an ADC.
1. Introduction
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]_.
+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
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
-depending on the data it can offer, a component can also use a
-``AdcConfigure<atm128_adc_config_t>`` or
+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 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.
+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 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). 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]_).
+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
+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
+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 hardware stack is as follows ::
+(without virtualization) of the ADC stack is as follows ::
^ |
====================================================================
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 a ``AdcConfigure`` interface.
+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
--------------------------------------------------------------------
async command config_type getConfiguration();
}
-This interface is used by the ADC implementation to retrieve the hardware
-configuration of an ADC 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.
-
+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 three generic, source-independent data
+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 ReadNow< size_type >
interface ReadStream< size_type >
+In addition it proposes the following data collection interface for low-latency
+reading of conversion results::
+
+ interface ReadNow< 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.
+(e.g. uint16_t for a 12-bit ADC).
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]_.
+The ``Read`` interface can be used to sample an ADC channel once and return a
+single conversion result as an uninterpreted value. The ``Read`` interface is
+documented in [TEP114]_.
-ReadNow
+ReadStream
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-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 (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.
+The ``ReadStream`` interface can be used to sample an ADC channel multiple
+times with a specified sampling period. The ``ReadStream`` interface is
+documented in [TEP114]_ .
-ReadStream
+ReadNow
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
-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]_ .
+The ``ReadNow`` interface is intended for split-phase low-latency
+reading of small values::
+
+ interface ReadNow<val_t>
+ {
+ async command error_t read();
+ async event void readDone( error_t result, val_t val );
+ }
+
+This interface is similar to the ``Read`` interface, but works in asynchronous
+context. A successful call to ``ReadNow.read()`` means that the ADC hardware
+has started the sampling process and that ``ReadNow.readDone()`` will be
+signalled once it has finished (note that the asynchronous
+``ReadNow.readDone()`` might be signalled even before the call to
+``ReadNow.read()`` has returned). Due to its timing constraints the
+``ReadNow`` interface is always provided in conjunction with an instance of the
+``Resource`` interface and a client must reserve the ADC through the
+``Resource`` interface before the client may call ``ReadNow.read()``. Please
+refer to [TEP108]_ on how the ``Resource`` interface should be used by a client
+component.
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
-signature of the HAL for the MSP430.
+and representation, its design should follow the guidelines described in this
+section to facilitate the mapping to the HIL representation. Appendix B shows
+the signature of the HAL for the MSP430.
Resource reservation
--------------------------------------------------------------------
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()`` and it must release the ADC through the ``Resource``
-interface when it no longer needs to access it (for more details on the
-``Resource`` interface please refer to [TEP108]_). The associated ADC channel
-(port) and further configuration details are returned by the
+``ReadNow.read()`` and it MUST release the ADC through the ``Resource``
+interface when it no longer needs to access it (for more details on how to use
+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 HIL implementation will use the ``AdcConfigure`` interface
6. Implementation
====================================================================
+TestAdc application
+--------------------------------------------------------------------
+
+An ADC HIL test application can be found in ``tinyos-2.x/apps/tests/TestAdc``.
+Note that this application instantiates generic DemoSensorC, DemoSensorStreamC
+and DemoSensorNowC components (see [TEP114]_) and assumes that these components
+are actually wired to an ADC HIL. Please refer to
+``tinyos-2.x/apps/tests/TestAdc/README.txt`` for more information.
+
+
+HAA on the MSP430 and Atmega 128
+--------------------------------------------------------------------
+
The implementation of the ADC12 stack on the MSP430 can be found in
``tinyos-2.x/tos/chips/msp430/adc12``:
* ``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
+ * ``AdcP.nc``, ``WireAdcP.nc`` and the library components for arbitrating
+ 'Read', 'ReadNow' and 'ReadStream', ``ArbitratedReadC`` and
``ArbitratedReadStreamC`` (in ``tinyos-2.x/tos/system``), realize
- the HAL
+ the HIL
* ``AdcReadClientC.nc``, ``AdcReadNowClientC.nc`` and
``AdcReadStreamClientC.nc`` provide virtualized access to the HIL
async event uint16_t* multipleDataReady(uint16_t buffer[], uint16_t numSamples);
}
- typedef struct {
+ typedef struct
+ {
unsigned int inch: 4; // input channel
unsigned int sref: 3; // reference voltage
unsigned int ref2_5v: 1; // reference voltage level
projects / tinyos-2.x.git / commitdiff