John Bailey / XBeeApi

Important changes to repositories hosted on mbed.com

Mbed hosted mercurial repositories are deprecated and are due to be permanently deleted in July 2026.

To keep a copy of this software download the repository Zip archive or clone locally using Mercurial.

It is also possible to export all your personal repositories from the account settings page.

Dependencies:   CircularBuffer FixedLengthList

Dependents:   XBeeApiTest XBeeApiSimpleATCmdsExample XBeeApiBroadcastExample XBeeApiBroadcastExampleRTOS ... more

Base/XBeeApiFrame.hpp@50:f76b7e7959a2, 2014-07-13 (annotated)

Committer:
johnb
Date:
Sun Jul 13 15:47:40 2014 +0000
Revision:
50:f76b7e7959a2
Parent:
48:48397bedf95d
Child:
51:a7d0d2ef9261
Add support for Remote AT commands

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 5:b40a6fd3a334 41 XBEE_CMD_AT_RESPONSE = 0x88,
johnb 5:b40a6fd3a334 42 XBEE_CMD_TX_STATUS = 0x89,
johnb 5:b40a6fd3a334 43 XBEE_CMD_MODEM_STATUS = 0x8A,
johnb 5:b40a6fd3a334 44 XBEE_CMD_REMOTE_AT_RESPONSE = 0x97,
johnb 5:b40a6fd3a334 45 XBEE_CMD_INVALID = 0xFFF
johnb 5:b40a6fd3a334 46 } XBeeApiIdentifier_e;
johnb 5:b40a6fd3a334 47
johnb 5:b40a6fd3a334 48 /** Position of fixed meaning bytes within the API frame, relative to the start of the frame */
johnb 5:b40a6fd3a334 49 enum
johnb 5:b40a6fd3a334 50 {
johnb 5:b40a6fd3a334 51 /** Start delimiter, should be equal to XBEE_SB_FRAME_DELIMITER */
johnb 5:b40a6fd3a334 52 XBEE_CMD_POSN_SDELIM = 0x00,
johnb 5:b40a6fd3a334 53 /** High byte of the 16-bit length field */
johnb 5:b40a6fd3a334 54 XBEE_CMD_POSN_LEN_HI = 0x01,
johnb 5:b40a6fd3a334 55 /** Low byte of the 16-bit length field */
johnb 5:b40a6fd3a334 56 XBEE_CMD_POSN_LEN_LO = 0x02,
johnb 5:b40a6fd3a334 57 /** API identifier for the data which follows - see XBeeApiIdentifier_e */
johnb 15:ff9f12e38f44 58 XBEE_CMD_POSN_API_ID = 0x03,
johnb 15:ff9f12e38f44 59 /** Start of API identifier specific data */
johnb 15:ff9f12e38f44 60 XBEE_CMD_POSN_ID_SPECIFIC_DATA = 0x04
johnb 5:b40a6fd3a334 61 };
johnb 5:b40a6fd3a334 62
johnb 5:b40a6fd3a334 63 /** Helper macro to retrieve the frame payload length (i.e. excluding overhead - see XBEE_API_FRAME_OVERHEAD) from a buffer.
johnb 5:b40a6fd3a334 64
johnb 5:b40a6fd3a334 65 \param _b Pointer to a buffer containing a received API frame.
johnb 5:b40a6fd3a334 66 \returns Length of the frame payload excluding overhead */
johnb 5:b40a6fd3a334 67 #define MSG_LEN_IN_BUFFER( _b ) ((((uint16_t)_b[ XBEE_CMD_POSN_LEN_HI ]) << 8U) + _b[XBEE_CMD_POSN_LEN_LO])
johnb 5:b40a6fd3a334 68
johnb 48:48397bedf95d 69 #define XBEE_API_FRAME_OVERHEAD_START 3U
johnb 48:48397bedf95d 70 #define XBEE_API_FRAME_OVERHEAD_END 1U
johnb 48:48397bedf95d 71
johnb 5:b40a6fd3a334 72 /** The number of 'overhead' bytes in an API frame (i.e. those not included in the frame payload, namely the start delimiter, 2 length bytes & checksum */
johnb 48:48397bedf95d 73 #define XBEE_API_FRAME_OVERHEAD (XBEE_API_FRAME_OVERHEAD_START + XBEE_API_FRAME_OVERHEAD_END)
johnb 5:b40a6fd3a334 74
johnb 16:8095c43a2a6e 75 /* Forward declare this as XBeeDevice is dependent upon XBeeApiFrameDecoder */
johnb 16:8095c43a2a6e 76 class XBeeDevice;
johnb 16:8095c43a2a6e 77
johnb 5:b40a6fd3a334 78 /** Class which represents an API frame, exchanged with the XBee.
johnb 5:b40a6fd3a334 79 This class in itself will not create a valid API frame and needs to be sub-classed.
johnb 5:b40a6fd3a334 80 */
johnb 5:b40a6fd3a334 81 class XBeeApiFrame
johnb 5:b40a6fd3a334 82 {
johnb 5:b40a6fd3a334 83 private:
johnb 5:b40a6fd3a334 84 static const uint8_t m_cmdHeaderLen = 1;
johnb 5:b40a6fd3a334 85
johnb 5:b40a6fd3a334 86 protected:
johnb 5:b40a6fd3a334 87 /** API identifier for the data in the frame */
johnb 5:b40a6fd3a334 88 XBeeApiIdentifier_e m_apiId;
johnb 5:b40a6fd3a334 89
johnb 5:b40a6fd3a334 90 /** API identifier specific data */
johnb 5:b40a6fd3a334 91 const uint8_t* m_data;
johnb 5:b40a6fd3a334 92
johnb 5:b40a6fd3a334 93 /** Length of the data pointed to by m_data */
johnb 5:b40a6fd3a334 94 uint16_t m_dataLen;
johnb 5:b40a6fd3a334 95
johnb 5:b40a6fd3a334 96 public:
johnb 5:b40a6fd3a334 97
johnb 5:b40a6fd3a334 98 /** Constructor */
johnb 5:b40a6fd3a334 99 XBeeApiFrame( void );
johnb 5:b40a6fd3a334 100
johnb 24:2cd1094c4fd7 101 /** Constructor */
johnb 24:2cd1094c4fd7 102 XBeeApiFrame( XBeeApiIdentifier_e p_id,
johnb 38:291aee9eb900 103 const uint8_t* const p_data,
johnb 38:291aee9eb900 104 const size_t p_dataLen );
johnb 24:2cd1094c4fd7 105
johnb 5:b40a6fd3a334 106 /** 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 16:8095c43a2a6e 107 virtual uint16_t getCmdLen( void ) const;
johnb 5:b40a6fd3a334 108
johnb 5:b40a6fd3a334 109 /** Retrieve the API identifier for this frame */
johnb 5:b40a6fd3a334 110 XBeeApiIdentifier_e getApiId( void ) const;
johnb 5:b40a6fd3a334 111
johnb 10:0d084d0253a7 112 /** Retrieve a pointer to the API-specific data (i.e. that which follows the API identifier in
johnb 10:0d084d0253a7 113 the frame). In *total*, getDataPtr will return sufficient data to match getCmdLen(), however
johnb 10:0d084d0253a7 114 it may be done in chunks using p_start and *p_len to control the fragmentation process.
johnb 10:0d084d0253a7 115 For example:
johnb 10:0d084d0253a7 116
johnb 10:0d084d0253a7 117 getCmdLen() == 5;
johnb 10:0d084d0253a7 118 getDataPtr( 0, &b, &l );
johnb 10:0d084d0253a7 119 l == 2; b[0] == 'a'; b[1] == 'b';
johnb 10:0d084d0253a7 120 getDataPtr( 2, &b, &l );
johnb 10:0d084d0253a7 121 l == 1; b[2] == 'c';
johnb 10:0d084d0253a7 122 getDataPtr( 3, &b, &l );
johnb 10:0d084d0253a7 123 l == 2; b[0] == 'd'; b[1] == 'e';
johnb 10:0d084d0253a7 124
johnb 10:0d084d0253a7 125 \param[in] p_start The start point within the buffer. It is only meaningful to use a non-zero
johnb 10:0d084d0253a7 126 value in the case that a previous call to getDataPtr did not return a buffer
johnb 10:0d084d0253a7 127 of length getCmdLen(), in which case p_start should be set to be the next
johnb 10:0d084d0253a7 128 byte that is required.
johnb 10:0d084d0253a7 129 \param[out] p_buff Pointer to a pointer to receive the buffer pointer
johnb 10:0d084d0253a7 130 \param[out] p_len Pointer to receive the length of the data pointed to by *p_buff */
johnb 47:5d3608835668 131 virtual void getDataPtr( const uint16_t p_start, const uint8_t** p_buff, uint16_t* const p_len ) const;
johnb 5:b40a6fd3a334 132 };
johnb 5:b40a6fd3a334 133
johnb 6:3cb62daace78 134 /** Class which acts as a receiver for data from the XBee and takes care of decoding it.
johnb 6:3cb62daace78 135 This class needs to be sub-classed in order to create a valid decoder.
johnb 6:3cb62daace78 136
johnb 6:3cb62daace78 137 An object implementing the XBeeApiFrameDecoder interface should be registered with
johnb 6:3cb62daace78 138 an XBeeDevice-type object using the registerDecoder() method. If the class destructor
johnb 6:3cb62daace78 139 is called it will automatically un-register itself from the XBeeDevice. Alternatively
johnb 6:3cb62daace78 140 unregisterDecoder() may be called */
johnb 5:b40a6fd3a334 141 class XBeeApiFrameDecoder
johnb 5:b40a6fd3a334 142 {
johnb 5:b40a6fd3a334 143 protected:
johnb 6:3cb62daace78 144 /** Pointer to the XBeeDevice with which this decoder is associated. Kept around
johnb 6:3cb62daace78 145 so that we know where to go at time of destruction and the XBeeDevice isn't
johnb 6:3cb62daace78 146 left with a pointer to an invalidated object */
johnb 5:b40a6fd3a334 147 XBeeDevice* m_device;
johnb 5:b40a6fd3a334 148
johnb 5:b40a6fd3a334 149 public:
johnb 5:b40a6fd3a334 150
johnb 6:3cb62daace78 151 /** Constructor */
johnb 16:8095c43a2a6e 152 XBeeApiFrameDecoder( XBeeDevice* const p_device = NULL );
johnb 5:b40a6fd3a334 153
johnb 6:3cb62daace78 154 /** Destructor. Un-registers the decoder from any XBeeDevice object with which it is registered */
johnb 5:b40a6fd3a334 155 virtual ~XBeeApiFrameDecoder();
johnb 5:b40a6fd3a334 156
johnb 6:3cb62daace78 157 /** XBeeDevice is a friend so that it can access registerCallback and unregisterCallback */
johnb 6:3cb62daace78 158 friend class XBeeDevice;
johnb 6:3cb62daace78 159
johnb 6:3cb62daace78 160 protected:
johnb 6:3cb62daace78 161
johnb 6:3cb62daace78 162 /** Called by an XBeeDevice object to let this object know that it's being associated with a device */
johnb 5:b40a6fd3a334 163 void registerCallback( XBeeDevice* const p_device );
johnb 5:b40a6fd3a334 164
johnb 6:3cb62daace78 165 /** Called by an XBeeDevice object to let this object know that it's no longer associated with the device */
johnb 5:b40a6fd3a334 166 void unregisterCallback( void );
johnb 6:3cb62daace78 167
johnb 6:3cb62daace78 168 /** Called by an XBeeDevice in order to give this object the opportunity to examine and decode data received
johnb 6:3cb62daace78 169 from the XBee
johnb 6:3cb62daace78 170
johnb 6:3cb62daace78 171 Note: When implementing this method in an inheriting class the method must only return true in the case that
johnb 6:3cb62daace78 172 the data was intended for and was decoded by this class. Returning true in other cases may result in
johnb 6:3cb62daace78 173 other decoders being denied the opportunity to examine the data
johnb 6:3cb62daace78 174
johnb 34:2535760d53a6 175 \param p_data Pointer to the first byte of the data buffer (i.e. XBEE_CMD_POSN_SDELIM). The implementation
johnb 34:2535760d53a6 176 of any over-riding function should not expect that the data referenced by this pointer will
johnb 34:2535760d53a6 177 remain valid after the call-back has completed.
johnb 6:3cb62daace78 178 \param p_len Size of the data pointed to by p_data
johnb 6:3cb62daace78 179 \returns true in the case that the data was examined and decoded successfully
johnb 6:3cb62daace78 180 false in the case that the data was not of interest or was not decoded successfully
johnb 6:3cb62daace78 181 */
johnb 6:3cb62daace78 182 virtual bool decodeCallback( const uint8_t* const p_data, size_t p_len ) = 0;
johnb 5:b40a6fd3a334 183 };
johnb 5:b40a6fd3a334 184
johnb 27:6356ef5fe39b 185 /** Value which represents the broadcast address */
johnb 27:6356ef5fe39b 186 #define XBEE_BROADCAST_ADDR 0xFFFF
johnb 27:6356ef5fe39b 187
johnb 50:f76b7e7959a2 188 /** Value which indicates that 64-bit addressing should be used */
johnb 50:f76b7e7959a2 189 #define XBEE_USE_64BIT_ADDR 0xFFFE
johnb 27:6356ef5fe39b 190
johnb 5:b40a6fd3a334 191 #endif