[Tinyos-2-commits] CVS: tinyos-2.x/doc/txt tep1.txt, 1.4, 1.5 tep101.txt, 1.5, 1.6 tep102.txt, 1.6, 1.7 tep106.txt, 1.5, 1.6 tep107.txt, 1.4, 1.5 tep108.txt, 1.5, 1.6 tep109.txt, 1.4, 1.5 tep110.txt, 1.4, 1.5 tep111.txt, 1.4, 1.5 tep112.txt, 1.4, 1.5 tep113.txt, 1.4, 1.5 tep114.txt, 1.5, 1.6 tep115.txt, 1.4, 1.5 tep116.txt, 1.4, 1.5 tep117.txt, 1.4, 1.5 tep118.txt, 1.5, 1.6 tep119.txt, 1.5, 1.6 tep120.txt, 1.4, 1.5 tep123.txt, 1.4, 1.5 tep3.txt, 1.4, 1.5

[Vlado Handziski]

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

Modified Files:
	tep1.txt tep101.txt tep102.txt tep106.txt tep107.txt 
	tep108.txt tep109.txt tep110.txt tep111.txt tep112.txt 
	tep113.txt tep114.txt tep115.txt tep116.txt tep117.txt 
	tep118.txt tep119.txt tep120.txt tep123.txt tep3.txt 
Log Message:
Swapping HEAD and DEVEL branches




Index: tep106.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep106.txt,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** tep106.txt	7 Nov 2006 19:30:39 -0000	1.5
--- tep106.txt	12 Dec 2006 18:22:54 -0000	1.6
***************
*** 352,358 ****
  The key used for task unique identifiers MUST be "TinySchedulerC.TaskInterface",
  where *TaskInterface* is the name of the new task interface as presented
! by the scheduler.  For example, the module SomethingP requires two EDF
! tasks::
  
    configuration SomethingC {  
      ...  
--- 352,363 ----
  The key used for task unique identifiers MUST be "TinySchedulerC.TaskInterface",
  where *TaskInterface* is the name of the new task interface as presented
! by the scheduler.  A common way to make sure a consistent string is used
! is to #define it. For example, TaskEdf.nc might include::
  
+ #define UQ_TASK_EDF "TinySchedulerC.TaskEdf"
+ 
+ In this example, the module SomethingP requires two EDF
+ tasks::
+   
    configuration SomethingC {  
      ...  
***************
*** 360,365 ****
    implementation {  
      components SomethingP, TinySchedulerC;  
!     SomethingP.SendTask -> TinySchedulerC.TaskEdf["TinySchedulerC.TaskEdf"];  
!     SomethingP.SenseTask -> TinySchedulerC.TaskEdf["TinySchedulerC.TaskEdf"];  
    }  
  
--- 365,370 ----
    implementation {  
      components SomethingP, TinySchedulerC;  
!     SomethingP.SendTask -> TinySchedulerC.TaskEdf[unique(UQ_TASK_EDF)];  
!     SomethingP.SenseTask -> TinySchedulerC.TaskEdf[unique(UQ_TASK_EDF)];  
    }  
  



Index: tep109.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep109.txt,v
retrieving revision 1.4
retrieving revision 1.5
diff -C2 -d -r1.4 -r1.5
*** tep109.txt	7 Nov 2006 00:43:44 -0000	1.4
--- tep109.txt	12 Dec 2006 18:22:54 -0000	1.5
***************
*** 34,38 ****
  drivers in TinyOS.
  
! For background, a sensor may be attached to the microcontroller on a
  TinyOS platform through a few different types of connections:
  
--- 34,38 ----
  drivers in TinyOS.
  
! For background, a sensor can be attached to the microcontroller on a
  TinyOS platform through a few different types of connections:
  
***************
*** 43,73 ****
   * 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
--- 43,73 ----
   * 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
***************
*** 76,89 ****
  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 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 interpret the value properly.
  
  2. Sensor HIL Components
--- 76,90 ----
  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 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
***************
*** 103,109 ****
  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::
--- 104,110 ----
  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::
***************
*** 112,117 ****
--- 113,121 ----
      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 {
***************
*** 129,139 ****
  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.
  
  Generally, simple types are made up of octets. However, sensor values
! often have levels of precision besides a multiple of 8. A device MAY
! specify the precision of one of its interfaces with the DeviceMetadata
! interface::
  
    interface DeviceMetadata {
--- 133,143 ----
  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 {
***************
*** 141,158 ****
    }
  
! The name of the instance of DeviceMetadata SHOULD clearly indicate
! which interface it corresponds to.
! 
! A value contained returned from the device through a SID interface
! MAY be left shifted so that it covers as much of the type's range as
! possible. For example, if a 12-bit ADC reading is presented as a
! 16-bit Read interface::
! 
!   component DemoSensorC {
!     provides interface Read<uint16_t>;
!   }
  
! then the driver MAY shift the 12-bit value left so that its range is
! 0x0000 - 0xfff0, rather than 0x0000 - 0x0fff. 
  
  Sensor driver components SHOULD be named according to the make and
--- 145,154 ----
    }
  
! 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 MUST return the value "12". 
  
  Sensor driver components SHOULD be named according to the make and
***************
*** 165,173 ****
  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 {
--- 161,170 ----
  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 {
***************
*** 175,178 ****
--- 172,176 ----
      Read = SensirionSht11C.Temperature;
      ReadStream = SensirionSht11C.TemperatureStream;
+     DeviceMetadata = SensirionSht11C.TemperatureDeviceMetadata;
    }
  
***************
*** 180,183 ****
--- 178,182 ----
      provides interface Read<uint16_t>;
      provides interface ReadStream<uint16_t>;
+     provides interface DeviceMetadata;
    }
    implementation {
***************
*** 185,188 ****
--- 184,188 ----
      Read = SensirionSht11C.Humidity;
      ReadStream = SensirionSht11C.HumidityStream;
+     DeviceMetadata = SensirionSht11C.HumidityDeviceMetadata;
    }
  
***************
*** 223,228 ****
  ====================================================================
  
! 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.
  
--- 223,228 ----
  ====================================================================
  
! 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.
  
***************
*** 268,272 ****
  
  - @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.
  
--- 268,272 ----
  
  - @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.
  
***************
*** 279,283 ****
  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>".
  
--- 279,283 ----
  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>".
  
***************
*** 286,290 ****
  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.
  
--- 286,290 ----
  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.
  
***************
*** 299,303 ****
  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.
  
--- 299,303 ----
  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.
  
***************
*** 376,379 ****
--- 376,380 ----
      provides interface Read<uint16_t>;
      provides interface ReadStream<uint16_t>;
+     provides interface DeviceMetadata;
    }
    implementation {
***************
*** 385,390 ****
  
      components HamamatsuS1087ParP;
!     AdcReadClientC.Msp430Adc12Config -> HamamatsuS1087ParP;
!     AdcReadStreamClientC.Msp430Adc12Config -> HamamatsuS1087ParP;
    }
    
--- 386,392 ----
  
      components HamamatsuS1087ParP;
!     DeviceMetadata = HamamatsuS1087ParP;
!     AdcReadClientC.AdcConfigure -> HamamatsuS1087ParP;
!     AdcReadStreamClientC.AdcConfigure -> HamamatsuS1087ParP;
    }
    
***************
*** 393,417 ****
    tos/platforms/telosa/chips/s1087/HamamatsuS1087ParP.nc
  
    module HamamatsuS1087ParP {
!     provides interface Msp430Adc12Config;
    }
    implementation {
  
!     async command msp430adc12_channel_config_t 
!       Msp430Adc12Config.getChannelSettings() {
   
!       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
!       };
!       
!       return config;
      }
    }
  
--- 395,422 ----
    tos/platforms/telosa/chips/s1087/HamamatsuS1087ParP.nc
  
+   #include "Msp430Adc12.h"
+ 
    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; }
    }
  
***************
*** 439,453 ****
      provides interface Get<bool>;
      provides interface Notify<bool>;
    }
    implementation {
  
      components UserButtonLogicP;
  
      components HplUserButtonC;
      UserButtonLogicP.GpioInterrupt -> HplUserButtonC.GpioInterrupt;
      UserButtonLogicP.GeneralIO -> HplUserButtonC.GeneralIO;
- 
-     Get = UserButtonLogicP;
-     Notify = UserButtonLogicP;
    }
  
--- 444,459 ----
      provides interface Get<bool>;
      provides interface Notify<bool>;
+     provides interface DeviceMetadata;
    }
    implementation {
  
      components UserButtonLogicP;
+     Get = UserButtonLogicP;
+     Notify = UserButtonLogicP;
+     DeviceMetadata = UserButtonLogicP;
  
      components HplUserButtonC;
      UserButtonLogicP.GpioInterrupt -> HplUserButtonC.GpioInterrupt;
      UserButtonLogicP.GeneralIO -> HplUserButtonC.GeneralIO;
    }
  
***************
*** 459,462 ****
--- 465,469 ----
      provides interface Get<bool>;
      provides interface Notify<bool>;
+     provides interface DeviceMetadata;
  
      uses interface GeneralIO;
***************
*** 506,509 ****
--- 513,518 ----
        }
      }
+ 
+     command uint8_t DeviceMetadata.getSignificantBits() { return 1; }
    }
  
***************
*** 565,569 ****
--- 574,580 ----
    generic configuration SensirionSht11C() {  
      provides interface Read<uint16_t> as Temperature;
+     provides interface DeviceMetadata as TemperatureDeviceMetadata;
      provides interface Read<uint16_t> as Humidity;
+     provides interface DeviceMetadata as HumidityDeviceMetadata;
    }
    implementation {
***************
*** 571,576 ****
    
      Temperature = SensirionSht11ReaderP.Temperature;
      Humidity = SensirionSht11ReaderP.Humidity;
!   
      components HalSensirionSht11C;
    
--- 582,589 ----
    
      Temperature = SensirionSht11ReaderP.Temperature;
+     TemperatureDeviceMetadata = SensirionSht11ReaderP.TemperatureDeviceMetadata;
      Humidity = SensirionSht11ReaderP.Humidity;
!     HumidityDeviceMetadata = SensirionSht11ReaderP.HumidityDeviceMetadata;
! 
      components HalSensirionSht11C;
    
***************
*** 590,594 ****
--- 603,609 ----
    generic module SensirionSht11ReaderP() {
      provides interface Read<uint16_t> as Temperature;
+     provides interface DeviceMetadata as TemperatureDeviceMetadata;
      provides interface Read<uint16_t> as Humidity;
+     provides interface DeviceMetadata as HumidityDeviceMetadata;
      
      uses interface Resource as TempResource;
***************
*** 615,619 ****
        signal Temperature.readDone( result, val );
      }
!   
      command error_t Humidity.read() {
        call HumResource.request();
--- 630,636 ----
        signal Temperature.readDone( result, val );
      }
! 
!     command uint8_t TemperatureDeviceMetadata.getSignificantBits() { return 14; }
! 
      command error_t Humidity.read() {
        call HumResource.request();
***************
*** 634,637 ****
--- 651,656 ----
      }
    
+     command uint8_t HumidityDeviceMetadata.getSignificantBits() { return 12; }
+ 
      event void Sht11Temp.resetDone( error_t result ) { }
      event void Sht11Temp.measureHumidityDone( error_t result, uint16_t val ) { }





Index: tep114.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep114.txt,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** tep114.txt	7 Nov 2006 19:30:39 -0000	1.5
--- tep114.txt	12 Dec 2006 18:22:54 -0000	1.6
***************
*** 138,141 ****
--- 138,148 ----
  ``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.
+ 
  Examples of sensors that would be suited to this class of interface
  include many basic sensors, such as photo, temp, voltage, and ADC





Index: tep119.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep119.txt,v
retrieving revision 1.5
retrieving revision 1.6
diff -C2 -d -r1.5 -r1.6
*** tep119.txt	7 Nov 2006 19:30:39 -0000	1.5
--- tep119.txt	12 Dec 2006 18:22:54 -0000	1.6
***************
*** 25,29 ****
  The memo documents the interfaces, components, and semantics used by
  collection protocol in TinyOS 2.x. Collection provides a best-effort,
! multihop delivery of packets to the root of a tree.
  
  1. Introduction
--- 25,33 ----
  The memo documents the interfaces, components, and semantics used by
  collection protocol in TinyOS 2.x. Collection provides a best-effort,
! multihop delivery of packets to the root of *a* tree. There may be
! multiple roots in a network, and in this case the semantics implemented
! are of *anycast* delivery to at least one of the roots. A node sending
! a packet does not specify which root the packet is destined to.
!  
  
  1. Introduction
***************
*** 45,49 ****
  trees. Collection provides a best-effort,
  multihop delivery of packets to one of a network's tree roots:
! it is an *anycast* protocol.
  
  Given the limited state that nodes can store and a general need
--- 49,57 ----
  trees. Collection provides a best-effort,
  multihop delivery of packets to one of a network's tree roots:
! it is an *anycast* protocol. The semantics is that the protocol
! will make a reasonable effort to deliver the message to at least
! one of the roots in the network. There are however no guarantees of 
! delivery, and there can be duplicates delivered to one or more
! roots. There is also no ordering guarantees.
  
  Given the limited state that nodes can store and a general need
***************
*** 76,107 ****
  consumer, snooper, and in-network processor. Depending on their role,
  the nodes use different interfaces to interact with the collection
! component.
! 
! The nodes that generate data to be sent to the root are
! *producers*. The producers use the Send interface [1_] to send
! data to the root of the collection tree. The collection tree
! identifier is be specified as a parameter to Send during
! instantiation.
! 
! Root nodes that receive data from the network are *consumers*. The
! consumers use the Receive interface [1_] to receive a message
! delivered by collection. The collection tree identifier is be
! specified as a parameter to Receive during instantiation.
! 
! The nodes that overhear messages in transit are *snoopers*. The snoopers
! use the Receive interface [1_] to receive a snooped message. The
! collection tree identifier is be specified as a parameter to Receive
! during instantiation.
  
! The nodes can process a packet that are in transit. These in-network
! *processors* use the Intercept interface [1_] to receive and
! update a packet. The collection tree identifier is be specified as a
! parameter to Intercept during instantiation.
  
  A node is configured to become a root by using the RootControl
  interface. RootControl.setRoot() MUST make the current node a root of
! the tree specified during instantiation. RootControl.unsetRoot() MUST
! make the current root no longer a root in the tree specified during
! instantiation. RootControl.unsetRoot() MAY be called on a node that is
  not a root::
  
--- 84,102 ----
  consumer, snooper, and in-network processor. Depending on their role,
  the nodes use different interfaces to interact with the collection
! component. 
  
! A consumer is a root of a tree. The set of all roots and the paths that
! lead to them form the collection routing infrastructure in the network.
! For any connected set of nodes implementing the collection protocol 
! there is only one collection infrastructure, *i.e.*, all roots in this 
! set active at the same time are part of the same infrastructure.
  
  A node is configured to become a root by using the RootControl
  interface. RootControl.setRoot() MUST make the current node a root of
! the the collection infrastructure. RootControl.unsetRoot() MUST
! make the current root no longer a root in the collection infrastructure.
! Both calls are idempotent.
! RootControl.setRoot() MAY be called on a node that is already a root, to
! no effect. RootControl.unsetRoot() MAY be called on a node that is
  not a root::
  
***************
*** 112,123 ****
    }
  
  
  3 Collection Services
  ====================================================================
  
! A collection service MUST provide one component, TreeCollectionC,
  which has the following signature::
  
!   configuration TreeCollectionC {
      provides {
        interface StdControl;
--- 107,142 ----
    }
  
+ The collection infrastructure can be multiplexed among independent
+ applications, by means of a *collection identifier*. It is important
+ to note that the *data* traffic in the protocol is multiplexed,
+ while the *control* traffic is not.
+ 
+ The nodes that generate data to be sent to the root are *producers*.
+ The producers use the Send interface [1_] to send data to the root
+ of the collection tree.  The collection identifier is specified as a
+ parameter to Send during instantiation.
+ 
+ Root nodes that receive data from the network are *consumers*. The
+ consumers use the Receive interface [1_] to receive a message
+ delivered by collection. The collection identifier is specified
+ as a parameter to Receive during instantiation.
+ 
+ The nodes that overhear messages in transit are *snoopers*. The
+ snoopers use the Receive interface [1_] to receive a snooped
+ message. The collection identifier is specified as a parameter
+ to Receive during instantiation.
+ 
+ The nodes can process a packet that are in transit. These in-network
+ *processors* use the Intercept interface [1_] to receive and update
+ a packet. The collection identifier is specified as a parameter
+ to Intercept during instantiation.
  
  3 Collection Services
  ====================================================================
  
! A collection service MUST provide one component, CollectionC,
  which has the following signature::
  
!   configuration CollectionC {
      provides {
        interface StdControl;
***************
*** 129,133 ****
        interface Packet;
        interface CollectionPacket;
-       interface TreeRoutingInspect;
      }
      uses {
--- 148,151 ----
***************
*** 137,146 ****
  
  
! TreeCollectionC MAY have additional interfaces, but they MUST have
  default functions on all outgoing invocations (commands for uses,
  events for provides) of those interfaces so that it can operate
  properly if they are not wired.
  
! Components SHOULD NOT wire to TreeCollectionC.Send. The generic
  component CollectionSenderC (described in section 3.1) provides
  a virtualized sending interface.
--- 155,164 ----
  
  
! CollectionC MAY have additional interfaces, but they MUST have
  default functions on all outgoing invocations (commands for uses,
  events for provides) of those interfaces so that it can operate
  properly if they are not wired.
  
! Components SHOULD NOT wire to CollectionC.Send. The generic
  component CollectionSenderC (described in section 3.1) provides
  a virtualized sending interface.
***************
*** 155,193 ****
  
  Receive.receive MUST NOT be signaled on non-root
! nodes. TreeCollectionC MAY signal Receive.receive on a root node when
  a data packet successfully arrives at that node. If a root node calls
! Send, TreeCollectionC MUST treat it as it if were a received packet.
  Note that the buffer swapping semantics of Receive.receive, when
! combined with the pass semantics of Send, require that TreeCollectionC
  make a copy of the buffer if it signals Receive.receive.
  
! If TreeCollectionC receives a data packet to forward and it is not a
  root node, it MAY signal Intercept.forward.
  
! If TreeCollectionC receives a data packet that a different node
  is supposed to forward, it MAY signal Snoop.receive.
  
  RootControl allows a node to be made a collection tree root.
! TreeCollectionC SHOULD NOT configure a node as a root by default.
  
  Packet and CollectionPacket allow components to access collection
  data packet fields [1_].
  
- TreeRoutingInspect provides information on the current position of
- the node in a routing tree::
- 
-   interface TreeRoutingInspect {
-     command error_t getParent(am_addr_t* parent);
-     command error_t getHopcount(uint8_t* hopcount);
-     command error_t getMetric(uint16_t* metric);
-   }
- 
- In each of these commands, if the return value is not SUCCESS, the
- value stored in the pointer argument is undefined. The getMetric
- command provides a measure of the quality of a node's route to the
- base station. This routing metric MUST be monotonically increasing
- across hops. In a collection tree, if node A is the parent of node B,
- then node B's metric value MUST be greater than node A's.
- 
  3.1 CollectionSenderC
  --------------------------------------------------------------------
--- 173,195 ----
  
  Receive.receive MUST NOT be signaled on non-root
! nodes. CollectionC MAY signal Receive.receive on a root node when
  a data packet successfully arrives at that node. If a root node calls
! Send, CollectionC MUST treat it as it if were a received packet.
  Note that the buffer swapping semantics of Receive.receive, when
! combined with the pass semantics of Send, require that CollectionC
  make a copy of the buffer if it signals Receive.receive.
  
! If CollectionC receives a data packet to forward and it is not a
  root node, it MAY signal Intercept.forward.
  
! If CollectionC receives a data packet that a different node
  is supposed to forward, it MAY signal Snoop.receive.
  
  RootControl allows a node to be made a collection tree root.
! CollectionC SHOULD NOT configure a node as a root by default.
  
  Packet and CollectionPacket allow components to access collection
  data packet fields [1_].
  
  3.1 CollectionSenderC
  --------------------------------------------------------------------
***************
*** 196,205 ****
  component CollectionSenderC::
  
! generic configuration CollectionSenderC(collection_id_t collectid) {
!   provides {
!     interface Send;
!     interface Packet;
    }
! }
  
  This abstraction follows a similar virtualization approach to
--- 198,209 ----
  component CollectionSenderC::
  
!   generic configuration CollectionSenderC(collection_id_t collectid) {
!     provides {
!       interface Send;
!       interface Packet;
!     }
    }
! 
! 
  
  This abstraction follows a similar virtualization approach to
***************
*** 213,225 ****
  
  An implementation of this TEP can be found in
! ``tinyos-2.x/tos/lib/net/collection``. The implementation consists of
! three major components, which are wired together to form a
! CollectionC: LinkEstimatorP, TreeRoutingEngineP, and ForwardingEngineP.
  
! This decomposition tries to encourage evolution of components and ease
! of use through modularization. Neighbor management and link estimation
! are are decoupled from the routing protocol. Furthermore, the routing
! protocol and route selection are decoupled from the forwarding policies,
! such as queueing and timing.
  
  4.1 LinkEstimatorP
--- 217,234 ----
  
  An implementation of this TEP can be found in
! ``tinyos-2.x/tos/lib/net/ctp`` and ``tinyos-2.x/tos/lib/net/le``, in
! the CTP protocol. It is beyond the scope of this document to fully
! describe CTP, but we outline its main components. CTP will be
! described in an upcoming TEP [2_].  This implementation is a
! reference implementation, and is not the only possibility.  It
! consists of three major components, which are wired together to form
! a CollectionC: LinkEstimatorP, CtpTreeRoutingEngineP, and
! CtpForwardingEngineP. 
  
! This decomposition tries to encourage evolution of components and
! ease of use through modularization. Neighbor management and link
! estimation are decoupled from the routing protocol. Furthermore, the
! routing protocol and route selection are decoupled from the
! forwarding policies, such as queueing and timing.
  
  4.1 LinkEstimatorP
***************
*** 227,250 ****
  
  LinkEstimatorP estimates the quality of link to or from each
! neighbor. Link estimation can be done in a variety of ways, and we do
! not impose one here. It is decoupled from the establishment of
! routes. There is a narrow interface (LinkEstimator and
! NeighborTableEviction) between the link estimator and the routing
! engine. The one requirement is that the quality returned is
! standardized. A smaller return value from LinkEstimator.getQuality(),
! LinkEstimator.getforwardQuality(), LinkEstimator.getreserveQuality()
! MUST imply that the link to the neighbor is estimated to be of a
! higher quality than the one that results in a smaller return
! value. The range of value SHOULD be [0,255] and the variation in link
! quality in that range SHOULD be linear. Radio provided values such as
! LQI or RSI, beacon based link estimation to compute ETX, or their
! combination are some possible approaches to estimating link
! qualities. LinkEstimatorP MAY have its own control messages to compute
! bi-directional link qualities. LinkEstimatorP provides calls (txAck(),
! txNoAck(), and clearDLQ()) to update the link estimates based on
! successful or unsuccessful data transmission to the neighbors. The
! user of LinkEstimatorP can call insertNeighbor() to manually insert a
! node in the neighbor table, pinNeighbor() to prevent a neighbor from
! being evicted, and unpinNeighbor() to restore eviction policy::
  
    typedef uint16_t neighbor_table_entry_t
--- 236,263 ----
  
  LinkEstimatorP estimates the quality of link to or from each
! neighbor. Link estimation can be done in a variety of ways, and we
! do not impose one here. It is decoupled from the establishment of
! routes. There is a narrow interface -- LinkEstimator -- between the
! link estimator and the routing engine. The one requirement is that
! the quality returned is standardized. A smaller return value from
! LinkEstimator.getQuality(), LinkEstimator.getforwardQuality(),
! LinkEstimator.getReverseQuality() MUST imply that the link to the
! neighbor is estimated to be of a higher quality than the one that
! results in a larger return value. The range of value SHOULD be
! [0,255] and the variation in link quality in that range SHOULD be
! linear. Radio provided values such as LQI or RSI, beacon based link
! estimation to compute ETX, or their combination are some possible
! approaches to estimating link qualities. 
! 
! LinkEstimatorP MAY have its own control messages to compute
! bi-directional link qualities. LinkEstimatorP provides calls
! (txAck(), txNoAck(), and clearDLQ()) to update the link estimates
! based on successful or unsuccessful data transmission to the
! neighbors. 
! 
! The user of LinkEstimatorP can call insertNeighbor() to manually
! insert a node in the neighbor table, pinNeighbor() to prevent a
! neighbor from being evicted, and unpinNeighbor() to restore eviction
! policy::
  
    typedef uint16_t neighbor_table_entry_t
***************
*** 275,324 ****
    }
  
-   interface NeighborTableEviction {
-     event void evicted(uint16_t neighbor)
-   }
  
  
! 4.2 TreeRoutingEngineP
  --------------------------------------------------------------------
  
! TreeRoutingEngineP is responsible for computing routes to the roots of a
! tree. It uses NeighborTable and LinkEstimator interfaces to learn
  about the nodes in the neighbor table maintained by LinkEstimatorP and
  the quality of links to and from the neighbors. The routing protocol
  on which collection is implemented MUST be a tree-based routing
! protocol with a single or multiple roots. TreeRoutingEngineP 
  allows a node to be configured as a root or a non-root node
! dynamically. TreeRoutingEngineP maintains multiple candidate next hops::
  
!   generic module TreeRoutingEngineP(uint8_t routingTableSize) {
!     provides {
!         interface UnicastNameFreeRouting as Routing;
!         interface RootControl;
!         interface TreeRoutingInspect;
!         interface StdControl;
!         interface Init;
!     } 
!     uses {
!         interface AMSend as BeaconSend;
!         interface Receive as BeaconReceive;
!         interface LinkEstimator;
!         interface AMPacket;
!         interface LinkSrcPacket;
!         interface SplitControl as RadioControl;
!         interface Timer<TMilli> as BeaconTimer;
!         interface Random;
!         interface CollectionDebug;
!     }
    }
  
! 4.3 ForwardingEngineP
  --------------------------------------------------------------------
  
! The ForwardingEngineP component provides all the top level interfaces
! (except RootControl) which TreeCollectionC provides and an application 
! uses:: 
  
!   generic module ForwardingEngineP() {
      provides {
        interface Init;
--- 288,359 ----
    }
  
  
  
! 4.2 CtpRoutingEngineP
  --------------------------------------------------------------------
  
! CtpRoutingEngineP is responsible for computing routes to the roots of a
! tree. In traditional networking terminology, this is part of the
! control plane of the network, and is does not directly forward any
! data packets, which is the responsibility of CtpForwardingEngine. 
! The main interface between the two is UnicastNameFreeRouting.
! 
! CtpRoutingEngineP uses the LinkEstimator interface to learn
  about the nodes in the neighbor table maintained by LinkEstimatorP and
  the quality of links to and from the neighbors. The routing protocol
  on which collection is implemented MUST be a tree-based routing
! protocol with a single or multiple roots. CtpRoutingEngineP 
  allows a node to be configured as a root or a non-root node
! dynamically. CtpRoutingEngineP maintains multiple candidate next hops::
  
!   generic module CtpRoutingEngineP(uint8_t routingTableSize, 
!                                    uint16_t minInterval, 
!                                    uint16_t maxInterval) {
!       provides {
!           interface UnicastNameFreeRouting as Routing;
!           interface RootControl;
!           interface CtpInfo;
!           interface StdControl;
!           interface CtpRoutingPacket;
!           interface Init;
!       } 
!       uses {
!           interface AMSend as BeaconSend;
!           interface Receive as BeaconReceive;
!           interface LinkEstimator;
!           interface AMPacket;
!           interface LinkSrcPacket;
!           interface SplitControl as RadioControl;
!           interface Timer<TMilli> as BeaconTimer;
!           interface Timer<TMilli> as RouteTimer;
!           interface Random;
!           interface CollectionDebug;
!           interface CtpCongestion;
!       }
    }
  
! 
! ::
! 
!  interface UnicastNameFreeRouting {
!    command am_addr_t nextHop();
! 
!    command bool hasRoute();
!    event void routeFound();
!    event void noRoute();
!  }
! 
! 
! 
! 4.3 CtpForwardingEngineP
  --------------------------------------------------------------------
  
! The CtpForwardingEngineP component provides all the top level interfaces
! (except RootControl) which CollectionC provides and an application 
! uses. It deals with retransmissions, duplicate suppression, packet
! timing, loop detection, and also informs the LinkEstimator of the
! outcome of attempted transmissions.::
  
!   generic module CtpForwardingEngineP() {
      provides {
        interface Init;
***************
*** 330,335 ****
--- 365,373 ----
        interface Packet;
        interface CollectionPacket;
+       interface CtpPacket;
+       interface CtpCongestion;
      }
      uses {
+       interface SplitControl as RadioControl;
        interface AMSend as SubSend;
        interface Receive as SubReceive;
***************
*** 337,347 ****
        interface Packet as SubPacket;
        interface UnicastNameFreeRouting;
-       interface SplitControl as RadioControl;
        interface Queue<fe_queue_entry_t*> as SendQueue;
        interface Pool<fe_queue_entry_t> as QEntryPool;
        interface Pool<message_t> as MessagePool;
        interface Timer<TMilli> as RetxmitTimer;
!       interface Cache<uint32_t> as SentCache;
!       interface TreeRoutingInspect;
        interface PacketAcknowledgements;
        interface Random;
--- 375,386 ----
        interface Packet as SubPacket;
        interface UnicastNameFreeRouting;
        interface Queue<fe_queue_entry_t*> as SendQueue;
        interface Pool<fe_queue_entry_t> as QEntryPool;
        interface Pool<message_t> as MessagePool;
        interface Timer<TMilli> as RetxmitTimer;
!       interface LinkEstimator;
!       interface Timer<TMilli> as CongestionTimer;
!       interface Cache<message_t*> as SentCache;
!       interface CtpInfo;
        interface PacketAcknowledgements;
        interface Random;
***************
*** 353,363 ****
    }
  
! ForwardingEngineP uses a large number of interfaces, which can be
  broken up into a few groups of functionality:
  
    * Single hop communication: SubSend, SubReceive, SubSnoop,
      SubPacket, PacketAcknowledgments, AMPacket
!   * Routing: UnicastNameFreeRouting, TreeRoutingInspect, 
!     RootControl, CollectionId, SentCache
    * Queue and buffer management: SendQueue, MessagePool,
      QEntryPool
--- 392,403 ----
    }
  
! 
! CtpForwardingEngineP uses a large number of interfaces, which can be
  broken up into a few groups of functionality:
  
    * Single hop communication: SubSend, SubReceive, SubSnoop,
      SubPacket, PacketAcknowledgments, AMPacket
!   * Routing: UnicastNameFreeRouting, RootControl, CtpInfo,
!     CollectionId, SentCache
    * Queue and buffer management: SendQueue, MessagePool,
      QEntryPool
***************
*** 407,409 ****
--- 447,450 ----
  
  .. [1] TEP 116: Packet Protocols
+ .. [2] TEP 124: The Collection Tree Protocol (CTP) - (upcoming)