added ack, received packet strength, LPL (compile with PFLAGS +=-DLOW_POWER_LISTENING)

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

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