tep109.txt

tinyos-2.x.rar

=========================
Sensors and Sensor Boards
=========================

:TEP: 109
:Group: Core Working Group 
:Type: Documentary
:Status: Final
:TinyOS-Version: 2.x
:Author: David Gay, Philip Levis, Wei Hong, Joe Polastre, and Gilman Tolle

.. Note::

   This memo documents a part of TinyOS for the TinyOS Community, and
   requests discussion and suggestions for improvements.  Distribution
   of this memo is unlimited. This memo is in full compliance with
   TEP 1.

Abstract
====================================================================

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 can 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 can also be decoupled by attaching the
sensors to a `sensor board`, which can be removed from the TinyOS
platform, and could attach to 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 can be shared, can benefit from
virtualization and arbitration. This document describes a design
pattern for sensor virtualization that SHOULD be followed by sensor
drivers.

The same physical sensor can 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 MAY provide a component
with a generic name for application authors who only care about the
general class of the sensor.

This document requires that sensor components specify the range (in
bits) of values returned by sensor drivers, but takes no position on
the meaning of these values. They MAY be raw uninterpreted values or
they MAY have some physical meaning. If a driver returns uninterpreted
values, the driver MAY provide additional interfaces that would allow
higher-level clients to obtain information (e.g. calibration
coefficients) needed to properly interpret the value.

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. Using one of the system arbiters can make the
implementation of this requirement easier to accomplish.

For example::

  generic configuration SensirionSht11C() {
    provides interface Read<uint16_t> as Temperature;
    provides interface ReadStream<uint16_t> as TemperatureStream;
    provides interface DeviceMetadata as TemperatureDeviceMetadata;

    provides interface Read<uint16_t> as Humidity;
    provides interface ReadStream<uint16_t> as HumidityStream;
    provides interface DeviceMetadata as HumidityDeviceMetadata;
  }
  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. Using one of the power-management
components described in [TEP115]_ can make this implementation easier.

Generally, simple types are made up of octets. However, sensor values
often have levels of precision besides a multiple of 8. To account for
such cases, each device MUST specify the precision of each one of its
interfaces by providing the DeviceMetadata interface::

  interface DeviceMetadata {
    command uint8_t getSignificantBits();
  }

The name of the instance of DeviceMetadata MUST clearly indicate which
interface it corresponds to.

The getSignificantBits() call MUST return the number of significant
bits in the reading. For example, a sensor reading taken from a 12-bit
ADC would typically return the value 12 (it might return less if, e.g.,
physical constraints limit the maximum A/D result to 10-bits).

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 might look like this::

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

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

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, following
  the conventions described in [TEP108]_ and [TEP115]_.

- Any other interfaces needed to control the device, e.g., to
  read or write calibration coefficients.

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 Component Organization and Compiler Interaction Guidelines
====================================================================

Sensors are associated either with a particular sensor board or with a
particular platform. Both sensors and sensor boards MUST have unique
names. Case is significant, but two sensor (or sensor board) names
MUST differ in more than case. This is necessary to support platforms
where filename case differences are not significant.

Each sensor board MUST have its own directory whose name is the sensor
board's unique name (referred to as <sensorboard> in the rest of this
section). 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. Each sensor board directory
MUST contain a ``.sensor`` file (described below). 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 MAY contain components that override the default TinyOS
*demo sensors*. This allows the sensor board to easily be used with
TinyOS sample applications that use the demo sensors. If a sensor 
board wishes to override the default demo sensor:

* It MUST provide a generic component named ``DemoSensorC`` with the
  following signature::

    provides interface Read<uint16_t>;
    provides interface DeviceMetadata;

* It MAY provide a generic component named ``DemoSensorNowC`` with the
  following signature::

    provides interface ReadNow<uint16_t>;
    provides interface DeviceMetadata;

  This component SHOULD sample the same sensor as ``DemoSensorC``.

* It MAY provide a generic component named ``DemoSensorStreamC`` with the
  following signature::

    provides interface ReadStream<uint16_t>;
    provides interface DeviceMetadata;

  This component SHOULD sample the same sensor as ``DemoSensorC``.

These components MUST be an alias for one of the sensor board's usual
sensors, though they change the precision of the sensor if necessary.
For instance, if ``DemoSensorC`` is an alias for a 20-bit sensor that
provides a ``Read<uint32_t>`` interface, ``DemoSensorC`` would still
provide ``Read<uint16_t>`` and would include code to reduce the
precision of the aliased sensor.


4.1 Compiler Interaction
------------------------

When the ``ncc`` nesC compiler frontend is passed a ``-board=X`` option,
it executes the ``.sensor`` file found in the sensor board directory
``X``.  This file is a perl script which can add or modify any
compile-time options necessary for the sensor board. It MAY modify the
following perl variables, and MUST NOT modify any others:

- ``@includes``: This array contains the TinyOS search path, i.e., the
  directories which will be passed to nescc (the TinyOS-agnostic nesC
  compiler) as ``-I`` arguments. You MUST add to ``@includes`` any
  directories needed to compile this sensor board's components.  For
  instance, if your sensor boards depends on support code found in
  ``tos/chips/sht11``, you would add ``"%T/chips/sht11"`` to ``@includes``.

- ``@new_args``: This is the array of arguments which will be passed to
  nescc. You MUST add any arguments other than ``-I`` that are necessary
  to compile your sensor board components to ``@new_args``.

If a sensor is associated with a platform `P` rather than a sensor
board, then that platform MUST ensure that, when compiling for
platform `P`, all directories needed to compile that sensor's 
component are added to the TinyOS search path (see [TEP131]_ for
information on how to set up a TinyOS platform).

4.2 Sensor Components
---------------------

A particular sensor is typically supported by many components,
including the HIL and HAL components from Sections 2 and 3, A/D
conversion components (for analog sensors), digital bus components
(e.g., SPI, for digital sensors), system services (timers, resource
and power management, ...), glue components (to connect sensors,
sensor boards and platforms), etc.  These components can be divided
into three classes: sensorboard-dependent, platform-dependent and