radio.h

00001 /*
00002  * Copyright (c) 2005, Swedish Institute of Computer Science.
00003  * All rights reserved.
00004  *
00005  * Redistribution and use in source and binary forms, with or without
00006  * modification, are permitted provided that the following conditions
00007  * are met:
00008  * 1. Redistributions of source code must retain the above copyright
00009  *    notice, this list of conditions and the following disclaimer.
00010  * 2. Redistributions in binary form must reproduce the above copyright
00011  *    notice, this list of conditions and the following disclaimer in the
00012  *    documentation and/or other materials provided with the distribution.
00013  * 3. Neither the name of the Institute nor the names of its contributors
00014  *    may be used to endorse or promote products derived from this software
00015  *    without specific prior written permission.
00016  *
00017  * THIS SOFTWARE IS PROVIDED BY THE INSTITUTE AND CONTRIBUTORS ``AS IS'' AND
00018  * ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00019  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
00020  * ARE DISCLAIMED.  IN NO EVENT SHALL THE INSTITUTE OR CONTRIBUTORS BE LIABLE
00021  * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00022  * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS
00023  * OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION)
00024  * HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT
00025  * LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY
00026  * OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF
00027  * SUCH DAMAGE.
00028  *
00029  * This file is part of the Contiki operating system.
00030  *
00031  */
00032 
00033 /**
00034  * \file
00035  *         Header file for the radio API
00036  * \author
00037  *         Adam Dunkels <adam@sics.se>
00038  *         Joakim Eriksson <joakime@sics.se>
00039  *         Niclas Finne <nfi@sics.se>
00040  *         Nicolas Tsiftes <nvt@sics.se>
00041  */
00042 
00043 /**
00044  * \addtogroup dev
00045  * @{
00046  */
00047 
00048 /**
00049  * \defgroup radio Radio API
00050  *
00051  * The radio API module defines a set of functions that a radio device
00052  * driver must implement.
00053  *
00054  * @{
00055  */
00056 
00057 #ifndef RADIO_H_
00058 #define RADIO_H_
00059 
00060 #include <stddef.h>
00061 
00062 /**
00063  * Each radio has a set of parameters that designate the current
00064  * configuration and state of the radio. Parameters can either have
00065  * values of type radio_value_t, or, when this type is insufficient, a
00066  * generic object that is specified by a memory pointer and the size
00067  * of the object.
00068  *
00069  * The radio_value_t type is set to an integer type that can hold most
00070  * values used to configure the radio, and is therefore the most
00071  * common type used for a parameter. Certain parameters require
00072  * objects of a considerably larger size than radio_value_t, however,
00073  * and in these cases the documentation below for the parameter will
00074  * indicate this.
00075  *
00076  * All radio parameters that can vary during runtime are prefixed by
00077  * "RADIO_PARAM", whereas those "parameters" that are guaranteed to
00078  * remain immutable are prefixed by "RADIO_CONST". Each mutable
00079  * parameter has a set of valid parameter values. When attempting to
00080  * set a parameter to an invalid value, the radio will return
00081  * RADIO_RESULT_INVALID_VALUE.
00082  *
00083  * Some radios support only a subset of the defined radio parameters.
00084  * When trying to set or get such an unsupported parameter, the radio
00085  * will return RADIO_RESULT_NOT_SUPPORTED.
00086  */
00087 
00088 typedef int radio_value_t;
00089 typedef unsigned radio_param_t;
00090 
00091 enum {
00092 
00093   /* Radio power mode determines if the radio is on
00094     (RADIO_POWER_MODE_ON) or off (RADIO_POWER_MODE_OFF). */
00095   RADIO_PARAM_POWER_MODE,
00096 
00097   /*
00098    * Channel used for radio communication. The channel depends on the
00099    * communication standard used by the radio. The values can range
00100    * from RADIO_CONST_CHANNEL_MIN to RADIO_CONST_CHANNEL_MAX.
00101    */
00102   RADIO_PARAM_CHANNEL,
00103 
00104   /* Personal area network identifier, which is used by the address filter. */
00105   RADIO_PARAM_PAN_ID,
00106 
00107   /* Short address (16 bits) for the radio, which is used by the address
00108      filter. */
00109   RADIO_PARAM_16BIT_ADDR,
00110 
00111   /*
00112    * Radio receiver mode determines if the radio has address filter
00113    * (RADIO_RX_MODE_ADDRESS_FILTER) and auto-ACK (RADIO_RX_MODE_AUTOACK)
00114    * enabled. This parameter is set as a bit mask.
00115    */
00116   RADIO_PARAM_RX_MODE,
00117 
00118   /*
00119    * Radio transmission mode determines if the radio has send on CCA
00120    * (RADIO_TX_MODE_SEND_ON_CCA) enabled or not. This parameter is set
00121    * as a bit mask.
00122    */
00123   RADIO_PARAM_TX_MODE,
00124 
00125   /*
00126    * Transmission power in dBm. The values can range from
00127    * RADIO_CONST_TXPOWER_MIN to RADIO_CONST_TXPOWER_MAX.
00128    *
00129    * Some radios restrict the available values to a subset of this
00130    * range.  If an unavailable TXPOWER value is requested to be set,
00131    * the radio may select another TXPOWER close to the requested
00132    * one. When getting the value of this parameter, the actual value
00133    * used by the radio will be returned.
00134    */
00135   RADIO_PARAM_TXPOWER,
00136 
00137   /*
00138    * Clear channel assessment threshold in dBm. This threshold
00139    * determines the minimum RSSI level at which the radio will assume
00140    * that there is a packet in the air.
00141    *
00142    * The CCA threshold must be set to a level above the noise floor of
00143    * the deployment. Otherwise mechanisms such as send-on-CCA and
00144    * low-power-listening duty cycling protocols may not work
00145    * correctly. Hence, the default value of the system may not be
00146    * optimal for any given deployment.
00147    */
00148   RADIO_PARAM_CCA_THRESHOLD,
00149 
00150   /* Received signal strength indicator in dBm. */
00151   RADIO_PARAM_RSSI,
00152 
00153   /*
00154    * Long (64 bits) address for the radio, which is used by the address filter.
00155    * The address is specified in network byte order.
00156    *
00157    * Because this parameter value is larger than what fits in radio_value_t,
00158    * it needs to be used with radio.get_object()/set_object().
00159    */
00160   RADIO_PARAM_64BIT_ADDR,
00161 
00162   /* Constants (read only) */
00163 
00164   /* The lowest radio channel. */
00165   RADIO_CONST_CHANNEL_MIN,
00166   /* The highest radio channel. */
00167   RADIO_CONST_CHANNEL_MAX,
00168 
00169   /* The minimum transmission power in dBm. */
00170   RADIO_CONST_TXPOWER_MIN,
00171   /* The maximum transmission power in dBm. */
00172   RADIO_CONST_TXPOWER_MAX
00173 };
00174 
00175 /* Radio power modes */
00176 enum {
00177   RADIO_POWER_MODE_OFF,
00178   RADIO_POWER_MODE_ON
00179 };
00180 
00181 /**
00182  * The radio reception mode controls address filtering and automatic
00183  * transmission of acknowledgements in the radio (if such operations
00184  * are supported by the radio). A single parameter is used to allow
00185  * setting these features simultaneously as an atomic operation.
00186  *
00187  * To enable both address filter and transmissions of automatic
00188  * acknowledgments:
00189  *
00190  * NETSTACK_RADIO.set_value(RADIO_PARAM_RX_MODE,
00191  *       RADIO_RX_MODE_ADDRESS_FILTER | RADIO_RX_MODE_AUTOACK);
00192  */
00193 #define RADIO_RX_MODE_ADDRESS_FILTER   (1 << 0)
00194 #define RADIO_RX_MODE_AUTOACK          (1 << 1)
00195 
00196 /**
00197  * The radio transmission mode controls whether transmissions should
00198  * be done using clear channel assessment (if supported by the
00199  * radio). If send-on-CCA is enabled, the radio's send function will
00200  * wait for a radio-specific time window for the channel to become
00201  * clear. If this does not happen, the send function will return
00202  * RADIO_TX_COLLISION.
00203  */
00204 #define RADIO_TX_MODE_SEND_ON_CCA      (1 << 0)
00205 
00206 /* Radio return values when setting or getting radio parameters. */
00207 typedef enum {
00208   RADIO_RESULT_OK,
00209   RADIO_RESULT_NOT_SUPPORTED,
00210   RADIO_RESULT_INVALID_VALUE,
00211   RADIO_RESULT_ERROR
00212 } radio_result_t;
00213 
00214 /* Radio return values for transmissions. */
00215 enum {
00216   RADIO_TX_OK,
00217   RADIO_TX_ERR,
00218   RADIO_TX_COLLISION,
00219   RADIO_TX_NOACK,
00220 };
00221 
00222 /**
00223  * The structure of a device driver for a radio in Contiki.
00224  */
00225 struct radio_driver {
00226 
00227   int (* init)(void);
00228 
00229   /** Prepare the radio with a packet to be sent. */
00230   int (* prepare)(const void *payload, unsigned short payload_len);
00231 
00232   /** Send the packet that has previously been prepared. */
00233   int (* transmit)(unsigned short transmit_len);
00234 
00235   /** Prepare & transmit a packet. */
00236   int (* send)(const void *payload, unsigned short payload_len);
00237 
00238   /** Read a received packet into a buffer. */
00239   int (* read)(void *buf, unsigned short buf_len);
00240 
00241   /** Perform a Clear-Channel Assessment (CCA) to find out if there is
00242       a packet in the air or not. */
00243   int (* channel_clear)(void);
00244 
00245   /** Check if the radio driver is currently receiving a packet */
00246   int (* receiving_packet)(void);
00247 
00248   /** Check if the radio driver has just received a packet */
00249   int (* pending_packet)(void);
00250 
00251   /** Turn the radio on. */
00252   int (* on)(void);
00253 
00254   /** Turn the radio off. */
00255   int (* off)(void);
00256 
00257   /** Get a radio parameter value. */
00258   radio_result_t (* get_value)(radio_param_t param, radio_value_t *value);
00259 
00260   /** Set a radio parameter value. */
00261   radio_result_t (* set_value)(radio_param_t param, radio_value_t value);
00262 
00263   /**
00264    * Get a radio parameter object. The argument 'dest' must point to a
00265    * memory area of at least 'size' bytes, and this memory area will
00266    * contain the parameter object if the function succeeds.
00267    */
00268   radio_result_t (* get_object)(radio_param_t param, void *dest, size_t size);
00269 
00270   /**
00271    * Set a radio parameter object. The memory area referred to by the
00272    * argument 'src' will not be accessed after the function returns.
00273    */
00274   radio_result_t (* set_object)(radio_param_t param, const void *src,
00275                                 size_t size);
00276 
00277 };
00278 
00279 #endif /* RADIO_H_ */
00280 
00281 /** @} */
00282 /** @} */