[Tinyos-2-commits] CVS: tinyos-2.x/doc/txt tep109.txt, 1.1.2.1, 1.1.2.1.10.1

Fri Jul 7 09:30:57 PDT 2006

Update of /cvsroot/tinyos/tinyos-2.x/doc/txt
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv28878/txt

Modified Files:
      Tag: tinyos-2-0-0-beta2-candidate
	tep109.txt 
Log Message:
Updated TEP109 - Sensors and Sensor Boards - to match current practice.

Index: tep109.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/Attic/tep109.txt,v
retrieving revision 1.1.2.1
retrieving revision 1.1.2.1.10.1
diff -C2 -d -r1.1.2.1 -r1.1.2.1.10.1
*** tep109.txt	31 Oct 2005 22:16:36 -0000	1.1.2.1
--- tep109.txt	7 Jul 2006 16:30:55 -0000	1.1.2.1.10.1
***************
*** 1,5 ****
! ============================
! Sensor Boards
! ============================

  :TEP: 109
--- 1,5 ----
! =========================
! Sensors and Sensor Boards
! =========================

  :TEP: 109
***************
*** 8,16 ****
  :Status: Draft
  :TinyOS-Version: 2.x
! :Author: David Gay, Phil Levis, Wei Hong, and Joe Polastre

! :Draft-Created: 19-Apr-2005
! :Draft-Version: $Revision$
! :Draft-Modified: $Date$
  :Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>

--- 8,14 ----
  :Status: Draft
  :TinyOS-Version: 2.x
! :Author: David Gay, Phil Levis, Wei Hong, Joe Polastre, and Gilman Tolle

! :Draft-Created: 10-Jun-2006
  :Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>

***************
*** 25,272 ****
  ====================================================================

! This memo documents how sensor boards are organized in TinyOS, and the
! general principles followed by the components that provide access to
! its sensors.

! 1. Introduction
  ====================================================================

! This document defines the default organization of a sensor board in
! TinyOS. There likely will be sensor boards that cannot conform 
! to this specification, but following as closely to its spirit as possible 
! will simplify generic applications that use a range of sensor boards.
! 
! This document assumes that sensors return uninterpreted 16-bit values, and,
! optionally uninterpreted, arbitrary-size calibration data. Conversion of
! sensor values to something with actual physical meaning is beyond the
! scope of this document.
! 
! 2. Directory Organization
! ====================================================================

! - A sensor board MUST have a unique name, composed of letters, numbers
!   and underscores. Case is significant, but two sensor boards MUST
!   differ in more than case. This is necessary to support platforms where
!   filename case differences are not significant. We will use SBOARD to
!   denote the sensor board name in the rest of this document.

! - Each sensor board MUST have its own directory named SBOARD; default TinyOS
!   sensor boards are placed in tinyos-2.x/tos/sensorboards, but
!   sensor board directories can be placed anywhere as long as the nesC compiler
!   receives a `-I` directive pointing to the sensor board's directory.

! - Each sensor board directory MUST contain a `.sensor` file. This file
!   is a perl script which contains any additional compiler settings needed for
!   this sensor board (this file will be empty in many cases). 

! - If the sensor board wishes to define any C types or constants, it SHOULD
!   place these in a file named SBOARD.h in the sensor board's directory.

! - The sensor board directory SHOULD contain sensor board components
!   for accessing each sensor on the sensor board. The conventions for these
!   components are detailed in Section 3.

! - A sensor board MAY include additional components providing alternative or
!   higher-level interfaces to the sensors (e.g., for TinyDB). These components
!   are beyond the scope of this document. 

! - Finally, the sensor board MAY contain any number of components,
!   interfaces, C files, etc for internal use. To avoid name collisions, all
!   externally visible names (interface types, components, C constants and
!   types) used for internal purposes SHOULD be prefixed with SBOARD. All such
!   components should end in P.

! A simple example: the basic sensor board is named `basicsb`, it's directory
! is `tinyos-2.x/tos/sensorboards/basicsb`. It has no `basicsb.h` file and
! its `.sensor` file is empty. It has two components, `PhotoC` and `TempC`
! representing its light and temperature sensors.

! 3. Sensor Board Components
  ====================================================================

! We have not yet selected any naming conventions for sensor board
! components. Please select reasonable names\ldots

! A sensor board component MUST provide:

! - An `Init` interface.

! - A `StdControl` or `SplitControl` interface for power management.

! - A non-empty set of `AcquireData` interfaces for sampling.

! A sensor board component MAY provide:

! - Some `CalibrationData` interfaces for obtaining calibration data.
!   A calibration interface for a sensor accessed via interface X should
!   be called XCalibration.

! - Some `AcquireDataNow` and `AcquireDataBuffered` interfaces, for high-speed 
!   or low-latency data acquisition.

! - Any other appropriate interface.

! The `CalibrationData` interface is shown below, while `AcquireData`,
! `AcquireDataNow` and `AcquireDataBuffered` are in TEP 101. The
! `AcquireData` interface returns uinterpreted 16-bit data. This might
! represent an A/D conversion result, a counter, etc. The optional
! calibration interface returns uninterpreted, arbitrary-size data.

! A sensor board component SHOULD be as lightweight as possible - it should
! just provide basic access to the physical sensors and SHOULD NOT attempt to do
! calibration, signal processing, etc. If such functionality is desired, it
! SHOULD be provided in separate components.

! |  ``interface CalibrationData {``
! |    ``/* Collect uninterpreted calibration data from a sensor */``
! |
! |    ``/** Request calibration data``
! |     ``*  @return SUCCESS if request accepted, FAIL if it is refused``
! |     ``*    data error will be signaled if SUCCESS is returned``
! |     ``*/``
! |    ``command result_t get();``
! |
! |   ``/** Returns calibration data``
! |    ``* @param x Pointer to (uinterpreted) calibration data. This data``
! |    ``*   must not be modified.``
! |    ``* @param len Length of calibration data``
! |    ``* @return Ignored.``
! |    ``*/``
! |   ``event result_t data(const void *x, uint8_t len);``
! | ``}``

! Some common setups for sensor board components are:

! - A single `AcquireData` interface. This is probably the most common case,
!   where a single component corresponds to a single physical sensor, e.g., for
!   light, temperature, pressure and there is no expectation of high sample
!   rates.

! - Multiple `AcquireData` interfaces. Some sensors might be strongly
!   related, e.g., the axes of an accelerometer.  A single component could then
!   provide a sensor interface for each axis. For instance, a 2-axis
!   accelerometer which can be sampled at high speed, and which has some
!   calibration data might be declared with:

! |  ``configuration Accelerometer2D {``
! |    ``provides {``
! |      ``interface StdControl``
! |      ``interface AcquireData as AccelX;``
! |      ``interface AcquireDataNow as AccelXSingle;``
! |      ``interface AcquireDataBuffered as AccelXMultiple;``
! |      ``interface CalibrationData as AccelXCalibration;``
! |
! |      ``interface AcquireData as AccelY;``
! |      ``interface AcquireDataNow as AccelYSingle;``
! |      ``interface AcquireDataBuffered as AccelYMultiple;``
! |      ``interface CalibrationData as AccelYCalibration;``
! |    ``}``
! |  ``}``

! - A parameterised `AcquireData` interface. If a sensor board has multiple
!   similar sensors, it may make sense to provide a single component to access
!   all of these, using a parameterised `AcquireData` interface. For instance,
!   a general purpose sensor board with multiple A/D channels might provide an
!   `AcquireData` interface parameterised by the A/D channel id.

! - In all of these examples, if high-speed sampling makes sensor for the
!   sensor (e.g., a microphone), and the sensor is connected in a way that
!   supports high-frequency and/or low-latency access (e.g., via an 
!   on-microcontroller A/D converter), the component should offer 
!   `AcquireDataNow` and `AcquireDataBuffered` interfaces.

! Sensor board components MUST respect the following conventions
! on the use of the `Init`, `StdControl`,  and `SplitControl` 
! interfaces.  These are given assuming `StdControl` is used, but the
! behaviour with `SplitControl` is identical except that `start` and `stop`
! are not considered complete until the `startDone` and `stopDone` events are
! signaled. The conventions are:

! 1) `Init.init`: must be called at mote boot time.

! 2) `StdControl.start`: ensure the sensor corresponding to this component is
!     ready for use. For instance, this should power-up the sensor if
!     necessary. The application can call `getData` once `StdControl.start`
!     completes.

!     If a sensor takes a while to power-up, the sensor board implementer can
!     either use a `SplitControl` interface and signal `startDone`
!     when the sensor is ready for use, or delay `dataReady` events
!     until the sensor is ready. The former choice is preferable.

! 3) `StdControl.stop`: put the sensor in a low-power mode. 
!    `StdControl.start` must be called before any further readings 
!    are taken. The behaviour of calls to `StdControl.stop` during
!    sampling (i.e., when an `dataReady` event is going to be
!    signaled) is undefined.

! `.sensor` File
  ====================================================================

! This file is a perl script which gets executed as part of the `ncc`
! nesC compiler frontend. It can add or modify any compile-time options 
! necessary for a particular sensor board. It MAY modify the following perl
! variables, and MUST NOT modify any others:

! - @new_args: This is the array of arguments which will be
!   passed to nescc. For instance, you might add an include directive
!   to @new_args with push @new_args, `-Isomedir`

! - @commonboards: This can be set to a list of sensor board names which
!   should be added to the include path list. These sensor boards must be
!   in tinyos-2.x/tos/sensorboards.

! Example: mts3x0
  ====================================================================

! The mica sensor board (mts300/mts310) has five sensors (and one actuator,
! the sounder) -- the accelerometer and magnetometer are only present on 
! the mts310:
! 
! +------------------------------------------------------------------+
! 
! | Name          | Component | Sensor Interfaces | Other Interfaces |
! 
! +===============+===========+===================+==================+

! | Accelerometer | AccelC    | AccelX            |                  |

! |               |           | AccelY            |                  |

! | Magnetometer  | MagC      | MagX              | MagSetting       |

! |               |           | MagY              |                  |

! | Microphone    | MicC      | MicADC            | Mic              |

! |               |           |                   | MicInterrupt     |

! | Light         | PhotoC    | PhotoADC          |                  |

! | Temperature   | TempC     | TempADC           |                  |

! +------------------------------------------------------------------+

! Each physical sensor is represented by a separate component. Specific
! sensors that have more than one axis of measurement (AccelC and MagC)
! provide more than one `AcquireData` interface on a single component. Some
! sensors, such as the magnetometer and microphone, have additional
! functionality provided through sensor-specific interfaces.

! Although light and temperature are represented by separate components, in
! reality they share a single microcontroller pin. The two components PhotoC
! and TempC sit on top of the PhotoTempP component, which controls access to
! the shared pin, and orchestrates which sensor is currently connected to
! it. From a programmer's perspective, they appear as individual sensors,
! even though their underlying implementation is a bit more complex.

! The board's mts3x0.h file contains private configuration data
! (pin usage, ADC ports, etc).

! The mica sensor board has an empty .sensor file.

! 6. Author's Address
  ====================================================================

--- 23,305 ----
  ====================================================================

! This memo documents how sensor drivers are organized in TinyOS and how
! sets of sensor drivers are combined into sensor boards and sensor
! platforms, along with general principles followed by the components
! that provide access to sensors.

! 1. Principles
  ====================================================================

! This section describes the basic organization principles for sensor
! drivers in TinyOS.

! For background, a sensor may be attached to the microcontroller on a
! TinyOS platform through a few different types of connections:

!  * Included within the microcontroller itself
!  * Connected to general-purpose IO pins for level/edge detection
!  * Connected to an ADC in the microcontroller for voltage sampling
!  * Connected to general-purpose IO pins for digital communication
!  * Connected through a standard digital bus protocol (1-Wire, I2C, SPI)

! Physically, these connections may also be decoupled by attaching the
! sensors to a `sensor board`, which can be removed from the TinyOS
! platform, and may fit multiple different TinyOS platforms.

! The capabilities of a physical sensor are made available to a TinyOS
! application through a `sensor driver`. 

! According to the HAA [TEP2]_, TinyOS devices should provide both
! simple hardware-independent interfaces for common-case use (HIL) and
! rich hardware-dependent interfaces for special-case use (HAL). Sensor
! drivers should follow this spirit as well.

! TinyOS 2.x represents each sensor as an individual component. This
! allows the compilation process to minimize the amount of code
! included. A sensor board containing multiple sensors should be
! represented as a collection of components, one for each sensor,
! contained within a sensor board directory.

! Sensors, being physical devices that may be shared, can benefit from
! virtualization and arbitration. This document describes a design
! pattern for sensor virtualization that may be followed by sensor
! drivers.

! The same physical sensor may be attached to multiple different TinyOS
! platforms, through platform-dependent interconnections. The common
! logic of sensor driver should be factored into chip-dependent,
! platform-independent components, and those components should be bound
! to the hardware resources on a platform by platform-dependent
! components, and to the hardware resources on a sensor board by
! sensorboard-dependent components.

+ A physical sensor has a general class and a specific set of
+ performance characteristics, captured by the make and model of the
+ sensor itself. The naming of the sensor driver components should
+ reflect the specifc name of the sensor, and optionally provide a
+ component with a generic name for application authors who only care
+ about the general class of the sensor.

+ This document assumes that sensors return uninterpreted values of
+ arbitrary size or datatype. Conversion of sensor values to something
+ with actual physical meaning is beyond the scope of this document.

! 2. Sensor HIL Components
  ====================================================================

! A sensor HIL component MUST provide:

! - One or more SID interfaces [TEP114]_, for reading data.

! A sensor HIL component MAY provide:

! - One or more SID interfaces [TEP114]_, for reading or
!   writing calibration coefficients or control registers.

! A sensor device driver SHOULD be a generic component that virtualizes
! access to the sensor. A sensor device driver can provide such
! virtualization for itself by defining a nesC generic client
! component. When a client component is being used, a call to a
! top-level SID interface should be delayed when the device is busy,
! rather than failing. This virtualization may be easier to accomplish
! by using one of the arbiters provided by the system.

! For example::

!   generic configuration SensirionSht11C() {
!     provides interface Read<uint16_t> as Temperature;
!     provides interface ReadStream<uint16_t> as TemperatureStream;
!     provides interface Read<uint16_t> as Humidity;
!     provides interface ReadStream<uint16_t> as HumidityStream;
!   }
!   implementation {
!     // connect to the ADC HIL, GPIO HAL, or sensor's HAL
!   }

! When a HIL component is being used, the sensor MUST initialize itself,
! either by including the `MainC` component and wiring to the
! `SoftwareInit` interface, or by allowing a lower-level component (like
! an ADC) to initialize itself.

! In addition, the HIL sensor driver MUST start the physical sensor
! automatically. For sensors without a constant power draw, the sensor
! MAY be started once at boot time by wiring to the `MainC.Boot`
! interface. Sensors that draw appreciable power MUST be started in
! response to a call to one of the top-level SID interfaces, and stopped
! some time after that call completes. One of the power-management
! components described in [TEP115]_ may be useful for this purpose.

! Sensor driver components SHOULD be named according to the make and
! model of the sensing device being presented. Using specific names
! gives the developer the option to bind to a particular sensor, which
! provides compile-time detection of missing sensors. However, wrapper
! components using "common" names MAY also be provided by the driver
! author, to support application developers who are only concerned with
! the particular type of the sensor and not its make, model, or detailed
! performance characteristics.

! A "common" naming layer atop a HIL may look like this::

!   generic configuration TemperatureC() {
!     provides interface Read<uint16_t>;
!     provides interface ReadStream<uint16_t>;
!   }
!   implementation {
!     components new SensirionSht11C();
!     Read = SensirionSht11C.Temperature;
!     ReadStream = SensirionSht11C.TemperatureStream;
!   }

!   generic configuration HumidityC() {
!     provides interface Read<uint16_t>;
!     provides interface ReadStream<uint16_t>;
!   }
!   implementation {
!     components new SensirionSht11C();
!     Read = SensirionSht11C.Humidity;
!     ReadStream = SensirionSht11C.HumidityStream;
!   }

! 3. Sensor HAL Components
! ====================================================================

! Sensors with a richer interface than would be supported by the SID
! interfaces MAY provide a HAL component in addition to a HIL
! component.

! A sensor HAL component MUST provide:

! - A SID-based interface or a specific hardware-dependent interface
!   with commands for sampling and controlling the sensor device.

! A sensor HAL component MAY need to provide:

! - A `StdControl` or `SplitControl` interface for manual power
!   management by the user, following the conventions described in
!   [TEP115]_.

! - A Resource[] interface for requesting access to the device and
!   possibly performing automated power management.

! - Any other interfaces needed to control the device.

! For example::

!   configuration SensirionSht11DeviceC {
!     provides interface Resource[ uint8_t client ];
!     provides interface SensirionSht11[ uint8_t client ];
!   }
!   implementation {
!     // connect to the sensor's platform-dependent HPL here
!   }

! 4. Sensor HPL Components
  ====================================================================

! A sensor HPL is necessarily platform-dependent or
! sensorboard-dependent. These components should provide access to the
! physical resources needed by the sensor, in a platform-independent
! manner that can be used by the shared logic of the sensor HAL
! components. In the case of bus-based sensors, this HPL may be nothing
! more than wiring to the appropriate bus interface for use by the HAL
! component.

! For example::

!   configuration HplSensirionSht11C {
!     provides interface Init;
!     provides interface Resource[ uint8_t id ];
!     provides interface GeneralIO as DATA;
!     provides interface GeneralIO as SCK;
!     provides interface GpioInterrupt as InterruptDATA;
!   }
!   implementation {
!     // connect to platform or sensorboard-dependent resources
!     // power-manage the sensor through platform-specific means
!   }

! 5. Directory Organization Guidelines
  ====================================================================

! Because the same physical sensor may be attached to TinyOS platforms
! in many different ways, the organization of sensor drivers should
! reflect the distinction between sensor and sensor interconnect.

! Sensor components commonly exist at three levels:
! platform-independent, sensorboard-dependent, and
! platform-dependent. Factoring a sensor driver into these three pieces
! allows for greater code reuse when the same sensor is attached to
! different sensorboards or platforms.

! Platform-independent sensor driver components for a particular sensor,
! like protocol logic, when in the core TinyOS 2.x source tree, SHOULD
! be placed into "tos/chips/<sensor>", where <sensor> reflects the make
! and model of the sensor device being supported. When not a part of the
! core source tree, this directory can be placed anywhere as long as the
! nesC compiler recieves a `-I` directive pointing to the sensor's
! directory. However, not all sensors have a sufficiently large amount
! of platform-independent logic to justify a separate "chips"
! directory. Sensor chips are more likely to be digital sensors than
! analog sensors, for example.

! A sensor board is a collection of sensor components with a fixed name,
! intended for attachment to multiple platforms. Each sensor board MUST
! have its own directory named <sensorboard>. Default TinyOS 2.x sensor
! boards are placed in "tos/sensorboards/<sensorboard>", but sensor
! board directories can be placed anywhere as long as the nesC compiler
! receives a `-I` directive pointing to the sensor board's directory.

! Both sensors and sensor boards MUST have unique names. Case is
! significant, but two sensor boards MUST differ in more than case. This
! is necessary to support platforms where filename case differences are
! not significant.

! Each sensor board directory MUST contain a `.sensor` file.  This file
! is a perl script which gets executed as part of the `ncc` nesC
! compiler frontend. It can add or modify any compile-time options
! necessary for a particular sensor board. It MAY modify the following
! perl variables, and MUST NOT modify any others:

! - @new_args: This is the array of arguments which will be passed to
!   nescc. For instance, you might add an include directive to @new_args
!   with push @new_args, `-Isomedir`. This could be used to include
!   subdirectories.

! - @commonboards: This can be set to a list of sensor board names which
!   should be added to the include path list. These sensor boards must be
!   in tinyos-2.x/tos/sensorboards.

! If the sensor board wishes to define any C types or constants, it
! SHOULD place these in a file named <sensorboard>.h in the sensor
! board's directory.

! A sensor board directory MAY contain a "chips" directory, with
! subdirectories for each of the sensors connected to the sensor board.
! If a "chips" subdirectory is used, sensorboard-dependent driver
! components needed to connect platform-independent logic to a
! particular attachment for that sensor should be placed in
! "<sensorboard>/chips/<sensor>".

! Components needed to connect the platform-independent sensor driver
! components or sensorboard-dependent components to the hardware
! resources available on a particular platform SHOULD be placed in
! "tos/<platform>/chips/<sensor>". In addition, components for a sensor
! that only exists on a particular platform should be placed in a such a
! directory.

! Sensors that exist as part of a larger chip, like a MCU internal
! voltage sensor, SHOULD be placed in a subdirectory of the chip's
! directory. "tos/<chip>/sensors/<sensor>".

! The `.platform` and `.sensor` files need to include enough `-I`
! directives to locate all of the necessary components needed to support
! the sensors on a platform and/or sensorboard.

! All of these directory organization guidelines are only intended for
! code that will enter the core source tree. In general, sensor
! components may be placed anywhere as long as the nesC compiler
! receives enough `-I` directives to locate all of the necessary pieces.

! 6. Authors' Addresses
  ====================================================================

***************
*** 281,286 ****
  |
  | Wei Hong
! | Arched Rock
! | Berkeley, CA 94704
  |
  | email - wei.hong at gmail.com
--- 314,320 ----
  |
  | Wei Hong
! | Arch Rock
! | 657 Mission St. Suite 600
! | San Francisco, CA 94105
  |
  | email - wei.hong at gmail.com
***************
*** 302,305 ****
--- 336,352 ----
  |
  | email - polastre at cs.berkeley.edu
+ |
+ | Gilman Tolle
+ | Arch Rock
+ | 657 Mission St. Suite 600
+ | San Francisco, CA 94105
+ |
+ | email - gtolle at archrock.com

+ 7. Citations
+ ====================================================================
+ 
+ .. [TEP2] TEP 2: Hardware Abstraction Architecture
+ .. [TEP114] TEP 114: SIDs: Source and Sink Indepedent Drivers
+ .. [TEP115] TEP 115: Power Management of Non-Virtualized Devices