- Main Page
- Related Pages
- Modules
- Data Structures
- Files

- File List
- Globals

# xbee.h

Go to the documentation of this file.

    00001 /*********************************************************************************
    00002
    00003  Copyright 2006-2008 MakingThings
    00004
    00005  Licensed under the Apache License,
    00006  Version 2.0 (the "License"); you may not use this file except in compliance
    00007  with the License. You may obtain a copy of the License at
    00008
    00009  http://www.apache.org/licenses/LICENSE-2.0
    00010
    00011  Unless required by applicable law or agreed to in writing, software distributed
    00012  under the License is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
    00013  CONDITIONS OF ANY KIND, either express or implied. See the License for
    00014  the specific language governing permissions and limitations under the License.
    00015
    00016 *********************************************************************************/
    00017
    00018 /** @file xbee.h
    00019   XBee defines
    00020 */
    00021
    00022 #ifndef XBEE_H
    00023 #define XBEE_H
    00024
    00025 #include "types.h"
    00026
    00027 // states for receiving packets
    00028 #define XBEE_PACKET_RX_START 0
    00029 #define XBEE_PACKET_RX_LENGTH_1 1
    00030 #define XBEE_PACKET_RX_LENGTH_2 2
    00031 #define XBEE_PACKET_RX_PAYLOAD 3
    00032 #define XBEE_PACKET_RX_CRC 4
    00033
    00034 // general xbee constants
    00035 #define XBEE_PACKET_STARTBYTE 0x7E
    00036 #define XBEE_PACKET_ESCAPE 0x7D
    00037 #define XBEE_INPUTS 15 // counts analog and digital ins separately
    00038 #define XBEE_MAX_PACKET_SIZE 100
    00039
    00040 // xbee io options
    00041 #define XBEE_IO_DISABLED 0
    00042 #define XBEE_IO_ANALOGIN 2
    00043 #define XBEE_IO_DIGITALIN 3
    00044 #define XBEE_IO_DIGOUT_HIGH 4
    00045 #define XBEE_IO_DIGOUT_LOW 5
    00046
    00047 /** \defgroup XBeePacketTypes XBee Packet Types
    00048   The different types of packet that can be used with the \ref XBee subsystem.
    00049
    00050   These structures are to be used when the module has already been set into packet (API) mode
    00051   with a call to XBee_SetPacketApiMode( )
    00052
    00053   \ingroup XBee
    00054   @{
    00055 */
    00056
    00057 /**
    00058   The structure used for a standard AT Command packet.
    00059 */
    00060 typedef struct
    00061 {
    00062   uint8 frameID;          /**< the ID for this packet that subsequent response/status messages can refer to. */
    00063   uint8 command[ 2 ];     /**< the 2-character AT command. */
    00064   uint8 parameters[ 97 ]; /**< a buffer that holds the value of the AT command. */
    00065 } XBee_ATCommand;
    00066
    00067 /**
    00068   The structure used for a response to a standard AT Command packet.
    00069 */
    00070 typedef struct
    00071 {
    00072   uint8 frameID;      /**< the ID that this response is referring to. */
    00073   uint8 command[ 2 ]; /**< the 2-character AT command. */
    00074   uint8 status;       /**< response value - 0 (OK) or 1 (ERROR). */
    00075   uint8 value[ 96 ];  /**< a buffer containing the value of the AT command response. */
    00076 } XBee_ATCommandResponse;
    00077
    00078 /**
    00079   The structure used to transmit a data packet with a 64-bit destination address.
    00080 */
    00081 typedef struct
    00082 {
    00083   uint8 frameID;          /**< the ID for this packet that subsequent response/status messages can refer to. */
    00084   uint8 destination[ 8 ]; /**< the 64-bit (8-byte) address of the destination. */
    00085   uint8 options;          /**< 0x01 (disable ACK) or 0x04 (Send with Broadcast PAN ID). */
    00086   uint8 data[ 90 ];       /**< a buffer containing the value of the outgoing packet. */
    00087 }  XBee_TX64;
    00088
    00089 /**
    00090   The structure used to transmit a data packet with a 16-bit destination address.
    00091  */
    00092 typedef struct
    00093 {
    00094   uint8 frameID;          /**< the ID for this packet that subsequent response/status messages can refer to. */
    00095   uint8 destination[ 2 ]; /**< the 16-bit (2-byte) address of the destination. */
    00096   uint8 options;          /**< 0x01 (disable ACK) or 0x04 (Send with Broadcast PAN ID). */
    00097   uint8 data[ 96 ];       /**< a buffer containing the value of the outgoing packet. */
    00098 }  XBee_TX16;
    00099
    00100 /**
    00101   When a transmit request is completed, the module sends a transmit status message.
    00102  */
    00103 typedef struct
    00104 {
    00105   uint8 frameID; /**< the ID that this response is referring to. */
    00106   uint8 status;  /**< can have values of:
    00107     - 0 - success
    00108     - 1 - No ACK received
    00109     - 2 - CCA failure
    00110     - 3 - Purged. */
    00111 }  XBee_TXStatus;
    00112
    00113 /**
    00114   An incoming data packet with a 64-bit address.
    00115  */
    00116 typedef struct
    00117 {
    00118   uint8 source[ 8 ]; /**< the 64-bit (8-byte) address of the sender. */
    00119   uint8 rssi;        /**< the signal strength of the received message. */
    00120   uint8 options;     /**< bit 1 is Address Broadcast, bit 2 is PAN broadcast.  Other bits reserved. */
    00121   uint8 data[ 89 ];  /**< a buffer containing the value of the incoming packet. */
    00122 }  XBee_RX64;
    00123
    00124 /**
    00125   An incoming data packet with a 16-bit address.
    00126  */
    00127 typedef struct
    00128 {
    00129   uint8 source[ 2 ]; /**< the 16-bit (2-byte) address of the sender. */
    00130   uint8 rssi;        /**< the signal strength of the received message. */
    00131   uint8 options;     /**< bit 1 is Address Broadcast, bit 2 is PAN broadcast.  Other bits reserved. */
    00132   uint8 data[ 95 ];  /**< a buffer containing the value of the incoming packet. */
    00133 }  XBee_RX16;
    00134
    00135 /**
    00136   An incoming packet with IO data from a 64-bit address.
    00137  */
    00138 typedef struct
    00139 {
    00140   uint8 source[ 8 ];            /**< the 64-bit (8-byte) address of the sender. */
    00141   uint8 rssi;                   /**< the signal strength of the received message. */
    00142   uint8 options;                /**< bit 1 is Address Broadcast, bit 2 is PAN broadcast.  Other bits reserved. */
    00143   uint8 samples;                /**< the number of samples in this packet. */
    00144   uint8 channelIndicators[ 2 ]; /**< bit mask indicating which channels have been sampled. */
    00145   uint8 data[ 86 ];             /**< a buffer containing the IO values as indicated by \b channelIndicators. */
    00146 }  XBee_IO64;
    00147
    00148 /**
    00149   An incoming packet with IO data from a 16-bit address.
    00150  */
    00151 typedef struct
    00152 {
    00153   uint8 source[ 2 ];            /**< the 16-bit (2-byte) address of the sender. */
    00154   uint8 rssi;                   /**< the signal strength of the received message. */
    00155   uint8 options;                /**< bit 1 is Address Broadcast, bit 2 is PAN broadcast.  Other bits reserved. */
    00156   uint8 samples;                /**< the number of samples in this packet. */
    00157   uint8 channelIndicators[ 2 ]; /**< a bit mask indicating which channels have been sampled. */
    00158   uint8 data[ 92 ];             /**< a buffer containing the IO values as indicated by \b channelIndicators. */
    00159 }  XBee_IO16;
    00160
    00161 /**
    00162   Possible API IDs for different kinds of packets.
    00163   In the main XBeePacket structure, its \b apiId member will be set to one of these values,
    00164   indicating which kind of packet it is.
    00165
    00166   \b Example
    00167   \code
    00168   XBeePacket* xbp;
    00169   if( xbp->apiId == XBEE_IO16 )
    00170   {
    00171     // then we have an XBee_IO16 packet,
    00172     // accessible at xbp->io16
    00173   }
    00174   \endcode
    00175 */
    00176 enum XBeeApiId
    00177 {
    00178   XBEE_TX64 = 0x00,               /**< An outgoing data packet with a 64-bit address. */
    00179   XBEE_TX16 = 0x01,               /**< An outgoing data packet with a 16-bit address. */
    00180   XBEE_TXSTATUS = 0x89,           /**< TX status packet. */
    00181   XBEE_RX64 = 0x80,               /**< An incoming data packet with a 64-bit address. */
    00182   XBEE_RX16 = 0x81,               /**< An incoming data packet with a 16-bit address. */
    00183   XBEE_ATCOMMAND = 0x08,          /**< An AT command packet. */
    00184   XBEE_ATCOMMANDQ = 0x09,         /**< An AT command queue packet. */
    00185   XBEE_ATCOMMANDRESPONSE = 0x88,  /**< A response to an AT command query. */
    00186   XBEE_IO64 = 0x82,               /**< An incoming IO packet with a 64-bit address. */
    00187   XBEE_IO16 = 0x83                /**< An incoming IO packet with a 16-bit address. */
    00188 };
    00189
    00190 /** @}
    00191 */
    00192
    00193 /**
    00194   Representation of an XBee packet.
    00195   The XBeePacket structure consists of an API ID, indicating the kind of packet it is, as well as
    00196   providing the structure for that particular packet.  Only one packet type will be valid at a time,
    00197   as indicated by the \b apiId:
    00198
    00199   \b Example
    00200   \code
    00201   XBeePacket* xbp;
    00202   if( xbp->apiId == XBEE_IO16 )
    00203   {
    00204     int signalStrength = xbp->io16.rssi;
    00205     // and so on...
    00206   }
    00207   \endcode
    00208   See \ref XBeeApiId for a list of valid API IDs.
    00209
    00210   \ingroup XBee
    00211 */
    00212 typedef struct
    00213 {
    00214   uint8 apiId; /**< the API ID for this packet that subsequent response/status messages can refer to. */
    00215   union
    00216   {
    00217     uint8 payload[ 100 ];
    00218     XBee_TX64 tx64;                    /**< TX 64 packet. */
    00219     XBee_TX16 tx16;                    /**< TX 16 packet. */
    00220     XBee_TXStatus txStatus;            /**< TX status packet. */
    00221     XBee_RX64 rx64;                    /**< RX 64 packet. */
    00222     XBee_RX16 rx16;                    /**< RX 16 packet. */
    00223     XBee_ATCommand atCommand;          /**< AT Command packet. */
    00224     XBee_ATCommandResponse atResponse; /**< AT Command Response packet. */
    00225     XBee_IO64 io64;                    /**< IO 64 packet. */
    00226     XBee_IO16 io16;                    /**< IO 16 packet. */
    00227   };
    00228
    00229   uint8 crc;       /**< The checksum for this packet - mostly used internally by XBee_SendPacket() and XBee_GetPacket().  */
    00230   uint8 *dataPtr;  /**< A pointer into the packet structure itself.  */
    00231   int rxState;     /**< Used internally by XBee_GetPacket() to keep track of the parse state. */
    00232   int length;      /**< The length of a packet - only useful after a successful call to XBee_GetPacket().  */
    00233   int index;       /**< Used internally by XBee_GetPacket() to keep track of the current length.  */
    00234 } __attribute__((packed)) XBeePacket;
    00235
    00236 int XBee_SetActive( int state );
    00237 int XBee_GetActive( void );
    00238 int XBee_GetPacket( XBeePacket* packet, int timeout );
    00239 int XBee_SendPacket( XBeePacket* packet, int datalength );
    00240 void XBee_ResetPacket( XBeePacket* packet );
    00241 int XBee_Write( uchar *buffer, int count, int timeout );
    00242 int XBee_Read( uchar* buffer, int count, int timeout );
    00243 int XBee_IsBusyPacket( XBeePacket* packet );
    00244
    00245 // packet creators and unpackers
    00246 bool XBee_CreateTX16Packet( XBeePacket* xbp, uint8 frameID, uint16 destination, uint8 options, uint8* data, uint8 datalength );
    00247 bool XBee_CreateTX64Packet( XBeePacket* xbp, uint8 frameID, uint64 destination, uint8 options, uint8* data, uint8 datalength );
    00248 bool XBee_ReadRX16Packet( XBeePacket* xbp, uint16* srcAddress, uint8* sigstrength, uint8* options, uint8** data, uint8* datalength );
    00249 bool XBee_ReadRX64Packet( XBeePacket* xbp, uint64* srcAddress, uint8* sigstrength, uint8* options, uint8** data, uint8* datalength  );
    00250 bool XBee_ReadIO16Packet( XBeePacket* xbp, uint16* srcAddress, uint8* sigstrength, uint8* options, int* samples );
    00251 bool XBee_ReadIO64Packet( XBeePacket* xbp, uint64* srcAddress, uint8* sigstrength, uint8* options, int* samples );
    00252 void XBee_CreateATCommandPacket( XBeePacket* packet, uint8 frameID, char* cmd, uint8* params, uint8 datalength );
    00253 bool XBee_ReadAtResponsePacket( XBeePacket* xbp, uint8* frameID, char** command, uint8* status, int* datavalue );
    00254 bool XBee_ReadTXStatusPacket( XBeePacket* xbp, uint8* frameID, uint8* status );
    00255
    00256 // XBee Config stuff
    00257 void XBeeConfig_SetPacketApiMode( int value );
    00258 int XBeeConfig_RequestPacketApiMode( void );
    00259 void XBeeConfig_WriteStateToMemory( void );
    00260 void XBeeConfig_SetAddress( uint16 address );
    00261 int XBeeConfig_RequestAddress( void );
    00262 void XBeeConfig_SetPanID( uint16 id );
    00263 int XBeeConfig_RequestPanID( void );
    00264 void XBeeConfig_SetChannel( uint8 channel );
    00265 int XBeeConfig_RequestChannel( void );
    00266 void XBeeConfig_SetSampleRate( uint16 rate );
    00267 int XBeeConfig_RequestSampleRate( void );
    00268 void XBeeConfig_SetIO( int index, int value );
    00269 int XBeeConfig_RequestIO( int pin );
    00270 int XBeeConfig_RequestATResponse( char* cmd );
    00271
    00272 bool XBee_GetAutoSend( bool init );
    00273 void XBee_SetAutoSend( int onoff );
    00274
    00275 void XBee_IntToBigEndianArray( int value, uint8* array );
    00276
    00277
    00278 // XBee OSC stuff
    00279 const char* XBeeOsc_GetName( void );
    00280 int XBeeOsc_ReceiveMessage( int channel, char* message, int length );
    00281 int XBeeOsc_Async( int channel );
    00282 int XBeeOsc_HandleNewPacket( XBeePacket* xbp, int channel );
    00283
    00284 const char* XBeeConfigOsc_GetName( void );
    00285 int XBeeConfigOsc_ReceiveMessage( int channel, char* message, int length );
    00286
    00287 #endif // XBEE_H

The Make Controller Kit is an open source project maintained by MakingThings.
MakingThings code is released under the Apache 2.0 license.
Bug tracker, development wiki and status can be found at http://dev.makingthings.com.
This document was last updated on 18 May 2009.