[Firebug-cvs] mts400/interfaces Sensor.nc,NONE,1.1

[<do...@us...>]

Update of /cvsroot/firebug/mts400/interfaces
In directory sc8-pr-cvs1:/tmp/cvs-serv26329

Added Files:
	Sensor.nc 
Log Message:
Please read through this file.  
This is how we should eventually handle writing the 
application.

--- NEW FILE: Sensor.nc ---
/* -*- Mode: C; c-basic-indent: 3; indent-tabs-mode: nil -*- */ 


/**
 * "Copyright (c) 2000-2002 The Regents of the University  of California.  
 * All rights reserved.
 *
 * Permission to use, copy, modify, and distribute this software and its
 * documentation for any purpose, without fee, and without written agreement is
 * hereby granted, provided that the above copyright notice, the following
 * two paragraphs and the author appear in all copies of this software.
 * 
 * IN NO EVENT SHALL THE UNIVERSITY OF CALIFORNIA BE LIABLE TO ANY PARTY FOR
 * DIRECT, INDIRECT, SPECIAL, INCIDENTAL, OR CONSEQUENTIAL DAMAGES ARISING OUT
 * OF THE USE OF THIS SOFTWARE AND ITS DOCUMENTATION, EVEN IF THE UNIVERSITY OF
 * CALIFORNIA HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
 * 
 * THE UNIVERSITY OF CALIFORNIA SPECIFICALLY DISCLAIMS ANY WARRANTIES,
 * INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY
 * AND FITNESS FOR A PARTICULAR PURPOSE.  THE SOFTWARE PROVIDED HEREUNDER IS
 * ON AN "AS IS" BASIS, AND THE UNIVERSITY OF CALIFORNIA HAS NO OBLIGATION TO
 * PROVIDE MAINTENANCE, SUPPORT, UPDATES, ENHANCEMENTS, OR MODIFICATIONS."
 *
 */

/** 
 * $Id: Sensor.nc,v 1.1 2003/11/18 22:42:49 doolin Exp $
 */

/**
 * A standard interface for Sensors driven by TinyOS 
 * programs.  Sensors come with a wide variety of 
 * capabilities, and this interface is designed to
 * allow the programmer to wire a sensor without
 * worrying about whether it needs UART, I2C, ADC
 * or whatever capabilities.
 * 
 * The interface reflects the mechanical operation 
 * of the sensor, thus powering on a sensor need not
 * result in immediate sampling. 
 *
 * @author David M. Doolin
 */

interface Sensor {

  /**
   * Turn on the power, but do not collect data.  If the 
   * sensor provides data given power, this command should 
   * set a state where that data is only fired back through 
   * dataReady when the user is ready for it.  Any system
   * bus, I/O state, whatever should be left in a consistent 
   * state.  Implementation should be idempotent.
   *
   * @return Whether powering on was successful.
   */
  command result_t powerOn();

    /** 
     * Notify components that the component has been started 
     * and is ready to receive other commands.  Implementation
     * should be idempotent.
     */
    event result_t powerOnDone();

  /**
   * Stop the component cleanly, without leaving
   * the system in an inconsistent state.
   *
   * @return Whether stopping was successful.
   */
  command result_t powerOff();

    /**
     * Notify components that the component has been stopped. 
     */

    event result_t powerOffDone();

    command result_t setSamplingInterval(uint16_t sampling_rate);
    command result_t getSamplingInterval(uint16_t sampling_rate);


    /** startSampling puts the sensor into a state such that 
     * the dataReady event will fire when data is ready to 
     * to be collected from the sensor.
     */
    command result_t startSampling();

    /** Stop the sensor from sampling.
     */
    command result_t stopSampling();

    /** This is for collecting a single sample from 
     * sensor.  It should leave whatever state the sensor is
     * in unchanged.  It should not be used in conjunction 
     * with startSampling().
     */
    command result_t sampleOnce();

    /** dataReady is where the main action is;
     * the entire system exists to support what
     * happens here.
     */
    event result_t dataReady();    

    /** Some sensors, for example the Leadtek 9546 sued on
     * the Crossbow MTS420CA, are programmable.  It isn't 
     * practicle to define one interface to handle 
     * programming for arbitrary sensors, but any of the 
     * sensors that can be programmed should have the 
     * capability to read from some sort of I/O, which 
     * an implementation of this command should encapsulate.
     */
    command result_t loadProgram(uint8_t * program);
}