Interface: moteiv.tos.platform.msp430.adc.RefVolt

interface RefVolt

Interface for the msp430 reference voltage generator. This interface treats the reference voltage generator like a semaphore: Components can request that they need the generator be switched on at a certain voltage level (1.5V or 2.5V). Once a level has been set (signalled by an event) these settings remain fixed until every component that has successfully requested these settings has released them. This implies that every component that called the get must call release after it is done.

Author::
Jan Hauer (hauer@tkn.tu-berlin.de)

Commands
command result_t get(RefVolt_t vref) This command is similar to the P operation on semaphores: If successful the reference voltage generator will be set to the settings in vref.
command RefVolt_t getState() State of reference voltage generator.
command result_t release() This command is similar to the V operation on semaphores: It turns the reference voltage generator off, if it is not needed by any other component that previously getd it.

Events
event void isStable(RefVolt_t vref) After this event has been signalled, reference voltage generator is stable at a new state.

Commands - Details

get

command result_t get(RefVolt_t vref)

This command is similar to the P operation on semaphores: If successful the reference voltage generator will be set to the settings in vref. These settings can not be changed, until release has been called, ie. any further call to get with different vref will fail.

Note that a SUCCESS as return value does NOT imply that vref is stable (the initial switching time is 17ms). However after a change of vref the event isStable will be signalled (only once).

Implementation-Example:

           ...
           if (call RefVolt.get(REFERENCE_2_5V) == SUCCESS){
             if (call RefVolt.getState() == REFERENCE_2_5V){
                continueWithStableVref();
                return;
             } else
                return; // we will get the event isStable
           } else {
           ... we failed ...
           }

         event void RefVolt.isStable(RefVolt_t vref){
           // maybe also check some global state if we are ready
           if (vref == REFERENCE_STABLE_2_5V) continueWithStableVref();
         }

         void continueWithStableVref(){ // remember to call RefVolt.release! }
 

Parameters:
REFERENCE_1_5V - set vref to 1.5 V. REFERENCE_2_5V set vref to 2.5 V.
Returns:
SUCCESS if command was accepted, use getState to find out if vref is stable. Always call release after you dont need vref anymore.
FAIL if reference voltage generator is already in use at a different voltage level or ADC is busy doing a conversion (during that time the reference voltage generator may not be switched on).

getState

command RefVolt_t getState()

State of reference voltage generator.

Returns:
REFERENCE_1_5V if vref is 1.5 V (stable)
REFERENCE_2_5V if vref is 2.5 V (stable)
UNSTABLE if reference voltage generator is off or vref is unstable.

release

command result_t release()

This command is similar to the V operation on semaphores: It turns the reference voltage generator off, if it is not needed by any other component that previously getd it. It will not be turned off immediately, but with a delay specified in RefVolt.h, to avoid 17 ms startup time if components frequenty need to use VREF.

(If there were n successful calls to get there must be n calls to release to actually switch the reference voltage generator off).

Returns:
FAIL if the semaphore-counter is 0 already
SUCCESS else

Events - Details

isStable

event void isStable(RefVolt_t vref)

After this event has been signalled, reference voltage generator is stable at a new state.

Parameters:
REFERENCE_1_5V - if vref is 1.5 V (stable)
REFERENCE_2_5V if vref is 2.5 V (stable)