radio.h

00001 /* Copyright (c) 2007-2009 Axel Wachtler
00002    All rights reserved.
00003 
00004    Redistribution and use in source and binary forms, with or without
00005    modification, are permitted provided that the following conditions
00006    are met:
00007 
00008    * Redistributions of source code must retain the above copyright
00009      notice, this list of conditions and the following disclaimer.
00010    * 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    * Neither the name of the authors 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 COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00018    AND 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 COPYRIGHT OWNER OR CONTRIBUTORS BE
00021    LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
00022    CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
00023    SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
00024    INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
00025    CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
00026    ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
00027    POSSIBILITY OF SUCH DAMAGE. */
00028 
00029 /* $Id$ */
00030 /**
00031  * @file
00032  * @brief Interface for @ref grpLibRadio.
00033  *
00034  */
00035 #ifndef RADIO_H
00036 #define RADIO_H
00037 
00038 /* === Includes ============================================================== */
00039 #include <stdbool.h>
00040 #include <stdio.h>
00041 #include "const.h"
00042 
00043 /**
00044  * @addtogroup grpRadio
00045  * @{
00046  */
00047 
00048 /* === Externals ============================================================= */
00049 
00050 /* === Types ================================================================= */
00051 
00052 /**
00053  * Radio state enumeration
00054  */
00055 
00056 /** TRX in OFF state. */
00057 #define  STATE_OFF (0)
00058 /** Basic mode TX state. */
00059 #define  STATE_TX (1)
00060 /** Basic mode RX state. */
00061 #define STATE_RX (2)
00062 /** Extended mode TX state (TX_ARET). */
00063 #define STATE_TXAUTO (3)
00064 /** Extended mode RX state (RX_AACK). */
00065 #define STATE_RXAUTO (4)
00066 /** Sleep state (lowest power consumption). */
00067 #define STATE_SLEEP (5)
00068 
00069 
00070 /** Radio state type */
00071 typedef uint8_t radio_state_t;
00072 
00073 /**
00074  * error codes for tx done event
00075  */
00076 typedef enum
00077 {
00078     TX_OK,          /**< transmission completed successfully */
00079     TX_CCA_FAIL,        /**< channel was busy (TX_AUTO only) */
00080     TX_NO_ACK,          /**< no ACK received (TX_AUTO only) */
00081     TX_FAIL,            /**< unexpected error */
00082 } radio_tx_done_t;
00083 
00084 
00085 /**
00086  * codes for CCA
00087  */
00088 typedef enum SHORTENUM
00089 {
00090 #if defined(CCA_BUSY)
00091     /** @todo this is workaround for name clash for RFA1 and avr-libc
00092      *   avr/iom128rfa1.h, check if this is OK or if we should change
00093      *   the names of CCA_FREE, ..., etc.
00094      */
00095     RADIO_CCA_FREE = CCA_IDLE,
00096     RADIO_CCA_BUSY = CCA_BUSY,
00097     RADIO_CCA_FAIL = 255,
00098 #else
00099     /** The CCA measurement estimates, that the channel is free. */
00100     RADIO_CCA_FREE = 0,
00101     /** The CCA measurement estimates, that the channel is busy. */
00102     RADIO_CCA_BUSY,
00103     /** The CCA measurement was not finished. */
00104     RADIO_CCA_FAIL
00105 #endif
00106 
00107 } radio_cca_t;
00108 
00109 
00110 /** Enumeration to identify radio attributes.
00111  */
00112 typedef enum SHORTENUM
00113 {
00114     /** Set the current channel */
00115     phyCurrentChannel,
00116     /** Currently unused */
00117     phyChannelsSupported,
00118     /** Set the Tx power */
00119     phyTransmitPower,
00120     /** Transceiver state to return to after transmission */
00121     phyIdleState,
00122     /** CCA mode to use in CSMA-CA:
00123      * <table>
00124      *   <tr><th>value</th><th>CCA mode</th></tr>
00125      *   <tr><td>0</td>    <td>carrier sense OR energy above threshold</td></tr>
00126      *   <tr><td>1</td>    <td>energy above threshold (default)</td></tr>
00127      *   <tr><td>2</td>    <td>carrier sense</td></tr>
00128      *   <tr><td>3</td>    <td>carrier sense AND energy above threshold</td></tr>
00129      * </table>
00130      */
00131     phyCCAMode,
00132     /** PAN ID to use in STATE_RXAUTO frame filter */
00133     phyPanId,
00134     /** Short (16-bit) address to use in STATE_RXAUTO frame filter */
00135     phyShortAddr,
00136     /** Pointer to long (EUI-64) address to use in STATE_RXAUTO frame filter */
00137     phyLongAddr,
00138 
00139     /** Datarate */
00140     phyDataRate,
00141 
00142     /** PA enable */
00143     phyTxPa,
00144     /** LNA enable */
00145     phyRxLna
00146 
00147 } radio_attribute_t;
00148 
00149 
00150 /**
00151  * @brief Container for handover of radio parameter values.
00152  *
00153  * @note
00154  * The elements in this union should have max. a size
00155  * of 2 byte, all other parameters should be configured with
00156  * the void pointer.
00157  */
00158 typedef union radio_param_t
00159 {
00160 #if defined __cplusplus
00161 public:
00162     radio_param_t(int8_t c) { channel = c; } /* also used for txpwr_t */
00163     //radio_param_t(radio_state_t s) { idle_state = s; }
00164     radio_param_t(uint8_t m) { cca_mode = m; } /* also used for data_rate, tx_pa, rx_lna */
00165     radio_param_t(uint16_t p) { pan_id = p; } /* also used for short_addr */
00166     radio_param_t(uint64_t *la) { long_addr = la; }
00167 #endif
00168     /** Value for current radio channel. (@ref MIN_CHANNEL ... @ref MAX_CHANNEL)*/
00169     channel_t channel;
00170     /** Value for transmit power in dB.*/
00171     txpwr_t   tx_pwr;
00172     /** after TX go to idle state */
00173     radio_state_t idle_state;
00174     /** Value for cca mode. */
00175     ccamode_t cca_mode;
00176     /** Value for PANID */
00177     uint16_t pan_id;
00178     /** Value for short address */
00179     uint16_t short_addr;
00180     /** Pointer to long (64-bit) address */
00181     uint64_t *long_addr;
00182     /** data rate type */
00183     uint8_t data_rate;
00184 
00185     /** TX power amp type */
00186     uint8_t tx_pa;
00187     /** RX LNA type */
00188     uint8_t rx_lna;
00189 
00190 } radio_param_t;
00191 
00192 
00193 /**
00194  * @brief Error codes.
00195  */
00196 typedef enum SHORTENUM
00197 {
00198     #ifndef SUCCESS
00199     /** @todo same like CCA_FREE, include/avr/iom128rfa1.h:3687:#define SUCCESS*/
00200     SUCCESS = 0,        /**< OK Code*/
00201     #endif
00202     STATE_SET_FAILED = 1,   /**< function radio_set_state failed */
00203     SET_PARM_FAILED,    /**< function radio_set_param failed */
00204     GET_PARM_FAILED,    /**< function radio_get_param failed */
00205     GENERAL_ERROR,      /**< something unexpected happened */
00206 } radio_error_t;
00207 
00208 
00209 /**
00210  * @brief Structure for storage of radio parameters.
00211  */
00212 typedef struct
00213 {
00214     uint8_t  channel;      /**< Current radio channel.
00215                                 (@ref MIN_CHANNEL ... @ref MAX_CHANNEL) */
00216     uint8_t  tx_pwr;       /**< Current transmit power. */
00217     uint8_t  cca_mode;     /**< Current cca mode. */
00218     radio_state_t state;      /**< Current transceiver state. */
00219     radio_state_t idle_state; /**< after TX go to idle state */
00220     uint8_t  *rxframe;      /**< Pointer for frame data storage. */
00221     uint8_t  rxframesz;     /**< Length of the buffer rxframesz */
00222     uint8_t tx_pa;
00223     uint8_t rx_lna;
00224 } radio_status_t;
00225 
00226 /* === Macros ================================================================ */
00227 
00228 /**
00229  * Code for invalid RSSI value.
00230  */
00231 #define VOID_RSSI (0xff)
00232 
00233 #if defined(DOXYGEN)
00234 /**
00235  * Helper macro to construct the arguments for @ref radio_set_param in
00236  * order to set the channel number to @c x.
00237  */
00238 #  define RP_CHANNEL(x)
00239 #elif defined __cplusplus
00240 #  define RP_CHANNEL(x) phyCurrentChannel,radio_param_t((channel_t)x)
00241 #else
00242 #  define RP_CHANNEL(x) phyCurrentChannel,(radio_param_t){.channel=x}
00243 #endif
00244 
00245 #if defined(DOXYGEN)
00246 /**
00247  * Helper macro to construct the arguments for @ref radio_set_param in
00248  * order to set the tx power value to @c x.
00249  */
00250 #  define RP_TXPWR(x)
00251 #elif defined __cplusplus
00252 #  define RP_TXPWR(x)   phyTransmitPower,radio_param_t((txpwr_t)x)
00253 #else
00254 #  define RP_TXPWR(x)   phyTransmitPower,(radio_param_t){.tx_pwr=x}
00255 #endif
00256 
00257 #if defined(DOXYGEN)
00258 /**
00259  * Helper macro to construct the arguments for @ref radio_set_param in
00260  * order to set the transceiver's idle state to @c x.
00261  */
00262 #  define RP_IDLESTATE(x)
00263 #elif defined __cplusplus
00264 #  define RP_IDLESTATE(x)  phyIdleState,radio_param_t(x)
00265 #else
00266 #  define RP_IDLESTATE(x)  phyIdleState,(radio_param_t){.idle_state=x}
00267 #endif
00268 
00269 #if defined(DOXYGEN)
00270 /**
00271  * Helper macro to construct the arguments for @ref radio_set_param in
00272  * order to set the CCA mode to @c x.
00273  */
00274 #  define RP_CCAMODE(x)
00275 #elif defined __cplusplus
00276 #  define RP_CCAMODE(x)  phyCCAMode,radio_param_t((ccamode_t)x)
00277 #else
00278 #  define RP_CCAMODE(x) phyCCAMode,(radio_param_t){.cca_mode=x}
00279 #endif
00280 
00281 #if defined(DOXYGEN)
00282 /**
00283  * Helper macro to construct the arguments for @ref radio_set_param in
00284  * order to set the PAN ID to @c x.
00285  */
00286 #  define RP_PANID(x)
00287 #elif defined __cplusplus
00288 #  define RP_PANID(x) phyPanId,radio_param_t((uint16_t)x)
00289 #else
00290 #  define RP_PANID(x) phyPanId,(radio_param_t){.pan_id=x}
00291 #endif
00292 
00293 #if defined(DOXYGEN)
00294 /**
00295  * Helper macro to construct the arguments for @ref radio_set_param in
00296  * order to set the short address to @c x.
00297  */
00298 #  define RP_SHORTADDR(x)
00299 #elif defined __cplusplus
00300 #  define RP_SHORTADDR(x) phyShortAddr,radio_param_t((uint16_t)x)
00301 #else
00302 #  define RP_SHORTADDR(x) phyShortAddr,(radio_param_t){.short_addr=x}
00303 #endif
00304 
00305 #if defined(DOXYGEN)
00306 /**
00307  * Helper macro to construct the arguments for @ref radio_set_param in
00308  * order to set the long address pointer to @c x.
00309  */
00310 #  define RP_LONGADDR(x)
00311 #elif defined __cplusplus
00312 #  define RP_LONGADDR(x) phyLongAddr,radio_param_t((uint64_t *)x)
00313 #else
00314 #  define RP_LONGADDR(x) phyLongAddr,(radio_param_t){.long_addr=x}
00315 #endif
00316 
00317 
00318 #if defined(DOXYGEN)
00319 /**
00320  * Helper macro to construct the arguments for @ref radio_set_param in
00321  * order to set the data rate to @c x.
00322  */
00323 #  define RP_DATARATE(x)
00324 #elif defined __cplusplus
00325 #  define RP_DATARATE(x) phyDataRate,radio_param_t((uint16_t)x)
00326 #else
00327 #  define RP_DATARATE(x) phyDataRate,(radio_param_t){.data_rate=x}
00328 #endif
00329 
00330 #if defined(DOXYGEN)
00331 /**
00332  * Helper macro to construct the arguments for @ref radio_set_param in
00333  * order to set the TX power amplifier enable number to @c x.
00334  */
00335 #  define RP_CHANNEL(x)
00336 #elif defined __cplusplus
00337 #  define RP_TX_PA(x) phyTxPa,radio_param_t((tx_pa_t)x)
00338 #else
00339 #  define RP_TX_PA(x) phyTxPa,(radio_param_t){.tx_pa=x}
00340 #endif
00341 
00342 #if defined(DOXYGEN)
00343 /**
00344  * Helper macro to construct the arguments for @ref radio_set_param in
00345  * order to set the TX power amplifier enable number to @c x.
00346  */
00347 #  define RP_RX_LNA(x)
00348 #elif defined __cplusplus
00349 #  define RP_RX_LNA(x) phyRxLna,radio_param_t((rx_lna_t)x)
00350 #else
00351 #  define RP_RX_LNA(x) phyRxLna,(radio_param_t){.rx_lna=x}
00352 #endif
00353 
00354 #define CRC_CCITT_UPDATE(crc, data) crc16_update(crc, data)
00355 
00356 
00357 #ifndef RADIO_CFG_EEOFFSET
00358 /** offset of radio config data in EEPROM */
00359 #define RADIO_CFG_EEOFFSET (8)
00360 #endif
00361 
00362 #ifndef RADIO_CFG_DATA
00363 /** a default radio configuration data structure */
00364 #define RADIO_CFG_DATA {chan: 16, txp: 0, cca: 1, edt: 11, clkm: 0, crc: 0xab12}
00365 #endif
00366 
00367 /** @} */
00368 
00369 
00370 #endif  /* #ifndef RADIO_H */
00371 /* EOF */