| Jan-Hinrich Hauer, Philip Levis, Vlado Handziski, David Gay |
Note
This memo documents a part of TinyOS for the TinyOS Community, and @@ -310,15 +310,15 @@ requests discussion and suggestions for improvements. Distribution of this memo is unlimited. This memo is in full compliance with [TEP1].
This TEP proposes a hardware abstraction for analog-to-digital converters (ADCs) in TinyOS 2.x, which is aligned to the three-layer Hardware Abstraction Architecture (HAA) specified in [TEP2]. It describes some design principles and documents the set of hardware-independent interfaces to an ADC.
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
@@ -421,31 +421,31 @@ provides access to the hardware registers (see
This TEP ends with appendices documenting, as an example, the ADC implementation
for the TI MSP430 MCU.
This TEP proposes the AdcConfigure interface for ADC hardware configuration and the Read, ReadStream and ReadNow interfaces to acquire conversion results. The Read and ReadStream interfaces are documented in [TEP114] and the ReadNow interface is documented in this TEP. A Read[Now|Stream] interface is always provided in conjunction with a AdcConfigure interface.
-The AdcConfigure interface is defined as follows:
-interface AdcConfigure< config_type >
+interface AdcConfigure< config_type >
{
- async command config_type getConfiguration();
+ async command config_type getConfiguration();
}
This interface is used by the ADC stack to retrieve the hardware configuration @@ -468,8 +468,8 @@ The rationale is that the ADC HIL implementation does not have to store an ADC configuration per client - instead the ADC client can, for example, store its configuration in program memory.
This TEP proposes to adopt the following two source-independent data collection interfaces from [TEP114] for the collection of ADC conversion results on the level of HIL:
@@ -488,24 +488,24 @@ requirements). As the resolution of conversion results is chip-specific, th size_type parameter reflects an upper bound for the chip-specific resolution of the conversion results - the actual resolution may be smaller (e.g. uint16_t for a 12-bit ADC). -The Read interface can be used to sample an ADC channel once and return a single conversion result as an uninterpreted value. The Read interface is documented in [TEP114].
The ReadStream interface can be used to sample an ADC channel multiple times with a specified sampling period. The ReadStream interface is documented in [TEP114] .
As explained in 1. Introduction the HAL exposes the full capabilities of the ADC hardware. Therefore only chip- and platform-dependent clients can wire to the HAL. Although the HAL is chip-specific, both, in terms of implementation and representation, its design should follow the guidelines described in this section to facilitate the mapping to the HIL representation. Appendix B shows the signature of the HAL for the MSP430.
-As the ADC hardware is a shared resource that is usually multiplexed between several clients some form of access arbitration is necessary. The HAL should therefore provide a parameterized Resource interface, instantiate a @@ -543,8 +543,8 @@ arbiter as described in Resource interface are the topic of [TEP108].
As the ADC hardware is a shared resource the HAL should support hardware configuration and sampling per client (although per-port configuration is possible, it is not recommended, because it forces all clients to use the same @@ -566,8 +566,8 @@ configuration data is passed as a pointer, the HAL component MUST NOT reference it after the return of the respective command. Appendix B shows the HAL interfaces for the MSP430.
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 HAL. Such components can also be used to ensure that a sampling interface is always @@ -575,14 +575,14 @@ provided with a Resource
The following generic components MUST be provided on all platforms that have an ADC:
-AdcReadClientC -AdcReadNowClientC -AdcReadStreamClientC +AdcReadClientC +AdcReadNowClientC +AdcReadStreamClientC
These components provide virtualized access to the HIL of an ADC. They are instantiated by an ADC client and provide/use the four interfaces described in @@ -592,8 +592,8 @@ TEP does not address the issue of how to deal with multiple ADCs on the same platform (the question of how to deal with multiple devices of the same class is a general one in TinyOS 2.x). Appendix C shows the AdcReadClientC for the MSP430.
-
generic configuration AdcReadClientC() {
provides {
@@ -615,8 +615,8 @@ command. Note that both, size_ty
placeholders and will be instantiated by the respective HIL implementation (for
an example, see the AdcReadClientC for the MSP430 in Appendix C).
generic configuration AdcReadNowClientC() {
provides {
@@ -647,8 +647,8 @@ to dynamically "pull" the client's ADC settings when it translates the
instantiated by the respective HIL implementation (for an example how this is
done for the AdcReadClientC see Appendix C).
generic configuration AdcReadStreamClientC() {
provides {
@@ -668,8 +668,8 @@ will be instantiated by the respective HIL implementation (for an example how
this is done for the AdcReadClientC see Appendix C).
The HIL implementation of an ADC stack has two main tasks: it translates a Read, ReadNow or ReadStream request to a chip-specific HAL sampling command and it abstracts from the Resource interface (the latter only for @@ -699,18 +699,18 @@ check ownership of the client through the ReadNow client.
An ADC HIL test application can be found in tinyos-2.x/apps/tests/TestAdc. Note that this application instantiates generic DemoSensorC, DemoSensorStreamC and DemoSensorNowC components (see [TEP114]) and assumes that these components are actually wired to an ADC HIL. Please refer to tinyos-2.x/apps/tests/TestAdc/README.txt for more information.
The implementation of the ADC12 stack on the MSP430 can be found in tinyos-2.x/tos/chips/msp430/adc12:
@@ -730,7 +730,7 @@ HAL virtualization components are explained inHplAtm128AdcC.nc is the HPL implementation Atm128AdcP.nc is the HAL implementation -AdcP.nc, WireAdcP.nc and the library components for arbitrating + AdcP.nc, WireAdcP.nc and the library components for arbitrating 'Read', 'ReadNow' and 'ReadStream', ArbitratedReadC and ArbitratedReadStreamC (in tinyos-2.x/tos/system), realize the HIL @@ -740,8 +740,8 @@ the HIL
The following table compares the characteristics of two microcontrollers commonly used in TinyOS platforms:
| - | Atmel Atmega 128 | -TI MSP430 ADC12 | +
|---|---|---|
| + | Atmel Atmega 128 | +TI MSP430 ADC12 |
This section shows the HAL signature for the ADC12 of the TI MSP430 MCU. It reflects the four MSP430 ADC12 conversion modes as it lets a client sample an ADC channel once ("Single-channel-single-conversion") or repeatedly @@ -882,41 +882,41 @@ interrupt after multiple samples and thus enable high-frequency sampling. The DMAExtension interface is used to reset the state machine when the DMA is responsible for data transfer (managed in an exterior component):
-configuration Msp430Adc12P
-{
+configuration Msp430Adc12P
+{
provides {
- interface Resource[uint8_t id];
- interface Msp430Adc12SingleChannel as SingleChannel[uint8_t id];
+ interface Resource[uint8_t id];
+ interface Msp430Adc12SingleChannel as SingleChannel[uint8_t id];
interface AsyncStdControl as DMAExtension[uint8_t id];
}
}
-interface Msp430Adc12SingleChannel
-{
+interface Msp430Adc12SingleChannel
+{
async command error_t configureSingle(const msp430adc12_channel_config_t *config);
async command error_t configureSingleRepeat(const msp430adc12_channel_config_t *config, uint16_t jiffies);
async command error_t configureMultiple( const msp430adc12_channel_config_t *config, uint16_t buffer[], uint16_t numSamples, uint16_t jiffies);
async command error_t configureMultipleRepeat(const msp430adc12_channel_config_t *config, uint16_t buffer[], uint8_t numSamples, uint16_t jiffies);
async command error_t getData();
async event error_t singleDataReady(uint16_t data);
- async event uint16_t* multipleDataReady(uint16_t buffer[], uint16_t numSamples);
+ async event uint16_t* multipleDataReady(uint16_t buffer[], uint16_t numSamples);
}
-typedef struct
-{
- unsigned int inch: 4; // input channel
- unsigned int sref: 3; // reference voltage
- unsigned int ref2_5v: 1; // reference voltage level
- unsigned int adc12ssel: 2; // clock source sample-hold-time
- unsigned int adc12div: 3; // clock divider sample-hold-time
+typedef struct
+{
+ unsigned int inch: 4; // input channel
+ unsigned int sref: 3; // reference voltage
+ unsigned int ref2_5v: 1; // reference voltage level
+ unsigned int adc12ssel: 2; // clock source sample-hold-time
+ unsigned int adc12div: 3; // clock divider sample-hold-time
unsigned int sht: 4; // sample-hold-time
- unsigned int sampcon_ssel: 2; // clock source sampcon signal
+ unsigned int sampcon_ssel: 2; // clock source sampcon signal
unsigned int sampcon_id: 2; // clock divider sampcon signal
} msp430adc12_channel_config_t;
The signature of the AdcReadClientC component for the MSP430 ADC12 is as follows: