:TEP: 114
:Group: Core Working Group
:Type: Documentary
-:Status: Draft
+:Status: Final
:TinyOS-Version: 2.x
:Author: Gilman Tolle, Philip Levis, and David Gay
-:Draft-Created: 30-Oct-2005
-:Draft-Version: $Revision$
-:Draft-Modified: $Date$
-:Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>
-
.. Note::
This memo documents a part of TinyOS for the TinyOS Community, and
1. Introduction
====================================================================
-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
-small and static set. However, applications often build on top of more
-general systems, such as management or database layers, which may need
-to sample sensors. Since these are general and sensor-independent
-systems, they require a sensor-independent interface. TinyOS 2.0
-therefore has telescoping sensor abstractions, providing both simple
-and sensor-independent as well as sensor-specific interfaces.
+Sensing is an integral part of any sensor network application. The
+diversity of sensors can lead to a wide variety of different software
+interfaces to these sensors. However, the burden of connecting a
+general sensor data management application to every one of these
+different interfaces suggests that sensors also provide a simple,
+general-purpose interface for data acquisition. Therefore, TinyOS 2.0
+has telescoping sensor abstractions, providing both sensor-independent
+and sensor-specific interfaces. This memo documents a set of hardware-
+and sensor-independent interfaces for data sources and sinks in TinyOS
+2.x.
2. Sensors in TinyOS 1.x
====================================================================
and sensor values are always 16 bits, although only some subset of the
bits may be significant (e.g., a 12-bit value).
-Because sensing can be a part of high-level application logic,
-the asynchronicity of these events means that high-level components
-must deal with atomic sections and possible race conditions, even
-if the sampling rate is very low (e.g., every five minutes)
-and so could be easily placed in a task.
+Because sensing is an integral part of high-level application logic,
+having asynchronous events means that high-level components
+must work with atomic sections, even if the sampling rate is very low
+(e.g., every five minutes) and so could be easily placed in a
+task. Race conditions are problematic and possible in any real time
+multi-tasking design. Race conditions are a failure in design, and
+especially difficult to detect at low sampling rates.
Additionally, not all sensors require ADC conversions from the MCU.
Many sensors today are digital. To sample these sensors, the MCU sends
application has to deal with async code even though the event is, in
practice, in a task.
-Finally, the simplicity of the ADC interface has led many sensors to
-introduce several new ones for calibration and control, such as
-``Mic`` and ``MagSetting``. Because ADCs generally do not have error
-conditions, the ADC interface has no way to signal that a sample
-failed. This turns out to be important for sensors where the sampling
-request is split-phase, such as sensors over a bus. In these cases, it
-is possible that the driver accepts the request to sample, but once
-acquiring the bus discovers something is wrong with the sensor. This
-property has led bus-based sensors to also have a separate
-``ADCError`` interface; this interface breaks the basic TinyOS pattern
-of a tight coupling between split-phase commands and their completion
-events, as the command is in ADC but the completion event is in
-ADCError.
-
-All of these complications can make it difficult to write high-level
-code that is sensor independent, unless the sensor is a simple ADC
-reading. Sensors, when possible, should follow an approach similar to
-the HAA[_haa], where they have sensor- or sensor-class-specific
-interfaces for high performance or special case use, but also simple
-and common interfaces for basic and portable use. Providing a
-telescoping sensor abstraction allows both classes of use.
+Finally, the simplicity of the ADC interface has led many sensor
+modules to introduce several new interfaces for calibration and
+control, such as ``Mic`` and ``MagSetting``. Because ADCs generally do
+not have error conditions, the ADC interface has no way to signal that
+a sample failed. This turns out to be important for sensors where the
+sampling request is split-phase, such as sensors over a bus. In these
+cases, it is possible that the driver accepts the request to sample,
+but once acquiring the bus discovers something is wrong with the
+sensor. This property has led bus-based sensors to also have a
+separate ``ADCError`` interface; this interface breaks the basic
+TinyOS pattern of a tight coupling between split-phase commands and
+their completion events, as the command is in ADC but the completion
+event is in ADCError.
+
+All of these complications provide the context of the challenge to
+write high-level code that is sensor independent. Sensors, when
+possible, should follow an approach similar to the HAA[_haa], where
+they have sensor- or sensor-class-specific interfaces for high
+performance or special case use, but also simple and common interfaces
+for basic and portable use. Providing a telescoping sensor abstraction
+allows both classes of use.
3. Sensors in TinyOS 2.x
====================================================================
-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
-independent because its interfaces do not themselves contain
-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.
+TinyOS 2.x contains several nesC interfaces that can be used to
+provide sensor-independent interfaces which cover a range of common
+use cases. This document describes these interfaces, and explains how
+to use these interfaces to write a Source- or Sink-Independent Driver
+(SID). A SID is source/sink independent because its interfaces do not
+themselves contain 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.
+
+This table summarizes the SID interfaces:
+
++------------------------+-----------+-----------+-----------+
+| Name | Phase | Data type | Section |
++------------------------+-----------+-----------+-----------+
+| Read | Split | Scalar | 3.1 |
++------------------------+-----------+-----------+-----------+
+| Get | Single | Scalar | 3.2 |
++------------------------+-----------+-----------+-----------+
+| Notify | Trigger | Scalar | 3.3 |
++------------------------+-----------+-----------+-----------+
+| ReadStream | Split | Stream | 3.4 |
++------------------------+-----------+-----------+-----------+
3.1 Split-Phase Small Scalar I/O
--------------------------------------------------------------------
event void readDone( error_t result, val_t val );
}
- interface Write<val_t> {
- command error_t write( val_t val );
- event void writeDone( error_t result );
- }
-
-A component that provides both read and write functionality might want
-to use a combined version of the interface, to reduce the amount of
-wiring required by the client application::
-
- interface ReadWrite<val_t> {
- command error_t read();
- event void readDone( error_t result, val_t val );
-
- command error_t write( val_t val );
- event void writeDone( error_t result );
- }
-
-A component that can support concurrent reads and writes SHOULD
-provide separate Read/Write interfaces. A component whose internal
-logic will cause a read to fail while a write is pending or a write to
-fail while a read is pending MUST provide a ReadWrite interface.
-
If the ``result`` parameter of the ``Read.readDone`` and
``ReadWrite.readDone`` events is not SUCCESS, then the memory of the
``val`` parameter MUST be filled with zeroes.
-If the call to ``Read.read`` has returned SUCCESS, but the
-``Read.readDone`` event has not yet been signalled, then a subsequent
-call to ``Read.read`` 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.
+If the call to ``read`` has returned SUCCESS, but the ``readDone``
+event has not yet been signaled, then a subsequent call to ``read``
+MUST return EBUSY or FAIL. 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 SID client code.
Examples of sensors that would be suited to this class of interface
include many basic sensors, such as photo, temp, voltage, and ADC
readings.
-3.2 Split-Phase Large Scalar I/O
---------------------------------------------------------------------
-
-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::
-
- interface ReadRef<val_t> {
- command error_t read( val_t* val );
- event void readDone( error_t result, val_t* val );
- }
-
- interface WriteRef<val_t> {
- command error_t write( val_t* val );
- event void writeDone( error_t result, val_t* val );
- }
-
- interface ReadWriteRef<val_t> {
- command error_t read( val_t* val );
- event void readDone( error_t result, val_t* val );
-
- command error_t write( val_t* val );
- event void writeDone( error_t result, val_t* val );
- }
-
-The caller is responsible for allocating storage pointed to by the val
-pointer which is passed to read() or write(). The SID MUST then
-take ownership of the storage, store a new value into it or copy a
-value out of it, and then relinquish it before signaling readDone() or
-writeDone(). If read or write() returns SUCCESS then the caller MUST
-NOT access or modify the storage pointed to by the val pointer until
-it handles the readDone() or writeDone() event.
-
-As is the case with the parameters by value, whether a component
-provides separate ReadRef and WriteRef or ReadWriteRef affects the
-concurrency it allows. If a component can allow the two to execute
-concurrently, then it SHOULD provide separate ReadRef and WriteRef
-interfaces. If the two cannot occur concurrently, then it MUST provide
-ReadWriteRef.
-
-If the ``result`` parameter of the ``ReadRef.readDone`` and
-``ReadWriteRef.readDone`` events is not SUCCESS, then the memory the
-``val`` parameter points to MUST be filled with zeroes.
-
-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
-accelerometer.
-
-3.4 Single-Phase Scalar I/O
+3.2 Single-Phase Scalar I/O
--------------------------------------------------------------------
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
the radio stack caches in memory), profiling information (e.g.,
-packets received), or a GPIO pin. These devices MAY use these
-single-phase interfaces::
+packets received), or a GPIO pin. These devices MAY use the
+Get interface::
interface Get<val_t> {
command val_t get();
}
- interface Set<val_t> {
- command void set( val_t val );
- }
-
- interface GetSet<val_t> {
- command val_t get();
- command void set( val_t val );
- }
-
-If a device's data object is readily available but still too large to
-be passed on the stack, then the device MAY use these interfaces::
- interface GetRef<val_t> {
- command error_t get( val_t* val );
- }
-
- interface SetRef<val_t> {
- command error_t set( val_t* val );
- }
-
- interface GetSetRef<val_t> {
- command error_t get( val_t* val );
- command error_t set( val_t* val );
- }
-3.5 Notification-Based Scalar I/O
+3.3 Notification-Based Scalar I/O
--------------------------------------------------------------------
Some sensor devices represent triggers, rather than request-driven
The enable() and disable() command enable and disable notification
events for the interface instance used by a single particular
client. They are distinct from the sensor's power state. For example,
-if an enabled sensor is powered down, then when powered up it MUST
+if an enabled sensor is powered down, then when powered up it will
remain enabled.
+If ``enable`` returns SUCCESS, the interface MUST subsequently
+signal notifications when appropriate. If ``disable`` returns SUCCESS,
+the interface MUST NOT signal any notifications.
+
The val parameter is used as defined in the Read interface.
-3.7 Split-Phase Streaming I/O
+3.4 Split-Phase Streaming I/O
--------------------------------------------------------------------
Some sensors can provide a continuous stream of readings, and some
enough when each new reading must be transferred from asynchronous to
synchronous context through the task queue.
-The ReadStreaming interface MAY be provided by a device that can
+The ReadStream interface MAY be provided by a device that can
provide a continuous stream of readings::
interface ReadStream<val_t> {
After posting at least one buffer, the client can call read() with a
specified sample period in terms of microseconds. The driver then
-begins to fill the buffers in the queue, signalling the bufferDone()
+begins to fill the buffers in the queue, signaling the bufferDone()
event when a buffer has been filled. The client MAY call postBuffer()
after read() in order to provide the device with new storage for
future reads.
-If the device ever takes a sample that it cannot store (e.g., no
-buffers are available), it MUST signal readDone(). If an error occurs
-during a read, then the device MUST signal readDone() with an
-appropriate failure code. Before a device signals readDone(), it MUST
-signal bufferDone() for all outstanding buffers. If a readDone() is
-pending, calls to postBuffer MUST return FAIL.
-
-The following interface can be used for bulk writes::
-
- interface WriteStream<val_t> {
+If the device ever takes a sample that it cannot store (e.g., due to
+buffer underrun), it MUST signal readDone() with an appropriate
+failure code. If an error occurs during a read, then the device MUST
+signal readDone() with an appropriate failure code. Before a device
+signals readDone(), it MUST signal bufferDone() for all outstanding
+buffers. If a readDone() is pending, calls to postBuffer MUST return
+FAIL.
+
+In the ReadStream interface, ``postBuffer`` returns SUCCESS if the buffer
+was successfully added to the queue, FAIL otherwise. A return value
+of SUCCESS from ``read`` indicates reading has begun and the interface
+will signal ``bufferDone`` and/or ``readDone`` in the future. A
+return value of FAIL means the read did not begin and the interface
+MUST NOT signal ``readDone`` or ``bufferDone``. Calls to ``read``
+MAY return EBUSY if the component cannot service the request.
+
+4. Implementation
+====================================================================
- command error_t postBuffer( val_t* buf, uint16_t count );
+An implementation of the Read interface can be found in
+``tos/system/SineSensorC.nc`` and ``tos/system/ArbitratedReadC.nc``.
- command error_t write( uint32_t period );
+An implementation of the Get interface can be found in
+``tos/platforms/telosb/UserButtonC.nc``.
- event void bufferDone( error_t result,
- val_t* buf, uint16_t count );
+An implementation of the ReadStream interface can be found in
+``tos/sensorboards/mts300/MageXStreamC.nc``.
- event void writeDone( error_t result );
- }
+Implementations of the Notify interface can be found in
+``tos/platforms/telosb/SwitchToggleC.nc`` and
+``tos/platforms/telosb/UserButtonP.nc``.
-postBuffer() and bufferDone() are matched in the same way described
-for the ReadStream interface, as are write() and writeDone().
-4. Summary
+5. Summary
====================================================================
According to the design principles described in the HAA[_haa], authors
who only need simple interfaces, and can reduce the effort needed to
connect a sensor into a more general system.
-5. Author's Address
+6. Author's Address
====================================================================
| Gilman Tolle
-| 2168 Shattuck Ave.
-| Arched Rock Corporation
-| Berkeley, CA 94704
+| 501 2nd St. Ste 410
+| Arch Rock Corporation
+| San Francisco, CA 94107
|
-| phone - +1 510 981 8714
-| email - gtolle@archedrock.com
+| phone - +1 415 692 0828
+| email - gtolle@archrock.com
|
|
| Philip Levis
| email - david.e.gay@intel.com
|
-6. Citations
+7. Citations
============================================================================
.. [1] TEP 108: Resource Arbitration.
+
projects / tinyos-2.x.git / blobdiff