<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.3.6: http://docutils.sourceforge.net/" />
<title>SIDs: Source and Sink Independent Drivers</title>
<meta name="author" content="Gilman Tolle, Philip Levis, and David Gay" />
<style type="text/css">
</style>
</head>
<body>
-<div class="document" id="sids-source-and-sink-independent-drivers">
<h1 class="title">SIDs: Source and Sink Independent Drivers</h1>
<table class="docinfo" frame="void" rules="none">
<col class="docinfo-name" />
<td>Gilman Tolle, Philip Levis, and David Gay</td></tr>
<tr class="field"><th class="docinfo-name">Draft-Created:</th><td class="field-body">30-Oct-2005</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.1.2.3</td>
+<tr class="field"><th class="docinfo-name">Draft-Version:</th><td class="field-body">1.7</td>
</tr>
-<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2006-06-09</td>
+<tr class="field"><th class="docinfo-name">Draft-Modified:</th><td class="field-body">2007-01-10</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>
</tbody>
</table>
+<div class="document" id="sids-source-and-sink-independent-drivers">
<div class="note">
<p class="first admonition-title">Note</p>
<p class="last">This memo documents a part of TinyOS for the TinyOS Community, and
of this memo is unlimited. This memo is in full compliance with
TEP 1.</p>
</div>
-<div class="section">
-<h1><a id="abstract" name="abstract">Abstract</a></h1>
-<p>This memo documents a set of hardware- and sensor-independent interfaces
+<div class="section" id="abstract">
+<h1><a name="abstract">Abstract</a></h1>
+<p>This memo documents a set of hardware- and sensor-independent interfaces
for data sources and sinks in TinyOS 2.x.</p>
</div>
-<div class="section">
-<h1><a id="introduction" name="introduction">1. Introduction</a></h1>
+<div class="section" id="introduction">
+<h1><a name="introduction">1. Introduction</a></h1>
<p>Sensing is an integral part of any sensor network application. Having
a wide variety of sensor interfaces usually does not impose a large
burden on an application developer, as any given application uses a
therefore has telescoping sensor abstractions, providing both simple
and sensor-independent as well as sensor-specific interfaces.</p>
</div>
-<div class="section">
-<h1><a id="sensors-in-tinyos-1-x" name="sensors-in-tinyos-1-x">2. Sensors in TinyOS 1.x</a></h1>
+<div class="section" id="sensors-in-tinyos-1-x">
+<h1><a name="sensors-in-tinyos-1-x">2. Sensors in TinyOS 1.x</a></h1>
<p>Early TinyOS sensors were generally analog. To sample one of these
sensors, an application makes an analog-to-digital conversion using
the MCU ADC. Because all early sensors required ADC conversions, the
Many sensors today are digital. To sample these sensors, the MCU sends
a sample command and receives the corresponding data over a bus (e.g.,
SPI, I2C). The latency involved, combined with possible Resource
-arbitration [_tep108], means that these bus operations are often
+arbitration <a class="footnote-reference" href="#id2" id="id1" name="id1">[1]</a>, means that these bus operations are often
synchronous code. In the command direction, this can force a task
allocation to convert async to sync; in the event direction, the
application has to deal with async code even though the event is, in
practice, in a task.</p>
-<p>Finallly, the simplicity of the ADC interface has led many sensors to
+<p>Finally, the simplicity of the ADC interface has led many sensors to
introduce several new ones for calibration and control, such as
<tt class="docutils literal"><span class="pre">Mic</span></tt> and <tt class="docutils literal"><span class="pre">MagSetting</span></tt>. Because ADCs generally do not have error
conditions, the ADC interface has no way to signal that a sample
and common interfaces for basic and portable use. Providing a
telescoping sensor abstraction allows both classes of use.</p>
</div>
-<div class="section">
-<h1><a id="sensors-in-tinyos-2-x" name="sensors-in-tinyos-2-x">3. Sensors in TinyOS 2.x</a></h1>
+<div class="section" id="sensors-in-tinyos-2-x">
+<h1><a name="sensors-in-tinyos-2-x">3. Sensors in TinyOS 2.x</a></h1>
<p>TinyOS 2.x has several sensor-independent interfaces, which cover a
range of common use cases. These interfaces can be used to write a
Source- or Sink-Independent Driver (SID). A SID is source/sink
information on the sort of sensor or device they sit on top of. A SID
SHOULD provide one or more of the interfaces described in this
section, depending on its expected uses and underlying data model.</p>
-<div class="section">
-<h2><a id="split-phase-small-scalar-i-o" name="split-phase-small-scalar-i-o">3.1 Split-Phase Small Scalar I/O</a></h2>
+<div class="section" id="split-phase-small-scalar-i-o">
+<h2><a name="split-phase-small-scalar-i-o">3.1 Split-Phase Small Scalar I/O</a></h2>
<p>The first set of interfaces can be used for low-rate scalar I/O:</p>
<pre class="literal-block">
interface Read<val_t> {
<p>If the <tt class="docutils literal"><span class="pre">result</span></tt> parameter of the <tt class="docutils literal"><span class="pre">Read.readDone</span></tt> and
<tt class="docutils literal"><span class="pre">ReadWrite.readDone</span></tt> events is not SUCCESS, then the memory of the
<tt class="docutils literal"><span class="pre">val</span></tt> parameter MUST be filled with zeroes.</p>
+<p>If the call to <tt class="docutils literal"><span class="pre">Read.read</span></tt> has returned SUCCESS, but the
+<tt class="docutils literal"><span class="pre">Read.readDone</span></tt> event has not yet been signalled, then a subsequent
+call to <tt class="docutils literal"><span class="pre">Read.read</span></tt> MUST not return SUCCESS. This simple locking
+technique, as opposed to a more complex system in which multiple
+read/readDone pairs may be outstanding, is intended to reduce the
+complexity of code that is a client of a SID interface.</p>
<p>Examples of sensors that would be suited to this class of interface
include many basic sensors, such as photo, temp, voltage, and ADC
readings.</p>
</div>
-<div class="section">
-<h2><a id="split-phase-large-scalar-i-o" name="split-phase-large-scalar-i-o">3.2 Split-Phase Large Scalar I/O</a></h2>
+<div class="section" id="split-phase-large-scalar-i-o">
+<h2><a name="split-phase-large-scalar-i-o">3.2 Split-Phase Large Scalar I/O</a></h2>
<p>If the SID's data object is too big to be passed efficienctly on the
stack, it can provide read/write interfaces that pass parameters by
pointer rather than value:</p>
<tt class="docutils literal"><span class="pre">val</span></tt> parameter points to MUST be filled with zeroes.</p>
<p>Examples of sensors that are suited to this set of interfaces include
those that generate multiple simultaneous readings for which
-passing by value is inefficient, such as a two-axis digital
+passing by value is inefficient, such as a two-axis digital
accelerometer.</p>
</div>
-<div class="section">
-<h2><a id="metadata-and-shifting" name="metadata-and-shifting">3.3 Metadata and Shifting</a></h2>
-<p>Generally, simple types are made up of octets. However, sensor values
-often have levels of precision besides a multiple of 8. Any value
-contained in a simple type MUST be left shifted so that it covers as
-much of the type's range as possible. For example, if a 12-bit ADC
-reading is presented as a 16-bit Read interface:</p>
-<pre class="literal-block">
-component DemoSensorC {
- provides interface Read<uint16_t>;
-}
-</pre>
-<p>then the 12-bit value MUST be shifted left so that its range is 0x0000
-- 0xfff0, rather than 0x0000 - 0x0fff. A device MAY specify the
-precision of one of its interfaces with the DeviceMetadata interface:</p>
-<pre class="literal-block">
-interface DeviceMetadata {
- command uint8_t getSignificantBits();
-}
-</pre>
-<p>The name of the instance of DeviceMetadata SHOULD clearly indicate
-which interface it corresponds to.</p>
-</div>
-<div class="section">
-<h2><a id="single-phase-scalar-i-o" name="single-phase-scalar-i-o">3.4 Single-Phase Scalar I/O</a></h2>
+<div class="section" id="single-phase-scalar-i-o">
+<h2><a name="single-phase-scalar-i-o">3.4 Single-Phase Scalar I/O</a></h2>
<p>Some devices may have their state cached or readily available. In
these cases, the device can provide a single-phase instead of
split-phase operation. Examples include a node's MAC address (which
}
</pre>
</div>
-<div class="section">
-<h2><a id="notification-based-scalar-i-o" name="notification-based-scalar-i-o">3.5 Notification-Based Scalar I/O</a></h2>
+<div class="section" id="notification-based-scalar-i-o">
+<h2><a name="notification-based-scalar-i-o">3.5 Notification-Based Scalar I/O</a></h2>
<p>Some sensor devices represent triggers, rather than request-driven
data acquisition. Examples of such sensors include switches,
passive-IR (PIR) motion sensors, tone detectors, and smoke
remain enabled.</p>
<p>The val parameter is used as defined in the Read interface.</p>
</div>
-<div class="section">
-<h2><a id="split-phase-streaming-i-o" name="split-phase-streaming-i-o">3.7 Split-Phase Streaming I/O</a></h2>
+<div class="section" id="split-phase-streaming-i-o">
+<h2><a name="split-phase-streaming-i-o">3.7 Split-Phase Streaming I/O</a></h2>
<p>Some sensors can provide a continuous stream of readings, and some
actuators can accept a continuous stream of new data. Depending on the
rate needed and jitter bounds that higher level components can
command error_t read( uint32_t usPeriod );
- event void bufferDone( error_t result,
+ event void bufferDone( error_t result,
val_t* buf, uint16_t count );
event void readDone( error_t result );
-}
+}
</pre>
<p>The postBuffer command takes an array parameterized by the sample
type, and the number of entries in that buffer. A driver can then
command error_t write( uint32_t period );
- event void bufferDone( error_t result,
+ event void bufferDone( error_t result,
val_t* buf, uint16_t count );
event void writeDone( error_t result );
for the ReadStream interface, as are write() and writeDone().</p>
</div>
</div>
-<div class="section">
-<h1><a id="summary" name="summary">4. Summary</a></h1>
+<div class="section" id="summary">
+<h1><a name="summary">4. Summary</a></h1>
<p>According to the design principles described in the HAA[_haa], authors
should write device drivers that provide rich, device-specific
interfaces that expose the full capabilities of each device. In
who only need simple interfaces, and can reduce the effort needed to
connect a sensor into a more general system.</p>
</div>
-<div class="section">
-<h1><a id="author-s-address" name="author-s-address">5. Author's Address</a></h1>
+<div class="section" id="author-s-address">
+<h1><a name="author-s-address">5. Author's Address</a></h1>
<div class="line-block">
<div class="line">Gilman Tolle</div>
<div class="line">2168 Shattuck Ave.</div>
<div class="line"><br /></div>
</div>
</div>
+<div class="section" id="citations">
+<h1><a name="citations">6. Citations</a></h1>
+<table class="docutils footnote" frame="void" id="id2" rules="none">
+<colgroup><col class="label" /><col /></colgroup>
+<tbody valign="top">
+<tr><td class="label"><a class="fn-backref" href="#id1" name="id2">[1]</a></td><td>TEP 108: Resource Arbitration.</td></tr>
+</tbody>
+</table>
+</div>
</div>
</body>
</html>
projects / tinyos-2.x.git / blobdiff