John Bailey / XBeeApi

API for communicating with XBee devices.

Dependencies:   CircularBuffer FixedLengthList

Dependents:   XBeeApiTest XBeeApiSimpleATCmdsExample XBeeApiBroadcastExample XBeeApiBroadcastExampleRTOS ... more

Overview

XBeeApi is intended to be a library for providing a high-level API interface to the XBee - for example getChannel() and setChannel(2) methods rather than needing to send( "ATCH" ) and send( "ATCH 2" ) - and then de-code the responses.

See the notebook page here for a description of how the API works & some details on the various classes.

Features:

  • Support for transmission & reception of data packets
  • Support for reading & changing settings
  • Support for "Remote AT" interface to access settings & I/O channels on remote XBees
  • XBeeApi should work if you're using mbed-rtos, though it is not currently threadsafe. Take a look at the XBeeApiBroadcastExampleRTOS example if you're including mbed-rtos.

Example Programs

There are also example programs available:

Transmit

Import programXBeeApiSimpleBroadcastExample

Simple example of how to use XBeeApi - set up the XBee, configure P2P networking then transmit a frame.

Last commit 06 Jul 2014 by John Bailey

Import programXBeeApiBroadcastExample

Example for XBeeAPI; a little more involved than XBeeApiSimpleBroadcastExample with report on failure to set up the XBee and on the transmit status of the message.

Last commit 05 Jul 2014 by John Bailey

Import programXBeeApiBroadcastExampleRTOS

Example of using the XBeeApi library to broadcast a message, based on XBeeApiBroadcastExample. This example shows how to use the library when using mbed-rtos. Before compiling you must open "XbeeApi\Config\XBeeApiCfg.hpp" and change the '#if 0' to '#if 1' on the line above the comment reading "Use RTOS features to make XBeeApi threadsafe"

Last commit 06 Jul 2014 by John Bailey

Settings/Status

Import programXBeeApiSimpleATCmdsExample

Simple example of using XBeeApi to send AT-style commands to the XBee

Last commit 31 Mar 2014 by John Bailey

Import programXBeeApiRemoteATCmdsExample

Example of using the XBeeApi library to send AT commands to remote XBee devices in order to read/write settings

Last commit 13 Jul 2014 by John Bailey

Receive

Import programXBeeApiSimpleReceiveExample

Simple example of using XBeeApi to receive data packets via wireless

Last commit 08 Jul 2014 by John Bailey

Import programXBeeApiReceiveCallbackExample

Example of using the XBeeApi library to receive a message via a callback method

Last commit 08 Jul 2014 by John Bailey

Import programXBeeApiReceiveCallbackExampleRTOS

Example of using the XBeeApi library to receive a message via a callback method. This example shows how to use the library when using mbed-rtos. See the comment at the top of main.cpp

Last commit 08 Jul 2014 by John Bailey

Remote I/O

Import programXBeeApiRemoteIOExample

Example of using the XBeeApi library to read inputs on a remote XBee

Last commit 28 Jul 2014 by John Bailey

If you have 2 mbed connected XBees available then you can use XBeeApiSimpleReceiveExample and XBeeApiSimpleBroadcastExample as a pair.

Note that this is still a work in progress! XBeeApiTodoList tracks some of the functionality still to be added.

Base/XBeeApiFrame.hpp@53:7b65422d7a32, 2014-07-28 (annotated)

Committer:
johnb
Date:
Mon Jul 28 13:27:58 2014 +0000
Revision:
53:7b65422d7a32
Parent:
51:a7d0d2ef9261 
Comments & clean-up

Who changed what in which revision?

UserRevisionLine numberNew contents of line
johnb 5:b40a6fd3a334 1 /**
johnb 5:b40a6fd3a334 2 @file
johnb 5:b40a6fd3a334 3 @brief Class to abstract commands send to the XBee API
johnb 5:b40a6fd3a334 4
johnb 5:b40a6fd3a334 5 @author John Bailey
johnb 5:b40a6fd3a334 6
johnb 5:b40a6fd3a334 7 @copyright Copyright 2013 John Bailey
johnb 5:b40a6fd3a334 8
johnb 5:b40a6fd3a334 9 @section LICENSE
johnb 5:b40a6fd3a334 10
johnb 5:b40a6fd3a334 11 Licensed under the Apache License, Version 2.0 (the "License");
johnb 5:b40a6fd3a334 12 you may not use this file except in compliance with the License.
johnb 5:b40a6fd3a334 13 You may obtain a copy of the License at
johnb 5:b40a6fd3a334 14
johnb 5:b40a6fd3a334 15 http://www.apache.org/licenses/LICENSE-2.0
johnb 5:b40a6fd3a334 16
johnb 5:b40a6fd3a334 17 Unless required by applicable law or agreed to in writing, software
johnb 5:b40a6fd3a334 18 distributed under the License is distributed on an "AS IS" BASIS,
johnb 5:b40a6fd3a334 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
johnb 5:b40a6fd3a334 20 See the License for the specific language governing permissions and
johnb 5:b40a6fd3a334 21 limitations under the License.
johnb 5:b40a6fd3a334 22
johnb 5:b40a6fd3a334 23 */
johnb 5:b40a6fd3a334 24
johnb 5:b40a6fd3a334 25 #if !defined XBEEAPICMD_HPP
johnb 5:b40a6fd3a334 26 #define XBEEAPICMD_HPP
johnb 5:b40a6fd3a334 27
johnb 5:b40a6fd3a334 28 #include <stdint.h>
johnb 5:b40a6fd3a334 29 #include <stddef.h> // for size_t
johnb 5:b40a6fd3a334 30
johnb 5:b40a6fd3a334 31 /** API identifiers - the first byte in the API-specific structure within an API frame which provides an indication as to the type of data which follows */
johnb 5:b40a6fd3a334 32 typedef enum
johnb 5:b40a6fd3a334 33 {
johnb 5:b40a6fd3a334 34 XBEE_CMD_TX_64B_ADDR = 0x00,
johnb 5:b40a6fd3a334 35 XBEE_CMD_TX_16B_ADDR = 0x01,
johnb 5:b40a6fd3a334 36 XBEE_CMD_AT_CMD = 0x08,
johnb 5:b40a6fd3a334 37 XBEE_CMD_QUEUE_PARAM_VAL = 0x09,
johnb 5:b40a6fd3a334 38 XBEE_CMD_REMOTE_AT_CMD = 0x17,
johnb 5:b40a6fd3a334 39 XBEE_CMD_RX_64B_ADDR = 0x80,
johnb 5:b40a6fd3a334 40 XBEE_CMD_RX_16B_ADDR = 0x81,
johnb 51:a7d0d2ef9261 41 XBEE_CMD_RX_64B_IO = 0x82,
johnb 51:a7d0d2ef9261 42 XBEE_CMD_RX_16B_IO = 0x83,
johnb 5:b40a6fd3a334 43 XBEE_CMD_AT_RESPONSE = 0x88,
johnb 5:b40a6fd3a334 44 XBEE_CMD_TX_STATUS = 0x89,
johnb 5:b40a6fd3a334 45 XBEE_CMD_MODEM_STATUS = 0x8A,
johnb 5:b40a6fd3a334 46 XBEE_CMD_REMOTE_AT_RESPONSE = 0x97,
johnb 5:b40a6fd3a334 47 XBEE_CMD_INVALID = 0xFFF
johnb 5:b40a6fd3a334 48 } XBeeApiIdentifier_e;
johnb 5:b40a6fd3a334 49
johnb 5:b40a6fd3a334 50 /** Position of fixed meaning bytes within the API frame, relative to the start of the frame */
johnb 5:b40a6fd3a334 51 enum
johnb 5:b40a6fd3a334 52 {
johnb 5:b40a6fd3a334 53 /** Start delimiter, should be equal to XBEE_SB_FRAME_DELIMITER */
johnb 5:b40a6fd3a334 54 XBEE_CMD_POSN_SDELIM = 0x00,
johnb 5:b40a6fd3a334 55 /** High byte of the 16-bit length field */
johnb 5:b40a6fd3a334 56 XBEE_CMD_POSN_LEN_HI = 0x01,
johnb 5:b40a6fd3a334 57 /** Low byte of the 16-bit length field */
johnb 5:b40a6fd3a334 58 XBEE_CMD_POSN_LEN_LO = 0x02,
johnb 5:b40a6fd3a334 59 /** API identifier for the data which follows - see XBeeApiIdentifier_e */
johnb 15:ff9f12e38f44 60 XBEE_CMD_POSN_API_ID = 0x03,
johnb 15:ff9f12e38f44 61 /** Start of API identifier specific data */
johnb 15:ff9f12e38f44 62 XBEE_CMD_POSN_ID_SPECIFIC_DATA = 0x04
johnb 5:b40a6fd3a334 63 };
johnb 5:b40a6fd3a334 64
johnb 5:b40a6fd3a334 65 /** Helper macro to retrieve the frame payload length (i.e. excluding overhead - see XBEE_API_FRAME_OVERHEAD) from a buffer.
johnb 5:b40a6fd3a334 66
johnb 5:b40a6fd3a334 67 \param _b Pointer to a buffer containing a received API frame.
johnb 5:b40a6fd3a334 68 \returns Length of the frame payload excluding overhead */
johnb 5:b40a6fd3a334 69 #define MSG_LEN_IN_BUFFER( _b ) ((((uint16_t)_b[ XBEE_CMD_POSN_LEN_HI ]) << 8U) + _b[XBEE_CMD_POSN_LEN_LO])
johnb 5:b40a6fd3a334 70
johnb 53:7b65422d7a32 71 /** The number of 'overhead' (i.e. those not included in the frame payload) bytes at the start of an API frame (namely the start delimiter & 2 length bytes) */
johnb 48:48397bedf95d 72 #define XBEE_API_FRAME_OVERHEAD_START 3U
johnb 53:7b65422d7a32 73
johnb 53:7b65422d7a32 74 /** The number of 'overhead' (i.e. those not included in the frame payload) bytes at the end of an API frame (namely the checksum) */
johnb 48:48397bedf95d 75 #define XBEE_API_FRAME_OVERHEAD_END 1U
johnb 48:48397bedf95d 76
johnb 53:7b65422d7a32 77 /** The total number of 'overhead' bytes in an API frame */
johnb 48:48397bedf95d 78 #define XBEE_API_FRAME_OVERHEAD (XBEE_API_FRAME_OVERHEAD_START + XBEE_API_FRAME_OVERHEAD_END)
johnb 5:b40a6fd3a334 79
johnb 16:8095c43a2a6e 80 /* Forward declare this as XBeeDevice is dependent upon XBeeApiFrameDecoder */
johnb 16:8095c43a2a6e 81 class XBeeDevice;
johnb 16:8095c43a2a6e 82
johnb 5:b40a6fd3a334 83 /** Class which represents an API frame, exchanged with the XBee.
johnb 5:b40a6fd3a334 84 This class in itself will not create a valid API frame and needs to be sub-classed.
johnb 5:b40a6fd3a334 85 */
johnb 5:b40a6fd3a334 86 class XBeeApiFrame
johnb 5:b40a6fd3a334 87 {
johnb 5:b40a6fd3a334 88 private:
johnb 53:7b65422d7a32 89 /** Length of the frame header which precedes the data - currently a single byte which is the API ID */
johnb 5:b40a6fd3a334 90 static const uint8_t m_cmdHeaderLen = 1;
johnb 5:b40a6fd3a334 91
johnb 5:b40a6fd3a334 92 protected:
johnb 5:b40a6fd3a334 93 /** API identifier for the data in the frame */
johnb 5:b40a6fd3a334 94 XBeeApiIdentifier_e m_apiId;
johnb 5:b40a6fd3a334 95
johnb 5:b40a6fd3a334 96 /** API identifier specific data */
johnb 5:b40a6fd3a334 97 const uint8_t* m_data;
johnb 5:b40a6fd3a334 98
johnb 5:b40a6fd3a334 99 /** Length of the data pointed to by m_data */
johnb 5:b40a6fd3a334 100 uint16_t m_dataLen;
johnb 5:b40a6fd3a334 101
johnb 5:b40a6fd3a334 102 public:
johnb 5:b40a6fd3a334 103
johnb 5:b40a6fd3a334 104 /** Constructor */
johnb 5:b40a6fd3a334 105 XBeeApiFrame( void );
johnb 5:b40a6fd3a334 106
johnb 24:2cd1094c4fd7 107 /** Constructor */
johnb 24:2cd1094c4fd7 108 XBeeApiFrame( XBeeApiIdentifier_e p_id,
johnb 38:291aee9eb900 109 const uint8_t* const p_data,
johnb 38:291aee9eb900 110 const size_t p_dataLen );
johnb 24:2cd1094c4fd7 111
johnb 53:7b65422d7a32 112 /** Return the length of the API-specific structure represented by this frame. i.e. the API frame without the overhead - see XBEE_API_FRAME_OVERHEAD.
johnb 53:7b65422d7a32 113 The value includes both the data which is returned by getDataPtr and the byte used to identify the type of the packet, as returned by getApiId */
johnb 16:8095c43a2a6e 114 virtual uint16_t getCmdLen( void ) const;
johnb 5:b40a6fd3a334 115
johnb 5:b40a6fd3a334 116 /** Retrieve the API identifier for this frame */
johnb 5:b40a6fd3a334 117 XBeeApiIdentifier_e getApiId( void ) const;
johnb 5:b40a6fd3a334 118
johnb 10:0d084d0253a7 119 /** Retrieve a pointer to the API-specific data (i.e. that which follows the API identifier in
johnb 10:0d084d0253a7 120 the frame). In *total*, getDataPtr will return sufficient data to match getCmdLen(), however
johnb 10:0d084d0253a7 121 it may be done in chunks using p_start and *p_len to control the fragmentation process.
johnb 10:0d084d0253a7 122 For example:
johnb 10:0d084d0253a7 123
johnb 10:0d084d0253a7 124 getCmdLen() == 5;
johnb 10:0d084d0253a7 125 getDataPtr( 0, &b, &l );
johnb 10:0d084d0253a7 126 l == 2; b[0] == 'a'; b[1] == 'b';
johnb 10:0d084d0253a7 127 getDataPtr( 2, &b, &l );
johnb 10:0d084d0253a7 128 l == 1; b[2] == 'c';
johnb 10:0d084d0253a7 129 getDataPtr( 3, &b, &l );
johnb 10:0d084d0253a7 130 l == 2; b[0] == 'd'; b[1] == 'e';
johnb 10:0d084d0253a7 131
johnb 10:0d084d0253a7 132 \param[in] p_start The start point within the buffer. It is only meaningful to use a non-zero
johnb 10:0d084d0253a7 133 value in the case that a previous call to getDataPtr did not return a buffer
johnb 10:0d084d0253a7 134 of length getCmdLen(), in which case p_start should be set to be the next
johnb 10:0d084d0253a7 135 byte that is required.
johnb 10:0d084d0253a7 136 \param[out] p_buff Pointer to a pointer to receive the buffer pointer
johnb 10:0d084d0253a7 137 \param[out] p_len Pointer to receive the length of the data pointed to by *p_buff */
johnb 47:5d3608835668 138 virtual void getDataPtr( const uint16_t p_start, const uint8_t** p_buff, uint16_t* const p_len ) const;
johnb 5:b40a6fd3a334 139 };
johnb 5:b40a6fd3a334 140
johnb 6:3cb62daace78 141 /** Class which acts as a receiver for data from the XBee and takes care of decoding it.
johnb 6:3cb62daace78 142 This class needs to be sub-classed in order to create a valid decoder.
johnb 6:3cb62daace78 143
johnb 6:3cb62daace78 144 An object implementing the XBeeApiFrameDecoder interface should be registered with
johnb 6:3cb62daace78 145 an XBeeDevice-type object using the registerDecoder() method. If the class destructor
johnb 6:3cb62daace78 146 is called it will automatically un-register itself from the XBeeDevice. Alternatively
johnb 6:3cb62daace78 147 unregisterDecoder() may be called */
johnb 5:b40a6fd3a334 148 class XBeeApiFrameDecoder
johnb 5:b40a6fd3a334 149 {
johnb 5:b40a6fd3a334 150 protected:
johnb 6:3cb62daace78 151 /** Pointer to the XBeeDevice with which this decoder is associated. Kept around
johnb 6:3cb62daace78 152 so that we know where to go at time of destruction and the XBeeDevice isn't
johnb 6:3cb62daace78 153 left with a pointer to an invalidated object */
johnb 5:b40a6fd3a334 154 XBeeDevice* m_device;
johnb 5:b40a6fd3a334 155
johnb 5:b40a6fd3a334 156 public:
johnb 5:b40a6fd3a334 157
johnb 6:3cb62daace78 158 /** Constructor */
johnb 16:8095c43a2a6e 159 XBeeApiFrameDecoder( XBeeDevice* const p_device = NULL );
johnb 5:b40a6fd3a334 160
johnb 6:3cb62daace78 161 /** Destructor. Un-registers the decoder from any XBeeDevice object with which it is registered */
johnb 5:b40a6fd3a334 162 virtual ~XBeeApiFrameDecoder();
johnb 5:b40a6fd3a334 163
johnb 6:3cb62daace78 164 /** XBeeDevice is a friend so that it can access registerCallback and unregisterCallback */
johnb 6:3cb62daace78 165 friend class XBeeDevice;
johnb 6:3cb62daace78 166
johnb 6:3cb62daace78 167 protected:
johnb 6:3cb62daace78 168
johnb 6:3cb62daace78 169 /** Called by an XBeeDevice object to let this object know that it's being associated with a device */
johnb 5:b40a6fd3a334 170 void registerCallback( XBeeDevice* const p_device );
johnb 5:b40a6fd3a334 171
johnb 6:3cb62daace78 172 /** Called by an XBeeDevice object to let this object know that it's no longer associated with the device */
johnb 5:b40a6fd3a334 173 void unregisterCallback( void );
johnb 6:3cb62daace78 174
johnb 6:3cb62daace78 175 /** Called by an XBeeDevice in order to give this object the opportunity to examine and decode data received
johnb 6:3cb62daace78 176 from the XBee
johnb 6:3cb62daace78 177
johnb 6:3cb62daace78 178 Note: When implementing this method in an inheriting class the method must only return true in the case that
johnb 6:3cb62daace78 179 the data was intended for and was decoded by this class. Returning true in other cases may result in
johnb 6:3cb62daace78 180 other decoders being denied the opportunity to examine the data
johnb 6:3cb62daace78 181
johnb 34:2535760d53a6 182 \param p_data Pointer to the first byte of the data buffer (i.e. XBEE_CMD_POSN_SDELIM). The implementation
johnb 34:2535760d53a6 183 of any over-riding function should not expect that the data referenced by this pointer will
johnb 34:2535760d53a6 184 remain valid after the call-back has completed.
johnb 6:3cb62daace78 185 \param p_len Size of the data pointed to by p_data
johnb 6:3cb62daace78 186 \returns true in the case that the data was examined and decoded successfully
johnb 6:3cb62daace78 187 false in the case that the data was not of interest or was not decoded successfully
johnb 6:3cb62daace78 188 */
johnb 6:3cb62daace78 189 virtual bool decodeCallback( const uint8_t* const p_data, size_t p_len ) = 0;
johnb 5:b40a6fd3a334 190 };
johnb 5:b40a6fd3a334 191
johnb 27:6356ef5fe39b 192 /** Value which represents the broadcast address */
johnb 27:6356ef5fe39b 193 #define XBEE_BROADCAST_ADDR 0xFFFF
johnb 27:6356ef5fe39b 194
johnb 50:f76b7e7959a2 195 /** Value which indicates that 64-bit addressing should be used */
johnb 50:f76b7e7959a2 196 #define XBEE_USE_64BIT_ADDR 0xFFFE
johnb 27:6356ef5fe39b 197
johnb 5:b40a6fd3a334 198 #endif