tep109.txt

tinyos-2.x.rar

platform-independent. The sensorboard and platform MUST ensure
(Section 4.1) that all these components can be found at compile-time.

Because the same physical sensor can be used on many platforms or
sensor boards, and attached in many different ways, to maximize code
reuse the organization of sensor drivers SHOULD reflect the
distinction between sensor and sensor interconnect. The sensor
components SHOULD be platform-independent, while the sensor
interconnect components are typically sensorboard or
platform-dependent. However, some sensors (e.g. analong sensors) will
not have a sufficiently large amount of platform-independent logic to
justify creating platform-independent components.

The following guidelines specify how to organize sensor and sensor
interconnect components within TinyOS's directory hierarchy. These
guidelines are only relevant to components that are part of the core
source tree. The string ``<sensor>`` SHOULD reflect the make and model
of the sensor device.

- Platform-independent sensor components 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>``.

- Other platform-independent sensor components SHOULD be placed
  in ``tos/chips/<sensor>``.

- Sensorboard-dependent sensor and sensor interconnect components
  SHOULD be placed either in the ``<sensorboard>`` directory or in a
  ``<sensorboard>/chips/<sensor>`` directory.

- Platform-dependent sensor and sensor interconnect components SHOULD
  be placed in ``tos/<platform>/chips/<sensor>``.

5. Authors' Addresses
====================================================================

| David Gay
| 2150 Shattuck Ave, Suite 1300
| Intel Research
| Berkeley, CA 94704
|
| phone - [phone]
|
| email - [e-mail]
|
| Wei Hong
| Arch Rock
| 657 Mission St. Suite 600
| San Francisco, CA 94105
|
| email - [e-mail]
|
| Philip Levis
| 358 Gates Hall
| Computer Science Department
| 353 Serra Mall
| Stanford, CA 94305
|
| phone - [phone]
|
| email - [e-mail]
| 
| Joe Polastre
| 467 Soda Hall
| UC Berkeley
| Berkeley, CA 94720
|
| email - [e-mail]
|
| Gilman Tolle
| Arch Rock
| 657 Mission St. Suite 600
| San Francisco, CA 94105
|
| email - [e-mail]

6. Citations
====================================================================

.. [TEP2] TEP 2: Hardware Abstraction Architecture
.. [TEP108] TEP 108: Resource Arbitration
.. [TEP114] TEP 114: SIDs: Source and Sink Indepedent Drivers
.. [TEP115] TEP 115: Power Management of Non-Virtualized Devices
.. [TEP131] TEP 131: Creating a New Platform for TinyOS 2.x

Appendix A: Sensor Driver Examples
====================================================================

1. Analog ADC-Connected Sensor
------------------------------

The Analog sensor requires two components

* a component to present the sensor itself (HamamatsuS1087ParC)

* a component to select the appropriate hardware resources, such as
  ADC port 4, reference voltage 1.5V, and a slow sample and hold time
  (HamamatsuS1087ParP).

The AdcReadClientC component and underlying machinery handles all of
the arbitration and access to the ADC.

::

  tos/platforms/telosa/chips/s1087/HamamatsuS1087ParC.nc

  // HIL for the HamamatsuS1087 analog photodiode sensor
  generic configuration HamamatsuS1087ParC() {
    provides interface Read<uint16_t>;
    provides interface ReadStream<uint16_t>;
    provides interface DeviceMetadata;
  }
  implementation {
    // Create a new A/D client and connect it to the Hamamatsu S1087 A/D
    // parameters
    components new AdcReadClientC();
    Read = AdcReadClientC;

    components new AdcReadStreamClientC();
    ReadStream = AdcReadStreamClientC;

    components HamamatsuS1087ParP;
    DeviceMetadata = HamamatsuS1087ParP;
    AdcReadClientC.AdcConfigure -> HamamatsuS1087ParP;
    AdcReadStreamClientC.AdcConfigure -> HamamatsuS1087ParP;
  }
  
::

  tos/platforms/telosa/chips/s1087/HamamatsuS1087ParP.nc

  #include "Msp430Adc12.h"

  // A/D parameters for the Hamamatsu - see the MSP430 A/D converter manual,
  // Hamamatsu specification, Telos hardware schematic and TinyOS MSP430
  // A/D converter component specifications for the explanation of these
  // parameters
  module HamamatsuS1087ParP {
    provides interface AdcConfigure<const msp430adc12_channel_config_t*>;
    provides interface DeviceMetadata;
  }
  implementation {
    msp430adc12_channel_config_t config = {
      inch: INPUT_CHANNEL_A4,
      sref: REFERENCE_VREFplus_AVss,
      ref2_5v: REFVOLT_LEVEL_1_5,
      adc12ssel: SHT_SOURCE_ACLK,
      adc12div: SHT_CLOCK_DIV_1,
      sht: SAMPLE_HOLD_4_CYCLES,
      sampcon_ssel: SAMPCON_SOURCE_SMCLK,
      sampcon_id: SAMPCON_CLOCK_DIV_1
    };
 
    async command const msp430adc12_channel_config_t* AdcConfigure.getConfiguration() {
      return &config;
    }

    command uint8_t DeviceMetadata.getSignificantBits() { return 12; }
  }

2. Binary Pin-Connected Sensor
------------------------------

The Binary sensor gets a bit more complex, because it has three
components: 

* one to present the sensor (UserButtonC)

* one to execute the driver logic (UserButtonLogicP)

* one to select the appropriate hardware resources, such as MSP430
  Port 27 (HplUserButtonC).

Note that the presentation of this sensor is not arbitrated because
none of the operations are split-phase. 

::

  tos/platforms/telosa/UserButtonC.nc

  // HIL for the user button sensor on Telos-family motes
  configuration UserButtonC {
    provides interface Get<bool>; // Get button status
    provides interface Notify<bool>; // Get button-press notifications
    provides interface DeviceMetadata;
  }
  implementation {

    // Simply connect the button logic to the button HPL
    components UserButtonLogicP;
    Get = UserButtonLogicP;
    Notify = UserButtonLogicP;
    DeviceMetadata = UserButtonLogicP;

    components HplUserButtonC;
    UserButtonLogicP.GpioInterrupt -> HplUserButtonC.GpioInterrupt;
    UserButtonLogicP.GeneralIO -> HplUserButtonC.GeneralIO;
  }

::

  tos/platforms/telosa/UserButtonLogicP.nc
 
  // Transform the low-level (GeneralIO and GpioInterrupt) interface to the
  // button to high-level SID interfaces  
  module UserButtonLogicP {
    provides interface Get<bool>;
    provides interface Notify<bool>;
    provides interface DeviceMetadata;

    uses interface GeneralIO;
    uses interface GpioInterrupt; 
  }
  implementation {
    norace bool m_pinHigh;

    task void sendEvent();
 
    command bool Get.get() { return call GeneralIO.get(); }

    command error_t Notify.enable() {
      call GeneralIO.makeInput();

      // If the pin is high, we need to trigger on falling edge interrupt, and
      // vice-versa
      if ( call GeneralIO.get() ) {
        m_pinHigh = TRUE;
        return call GpioInterrupt.enableFallingEdge();
      } else {
        m_pinHigh = FALSE;
        return call GpioInterrupt.enableRisingEdge();
      }
    }

    command error_t Notify.disable() {
      return call GpioInterrupt.disable();
    }

    // Button changed, signal user (in a task) and update interrupt detection
    async event void GpioInterrupt.fired() {
      call GpioInterrupt.disable();

      m_pinHigh = !m_pinHigh;

      post sendEvent();
    }

    task void sendEvent() {
      bool pinHigh;
      pinHigh = m_pinHigh;
    
      signal Notify.notify( pinHigh );
    
      if ( pinHigh ) {
        call GpioInterrupt.enableFallingEdge();
      } else {
        call GpioInterrupt.enableRisingEdge();
      }
    }

    command uint8_t DeviceMetadata.getSignificantBits() { return 1; }
  }

::

  tos/platforms/telosa/HplUserButtonC.nc

  // HPL for the user button sensor on Telos-family motes - just provides
  // access to the I/O and interrupt control for the pin to which the
  // button is connected
  configuration HplUserButtonC {
    provides interface GeneralIO;
    provides interface GpioInterrupt;
  }
  implementation {

    components HplMsp430GeneralIOC as GeneralIOC;

    components new Msp430GpioC() as UserButtonC;
    UserButtonC -> GeneralIOC.Port27;
    GeneralIO = UserButtonC;

    components HplMsp430InterruptC as InterruptC;

    components new Msp430InterruptC() as InterruptUserButtonC;
    InterruptUserButtonC.HplInterrupt -> InterruptC.Port27;
    GpioInterrupt = InterruptUserButtonC.Interrupt;
  }

3. Digital Bus-Connected Sensor
-------------------------------

The Digital sensor is the most complex out of the set, and includes
six components:

* one to present the sensor (SensirionSht11C)

* one to request arbitrated access and to transform the sensor HAL
  into the sensor HIL (SensirionSht11P)

* one to present the sensor HAL (HalSensirionSht11C)

* one to perform the driver logic needed to support the HAL, which
  twiddles pins according to a sensor-specific protocol
  (SensirionSht11LogicP).

* one to select the appropriate hardware resources, such as the clock,
  data, and power pins, and to provide an arbiter for the sensor
  (HplSensirionSht11C).

* one to perform the power control logic needed to support the power
  manager associated with the arbiter (HplSensirionSht11P).