[Tinyos-2-commits] CVS: tinyos-2.x/doc/txt tep109.txt, 1.1.2.5,
1.1.2.6
Gilman Tolle
gtolle at users.sourceforge.net
Wed Dec 6 09:47:48 PST 2006
Update of /cvsroot/tinyos/tinyos-2.x/doc/txt
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv27435/txt
Modified Files:
Tag: tinyos-2_0_devel-BRANCH
tep109.txt
Log Message:
Fixed lowercase 'must', 'should', and 'may' by uppercasing or correcting word choice. Added DeviceMetadata.getMostSignificantBit() to text and examples. Made DeviceMetadata a MUST requirement for sensor HILs that use a level of precision that is not a multiple of 8.
Index: tep109.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep109.txt,v
retrieving revision 1.1.2.5
retrieving revision 1.1.2.6
diff -C2 -d -r1.1.2.5 -r1.1.2.6
*** tep109.txt 15 Nov 2006 18:43:15 -0000 1.1.2.5
--- tep109.txt 6 Dec 2006 17:47:46 -0000 1.1.2.6
***************
*** 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::
***************
*** 129,152 ****
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 {
- command uint8_t getSignificantBits();
- }
-
- 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>;
--- 130,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. 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>;
***************
*** 156,159 ****
--- 147,170 ----
0x0000 - 0xfff0, rather than 0x0000 - 0x0fff.
+ Such a device MUST specify the precision of one of its interfaces by
+ providing the DeviceMetadata interface::
+
+ interface DeviceMetadata {
+ command uint8_t getSignificantBits();
+ command uint8_t getMostSignificantBit();
+ }
+
+ 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". The getMostSignificantBit() call MUST
+ return the index of the most significant bit in the reading, 0-indexed
+ from the least significant bit. For example, if the 12-bit ADC
+ reading is right-shifted, the call MUST return the value "11", and if
+ the 12-bit ADC reading is left-shifted, the call MUST return the value
+ "15".
+
Sensor driver components SHOULD be named according to the make and
model of the sensing device being presented. Using specific names
***************
*** 165,169 ****
performance characteristics.
! A "common" naming layer atop a HIL may look like this::
generic configuration TemperatureC() {
--- 176,180 ----
performance characteristics.
! A "common" naming layer atop a HIL might look like this::
generic configuration TemperatureC() {
***************
*** 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.
--- 234,239 ----
====================================================================
! 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.
--- 279,283 ----
- @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>".
--- 290,294 ----
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.
--- 297,301 ----
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.
--- 310,314 ----
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 ****
--- 387,391 ----
provides interface Read<uint16_t>;
provides interface ReadStream<uint16_t>;
+ provides interface DeviceMetadata;
}
implementation {
***************
*** 385,388 ****
--- 397,401 ----
components HamamatsuS1087ParP;
+ DeviceMetadata = HamamatsuS1087ParP;
AdcReadClientC.AdcConfigure -> HamamatsuS1087ParP;
AdcReadStreamClientC.AdcConfigure -> HamamatsuS1087ParP;
***************
*** 397,400 ****
--- 410,414 ----
module HamamatsuS1087ParP {
provides interface AdcConfigure<const msp430adc12_channel_config_t*>;
+ provides interface DeviceMetadata;
}
implementation {
***************
*** 414,417 ****
--- 428,434 ----
return &config;
}
+
+ command uint8_t DeviceMetadata.getSignificantBits() { return 12; }
+ command uint8_t DeviceMetadata.getMostSignificantBit() { return 11; }
}
***************
*** 565,569 ****
--- 582,588 ----
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;
--- 590,597 ----
Temperature = SensirionSht11ReaderP.Temperature;
+ TemperatureDeviceMetadata = SensirionSht11ReaderP.TemperatureDeviceMetadata;
Humidity = SensirionSht11ReaderP.Humidity;
! HumidityDeviceMetadata = SensirionSht11ReaderP.HumidityDeviceMetadata;
!
components HalSensirionSht11C;
***************
*** 590,594 ****
--- 611,617 ----
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();
--- 638,645 ----
signal Temperature.readDone( result, val );
}
!
! command uint8_t TemperatureDeviceMetadata.getSignificantBits() { return 14; }
! command uint8_t TemperatureDeviceMetadata.getMostSignificantBit() { return 13; }
!
command error_t Humidity.read() {
call HumResource.request();
***************
*** 634,637 ****
--- 660,666 ----
}
+ command uint8_t HumidityDeviceMetadata.getSignificantBits() { return 12; }
+ command uint8_t HumidityDeviceMetadata.getMostSignificantBit() { return 11; }
+
event void Sht11Temp.resetDone( error_t result ) { }
event void Sht11Temp.measureHumidityDone( error_t result, uint16_t val ) { }
More information about the Tinyos-2-commits
mailing list