tep101.txt

tinyos-2.x.rar

5. HIL guidelines
====================================================================

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
the ``AdcReadClientC`` and ``AdcReadStreamClientC``). The first task is solved
with the help of the ``AdcConfigure`` interface which is used by the HIL
implementation to retrieve a client's ADC configuration.  The second task MAY
be performed by the following library components: ``ArbitratedReadC``, and
``ArbitratedReadStreamC`` (in tinyos-2.x/tos/system) - please refer to the
Atmel Atmega 128 HAL 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 HIL implementation does not have
to perform the ADC resource reservation for an ``AdcReadNowClientC``, but may
simply forward an instance of the ``Resource`` interface from the HAL to the
``AdcReadNowClientC``.

The typical sequence of events is as follows: when a client requests data
through the ``Read`` or ``ReadStream`` interface the HIL will request access to
the HAL using the ``Resource`` interface.  After the HIL has been granted
access, it will "pull" the client's ADC configuration using the
``AdcConfigure`` interface and translate the client's ``Read`` or
``ReadStream`` command to a chip-specific HAL command. Once the HIL is
signalled the conversion result(s) from the HAL it releases the ADC through the
``Resource`` interface and signals the conversion result(s) to the client
though the ``Read`` or ``ReadStream`` interface.  When a client requests data
through the ``ReadNow`` interface the HIL translates the client's command to
the chip-specific HAL command without using the ``Resource`` interface (it may
check ownership of the client through the ``ArbiterInfo`` interface - this
check can also be done in the HAL implementation). Once the HIL is signalled
the conversion result(s) it forwards it to the respective ``ReadNow`` client.

6. Implementation
====================================================================

TestAdc application
--------------------------------------------------------------------

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.


HAA on the MSP430 and Atmega 128
--------------------------------------------------------------------

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 HAL implementation
  * ``AdcP.nc`` is the HIL implementation
  * ``AdcReadClientC.nc``, ``AdcReadNowClientC.nc`` and
    ``AdcReadStreamClientC.nc`` provide virtualized access to the HIL
  * the use of DMA or the reference voltage generator and the
    HAL virtualization components are explained in ``README.txt``

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 HAL implementation
  * ``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
  * ``AdcReadClientC.nc``, ``AdcReadNowClientC.nc`` and
    ``AdcReadStreamClientC.nc`` provide virtualized access to the HIL


Appendix A: Hardware differences between platforms
====================================================================

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

+----------------------+----------------------+---------------------+
|                      | Atmel Atmega 128     | TI MSP430 ADC12     |
+======================+======================+=====================+
|Resolution            | 10-bit               | 12-bit              |
+----------------------+----------------------+---------------------+
|channels              |- 8 multiplexed       |- 8 individually     |
|                      |  external channels   |  configurable       |
|                      |- 16 differential     |  external channels  |
|                      |  voltage input       |- internal channels  |
|                      |  combinations        |  (AVcc, temperature,|
|                      |- 2 differential      |  reference voltages)|
|                      |  inputs with gain    |                     |
|                      |  amplification       |                     |
+----------------------+----------------------+---------------------+
|internal reference    | 2.56V                | 1.5V or 2.5V        |
|voltage               |                      |                     |
+----------------------+----------------------+---------------------+
|conversion reference  |- positive terminal:  | individually        |
|                      |  AVcc or 2.56V  or   | selectable per      |
|                      |  AREF (external)     | channel:            |
|                      |- negative terminal:  |                     |
|                      |  GND                 |- AVcc and AVss      |
|                      |                      |- Vref+ and AVss     |
|                      |                      |- Veref+ and AVss    |
|                      |                      |- AVcc and (Vref- or |
|                      |                      |  Veref-)            |
|                      |                      |- AVref+ and (Vref-  |
|                      |                      |  or Veref-)         |
|                      |                      |- Veref+ and (Vref-  |
|                      |                      |  or Veref-)         |
+----------------------+----------------------+---------------------+
|conversion modes      |- single channel      |- single conversion  |
|                      |  conversion mode     |  mode               |
|                      |- free running mode   |- repeat single      |
|                      |  (channels and       |  conversion mode    |
|                      |  reference voltages  |- sequence mode      |
|                      |  can be switched     |  (sequence <= 16    |
|                      |  between samples)    |  channels)          |
|                      |                      |- repeat sequence    |
|                      |                      |  mode               |
+----------------------+----------------------+---------------------+
|conversion clock      |clkADC with prescaler |ACLK, MCLK, SMCLK or |
|source                |                      |ADC-oscillator (5MHz)|
|                      |                      |with prescaler       |
|                      |                      |respectively         |
+----------------------+----------------------+---------------------+
|sample-hold-time      |1.5 clock cycles      |selectable values    |
|                      |(fixed)               |from 4 to 1024 clock |
|                      |                      |cycles               |
+----------------------+----------------------+---------------------+
|conversion triggering |by software           |by software or timers|
+----------------------+----------------------+---------------------+
|conversion during     |yes                   |yes                  |
|sleep mode possible   |                      |                     |
+----------------------+----------------------+---------------------+
|interrupts            |after each conversion |after single or      |
|                      |                      |sequence conversion  |
+----------------------+----------------------+---------------------+


Appendix B: a HAL representation: 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
("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. 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 
  { 
    provides {
      interface Resource[uint8_t id]; 
      interface Msp430Adc12SingleChannel as SingleChannel[uint8_t id]; 
      interface AsyncStdControl as DMAExtension[uint8_t id];
    }
  }

  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); 
  }

  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_id: 2;      // clock divider sampcon signal
  } msp430adc12_channel_config_t;


Appendix C: a HIL representation: MSP430 ADC12
====================================================================

The signature of the AdcReadClientC component for the MSP430 ADC12 is as
follows::

  generic configuration AdcReadClientC() {
    provides interface Read<uint16_t>;
    uses interface AdcConfigure<const msp430adc12_channel_config_t*>;
  }

.. [TEP1] TEP 1: TEP Structure and Keywords. 
.. [TEP2] TEP 2: Hardware Abstraction Architecture. 
.. [TEP108] TEP 108: Resource Arbitration. 
.. [TEP109] TEP 109: Sensor Boards. 
.. [TEP114] TEP 114: SIDs: Source and Sink Independent Drivers.