[Tinyos-2-commits] CVS: tinyos-2.x/doc/txt tep101.txt, 1.2,
1.3 tep106.txt, 1.2, 1.3 tep108.txt, 1.2, 1.3 tep109.txt, 1.2,
1.3 tep114.txt, 1.2, 1.3
Phil Levis
scipio at users.sourceforge.net
Fri Sep 8 16:10:44 PDT 2006
Update of /cvsroot/tinyos/tinyos-2.x/doc/txt
In directory sc8-pr-cvs10.sourceforge.net:/tmp/cvs-serv456
Modified Files:
tep101.txt tep106.txt tep108.txt tep109.txt tep114.txt
Log Message:
Updated to devel branch versions.
Index: tep101.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep101.txt,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** tep101.txt 12 Jul 2006 16:59:41 -0000 1.2
--- tep101.txt 8 Sep 2006 23:10:41 -0000 1.3
***************
*** 36,40 ****
Analog-to-digital converters (ADCs) are devices that convert analog input
! signals to discrete digital output signals, typically voltage to a digital
number. The interested reader can refer to Appendix A for a brief overview of
the ADC hardware on some current TinyOS platforms. In earlier versions of
--- 36,40 ----
Analog-to-digital converters (ADCs) are devices that convert analog input
! signals to discrete digital output signals, typically voltage to a binary
number. The interested reader can refer to Appendix A for a brief overview of
the ADC hardware on some current TinyOS platforms. In earlier versions of
***************
*** 88,95 ****
* the set of platform-independent interfaces for the collection of ADC
conversion results (`2. Interfaces`_)
! * guidelines on how an ADC's HAL SHOULD should be split into HAL1 and HAL2 and
! how the HAL1 SHOULD expose chip-specific interfaces (`3. HAL1 guidelines`_)
* what components an ADC's HAL2 MUST implement (`4. HAL2 requirements`_)
* guidelines on how the HAL2 may be structured (`5. HAL2 implementation guidelines`_)
This TEP ends with appendices documenting, as an example, the ADC
--- 88,97 ----
* the set of platform-independent interfaces for the collection of ADC
conversion results (`2. Interfaces`_)
! * guidelines on how an ADC's HAL should be split into HAL1 and HAL2 and
! how the HAL1 should expose chip-specific interfaces (`3. HAL1 guidelines`_)
* what components an ADC's HAL2 MUST implement (`4. HAL2 requirements`_)
* guidelines on how the HAL2 may be structured (`5. HAL2 implementation guidelines`_)
+ * a section pointing to the current implementation (`6. Implementation`_)
+
This TEP ends with appendices documenting, as an example, the ADC
***************
*** 132,138 ****
channel immediately (the request is not buffered). Due to its timing
constraints the ReadNow interface is always provided in conjunction with an
! instance of the Resource interface. A client MUST request access to the ADC
! via the Resource interface before it can call ReadNow.read() and it MUST
! release access via the Resource interface when it is finished (see [TEP108]_).
ReadStream
--- 134,140 ----
channel immediately (the request is not buffered). Due to its timing
constraints the ReadNow interface is always provided in conjunction with an
! instance of the Resource interface. Refer to [TEP108]_ on how the 'Resource'
! interface should be used by a client component.
!
ReadStream
***************
*** 154,158 ****
HAA [TEP2]_. Therefore only chip- and platform-dependent clients MAY wire to
the HAL1. Although the HAL1 is chip-specific, both, in terms of implementation
! and representation, its design SHOULD follow the guidelines described below to
facilitate the mapping to platform-independent interfaces on the level of
HAL2. Appendix B shows the HAL1 specification for the TI MSP430 MCU.
--- 156,160 ----
HAA [TEP2]_. Therefore only chip- and platform-dependent clients MAY wire to
the HAL1. Although the HAL1 is chip-specific, both, in terms of implementation
! and representation, its design should follow the guidelines described below to
facilitate the mapping to platform-independent interfaces on the level of
HAL2. Appendix B shows the HAL1 specification for the TI MSP430 MCU.
***************
*** 163,193 ****
As the ADC hardware is a shared resource that is multiplexed between several
clients, it requires access arbitration. Therefore the HAL1 configuration
! component SHOULD provide a parameterized 'Resource' interface, instantiate a
generic arbiter component and connect the 'Resource' interface to the arbiter
! as described in [TEP108]_. To provide a uniform arbitration service for all
! platforms on the level of HAL2 (see `4. HAL2 requirements`_), all ADCs should
! be arbitrated in round robin fashion, i.e. the HAL1 SHOULD instantiate the
! standard round robin arbiter. On the level of HAL1 a client MUST have
! successfully requested access to the ADC via the 'Resource' interface before
! it can configure / sample a channel. After use it MUST release the ADC via the
! 'Resource' interface (see [TEP108]_).
Configuration and sampling
--------------------------------------------------------------------
! As the ADC hardware is a shared resource the HAL1 SHOULD support hardware
configuration and sampling on a per-client basis (although per-port
configuration is possible, it is not recommended, because it forces all
! clients to use the same settings for a given port). Therefore an HAL1 SHOULD
! provide "sampling interfaces" parameterized by a client identifier. An HAL1
client can use its instance of the sampling interface to configure the ADC
hardware, start the sampling process and get conversion results. It wires to a
sampling interface using a unique client identifier. All commands and events
! in the sampling interface SHOULD be 'async' to reflect the potential timing
! requirements of clients. An HAL1 MAY provide multiple different parameterized
sampling interfaces, depending on the hardware capabilities. This allows to
differentiate/group ADC functionality, for example single vs. repeated
sampling, single channel vs. multiple channels or low-frequency vs.
! high-frequency sampling. Every sampling interface SHOULD allow the client to
individually configure the ADC hardware, for example by including the
configuration data as parameters in the sampling commands. However, if
--- 165,191 ----
As the ADC hardware is a shared resource that is multiplexed between several
clients, it requires access arbitration. Therefore the HAL1 configuration
! component should provide a parameterized 'Resource' interface, instantiate a
generic arbiter component and connect the 'Resource' interface to the arbiter
! as described in [TEP108]_. To ensure fair and uniform arbitration on all
! platforms the standard round robin arbiter is recommended. Refer to [TEP108]_
! on how the 'Resource' interface is to be used by a client wiring to HAL1.
Configuration and sampling
--------------------------------------------------------------------
! As the ADC hardware is a shared resource the HAL1 should support hardware
configuration and sampling on a per-client basis (although per-port
configuration is possible, it is not recommended, because it forces all
! clients to use the same settings for a given port). Therefore an HAL1 should
! provide sampling interfaces parameterized by a client identifier. An HAL1
client can use its instance of the sampling interface to configure the ADC
hardware, start the sampling process and get conversion results. It wires to a
sampling interface using a unique client identifier. All commands and events
! in the sampling interface should be 'async' to reflect the potential timing
! requirements of clients. An HAL1 may provide multiple different parameterized
sampling interfaces, depending on the hardware capabilities. This allows to
differentiate/group ADC functionality, for example single vs. repeated
sampling, single channel vs. multiple channels or low-frequency vs.
! high-frequency sampling. Every sampling interface should allow the client to
individually configure the ADC hardware, for example by including the
configuration data as parameters in the sampling commands. However, if
***************
*** 200,204 ****
In order to hide wiring complexities and/or export only a subset of all ADC
! functions generic ADC wrapper components MAY be provided on the level of HAL1
to be instantiated by chip- and platform-dependent clients.
--- 198,202 ----
In order to hide wiring complexities and/or export only a subset of all ADC
! functions generic ADC wrapper components may be provided on the level of HAL1
to be instantiated by chip- and platform-dependent clients.
Index: tep106.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep106.txt,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** tep106.txt 12 Jul 2006 16:59:41 -0000 1.2
--- tep106.txt 8 Sep 2006 23:10:41 -0000 1.3
***************
*** 242,246 ****
A scheduler MUST provide a parameterized TaskBasic interface.
If a call to TaskBasic.postTask() returns SUCCESS, the scheduler MUST run it
! eventually. The scheduler MUST return SUCCESS to a TaskBasic.postTask()
operation unless it is not the first call to TaskBasic.postTask() since
that task's TaskBasic.runTask() event has been signaled. The
--- 242,247 ----
A scheduler MUST provide a parameterized TaskBasic interface.
If a call to TaskBasic.postTask() returns SUCCESS, the scheduler MUST run it
! eventually, so that starvation is not a concern. The scheduler MUST
! return SUCCESS to a TaskBasic.postTask()
operation unless it is not the first call to TaskBasic.postTask() since
that task's TaskBasic.runTask() event has been signaled. The
***************
*** 278,282 ****
}
! When a component declares a task with the task keyword in nesC, it
is implicitly declaring that it uses an instance of the TaskBasic
interface: the task body is the runTask event. When a component uses the
--- 279,283 ----
}
! When a component declares a task with the ``task`` keyword in nesC, it
is implicitly declaring that it uses an instance of the TaskBasic
interface: the task body is the runTask event. When a component uses the
***************
*** 306,314 ****
directory: this will replace the default. The scheduler component
provides a wire-through of the desired scheduler implementation. All
! scheduler implementations SHOULD provide a parameterize TaskBasic
interface, as SchedulerBasicP does; this supports nesC post statements
! and task declarations. If a scheduler does not provide the TaskBasic
! interface, compiling applications requires modifying the standard
! ncc scheduler parameters (as described in Appendix A). All scheduler
implementations MUST provide the Scheduler interface.
--- 307,315 ----
directory: this will replace the default. The scheduler component
provides a wire-through of the desired scheduler implementation. All
! scheduler implementations MUST provide a parameterize TaskBasic
interface, as SchedulerBasicP does; this supports nesC post statements
! and task declarations and enables TinyOS core systems to operate
! properly. Generally, TinyOS core code needs to be able to run unchanged
! with new scheduler implementations. All scheduler
implementations MUST provide the Scheduler interface.
***************
*** 388,396 ****
}
If the scheduler provides two instances of the same task interface,
their unique keys are based on the name of the interface as the
scheduler presents it (the "as" keyword). For example, imagine
a scheduler which provides two instances of TaskBasic: standard
! tasks and high-priority tasks. The scheduler always selects a task
for the high priority queue before the standard queue::
--- 389,402 ----
}
+ The requirement that basic tasks not be subject to starvation
+ requires that a scheduler supporting EDF tasks must ensure that
+ basic tasks run eventually even if there is an unending stream of
+ short deadline tasks to run.
+
If the scheduler provides two instances of the same task interface,
their unique keys are based on the name of the interface as the
scheduler presents it (the "as" keyword). For example, imagine
a scheduler which provides two instances of TaskBasic: standard
! tasks and high-priority tasks. The scheduler usually selects a task
for the high priority queue before the standard queue::
***************
*** 401,406 ****
}
! A component that uses a high priority task would then wire to
! TaskHighPriority with the key "TinySchedulerC.TaskHighPriority"::
configuration SomethingElseC {}
--- 407,413 ----
}
! It cannot always select a high priority task because that could
! starve basic tasks. A component that uses a high priority task would
! wire to TaskHighPriority with the key "TinySchedulerC.TaskHighPriority"::
configuration SomethingElseC {}
Index: tep108.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep108.txt,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** tep108.txt 12 Jul 2006 16:59:41 -0000 1.2
--- tep108.txt 8 Sep 2006 23:10:41 -0000 1.3
***************
*** 17,24 ****
.. 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
--- 17,24 ----
.. Note::
[...1335 lines suppressed...]
+ components Msp430I2C0P as I2CP;
+ components new Msp430Usart0C() as UsartC;
+ I2CP.ResourceConfigure[ CLIENT_ID ] <- UsartC.ResourceConfigure;
+ I2CP.UsartResource[ CLIENT_ID ] -> UsartC.Resource;
+ I2CP.I2CInterrupts -> UsartC.HplMsp430UsartInterrupts;
+ ...
+ }
+
+ The implementation of the ResourceConfigure interface is
+ provided by both the Msp430SpiNoDma0P and the Msp430I2C0P. In the
+ two different components, the same Msp430Usart0C component is used,
+ but wired to the proper implementation of the ResourceConfigure
+ interface. In this way, different instances of the Msp430Usart0C
+ can each have different configurations associated with them, but
+ still provide the same functionality.
+
+ Take a look in the tinyos-2.x source tree under
+ tinyos-2.x/tos/chips/msp430/usart to see the full implementation of
+ these components along with the corresponding Uart implementation.
Index: tep109.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep109.txt,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** tep109.txt 12 Jul 2006 16:59:41 -0000 1.2
--- tep109.txt 8 Sep 2006 23:10:41 -0000 1.3
***************
*** 1,5 ****
! ============================
! Sensor Boards
! ============================
:TEP: 109
--- 1,5 ----
! =========================
! Sensors and Sensor Boards
! =========================
:TEP: 109
***************
*** 8,16 ****
:Status: Draft
:TinyOS-Version: 2.x
! :Author: David Gay, Phil Levis, Wei Hong, and Joe Polastre
! :Draft-Created: 19-Apr-2005
! :Draft-Version: $Revision$
! :Draft-Modified: $Date$
:Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>
--- 8,14 ----
:Status: Draft
:TinyOS-Version: 2.x
! :Author: David Gay, Phil Levis, Wei Hong, Joe Polastre, and Gilman Tolle
! :Draft-Created: 10-Jun-2006
:Draft-Discuss: TinyOS Developer List <tinyos-devel at mail.millennium.berkeley.edu>
***************
*** 25,272 ****
====================================================================
! This memo documents how sensor boards are organized in TinyOS, and the
! general principles followed by the components that provide access to
! its sensors.
! 1. Introduction
====================================================================
! This document defines the default organization of a sensor board in
! TinyOS. There likely will be sensor boards that cannot conform
! to this specification, but following as closely to its spirit as possible
! will simplify generic applications that use a range of sensor boards.
! This document assumes that sensors return uninterpreted 16-bit values, and,
! optionally uninterpreted, arbitrary-size calibration data. Conversion of
! sensor values to something with actual physical meaning is beyond the
! scope of this document.
! 2. Directory Organization
! ====================================================================
! - A sensor board MUST have a unique name, composed of letters, numbers
! and underscores. 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. We will use SBOARD to
! denote the sensor board name in the rest of this document.
! - Each sensor board MUST have its own directory named SBOARD; default TinyOS
! sensor boards are placed in tinyos-2.x/tos/sensorboards, 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. This file
! is a perl script which contains any additional compiler settings needed for
! this sensor board (this file will be empty in many cases).
! - If the sensor board wishes to define any C types or constants, it SHOULD
! place these in a file named SBOARD.h in the sensor board's directory.
! - The sensor board directory SHOULD contain sensor board components
! for accessing each sensor on the sensor board. The conventions for these
! components are detailed in Section 3.
! - A sensor board MAY include additional components providing alternative or
! higher-level interfaces to the sensors (e.g., for TinyDB). These components
! are beyond the scope of this document.
! - Finally, the sensor board MAY contain any number of components,
! interfaces, C files, etc for internal use. To avoid name collisions, all
! externally visible names (interface types, components, C constants and
! types) used for internal purposes SHOULD be prefixed with SBOARD. All such
! components should end in P.
! A simple example: the basic sensor board is named `basicsb`, it's directory
! is `tinyos-2.x/tos/sensorboards/basicsb`. It has no `basicsb.h` file and
! its `.sensor` file is empty. It has two components, `PhotoC` and `TempC`
! representing its light and temperature sensors.
! 3. Sensor Board Components
! ====================================================================
! We have not yet selected any naming conventions for sensor board
! components. Please select reasonable names\ldots
! A sensor board component MUST provide:
! - An `Init` interface.
! - A `StdControl` or `SplitControl` interface for power management.
! - A non-empty set of `AcquireData` interfaces for sampling.
! A sensor board component MAY provide:
! - Some `CalibrationData` interfaces for obtaining calibration data.
! A calibration interface for a sensor accessed via interface X should
! be called XCalibration.
! - Some `AcquireDataNow` and `AcquireDataBuffered` interfaces, for high-speed
! or low-latency data acquisition.
! - Any other appropriate interface.
! The `CalibrationData` interface is shown below, while `AcquireData`,
! `AcquireDataNow` and `AcquireDataBuffered` are in TEP 101. The
! `AcquireData` interface returns uinterpreted 16-bit data. This might
! represent an A/D conversion result, a counter, etc. The optional
! calibration interface returns uninterpreted, arbitrary-size data.
! A sensor board component SHOULD be as lightweight as possible - it should
! just provide basic access to the physical sensors and SHOULD NOT attempt to do
! calibration, signal processing, etc. If such functionality is desired, it
! SHOULD be provided in separate components.
! | ``interface CalibrationData {``
! | ``/* Collect uninterpreted calibration data from a sensor */``
! |
! | ``/** Request calibration data``
! | ``* @return SUCCESS if request accepted, FAIL if it is refused``
! | ``* data error will be signaled if SUCCESS is returned``
! | ``*/``
! | ``command result_t get();``
! |
! | ``/** Returns calibration data``
! | ``* @param x Pointer to (uinterpreted) calibration data. This data``
! | ``* must not be modified.``
! | ``* @param len Length of calibration data``
! | ``* @return Ignored.``
! | ``*/``
! | ``event result_t data(const void *x, uint8_t len);``
! | ``}``
! Some common setups for sensor board components are:
! - A single `AcquireData` interface. This is probably the most common case,
! where a single component corresponds to a single physical sensor, e.g., for
! light, temperature, pressure and there is no expectation of high sample
! rates.
! - Multiple `AcquireData` interfaces. Some sensors might be strongly
! related, e.g., the axes of an accelerometer. A single component could then
! provide a sensor interface for each axis. For instance, a 2-axis
! accelerometer which can be sampled at high speed, and which has some
! calibration data might be declared with:
! | ``configuration Accelerometer2D {``
! | ``provides {``
! | ``interface StdControl``
! | ``interface AcquireData as AccelX;``
! | ``interface AcquireDataNow as AccelXSingle;``
! | ``interface AcquireDataBuffered as AccelXMultiple;``
! | ``interface CalibrationData as AccelXCalibration;``
! |
! | ``interface AcquireData as AccelY;``
! | ``interface AcquireDataNow as AccelYSingle;``
! | ``interface AcquireDataBuffered as AccelYMultiple;``
! | ``interface CalibrationData as AccelYCalibration;``
! | ``}``
! | ``}``
! - A parameterised `AcquireData` interface. If a sensor board has multiple
! similar sensors, it may make sense to provide a single component to access
! all of these, using a parameterised `AcquireData` interface. For instance,
! a general purpose sensor board with multiple A/D channels might provide an
! `AcquireData` interface parameterised by the A/D channel id.
! - In all of these examples, if high-speed sampling makes sensor for the
! sensor (e.g., a microphone), and the sensor is connected in a way that
! supports high-frequency and/or low-latency access (e.g., via an
! on-microcontroller A/D converter), the component should offer
! `AcquireDataNow` and `AcquireDataBuffered` interfaces.
! Sensor board components MUST respect the following conventions
! on the use of the `Init`, `StdControl`, and `SplitControl`
! interfaces. These are given assuming `StdControl` is used, but the
! behaviour with `SplitControl` is identical except that `start` and `stop`
! are not considered complete until the `startDone` and `stopDone` events are
! signaled. The conventions are:
! 1) `Init.init`: must be called at mote boot time.
! 2) `StdControl.start`: ensure the sensor corresponding to this component is
! ready for use. For instance, this should power-up the sensor if
! necessary. The application can call `getData` once `StdControl.start`
! completes.
! If a sensor takes a while to power-up, the sensor board implementer can
! either use a `SplitControl` interface and signal `startDone`
! when the sensor is ready for use, or delay `dataReady` events
! until the sensor is ready. The former choice is preferable.
! 3) `StdControl.stop`: put the sensor in a low-power mode.
! `StdControl.start` must be called before any further readings
! are taken. The behaviour of calls to `StdControl.stop` during
! sampling (i.e., when an `dataReady` event is going to be
! signaled) is undefined.
! `.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`
! - @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.
! Example: mts3x0
====================================================================
! The mica sensor board (mts300/mts310) has five sensors (and one actuator,
! the sounder) -- the accelerometer and magnetometer are only present on
! the mts310:
! +------------------------------------------------------------------+
! | Name | Component | Sensor Interfaces | Other Interfaces |
! +===============+===========+===================+==================+
! | Accelerometer | AccelC | AccelX | |
! | | | AccelY | |
! | Magnetometer | MagC | MagX | MagSetting |
! | | | MagY | |
! | Microphone | MicC | MicADC | Mic |
! | | | | MicInterrupt |
! | Light | PhotoC | PhotoADC | |
! | Temperature | TempC | TempADC | |
! +------------------------------------------------------------------+
! Each physical sensor is represented by a separate component. Specific
! sensors that have more than one axis of measurement (AccelC and MagC)
! provide more than one `AcquireData` interface on a single component. Some
! sensors, such as the magnetometer and microphone, have additional
! functionality provided through sensor-specific interfaces.
! Although light and temperature are represented by separate components, in
! reality they share a single microcontroller pin. The two components PhotoC
! and TempC sit on top of the PhotoTempP component, which controls access to
! the shared pin, and orchestrates which sensor is currently connected to
! it. From a programmer's perspective, they appear as individual sensors,
! even though their underlying implementation is a bit more complex.
! The board's mts3x0.h file contains private configuration data
! (pin usage, ADC ports, etc).
! The mica sensor board has an empty .sensor file.
! 6. Author's Address
====================================================================
--- 23,329 ----
====================================================================
! 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 may 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 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
! 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 optionally provide a
! component with a generic name for application authors who only care
! about the general class of the sensor.
! This document assumes that sensors return uninterpreted values of
! arbitrary size or datatype. Conversion of sensor values to something
! with actual physical meaning is beyond the scope of this document.
+ 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. This virtualization may be easier to accomplish
! by using one of the arbiters provided by the system.
! For example::
! generic configuration SensirionSht11C() {
! provides interface Read<uint16_t> as Temperature;
! provides interface ReadStream<uint16_t> as TemperatureStream;
! provides interface Read<uint16_t> as Humidity;
! provides interface ReadStream<uint16_t> as HumidityStream;
! }
! 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. 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>;
! }
! 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
! 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 may look like this::
! generic configuration TemperatureC() {
! provides interface Read<uint16_t>;
! provides interface ReadStream<uint16_t>;
! }
! implementation {
! components new SensirionSht11C();
! Read = SensirionSht11C.Temperature;
! ReadStream = SensirionSht11C.TemperatureStream;
! }
! generic configuration HumidityC() {
! provides interface Read<uint16_t>;
! provides interface ReadStream<uint16_t>;
! }
! implementation {
! components new SensirionSht11C();
! Read = SensirionSht11C.Humidity;
! ReadStream = SensirionSht11C.HumidityStream;
! }
! 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.
! - Any other interfaces needed to control the device.
! 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 HPL Components
====================================================================
! A sensor HPL is necessarily platform-dependent or
! sensorboard-dependent. These components should provide access to the
! physical resources needed by the sensor, in a platform-independent
! manner that can be used by the shared logic of the sensor HAL
! components. In the case of bus-based sensors, this HPL may be nothing
! more than wiring to the appropriate bus interface for use by the HAL
! component.
! For example::
! configuration HplSensirionSht11C {
! provides interface Init;
! provides interface Resource[ uint8_t id ];
! provides interface GeneralIO as DATA;
! provides interface GeneralIO as SCK;
! provides interface GpioInterrupt as InterruptDATA;
! }
! implementation {
! // connect to platform or sensorboard-dependent resources
! // power-manage the sensor through platform-specific means
! }
! 5. Directory Organization Guidelines
! ====================================================================
! 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.
! 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
! should 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 may be placed anywhere as long as the nesC compiler
! receives enough `-I` directives to locate all of the necessary pieces.
!
! 6. Authors' Addresses
====================================================================
***************
*** 281,286 ****
|
| Wei Hong
! | Arched Rock
! | Berkeley, CA 94704
|
| email - wei.hong at gmail.com
--- 338,344 ----
|
| Wei Hong
! | Arch Rock
! | 657 Mission St. Suite 600
! | San Francisco, CA 94105
|
| email - wei.hong at gmail.com
***************
*** 302,305 ****
--- 360,376 ----
|
| email - polastre at cs.berkeley.edu
+ |
+ | Gilman Tolle
+ | Arch Rock
+ | 657 Mission St. Suite 600
+ | San Francisco, CA 94105
+ |
+ | email - gtolle at archrock.com
+
+ 7. Citations
+ ====================================================================
+ .. [TEP2] TEP 2: Hardware Abstraction Architecture
+ .. [TEP114] TEP 114: SIDs: Source and Sink Indepedent Drivers
+ .. [TEP115] TEP 115: Power Management of Non-Virtualized Devices
Index: tep114.txt
===================================================================
RCS file: /cvsroot/tinyos/tinyos-2.x/doc/txt/tep114.txt,v
retrieving revision 1.2
retrieving revision 1.3
diff -C2 -d -r1.2 -r1.3
*** tep114.txt 12 Jul 2006 16:59:42 -0000 1.2
--- tep114.txt 8 Sep 2006 23:10:41 -0000 1.3
***************
*** 191,218 ****
accelerometer.
- 3.3 Metadata and Shifting
- --------------------------------------------------------------------
-
- Generally, simple types are made up of octets. However, sensor values
- often have levels of precision besides a multiple of 8. Any value
- contained in a simple type MUST 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 12-bit value MUST be shifted left so that its range is 0x0000
- - 0xfff0, rather than 0x0000 - 0x0fff. 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.
-
3.4 Single-Phase Scalar I/O
--------------------------------------------------------------------
--- 191,194 ----
More information about the Tinyos-2-commits
mailing list