Abstract

This TEP proposes a hardware abstraction for TinyOS 2.x analog-to-digital converters (ADCs). It focuses on aligning the ADC abstraction with the three-layer Hardware Abstraction Architecture (HAA) described in [TEP2], but addresses only the HPL and HAL, because the highest level abstraction of an ADC is platform-dependent.

1. Introduction

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 TinyOS, the distinction between a sensor and an ADC were blurred: this led components that had nothing to do with an ADC to still resemble one programatically, even though the semantics and forms of operation were completely different. To compensate for the difference non-ADC sensors introduced additional interfaces, such as ADCError, that were tightly bound to sensor acquisition but separate in wiring. The separation between the ADC and ADCError interface is bug prone and problematic, as is the equation of a sensor and an ADC. TinyOS 2.x separates the structure and interfaces of an ADC from those of sensors (which may be on top of an ADC, but this fact is hidden from higher level components). This TEP presents how TinyOS 2.x decomposes and structures ADC software. TEP 109 (Sensor Boards) shows how a platform can present actual named sensors [TEP109].

As can be seen in Appendix A the ADC hardware used on TinyOS platforms differ in many respects, which makes it difficult to find a chip independent representation for an ADC. Even if there were such a representation, the configuration details of an ADC would still depend on the actual device producing the input signal (sensor). Neither a platform independent application nor the ADC hardware stack itself has access to this information, as it can only be determined on a platform or sensorboard level. For example, determining which ADC port a sensor is attached to and how a conversion result is to be interpreted is a platform-specific determination.

In spite of their hardware differences, one aspect represents a common denominator of all ADCs: they produce conversion results. In order to facilitate sensor software development this capability can be made available via chip-independent interfaces for every ADC. However, conversion results depend on and have to be interpreted with respect to the platform-specific configuration settings (the ADC channel, the applied reference voltage, etc.). Therefore the highest level of ADC abstraction consists of platform-independent interfaces for ADC data collection and chip-specific interfaces for ADC hardware configuration. The top layer of the ADC stack thus remains platform-dependent and consequently the ADC abstraction does not include an HIL, but ends with the HAL. Following the principles of the HAA [TEP2] the HAL of an ADC should also expose the chip-specific capabilities for ADC data collection. For example, the ADC12 on the MSP430 MCU supports a complex repeat conversion mode for a set of different input channels, which is too specific to be represented by a platform-independent data collection interface. Therefore the HAL of an ADC abstraction is broken into two sublayers: The bottom HAL layer, called HAL1, exposes the full capabilities of the respective ADC in a chip-specific way. It realizes the standard HAL in the HAA [TEP2] and the HPL lies below it. On top of the HAL1 sits the HAL2 which maps the interfaces it uses from HAL1 to a set of platform-independent interfaces for data collection and chip-specific configuration interfaces.

The rest of this TEP specifies:

• 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 implementation for the TI MSP430 MCU.

2. Interfaces

This TEP proposes to adopt the following three generic, source-independent data collection interfaces from [TEP114] for the collection of ADC conversion results:

interface Read< size_type >
interface ReadNow< size_type >
interface ReadStream< size_type >

Every data collection interface is associated with certain chip-specific configuration data (e.g. input channel, sample-hold-time, etc.). How this association can be realized is explained in Section 4. HAL2 requirements. As the resolution of conversion results is chip-specific, the 'size_type' parameter reflects an upper bound for the chip-specific resolution of the conversion results - the actual resolution may be smaller, depending on the ADC and/or data source (e.g. uint16_t for a 12-bit ADC). The above interfaces are specified in [TEP114], in the following their usage is explained with respect to ADCs.

3. HAL1 guidelines

As explained in 1. Introduction the HAL of an ADC abstraction consists of two sublayers, HAL1 and HAL2. In the ADC component stack the HAL1 resides below HAL2 and above the HPL. It exposes the full capabilities of the ADC in a chip-specific way and has the same function as the 'traditional' HAL in the 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.

4. HAL2 requirements

The following components MUST be provided on all platforms that have an ADC:

AdcReadClient
AdcReadNowClient
AdcReadStreamClient

These generic components are instantiated and provide access to the ADC on a per-client basis via a platform-independent interface for data collection and a chip-specific ADC configuration interface. This section describes the representation of the HAL2. Guidelines on how the HAL2 can be implemented are discussed in Section 5. HAL2 implementation guidelines. Appendix C shows the AdcReadClient for the TI MSP430 MCU.

The fact that the components use chip-specific ADC configuration interfaces (see below) and the fact that the provided interfaces for data-collection must be interpreted with respect to the configuration data - for example the reference voltage - makes the HAL2 representation chip dependent. Therefore the ADC abstraction does not include an HIL.

generic configuration AdcReadClient() {
  provides {
    interface Read< size_type >;
  }
  uses {
    // chip-dependent configuration interface
  }
}

generic configuration AdcReadNowClient() {
  provides {
    interface Resource;
    interface ReadNow< size_type >;
  }
  uses {
     // chip-dependent configuration interface
  }
}

generic configuration AdcReadStreamClient() {
  provides {
    interface ReadStream< size_type >;
  }
  uses {
     // chip-dependent configuration interface
  }
}

5. HAL2 implementation guidelines

The HAL2 implementation of an ADC stack has two main tasks: It translates a platform-independent HAL2 request (from the 'Read', 'ReadNow' or 'ReadStream' interface) to a chip-specific HAL1 sampling command and it abstracts from the 'Resource' interface. The first task cannot be solved in a chip-independent way, because it involves chip-specific configuration data. The second task MAY be performed by the following library components: ArbitratedReadC, and ArbitratedReadStreamC (in tinyos-2.x/tos/system) - refer to the Atmel Atmega 128 HAL2 implementation (in tinyos-2.x/tos/chips/atm128/adc), for an example. Note that since the 'ReadNow' interface is always provided in conjunction with a 'Resource' interface the HAL2 implementation does not have to perform the ADC resource reservation in this case, but can simply forward an instance of the 'Resource' interface from the HAL1 (to AdcReadNowClient).

To support multiple ADC clients the HAL2 implementation should provide parameterized 'Read', 'ReadNow' and 'ReadStream' interfaces as well as a parameterized chip-specific configuration interface. It should also use an instance of the 'Resource' interface (provided by the HAL1) per provided 'Read' and 'ReadStream' interface to perform automatic resource reservation. The HAL2 representation ('AdcReadClient', 'AdcReadNowClient' and 'AdcReadStreamClient') should ensure the correct wiring between the HAL1 and HAL2.

From the perspective of the HAL2 the typical sequence of events is as follows: After a client has requested data via the 'Read' or 'ReadStream' interface the HAL2 will request access to the HAL1 via the 'Resource' interface, e.g. using the library components mentioned above. When it is signalled the 'granted' event, the HAL2 will 'pull' the client's ADC settings and translate the client's command to a chip-specific HAL1 sampling command. Once it is signalled the conversion result(s) it releases the ADC via the 'Resource' interface and forwards the conversion result(s) to the client. When a client has requested data via the 'ReadNow' interface the HAL2 translates the client's command to the chip-specific HAL1 sampling command without using the 'Resource' interface (it may check ownership of the client via the 'ArbiterInfo' interface). In order to reduce state in the HAL2 and facilitate the mapping between used and provided interfaces the 'AdcReadClient', 'AdcReadNowClient' and 'AdcReadStreamClient' should use the same interface identifier when it connects the HAL2 to HAL1 (see, for example, the MSP430 ADC12 implementation in Appendix C).

6. Implementation

The implementation of the ADC12 stack on the MSP430 can be found in tinyos-2.x/tos/chips/msp430/adc12:

• HplAdc12P.nc is the HPL implementation
• Msp430Adc12P.nc is the HAL1 implementation
• AdcC.nc is the HAL2 implementation
• AdcReadClientC.nc, AdcReadNowClientC.nc and AdcReadStreamClientC.nc provide access to the ADC on a per-client basis via the interfaces 'Read', 'ReadNow' and 'ReadStream', respectively, and the msp430-specific ADC configuration interface Msp430Adc12Config.nc

The Atmel Atmega 128 ADC implementation can be found in tinyos-2.x/tos/chips/atm128/adc:

• HplAtm128AdcC.nc is the HPL implementation
• Atm128AdcP.nc is the HAL1 implementation
• WireAdcP.nc and the library components for arbitrating 'Read', 'ReadNow' and 'ReadStream', ArbitratedReadC and ArbitratedReadStreamC (in tinyos-2.x/tos/system), realize the HAL2
• AdcReadClientC.nc, AdcReadNowClientC.nc and AdcReadStreamClientC.nc provide access to the ADC on a per-client basis via the platform-independent interfaces 'Read', 'ReadNow' and 'ReadStream', respectively, and the atmega-specific ADC configuration interface Atm128AdcConfig.nc

Appendix A: Hardware differences between platforms

The following table compares the characteristics of two microcontrollers commonly used in TinyOS platforms:

Appendix B: an HAL1 representation: MSP430 ADC12

The following shows the HAL1 representation 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 ("Repeat-single-channel"), multiple times ("Sequence-of-channels") or multiple times repeatedly ("Repeat-sequence-of-channels"). In contrast to the single channel conversion modes the sequence conversion modes trigger a single interrupt after multiple samples and thus enable high-frequency sampling (a sequence conversion mode for multiple different channels is not (yet) implemented).:

configuration Msp430Adc12C
{
  provides interface Resource[uint8_t id];
  provides interface Msp430Adc12SingleChannel as SingleChannel[uint8_t id];
}

interface Msp430Adc12SingleChannel
{
  async command error_t getSingleData(const msp430adc12_channel_config_t *config);
  async command error_t getSingleDataRepeat(const msp430adc12_channel_config_t *config,
    uint16_t jiffies);
  async command error_t getMultipleData( const msp430adc12_channel_config_t *config,
    uint16_t *buffer, uint16_t numSamples, uint16_t jiffies);
  async command error_t getMultipleDataRepeat(const msp430adc12_channel_config_t *config,
    uint16_t *buffer, uint8_t numSamples, uint16_t jiffies);
  async event error_t singleDataReady(uint16_t data);
  async event uint16_t* multipleDataReady(uint16_t *buffer, uint16_t
    numSamples);
}

There exist two wrapper components, Msp430Adc12ClientC and Msp430Adc12RefVoltAutoClientC, which SHOULD be used to eliminate wiring errors.

Appendix C: an HAL2 representation: MSP430 ADC12

The AdcReadClientC component for the MSP430 ADC12 is implemented as follows:

generic configuration AdcReadClientC() {
  provides interface Read<uint16_t>;
  uses interface Msp430Adc12Config;
} implementation {
  components AdcC;
#ifdef REF_VOLT_AUTO_CONFIGURE
  components new Msp430Adc12RefVoltAutoClientC() as Msp430AdcClient;
#else
  components new Msp430Adc12ClientC() as Msp430AdcClient;
#endif

  enum {
    CLIENT = unique(ADCC_SERVICE),
  };

  Read = AdcC.Read[CLIENT];
  Msp430Adc12Config = AdcC.Config[CLIENT];
  AdcC.SingleChannel[CLIENT] -> Msp430AdcClient.Msp430Adc12SingleChannel;
  AdcC.Resource[CLIENT] -> Msp430AdcClient.Resource;
#ifdef REF_VOLT_AUTO_CONFIGURE
  Msp430Adc12Config = Msp430AdcClient.Msp430Adc12Config;
#endif
}

Note that the same CLIENT identifier is used for all involved interfaces to facilitate the mapping between the HAL2 and HAL1 interfaces. The conditional compile directive REF_VOLT_AUTO_CONFIGURE can be used to automatically enable the internal reference voltage generator during the sampling process.