-/* tab:4
- *
- *
- * "Copyright (c) 2000-2002 The Regents of the University of California.
+/*
+ * Copyright (c) 2005-2006 Rincon Research Corporation
* 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."
+ * 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 Arch Rock 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
+ * ARCHED ROCK 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 control interface
+ * Low Power Listening interface
*
- * @author Joe Polastre
+ * @author David Moss
+ * @author Jonathan Hui
*/
-interface LowPowerListening
-{
+
+#include <message.h>
+
+interface LowPowerListening {
+
/**
- * Set the current Low Power Listening mode.
- * Setting the LPL mode sets both the check interval and preamble length.
- * The listening mode can only be set while the radio is stopped.
+ * 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.
*
- * Modes include:
- * 0 = Radio fully on
- * 1 = 10ms check interval
- * 2 = 25ms check interval
- * 3 = 50ms check interval
- * 4 = 100ms check interval (recommended)
- * 5 = 200ms check interval
- * 6 = 400ms check interval
- * 7 = 800ms check interval
- * 8 = 1600ms check interval
+ * This is the equivalent of setting the local duty cycle rate.
*
- * @param mode the mode number
- * @return SUCCESS if the mode was successfully changed, FAIL otherwise
+ * @param sleepIntervalMs the length of this node's Rx check interval, in [ms]
*/
- async command error_t setListeningMode(uint8_t mode);
-
+ command void setLocalSleepInterval(uint16_t sleepIntervalMs);
+
/**
- * Get the current Low Power Listening mode
- * @return mode number (see SetListeningMode)
+ * @return the local node's sleep interval, in [ms]
*/
- async command uint8_t getListeningMode();
-
+ command uint16_t getLocalSleepInterval();
+
/**
- * Set the transmit mode. This allows for hybrid schemes where
- * the transmit mode is different than the receive mode.
- * Use SetListeningMode first, then change the mode with SetTransmitMode.
+ * 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); // or equivalently...
+ * call LowPowerListening.setDutyCycle(00005); // for better readability?
+ * </code>
+ *
+ * For a 100% duty cycle (always on),
+ * <code>
+ * call LowPowerListening.setDutyCycle(10000);
+ * </code>
*
- * @param mode mode number (see SetListeningMode)
- * @return SUCCESS if the mode was successfully changed, FAIL otherwise
+ * This is the equivalent of setting the local sleep interval explicitly.
+ *
+ * @param dutyCycle The duty cycle percentage, in units of [percentage*100]
*/
- async command error_t setTransmitMode(uint8_t mode);
-
+ command void setLocalDutyCycle(uint16_t dutyCycle);
+
/**
- * Get the current Low Power Listening transmit mode
- * @return mode number (see SetListeningMode)
+ * @return this node's radio duty cycle rate, in units of [percentage*100]
*/
- async command uint8_t getTransmitMode();
-
+ command uint16_t getLocalDutyCycle();
+
+
/**
- * Set the preamble length of outgoing packets. Note that this overrides
- * the value set by setListeningMode or setTransmitMode.
- *
- * @param bytes length of the preamble in bytes
- * @return SUCCESS if the preamble length was successfully changed, FAIL
- * otherwise
+ * Configure this outgoing message so it can be transmitted to a neighbor mote
+ * with the specified Rx sleep interval.
+ * @param 'message_t* ONE msg' Pointer to the message that will be sent
+ * @param sleepInterval The receiving node's sleep interval, in [ms]
*/
- async command error_t setPreambleLength(uint16_t bytes);
-
+ command void setRxSleepInterval(message_t *msg, uint16_t sleepIntervalMs);
+
/**
- * Get the preamble length of outgoing packets
- *
- * @return length of the preamble in bytes
+ * @return the destination node's sleep interval configured in this message
*/
- async command uint16_t getPreambleLength();
-
+ command uint16_t getRxSleepInterval(message_t *msg);
+
/**
- * Set the check interval (time between waking up and sampling
- * the radio for activity in low power listening). The sleep time
- * can only be changed if low-power-listening is enabled
- * (setListeningMode called with a non-zero value).
- *
- * @param ms check interval in milliseconds
- * @return SUCCESS if the check interval was successfully changed,
- * FAIL otherwise.
+ * 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]
*/
- async command error_t setCheckInterval(uint16_t ms);
-
+ command void setRxDutyCycle(message_t *msg, uint16_t dutyCycle);
+
/**
- * Get the check interval currently used by low power listening
- *
- * @return length of the check interval in milliseconds
+ * @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]
*/
- async command uint16_t getCheckInterval();
+ command uint16_t sleepIntervalToDutyCycle(uint16_t sleepInterval);
+
}
projects / tinyos-2.x.git / blobdiff