Update of the default CC2420 to the low power listening stack. The "acknowledgement...

[tinyos-2.x.git] / tos / interfaces / LowPowerListening.nc

diff --git a/tos/interfaces/LowPowerListening.nc b/tos/interfaces/LowPowerListening.nc
new file mode 100644 (file)
index 0000000..0326907
--- /dev/null
+++ b/tos/interfaces/LowPowerListening.nc
@@ -0,0 +1,130 @@
+/*
+ * Copyright (c) 2005-2006 Rincon Research Corporation
+ * All rights reserved.
+ *
+ * Redistribution and use in source and binary forms, with or without
+ * modification, are permitted provided that the following conditions
+ * are met:
+ * - Redistributions of source code must retain the above copyright
+ *   notice, this list of conditions and the following disclaimer.
+ * - Redistributions in binary form must reproduce the above copyright
+ *   notice, this list of conditions and the following disclaimer in the
+ *   documentation and/or other materials provided with the
+ *   distribution.
+ * - Neither the name of the Rincon Research Corporation nor the names of
+ *   its contributors may be used to endorse or promote products derived
+ *   from this software without specific prior written permission.
+ *
+ * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS
+ * ``AS IS'' AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT
+ * LIMITED TO, THE IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS
+ * FOR A PARTICULAR PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL THE
+ * RINCON RESEARCH OR ITS CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT,
+ * INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES
+ * (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
+ * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
+ * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT,
+ * STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
+ * ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED
+ * OF THE POSSIBILITY OF SUCH DAMAGE
+ */
+ 
+/**
+ * Low Power Listening interface
+ *
+ * @author Jonathan Hui
+ * @author David Moss
+ */
+ 
+#include "message.h"
+ 
+interface LowPowerListening {
+
+  /**
+   * Set this this node's radio sleep interval, in milliseconds.
+   * Once every interval, the node will sleep and perform an Rx check 
+   * on the radio.  Setting the sleep interval to 0 will keep the radio
+   * always on.
+   *
+   * This is the equivalent of setting the local duty cycle rate.
+   *
+   * @param sleepIntervalMs the length of this node's Rx check interval, in [ms]
+   */
+  command void setLocalSleepInterval(uint16_t sleepIntervalMs);
+  
+  /**
+   * @return the local node's sleep interval, in [ms]
+   */
+  command uint16_t getLocalSleepInterval();
+  
+  /**
+   * Set this node's radio duty cycle rate, in units of [percentage*100].
+   * For example, to get a 0.05% duty cycle,
+   * <code>
+   *   call LowPowerListening.setDutyCycle(5);
+   * </code>
+   *
+   * For a 100% duty cycle (always on),
+   * <code>
+   *   call LowPowerListening.setDutyCycle(10000);
+   * </code>
+   *
+   * This is the equivalent of setting the local sleep interval explicitly.
+   * 
+   * @param dutyCycle The duty cycle percentage, in units of [percentage*100]
+   */
+  command void setLocalDutyCycle(uint16_t dutyCycle);
+  
+  /**
+   * @return this node's radio duty cycle rate, in units of [percentage*100]
+   */
+  command uint16_t getLocalDutyCycle();
+  
+  
+  /**
+   * Configure this outgoing message so it can be transmitted to a neighbor mote
+   * with the specified Rx sleep interval.
+   * @param msg Pointer to the message that will be sent
+   * @param sleepInterval The receiving node's sleep interval, in [ms]
+   */
+  command void setRxSleepInterval(message_t *msg, uint16_t sleepIntervalMs);
+  
+  /**
+   * @return the destination node's sleep interval configured in this message
+   */
+  command uint16_t getRxSleepInterval(message_t *msg);
+  
+  /**
+   * Configure this outgoing message so it can be transmitted to a neighbor mote
+   * with the specified Rx duty cycle rate.
+   * Duty cycle is in units of [percentage*100], i.e. 0.25% duty cycle = 25.
+   * 
+   * @param msg Pointer to the message that will be sent
+   * @param dutyCycle The duty cycle of the receiving mote, in units of 
+   *     [percentage*100]
+   */
+  command void setRxDutyCycle(message_t *msg, uint16_t dutyCycle);
+  
+  /**
+   * @return the destination node's duty cycle configured in this message
+   *     in units of [percentage*100]
+   */
+  command uint16_t getRxDutyCycle(message_t *msg);
+  
+  /**
+   * Convert a duty cycle, in units of [percentage*100], to
+   * the sleep interval of the mote in milliseconds
+   * @param dutyCycle The duty cycle in units of [percentage*100]
+   * @return The equivalent sleep interval, in units of [ms]
+   */
+  command uint16_t dutyCycleToSleepInterval(uint16_t dutyCycle);
+  
+  /**
+   * Convert a sleep interval, in units of [ms], to a duty cycle
+   * in units of [percentage*100]
+   * @param sleepInterval The sleep interval in units of [ms]
+   * @return The duty cycle in units of [percentage*100]
+   */
+  command uint16_t sleepIntervalToDutyCycle(uint16_t sleepInterval);
+  
+}