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.

Utility/XBeeApiCmdAt.hpp@32:af4e495afd62, 2014-02-07 (annotated)

Committer:
johnb
Date:
Fri Feb 07 21:17:32 2014 +0000
Revision:
32:af4e495afd62
Parent:
31:c144106e55b5
Child:
50:f76b7e7959a2
Add methods to access more XBee parameters.

Who changed what in which revision?

UserRevisionLine numberNew contents of line
johnb 8:1b48b619d7f6 1 /**
johnb 8:1b48b619d7f6 2 @file
johnb 8:1b48b619d7f6 3 @brief Class to abstract AT commands send to the XBee API
johnb 8:1b48b619d7f6 4
johnb 8:1b48b619d7f6 5 AT commands have the payload:
johnb 8:1b48b619d7f6 6
johnb 8:1b48b619d7f6 7 Byte 1 : Frame ID
johnb 8:1b48b619d7f6 8 Byte 2 & 3 : AT command
johnb 8:1b48b619d7f6 9 Byte 4-n : Parameter Value
johnb 8:1b48b619d7f6 10
johnb 8:1b48b619d7f6 11 @author John Bailey
johnb 8:1b48b619d7f6 12
johnb 8:1b48b619d7f6 13 @copyright Copyright 2014 John Bailey
johnb 8:1b48b619d7f6 14
johnb 8:1b48b619d7f6 15 @section LICENSE
johnb 8:1b48b619d7f6 16
johnb 8:1b48b619d7f6 17 Licensed under the Apache License, Version 2.0 (the "License");
johnb 8:1b48b619d7f6 18 you may not use this file except in compliance with the License.
johnb 8:1b48b619d7f6 19 You may obtain a copy of the License at
johnb 8:1b48b619d7f6 20
johnb 8:1b48b619d7f6 21 http://www.apache.org/licenses/LICENSE-2.0
johnb 8:1b48b619d7f6 22
johnb 8:1b48b619d7f6 23 Unless required by applicable law or agreed to in writing, software
johnb 8:1b48b619d7f6 24 distributed under the License is distributed on an "AS IS" BASIS,
johnb 8:1b48b619d7f6 25 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
johnb 8:1b48b619d7f6 26 See the License for the specific language governing permissions and
johnb 8:1b48b619d7f6 27 limitations under the License.
johnb 8:1b48b619d7f6 28
johnb 8:1b48b619d7f6 29 */
johnb 8:1b48b619d7f6 30
johnb 8:1b48b619d7f6 31 #if !defined XBEEAPICMDAT_HPP
johnb 8:1b48b619d7f6 32 #define XBEEAPICMDAT_HPP
johnb 8:1b48b619d7f6 33
johnb 8:1b48b619d7f6 34 #include "XBeeApiFrame.hpp"
johnb 8:1b48b619d7f6 35 #include "XBeeDevice.hpp"
johnb 8:1b48b619d7f6 36
johnb 8:1b48b619d7f6 37 #include <stdint.h>
johnb 8:1b48b619d7f6 38
johnb 26:f5df80e990f4 39 #define XBEE_API_CMD_SET_HEADER_LEN 3U
johnb 26:f5df80e990f4 40
johnb 26:f5df80e990f4 41 /** Class to access the configuration interface of the XBee.
johnb 26:f5df80e990f4 42 Requests to the XBee are non-blocking meaning that code
johnb 26:f5df80e990f4 43 which utilises this class must deal with the fact that
johnb 26:f5df80e990f4 44 there will be a delay between requesting the data from
johnb 26:f5df80e990f4 45 the XBee and the data being available via the API. See
johnb 26:f5df80e990f4 46 XBeeApiCmdAtBlocking for a blocking version.
johnb 26:f5df80e990f4 47
johnb 26:f5df80e990f4 48 Parameters from the XBee are cached in the object so
johnb 26:f5df80e990f4 49 subsequent requests do not need have the overhead of
johnb 26:f5df80e990f4 50 communication with the XBee */
johnb 8:1b48b619d7f6 51 class XBeeApiCmdAt : public XBeeApiFrameDecoder
johnb 8:1b48b619d7f6 52 {
johnb 13:302e7c1ea0b3 53 public:
johnb 26:f5df80e990f4 54 /** Type to represent the ID of a PAN (Personal Area Network) */
johnb 26:f5df80e990f4 55 typedef uint16_t panId_t;
johnb 26:f5df80e990f4 56 /** Type to represent a wireless channel number */
johnb 26:f5df80e990f4 57 typedef uint8_t channel_t;
johnb 32:af4e495afd62 58 /** Type to represent the different MAC modes supported by the XBee */
johnb 32:af4e495afd62 59 typedef enum {
johnb 32:af4e495afd62 60 XBEE_API_MAC_MODE_DIGI_ACK = 0,
johnb 32:af4e495afd62 61 XBEE_API_MAC_MODE_802_15_4_NO_ACK = 1,
johnb 32:af4e495afd62 62 XBEE_API_MAC_MODE_802_15_4_ACK = 2,
johnb 32:af4e495afd62 63 XBEE_API_MAC_MODE_DIGI_NO_ACK = 3,
johnb 32:af4e495afd62 64 } XBeeApiMACMode_e;
johnb 13:302e7c1ea0b3 65
johnb 8:1b48b619d7f6 66 protected:
johnb 26:f5df80e990f4 67 /** Indicates whether or not m_hwVer contains data retrieved from the XBee */
johnb 31:c144106e55b5 68 bool m_have_hwVer;
johnb 26:f5df80e990f4 69 /** Indicates whether or not m_fwVer contains data retrieved from the XBee */
johnb 31:c144106e55b5 70 bool m_have_fwVer;
johnb 26:f5df80e990f4 71 /** Indicates whether or not m_chan contains data retrieved from the XBee */
johnb 31:c144106e55b5 72 bool m_have_chan;
johnb 26:f5df80e990f4 73 /** Indicates whether or not m_PANId contains data retrieved from the XBee */
johnb 31:c144106e55b5 74 bool m_have_PANId;
johnb 26:f5df80e990f4 75 /** Indicates whether or not m_EDA contains data retrieved from the XBee */
johnb 31:c144106e55b5 76 bool m_have_EDA;
johnb 26:f5df80e990f4 77 /** Indicates whether or not m_CE contains data retrieved from the XBee */
johnb 31:c144106e55b5 78 bool m_have_CE;
johnb 31:c144106e55b5 79 bool m_have_sourceAddress;
johnb 32:af4e495afd62 80 bool m_have_snLow;
johnb 32:af4e495afd62 81 bool m_have_snHigh;
johnb 32:af4e495afd62 82 bool m_have_retries;
johnb 32:af4e495afd62 83 bool m_have_randomDelaySlots;
johnb 32:af4e495afd62 84 bool m_have_macMode;
johnb 13:302e7c1ea0b3 85
johnb 8:1b48b619d7f6 86 uint16_t m_hwVer;
johnb 8:1b48b619d7f6 87 uint16_t m_fwVer;
johnb 13:302e7c1ea0b3 88 channel_t m_chan;
johnb 13:302e7c1ea0b3 89 channel_t m_chanPend;
johnb 13:302e7c1ea0b3 90 panId_t m_PANId;
johnb 13:302e7c1ea0b3 91 panId_t m_PANIdPend;
johnb 13:302e7c1ea0b3 92 bool m_EDA;
johnb 13:302e7c1ea0b3 93 bool m_EDAPend;
johnb 13:302e7c1ea0b3 94 bool m_CE;
johnb 13:302e7c1ea0b3 95 bool m_CEPend;
johnb 31:c144106e55b5 96 uint16_t m_sourceAddress;
johnb 31:c144106e55b5 97 uint16_t m_sourceAddressPend;
johnb 32:af4e495afd62 98 uint32_t m_snLow;
johnb 32:af4e495afd62 99 uint32_t m_snHigh;
johnb 32:af4e495afd62 100 uint8_t m_retries;
johnb 32:af4e495afd62 101 uint8_t m_retriesPend;
johnb 32:af4e495afd62 102 uint8_t m_randomDelaySlots;
johnb 32:af4e495afd62 103 uint8_t m_randomDelaySlotsPend;
johnb 32:af4e495afd62 104 XBeeApiMACMode_e m_macMode;
johnb 32:af4e495afd62 105 XBeeApiMACMode_e m_macModePend;
johnb 8:1b48b619d7f6 106
johnb 26:f5df80e990f4 107 /** Template class to create an XBeeApiFrame which can be used to change
johnb 26:f5df80e990f4 108 the value of one of the XBee parameters. This class is used by the
johnb 26:f5df80e990f4 109 setXXX methods in XBeeApiCmdAt */
johnb 25:db6874b7ac4b 110 template< typename T >
johnb 25:db6874b7ac4b 111 class XBeeApiCmdAtSet : public XBeeApiFrame {
johnb 26:f5df80e990f4 112 uint8_t m_buffer[ XBEE_API_CMD_SET_HEADER_LEN + sizeof( T ) ];
johnb 13:302e7c1ea0b3 113 public:
johnb 26:f5df80e990f4 114 /** Constructor
johnb 26:f5df80e990f4 115
johnb 26:f5df80e990f4 116 \param p_data Pointer to a buffer of length 3 bytes containing a
johnb 26:f5df80e990f4 117 single byte frame ID followed by 2 bytes identifying
johnb 26:f5df80e990f4 118 the command, e.g. '0', 'V', 'R' would set up a version
johnb 26:f5df80e990f4 119 request with a frame identifier of 48 (ASCII value of
johnb 26:f5df80e990f4 120 '0').
johnb 26:f5df80e990f4 121 \param p_val New value for the parameter
johnb 26:f5df80e990f4 122 */
johnb 25:db6874b7ac4b 123 XBeeApiCmdAtSet( const uint8_t* const p_data,
johnb 25:db6874b7ac4b 124 const T p_val );
johnb 26:f5df80e990f4 125 /** Destructor */
johnb 26:f5df80e990f4 126 virtual ~XBeeApiCmdAtSet();
johnb 13:302e7c1ea0b3 127 };
johnb 13:302e7c1ea0b3 128
johnb 26:f5df80e990f4 129 /* Implement XBeeApiCmdDecoder interface */
johnb 26:f5df80e990f4 130 virtual bool decodeCallback( const uint8_t* const p_data, size_t p_len );
johnb 26:f5df80e990f4 131
johnb 8:1b48b619d7f6 132 public:
johnb 13:302e7c1ea0b3 133
johnb 29:c6d037cceb02 134 /** Constructor
johnb 29:c6d037cceb02 135
johnb 29:c6d037cceb02 136 \param p_device XBee device with which this object should be associated */
johnb 29:c6d037cceb02 137 XBeeApiCmdAt( XBeeDevice* const p_device = NULL );
johnb 26:f5df80e990f4 138
johnb 26:f5df80e990f4 139 /** Destructor */
johnb 26:f5df80e990f4 140 virtual ~XBeeApiCmdAt( void ) {};
johnb 8:1b48b619d7f6 141
johnb 26:f5df80e990f4 142 /** Request the hardware version identifier from the XBee.
johnb 26:f5df80e990f4 143 As the data is retrieved asynchronously to this call,
johnb 26:f5df80e990f4 144 once the response is received it can be accessed via
johnb 26:f5df80e990f4 145 getHardwareVersion() */
johnb 26:f5df80e990f4 146 bool requestHardwareVersion( void );
johnb 26:f5df80e990f4 147 bool requestFirmwareVersion( void );
johnb 26:f5df80e990f4 148 bool requestChannel( void );
johnb 26:f5df80e990f4 149 bool requestCoordinatorEnabled( void );
johnb 26:f5df80e990f4 150 bool requestEndDeviceAssociationEnabled( void );
johnb 26:f5df80e990f4 151 bool requestPanId( void );
johnb 31:c144106e55b5 152 bool requestSourceAddress( void );
johnb 32:af4e495afd62 153 bool requestSerialNumber( void );
johnb 32:af4e495afd62 154 /** Request the number of retries the XBee is configured to make.
johnb 32:af4e495afd62 155 Note that the 802.15.4 MAC already allows 3 retries, so this parameter
johnb 32:af4e495afd62 156 specifies an additional multiple of 3 retries
johnb 32:af4e495afd62 157 As the data is retrieved asynchronously to this call,
johnb 32:af4e495afd62 158 once the response is received it can be accessed via
johnb 32:af4e495afd62 159 getRetries()
johnb 32:af4e495afd62 160 */
johnb 32:af4e495afd62 161 bool requestRetries( void );
johnb 32:af4e495afd62 162
johnb 32:af4e495afd62 163 /** Request the minimum value of the back-off exponent in the CSMA-CA algorithm
johnb 32:af4e495afd62 164 used in collision avoidance.
johnb 32:af4e495afd62 165 */
johnb 32:af4e495afd62 166 bool requestRandomDelaySlots( void );
johnb 32:af4e495afd62 167
johnb 32:af4e495afd62 168 bool requestMacMode( void );
johnb 8:1b48b619d7f6 169
johnb 26:f5df80e990f4 170 /** Read the XBee's hardware version identifier.
johnb 26:f5df80e990f4 171
johnb 26:f5df80e990f4 172 This method does not initiate any communication with the
johnb 26:f5df80e990f4 173 XBee - the identifier must previously have been requested
johnb 26:f5df80e990f4 174 via requestHardwareVersion(). The method is non-blocking. */
johnb 26:f5df80e990f4 175 virtual bool getHardwareVersion( uint16_t* const p_ver );
johnb 26:f5df80e990f4 176
johnb 26:f5df80e990f4 177 /** Read the XBee's firmware version identifier.
johnb 26:f5df80e990f4 178
johnb 26:f5df80e990f4 179 This method does not initiate any communication with the
johnb 26:f5df80e990f4 180 XBee - the identifier must previously have been requested
johnb 26:f5df80e990f4 181 via requestFirmwareVersion(). The method is non-blocking. */
johnb 26:f5df80e990f4 182 virtual bool getFirmwareVersion( uint16_t* const p_ver );
johnb 32:af4e495afd62 183
johnb 32:af4e495afd62 184 virtual bool getSerialNumber( uint64_t* const p_sn );
johnb 13:302e7c1ea0b3 185
johnb 32:af4e495afd62 186 virtual bool getChannel( uint8_t* const p_chan );
johnb 32:af4e495afd62 187 virtual bool setChannel( uint8_t const p_chan );
johnb 8:1b48b619d7f6 188
johnb 32:af4e495afd62 189 virtual bool getCoordinatorEnabled( bool* const p_en );
johnb 32:af4e495afd62 190 virtual bool setCoordinatorEnabled( const bool p_en );
johnb 32:af4e495afd62 191
johnb 32:af4e495afd62 192 virtual bool getEndDeviceAssociationEnabled( bool* const p_en );
johnb 32:af4e495afd62 193 virtual bool setEndDeviceAssociationEnabled( const bool p_en );
johnb 13:302e7c1ea0b3 194
johnb 32:af4e495afd62 195 virtual bool getPanId( panId_t* const p_id );
johnb 32:af4e495afd62 196 virtual bool setPanId( const panId_t p_id );
johnb 32:af4e495afd62 197
johnb 32:af4e495afd62 198 virtual bool getSourceAddress( uint16_t* const p_addr );
johnb 32:af4e495afd62 199 virtual bool setSourceAddress( const uint16_t p_addr );
johnb 31:c144106e55b5 200
johnb 32:af4e495afd62 201 virtual bool getRetries( uint8_t* const p_addr );
johnb 32:af4e495afd62 202 virtual bool setRetries( const uint8_t p_addr );
johnb 31:c144106e55b5 203
johnb 32:af4e495afd62 204 virtual bool getRandomDelaySlots( uint8_t* const p_addr );
johnb 32:af4e495afd62 205 virtual bool setRandomDelaySlots( const uint8_t p_addr );
johnb 32:af4e495afd62 206
johnb 32:af4e495afd62 207 virtual bool getMacMode( XBeeApiMACMode_e* const p_mode );
johnb 32:af4e495afd62 208 virtual bool setMacMode( const XBeeApiMACMode_e p_mode );
johnb 8:1b48b619d7f6 209 };
johnb 8:1b48b619d7f6 210
johnb 26:f5df80e990f4 211 /** Class to access the configuration interface of the XBee.
johnb 26:f5df80e990f4 212 In contrast to XBeeApiCmdAt, the getXXX methods block
johnb 26:f5df80e990f4 213 until the data is received (or a timeout has occurred)
johnb 26:f5df80e990f4 214 which means that the caller doesn't have to deal with the
johnb 26:f5df80e990f4 215 asynchronous nature of the API provided by XBeeApiCmdAt.
johnb 26:f5df80e990f4 216
johnb 26:f5df80e990f4 217 It's not necessary to use any of the requestXXX methods
johnb 26:f5df80e990f4 218 (as the getXXX methods will take care of this, however
johnb 26:f5df80e990f4 219 calling a requestXXX method will effectively pre-fetch the
johnb 26:f5df80e990f4 220 data meaning that getXXX will not have to block */
johnb 8:1b48b619d7f6 221 class XBeeApiCmdAtBlocking : public XBeeApiCmdAt
johnb 8:1b48b619d7f6 222 {
johnb 8:1b48b619d7f6 223 protected:
johnb 26:f5df80e990f4 224 /** Timeout used for blocking methods in milliseconds */
johnb 8:1b48b619d7f6 225 uint16_t m_timeout;
johnb 26:f5df80e990f4 226
johnb 26:f5df80e990f4 227 /** Wait slice time while blocking. The function will
johnb 26:f5df80e990f4 228 wait_ms(m_slice) until the XBee responds with the
johnb 26:f5df80e990f4 229 data or m_timeout elapses */
johnb 8:1b48b619d7f6 230 uint16_t m_slice;
johnb 8:1b48b619d7f6 231
johnb 8:1b48b619d7f6 232 public:
johnb 26:f5df80e990f4 233 /** Constructor
johnb 26:f5df80e990f4 234
johnb 29:c6d037cceb02 235 \param p_device XBee device with which this object should
johnb 29:c6d037cceb02 236 be associated
johnb 26:f5df80e990f4 237 \param p_timeout Timeout to be used when waiting for
johnb 26:f5df80e990f4 238 data from the XBee, specified in
johnb 26:f5df80e990f4 239 milliseconds
johnb 26:f5df80e990f4 240 \param p_slice While waiting for data, blocking methods
johnb 26:f5df80e990f4 241 will call the OS wait_ms() function, using
johnb 26:f5df80e990f4 242 the value specified by p_slice */
johnb 29:c6d037cceb02 243 XBeeApiCmdAtBlocking( XBeeDevice* const p_device = NULL,
johnb 29:c6d037cceb02 244 const uint16_t p_timeout = 1000,
johnb 29:c6d037cceb02 245 const uint16_t p_slice = 100);
johnb 8:1b48b619d7f6 246
johnb 26:f5df80e990f4 247 /** Destructor */
johnb 8:1b48b619d7f6 248 virtual ~XBeeApiCmdAtBlocking( void ) {};
johnb 26:f5df80e990f4 249
johnb 8:1b48b619d7f6 250 /* Implement XBeeApiCmdAt's virtual methods */
johnb 26:f5df80e990f4 251
johnb 8:1b48b619d7f6 252 virtual bool getHardwareVersion( uint16_t* const p_ver );
johnb 8:1b48b619d7f6 253 virtual bool getFirmwareVersion( uint16_t* const p_ver );
johnb 32:af4e495afd62 254 virtual bool getSerialNumber( uint64_t* const p_sn );
johnb 13:302e7c1ea0b3 255
johnb 8:1b48b619d7f6 256 virtual bool getChannel( uint8_t* const p_chan );
johnb 13:302e7c1ea0b3 257 virtual bool setChannel( uint8_t const p_chan );
johnb 13:302e7c1ea0b3 258
johnb 13:302e7c1ea0b3 259 virtual bool getCoordinatorEnabled( bool* constp_en );
johnb 13:302e7c1ea0b3 260 virtual bool setCoordinatorEnabled( const bool p_en );
johnb 8:1b48b619d7f6 261
johnb 13:302e7c1ea0b3 262 virtual bool getEndDeviceAssociationEnabled( bool* const p_en );
johnb 13:302e7c1ea0b3 263 virtual bool setEndDeviceAssociationEnabled( const bool p_en );
johnb 13:302e7c1ea0b3 264
johnb 13:302e7c1ea0b3 265 virtual bool getPanId( panId_t* const p_id );
johnb 26:f5df80e990f4 266 virtual bool setPanId( const panId_t p_id );
johnb 31:c144106e55b5 267
johnb 31:c144106e55b5 268 virtual bool getSourceAddress( uint16_t* const p_addr );
johnb 32:af4e495afd62 269 virtual bool setSourceAddress( const uint16_t p_addr );
johnb 32:af4e495afd62 270
johnb 32:af4e495afd62 271 virtual bool getRetries( uint8_t* const p_addr );
johnb 32:af4e495afd62 272 virtual bool setRetries( const uint8_t p_addr );
johnb 32:af4e495afd62 273
johnb 32:af4e495afd62 274 virtual bool getRandomDelaySlots( uint8_t* const p_addr );
johnb 32:af4e495afd62 275 virtual bool setRandomDelaySlots( const uint8_t p_addr );
johnb 32:af4e495afd62 276
johnb 32:af4e495afd62 277 virtual bool getMacMode( XBeeApiMACMode_e* const p_mode );
johnb 32:af4e495afd62 278 virtual bool setMacMode( const XBeeApiMACMode_e p_mode );
johnb 8:1b48b619d7f6 279 };
johnb 8:1b48b619d7f6 280
johnb 8:1b48b619d7f6 281 #endif