[Tinyos-2-commits] CVS: tinyos-2.x/doc/txt tep109.txt,1.6,1.7
David Gay
idgay at users.sourceforge.net
Fri Jul 18 17:32:59 PDT 2008
Update of /cvsroot/tinyos/tinyos-2.x/doc/txt
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv25690/txt
Modified Files:
tep109.txt
Log Message:
tep109 update - in progress
Index: tep109.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep109.txt,v
retrieving revision 1.6
retrieving revision 1.7
diff -C2 -d -r1.6 -r1.7
*** tep109.txt 4 Feb 2007 19:54:47 -0000 1.6
--- tep109.txt 19 Jul 2008 00:32:56 -0000 1.7
***************
*** 81,90 ****
general class of the sensor.
! This document takes no position on the meaning of the values returned
! by sensor drivers. 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 needed to properly
! interpret the value.
2. Sensor HIL Components
--- 81,91 ----
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
***************
*** 150,154 ****
The getSignificantBits() call MUST return the number of significant
bits in the reading. For example, a sensor reading taken from a 12-bit
! ADC MUST return the value "12".
Sensor driver components SHOULD be named according to the make and
--- 151,156 ----
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
***************
*** 205,212 ****
[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::
--- 207,215 ----
[TEP115]_.
! - A `Resource` interface for requesting access to the device and
possibly performing automated power management.
! - Any other interfaces needed to control the device, e.g., to
! read or write calibration coefficients.
For example::
***************
*** 220,304 ****
}
! 4. Directory Organization Guidelines
====================================================================
! Because the same physical sensor can 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
! will 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 can be placed anywhere as long as the nesC compiler
! receives enough `-I` directives to locate all of the necessary pieces.
5. Authors' Addresses
--- 223,315 ----
}
! 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.
! 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
! 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
***************
*** 351,354 ****
--- 362,366 ----
.. [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
***************
*** 373,376 ****
--- 385,389 ----
tos/platforms/telosa/chips/s1087/HamamatsuS1087ParC.nc
+ // HIL for the HamamatsuS1087 analog photodiode sensor
generic configuration HamamatsuS1087ParC() {
provides interface Read<uint16_t>;
***************
*** 379,382 ****
--- 392,397 ----
}
implementation {
+ // Create a new A/D client and connect it to the Hamamatsu S1087 A/D
+ // parameters
components new AdcReadClientC();
Read = AdcReadClientC;
***************
*** 397,400 ****
--- 412,419 ----
#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*>;
***************
*** 402,406 ****
}
implementation {
-
msp430adc12_channel_config_t config = {
inch: INPUT_CHANNEL_A4,
--- 421,424 ----
***************
*** 441,451 ****
tos/platforms/telosa/UserButtonC.nc
configuration UserButtonC {
! provides interface Get<bool>;
! provides interface Notify<bool>;
provides interface DeviceMetadata;
}
implementation {
components UserButtonLogicP;
Get = UserButtonLogicP;
--- 459,471 ----
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;
***************
*** 462,465 ****
--- 482,487 ----
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>;
***************
*** 480,483 ****
--- 502,507 ----
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;
***************
*** 493,496 ****
--- 517,521 ----
}
+ // Button changed, signal user (in a task) and update interrupt detection
async event void GpioInterrupt.fired() {
call GpioInterrupt.disable();
***************
*** 521,524 ****
--- 546,552 ----
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;
***************
*** 572,575 ****
--- 600,604 ----
tos/platforms/telosa/chips/sht11/SensirionSht11C.nc
+ // HIL interface to Sensirion SHT11 temperature and humidity sensor
generic configuration SensirionSht11C() {
provides interface Read<uint16_t> as Temperature;
***************
*** 579,582 ****
--- 608,612 ----
}
implementation {
+ // Instantiate the module providing the HIL interfaces
components new SensirionSht11ReaderP();
***************
*** 586,589 ****
--- 616,620 ----
HumidityDeviceMetadata = SensirionSht11ReaderP.HumidityDeviceMetadata;
+ // And connect it to the HAL component for the Sensirion SHT11
components HalSensirionSht11C;
***************
*** 601,604 ****
--- 632,637 ----
tos/chips/sht11/SensirionSht11ReaderP.nc
+ // Convert Sensirion SHT11 HAL to HIL interfaces for a single
+ // client, performing automatic resource arbitration
generic module SensirionSht11ReaderP() {
provides interface Read<uint16_t> as Temperature;
***************
*** 607,610 ****
--- 640,647 ----
provides interface DeviceMetadata as HumidityDeviceMetadata;
+ // Using separate resource interfaces for temperature and humidity allows
+ // temperature and humidity measurements to be requested simultaneously
+ // (if a single Resource interface was used, a request for temperature would
+ // prevent any humidity requests until the temperature measurement was complete)
uses interface Resource as TempResource;
uses interface Resource as HumResource;
***************
*** 614,623 ****
implementation {
command error_t Temperature.read() {
! call TempResource.request();
! return SUCCESS;
}
event void TempResource.granted() {
error_t result;
if ((result = call Sht11Temp.measureTemperature()) != SUCCESS) {
call TempResource.release();
--- 651,661 ----
implementation {
command error_t Temperature.read() {
! // Start by requesting access to the SHT11
! return call TempResource.request();
}
event void TempResource.granted() {
error_t result;
+ // If the HAL measurement fails, release the SHT11 and signal failure
if ((result = call Sht11Temp.measureTemperature()) != SUCCESS) {
call TempResource.release();
***************
*** 627,630 ****
--- 665,669 ----
event void Sht11Temp.measureTemperatureDone( error_t result, uint16_t val ) {
+ // Release the SHT11 and signal the result
call TempResource.release();
signal Temperature.readDone( result, val );
***************
*** 634,643 ****
command error_t Humidity.read() {
! call HumResource.request();
! return SUCCESS;
}
event void HumResource.granted() {
error_t result;
if ((result = call Sht11Hum.measureHumidity()) != SUCCESS) {
call HumResource.release();
--- 673,683 ----
command error_t Humidity.read() {
! // Start by requesting access to the SHT11
! return call HumResource.request();
}
event void HumResource.granted() {
error_t result;
+ // If the HAL measurement fails, release the SHT11 and signal failure
if ((result = call Sht11Hum.measureHumidity()) != SUCCESS) {
call HumResource.release();
***************
*** 647,650 ****
--- 687,691 ----
event void Sht11Hum.measureHumidityDone( error_t result, uint16_t val ) {
+ // Release the SHT11 and signal the result
call HumResource.release();
signal Humidity.readDone( result, val );
***************
*** 653,656 ****
--- 694,698 ----
command uint8_t HumidityDeviceMetadata.getSignificantBits() { return 12; }
+ // Dummy handlers for unused portions of the HAL interface
event void Sht11Temp.resetDone( error_t result ) { }
event void Sht11Temp.measureHumidityDone( error_t result, uint16_t val ) { }
***************
*** 663,666 ****
--- 705,710 ----
event void Sht11Hum.writeStatusRegDone( error_t result ) { }
+ // We need default handlers as a client may wire to only the Temperature
+ // sensor or only the Humidity sensor
default event void Temperature.readDone( error_t result, uint16_t val ) { }
default event void Humidity.readDone( error_t result, uint16_t val ) { }
***************
*** 671,682 ****
--- 715,733 ----
tos/platforms/telosa/chips/sht11/HalSensirionSht11C.nc
+ // HAL interface to Sensirion SHT11 temperature and humidity sensor
configuration HalSensirionSht11C {
+ // The SHT11 HAL uses resource arbitration to allow the sensor to shared
+ // between multiple clients and for automatic power management (the SHT11
+ // is switched off when no clients are waiting to use it)
provides interface Resource[ uint8_t client ];
provides interface SensirionSht11[ uint8_t client ];
}
implementation {
+ // The HAL implementation logic
components new SensirionSht11LogicP();
SensirionSht11 = SensirionSht11LogicP;
+ // And it's wiring to the SHT11 HPL - the actual resource management is
+ // provided at the HPL layer
components HplSensirionSht11C;
Resource = HplSensirionSht11C.Resource;
***************
*** 716,720 ****
tos/platforms/telosa/chips/sht11/HplSensirionSht11C.nc
!
configuration HplSensirionSht11C {
provides interface Resource[ uint8_t id ];
--- 767,774 ----
tos/platforms/telosa/chips/sht11/HplSensirionSht11C.nc
!
! // Low-level, platform-specific glue-code to access the SHT11 sensor found
! // on telos-family motes - here the HPL just provides resource management
! // and access to the SHT11 data, clock and interrupt pins
configuration HplSensirionSht11C {
provides interface Resource[ uint8_t id ];
***************
*** 724,727 ****
--- 778,782 ----
}
implementation {
+ // Pins used to access the SHT11
components HplMsp430GeneralIOC;
***************
*** 737,740 ****
--- 792,796 ----
PWRM -> HplMsp430GeneralIOC.Port17;
+ // HPL logic for switching the SHT11 on and off
components HplSensirionSht11P;
HplSensirionSht11P.PWR -> PWRM;
***************
*** 750,753 ****
--- 806,810 ----
InterruptDATA = InterruptDATAC.Interrupt;
+ // The arbiter and power manager for the SHT11
components new FcfsArbiterC( "Sht11.Resource" ) as Arbiter;
Resource = Arbiter;
***************
*** 764,768 ****
--- 821,830 ----
tos/platforms/telosa/chips/sht11/HplSensirionSht11P.nc
+ // Switch the SHT11 on and off, and handle the 11ms warmup delay
module HplSensirionSht11P {
+ // The SplitControl interface powers the SHT11 on or off (it's automatically
+ // called by the SHT11 power manager, see HplSensirionSht11C)
+ // We use a SplitControl interface as we need to wait 11ms for the sensor to
+ // warm up
provides interface SplitControl;
uses interface Timer<TMilli>;
***************
*** 775,778 ****
--- 837,841 ----
command error_t SplitControl.start() {
+ // Power SHT11 on and wait for 11ms
call PWR.makeOutput();
call PWR.set();
***************
*** 786,789 ****
--- 849,853 ----
command error_t SplitControl.stop() {
+ // Power the SHT11 off
call SCK.makeInput();
call SCK.clr();
More information about the Tinyos-2-commits
mailing list