Show
Ignore:
Timestamp:
08/13/08 12:48:09 (5 months ago)
Author:
liamstask
Message:

- updated struct documentation: much better xbee doc

Files:
1 modified

Legend:

Unmodified
Added
Removed

  • firmware/trunk/libraries/xbee/xbee.h

    r792 r815  
    1616*********************************************************************************/ 
    1717 
    18 /* 
    19   xbee.h 
    20   MakingThings 
     18/** @file xbee.h 
     19  XBee defines 
    2120*/ 
    2221 
    … …  
    5857/** 
    5958  The structure used for a standard AT Command packet. 
    60   - \b frameID is the ID for this packet that subsequent response/status messages can refer to. 
    61   - \b command is the 2-character AT command. 
    62   - \b parameters is a buffer that holds the value of the AT command. 
    63  */ 
    64 typedef struct 
    65 { 
    66   uint8 frameID; 
    67   uint8 command[ 2 ]; 
    68   uint8 parameters[ 97 ]; 
     59*/ 
     60typedef struct 
     61{ 
     62  uint8 frameID;          /**< the ID for this packet that subsequent response/status messages can refer to. */ 
     63  uint8 command[ 2 ];     /**< the 2-character AT command. */ 
     64  uint8 parameters[ 97 ]; /**< a buffer that holds the value of the AT command. */ 
    6965} XBee_ATCommand; 
    7066 
    7167/**  
    7268  The structure used for a response to a standard AT Command packet. 
    73   - \b frameID is the ID that this response is referring to. 
    74   - \b command is the 2-character AT command. 
    75   - \b status is response value - 0 (OK) or 1 (ERROR). 
    76   - \b value is a buffer that holds the value of the AT command response. 
    77  */ 
    78 typedef struct 
    79 { 
    80   uint8 frameID; 
    81   uint8 command[ 2 ]; 
    82   uint8 status; 
    83   uint8 value[ 96 ]; 
    84 }  XBee_ATCommandResponse; 
    85  
    86 /**  
    87   The structure used to transmit an XBee packet with a 64-bit destination address. 
    88   - \b frameID is the ID for this packet that subsequent response/status messages can refer to. 
    89   - \b destination is the 64-bit (8-byte) address of the destination. 
    90   - \b options - 0x01 (disable ACK) or 0x04 (Send with Broadcast PAN ID). 
    91   - \b data is a buffer that holds the value of the outgoing packet. 
    92  */ 
    93 typedef struct 
    94 { 
    95   uint8 frameID; 
    96   uint8 destination[ 8 ]; 
    97   uint8 options; 
    98   uint8 data[ 90 ]; 
     69*/ 
     70typedef struct 
     71{ 
     72  uint8 frameID;      /**< the ID that this response is referring to. */ 
     73  uint8 command[ 2 ]; /**< the 2-character AT command. */ 
     74  uint8 status;       /**< response value - 0 (OK) or 1 (ERROR). */ 
     75  uint8 value[ 96 ];  /**< a buffer containing the value of the AT command response. */ 
     76} XBee_ATCommandResponse; 
     77 
     78/**  
     79  The structure used to transmit a data packet with a 64-bit destination address. 
     80*/ 
     81typedef struct 
     82{ 
     83  uint8 frameID;          /**< the ID for this packet that subsequent response/status messages can refer to. */ 
     84  uint8 destination[ 8 ]; /**< the 64-bit (8-byte) address of the destination. */ 
     85  uint8 options;          /**< 0x01 (disable ACK) or 0x04 (Send with Broadcast PAN ID). */ 
     86  uint8 data[ 90 ];       /**< a buffer containing the value of the outgoing packet. */ 
    9987}  XBee_TX64; 
    10088 
    10189/**  
    102   The structure used to transmit an XBee packet with a 16-bit destination address. 
    103   - \b frameID is the ID for this packet that subsequent response/status messages can refer to. 
    104   - \b destination is the 16-bit (2-byte) address of the destination. 
    105   - \b options - 0x01 (disable ACK) or 0x04 (Send with Broadcast PAN ID). 
    106   - \b data is a buffer that holds the value of the outgoing packet. 
    107  */ 
    108 typedef struct 
    109 { 
    110   uint8 frameID; 
    111   uint8 destination[ 2 ]; 
    112   uint8 options; 
    113   uint8 data[ 96 ]; 
     90  The structure used to transmit a data packet with a 16-bit destination address. 
     91 */ 
     92typedef struct 
     93{ 
     94  uint8 frameID;          /**< the ID for this packet that subsequent response/status messages can refer to. */ 
     95  uint8 destination[ 2 ]; /**< the 16-bit (2-byte) address of the destination. */ 
     96  uint8 options;          /**< 0x01 (disable ACK) or 0x04 (Send with Broadcast PAN ID). */ 
     97  uint8 data[ 96 ];       /**< a buffer containing the value of the outgoing packet. */ 
    11498}  XBee_TX16; 
    11599 
    116100/**  
    117101  When a transmit request is completed, the module sends a transmit status message. 
    118   - \b frameID is the ID that this response is referring to. 
    119   - \b status can have values of: 
     102 */ 
     103typedef struct 
     104{ 
     105  uint8 frameID; /**< the ID that this response is referring to. */ 
     106  uint8 status;  /**< can have values of: 
    120107    - 0 - success 
    121108    - 1 - No ACK received 
    122109    - 2 - CCA failure 
    123     - 3 - Purged 
    124  */ 
    125 typedef struct 
    126 { 
    127   uint8 frameID; 
    128   uint8 status; 
     110    - 3 - Purged. */ 
    129111}  XBee_TXStatus; 
    130112 
    131113/**  
    132   An incoming packet with a 64-bit address. 
    133   - \b source is the 64-bit (8-byte) address of the sender. 
    134   - \b rssi is the signal strength of the received message. 
    135   - \b options - bit 1 is Address Broadcast, bit 2 is PAN broadcast.  Other bits reserved. 
    136   - \b data is a buffer that holds the value of the incoming packet. 
    137  */ 
    138 typedef struct 
    139 { 
    140   uint8 source[ 8 ]; 
    141   uint8 rssi; 
    142   uint8 options; 
    143   uint8 data[ 89 ]; 
     114  An incoming data packet with a 64-bit address. 
     115 */ 
     116typedef struct 
     117{ 
     118  uint8 source[ 8 ]; /**< the 64-bit (8-byte) address of the sender. */ 
     119  uint8 rssi;        /**< the signal strength of the received message. */ 
     120  uint8 options;     /**< bit 1 is Address Broadcast, bit 2 is PAN broadcast.  Other bits reserved. */ 
     121  uint8 data[ 89 ];  /**< a buffer containing the value of the incoming packet. */ 
    144122}  XBee_RX64; 
    145123 
    146124/**  
    147   An incoming packet with a 16-bit address. 
    148   - \b source is the 16-bit (2-byte) address of the sender. 
    149   - \b rssi is the signal strength of the received message. 
    150   - \b options - bit 1 is Address Broadcast, bit 2 is PAN broadcast.  Other bits reserved. 
    151   - \b data is a buffer that holds the value of the incoming packet. 
    152  */ 
    153 typedef struct 
    154 { 
    155   uint8 source[ 2 ]; 
    156   uint8 rssi; 
    157   uint8 options; 
    158   uint8 data[ 95 ]; 
     125  An incoming data packet with a 16-bit address. 
     126 */ 
     127typedef struct 
     128{ 
     129  uint8 source[ 2 ]; /**< the 16-bit (2-byte) address of the sender. */ 
     130  uint8 rssi;        /**< the signal strength of the received message. */ 
     131  uint8 options;     /**< bit 1 is Address Broadcast, bit 2 is PAN broadcast.  Other bits reserved. */ 
     132  uint8 data[ 95 ];  /**< a buffer containing the value of the incoming packet. */ 
    159133}  XBee_RX16; 
    160134 
    161135/**  
    162136  An incoming packet with IO data from a 64-bit address. 
    163   - \b source is the 64-bit (8-byte) address of the sender. 
    164   - \b rssi is the signal strength of the received message. 
    165   - \b options - bit 1 is Address Broadcast, bit 2 is PAN broadcast.  Other bits reserved. 
    166   - \b samples - the number of samples in this packet. 
    167   - \b channelIndicators - bit mask indicating which channels have been sampled. 
    168   - \b data is a buffer that holds the IO values as indicated by \b channelIndicators. 
    169  */ 
    170 typedef struct 
    171 { 
    172   uint8 source[ 8 ]; 
    173   uint8 rssi; 
    174   uint8 options; 
    175   uint8 samples; 
    176   uint8 channelIndicators[ 2 ]; 
    177   uint8 data[ 86 ]; 
     137 */ 
     138typedef struct 
     139{ 
     140  uint8 source[ 8 ];            /**< the 64-bit (8-byte) address of the sender. */ 
     141  uint8 rssi;                   /**< the signal strength of the received message. */ 
     142  uint8 options;                /**< bit 1 is Address Broadcast, bit 2 is PAN broadcast.  Other bits reserved. */ 
     143  uint8 samples;                /**< the number of samples in this packet. */ 
     144  uint8 channelIndicators[ 2 ]; /**< bit mask indicating which channels have been sampled. */ 
     145  uint8 data[ 86 ];             /**< a buffer containing the IO values as indicated by \b channelIndicators. */ 
    178146}  XBee_IO64; 
    179147 
    180 /**  
     148/** 
    181149  An incoming packet with IO data from a 16-bit address. 
    182   - \b source is the 16-bit (2-byte) address of the sender. 
    183   - \b rssi is the signal strength of the received message. 
    184   - \b options - bit 1 is Address Broadcast, bit 2 is PAN broadcast.  Other bits reserved. 
    185   - \b samples - the number of samples in this packet. 
    186   - \b channelIndicators - bit mask indicating which channels have been sampled. 
    187   - \b data is a buffer that holds the IO values as indicated by \b channelIndicators. 
    188  */ 
    189 typedef struct 
    190 { 
    191   uint8 source[ 2 ]; 
    192   uint8 rssi; 
    193   uint8 options; 
    194   uint8 samples; 
    195   uint8 channelIndicators[ 2 ]; 
    196   uint8 data[ 92 ]; 
     150 */ 
     151typedef struct 
     152{ 
     153  uint8 source[ 2 ];            /**< the 16-bit (2-byte) address of the sender. */ 
     154  uint8 rssi;                   /**< the signal strength of the received message. */ 
     155  uint8 options;                /**< bit 1 is Address Broadcast, bit 2 is PAN broadcast.  Other bits reserved. */ 
     156  uint8 samples;                /**< the number of samples in this packet. */ 
     157  uint8 channelIndicators[ 2 ]; /**< a bit mask indicating which channels have been sampled. */ 
     158  uint8 data[ 92 ];             /**< a buffer containing the IO values as indicated by \b channelIndicators. */ 
    197159}  XBee_IO16; 
    198160 
    199 typedef enum  
     161/** 
     162  Possible API IDs for different kinds of packets. 
     163  In the main XBeePacket structure, its \b apiId member will be set to one of these values, 
     164  indicating which kind of packet it is. 
     165 
     166  \b Example 
     167  \code 
     168  XBeePacket* xbp; 
     169  if( xbp->apiId == XBEE_IO16 ) 
     170  { 
     171    // then we have an XBee_IO16 packet, 
     172    // accessible at xbp->io16 
     173  } 
     174  \endcode 
     175*/ 
     176enum XBeeApiId 
    200177{  
    201   XBEE_TX64 = 0x00, 
    202   XBEE_TX16 = 0x01, 
    203   XBEE_TXSTATUS = 0x89, 
    204   XBEE_RX64 = 0x80, 
    205   XBEE_RX16 = 0x81, 
    206   XBEE_ATCOMMAND = 0x08, 
    207   XBEE_ATCOMMANDQ = 0x09, 
    208   XBEE_ATCOMMANDRESPONSE = 0x88, 
    209   XBEE_IO64 = 0x82, 
    210   XBEE_IO16 = 0x83 
    211 } XBeeApiId; 
     178  XBEE_TX64 = 0x00,               /**< An outgoing data packet with a 64-bit address. */ 
     179  XBEE_TX16 = 0x01,               /**< An outgoing data packet with a 16-bit address. */ 
     180  XBEE_TXSTATUS = 0x89,           /**< TX status packet. */ 
     181  XBEE_RX64 = 0x80,               /**< An incoming data packet with a 64-bit address. */ 
     182  XBEE_RX16 = 0x81,               /**< An incoming data packet with a 16-bit address. */ 
     183  XBEE_ATCOMMAND = 0x08,          /**< An AT command packet. */ 
     184  XBEE_ATCOMMANDQ = 0x09,         /**< An AT command queue packet. */ 
     185  XBEE_ATCOMMANDRESPONSE = 0x88,  /**< A response to an AT command query. */ 
     186  XBEE_IO64 = 0x82,               /**< An incoming IO packet with a 64-bit address. */ 
     187  XBEE_IO16 = 0x83                /**< An incoming IO packet with a 16-bit address. */ 
     188}; 
    212189 
    213190/** @} 
    214191*/ 
    215192 
    216 typedef struct 
    217 { 
    218   uint8 apiId; 
     193/** 
     194  Representation of an XBee packet. 
     195  The XBeePacket structure consists of an API ID, indicating the kind of packet it is, as well as  
     196  providing the structure for that particular packet.  Only one packet type will be valid at a time, 
     197  as indicated by the \b apiId: 
     198   
     199  \b Example 
     200  \code 
     201  XBeePacket* xbp; 
     202  if( xbp->apiId == XBEE_IO16 ) 
     203  { 
     204    int signalStrength = xbp->io16.rssi; 
     205    // and so on... 
     206  } 
     207  \endcode 
     208  See \ref XBeeApiId for a list of valid API IDs. 
     209 
     210  \ingroup XBee 
     211*/ 
     212typedef struct 
     213{ 
     214  uint8 apiId; /**< the API ID for this packet that subsequent response/status messages can refer to. */ 
    219215  union 
    220216  { 
    221217    uint8 payload[ 100 ]; 
    222     XBee_TX64 tx64; 
    223     XBee_TX16 tx16; 
    224     XBee_TXStatus txStatus; 
    225     XBee_RX64 rx64; 
    226     XBee_RX16 rx16; 
    227     XBee_ATCommand atCommand; 
    228     XBee_ATCommandResponse atResponse; 
    229     XBee_IO64 io64; 
    230     XBee_IO16 io16; 
    231   }; 
     218    XBee_TX64 tx64;                    /**< TX 64 packet. */ 
     219    XBee_TX16 tx16;                    /**< TX 16 packet. */ 
     220    XBee_TXStatus txStatus;            /**< TX status packet. */ 
     221    XBee_RX64 rx64;                    /**< RX 64 packet. */ 
     222    XBee_RX16 rx16;                    /**< RX 16 packet. */ 
     223    XBee_ATCommand atCommand;          /**< AT Command packet. */ 
     224    XBee_ATCommandResponse atResponse; /**< AT Command Response packet. */ 
     225    XBee_IO64 io64;                    /**< IO 64 packet. */ 
     226    XBee_IO16 io16;                    /**< IO 16 packet. */ 
     227  };  
    232228   
    233   uint8 crc; 
    234   uint8 *dataPtr; 
    235   int rxState; 
    236   int length; 
    237   int index; 
     229  uint8 crc;       /**< The checksum for this packet - mostly used internally by XBee_SendPacket() and XBee_GetPacket().  */ 
     230  uint8 *dataPtr;  /**< A pointer into the packet structure itself.  */ 
     231  int rxState;     /**< Used internally by XBee_GetPacket() to keep track of the parse state. */ 
     232  int length;      /**< The length of a packet - only useful after a successful call to XBee_GetPacket().  */ 
     233  int index;       /**< Used internally by XBee_GetPacket() to keep track of the current length.  */ 
    238234} __attribute__((packed)) XBeePacket; 
    239  
    240235 
    241236int XBee_SetActive( int state );