X-Git-Url: https://oss.titaniummirror.com/gitweb/?a=blobdiff_plain;f=tos%2Fchips%2Fcc1000%2FLowPowerListening.nc;h=6fd5d19db2fa0b6c732b52791820e29365cc8520;hb=adf1de6c009d13b7b52e68535c63b28f59c97400;hp=600ebb6821b0e823240be20325be43ab81a7ebe4;hpb=1ba974b83d19fc41bf80acd52726f36f7f1df297;p=tinyos-2.x.git diff --git a/tos/chips/cc1000/LowPowerListening.nc b/tos/chips/cc1000/LowPowerListening.nc index 600ebb68..6fd5d19d 100644 --- a/tos/chips/cc1000/LowPowerListening.nc +++ b/tos/chips/cc1000/LowPowerListening.nc @@ -1,109 +1,131 @@ -/* 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 + +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, + * + * call LowPowerListening.setDutyCycle(5); // or equivalently... + * call LowPowerListening.setDutyCycle(00005); // for better readability? + * + * + * For a 100% duty cycle (always on), + * + * call LowPowerListening.setDutyCycle(10000); + * * - * @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); + }