John Bailey
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/XBeeDevice.hpp@41:07cb97b44e81, 2014-07-05 (annotated)
- Committer:
- johnb
- Date:
- Sat Jul 05 15:33:04 2014 +0000
- Revision:
- 41:07cb97b44e81
- Parent:
- 33:eccf4725930c
- Child:
- 42:81c789ba4c08
Change from Serial to RawSerial so that the library is RTOS friendly.
Who changed what in which revision?
| User | Revision | Line number | New contents of line |
|---|---|---|---|
| johnb | 3:c3d96b94041a | 1 | /** |
| johnb | 3:c3d96b94041a | 2 | @file |
| johnb | 3:c3d96b94041a | 3 | @brief Class to abstract the XBee serial interface |
| johnb | 3:c3d96b94041a | 4 | |
| johnb | 3:c3d96b94041a | 5 | @author John Bailey |
| johnb | 3:c3d96b94041a | 6 | |
| johnb | 3:c3d96b94041a | 7 | @copyright Copyright 2014 John Bailey |
| johnb | 3:c3d96b94041a | 8 | |
| johnb | 3:c3d96b94041a | 9 | @section LICENSE |
| johnb | 3:c3d96b94041a | 10 | |
| johnb | 3:c3d96b94041a | 11 | Licensed under the Apache License, Version 2.0 (the "License"); |
| johnb | 3:c3d96b94041a | 12 | you may not use this file except in compliance with the License. |
| johnb | 3:c3d96b94041a | 13 | You may obtain a copy of the License at |
| johnb | 3:c3d96b94041a | 14 | |
| johnb | 3:c3d96b94041a | 15 | http://www.apache.org/licenses/LICENSE-2.0 |
| johnb | 3:c3d96b94041a | 16 | |
| johnb | 3:c3d96b94041a | 17 | Unless required by applicable law or agreed to in writing, software |
| johnb | 3:c3d96b94041a | 18 | distributed under the License is distributed on an "AS IS" BASIS, |
| johnb | 3:c3d96b94041a | 19 | WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| johnb | 3:c3d96b94041a | 20 | See the License for the specific language governing permissions and |
| johnb | 3:c3d96b94041a | 21 | limitations under the License. |
| johnb | 3:c3d96b94041a | 22 | |
| johnb | 3:c3d96b94041a | 23 | */ |
| johnb | 3:c3d96b94041a | 24 | |
| johnb | 3:c3d96b94041a | 25 | #if !defined XBEEDEVICE_HPP |
| johnb | 3:c3d96b94041a | 26 | #define XBEEDEVICE_HPP |
| johnb | 3:c3d96b94041a | 27 | |
| johnb | 3:c3d96b94041a | 28 | #include "XBeeApiCfg.hpp" |
| johnb | 3:c3d96b94041a | 29 | |
| johnb | 3:c3d96b94041a | 30 | #include "mbed.h" // For serial interface |
| johnb | 3:c3d96b94041a | 31 | #if defined XBEEAPI_CONFIG_USING_RTOS |
| johnb | 3:c3d96b94041a | 32 | #include "rtos.h" // Mutex support |
| johnb | 3:c3d96b94041a | 33 | #endif |
| johnb | 3:c3d96b94041a | 34 | |
| johnb | 3:c3d96b94041a | 35 | #include "FixedLengthList.hpp" |
| johnb | 3:c3d96b94041a | 36 | #include "CircularBuffer.h" |
| johnb | 3:c3d96b94041a | 37 | |
| johnb | 3:c3d96b94041a | 38 | #include "XBeeApiFrame.hpp" |
| johnb | 3:c3d96b94041a | 39 | |
| johnb | 3:c3d96b94041a | 40 | /** Class to represent an XBee device & provide an interface to communicate with it |
| johnb | 3:c3d96b94041a | 41 | |
| johnb | 3:c3d96b94041a | 42 | Actual communication is performed by: |
| johnb | 3:c3d96b94041a | 43 | tx - using SendFrame to transmit messages to the XBee |
| johnb | 3:c3d96b94041a | 44 | rx - registering one or more decoders (via registerDecoder) to be called when |
| johnb | 3:c3d96b94041a | 45 | a message is received */ |
| johnb | 3:c3d96b94041a | 46 | class XBeeDevice |
| johnb | 3:c3d96b94041a | 47 | { |
| johnb | 29:c6d037cceb02 | 48 | public: |
| johnb | 29:c6d037cceb02 | 49 | /** Represent the different XBee models */ |
| johnb | 29:c6d037cceb02 | 50 | typedef enum { |
| johnb | 29:c6d037cceb02 | 51 | /* XBee S1 (aka XBee 802.15.4) - see http://www.digi.com/products/wireless-wired-embedded-solutions/zigbee-rf-modules/point-multipoint-rfmodules/xbee-series1-module */ |
| johnb | 29:c6d037cceb02 | 52 | XBEEDEVICE_S1, |
| johnb | 29:c6d037cceb02 | 53 | /* XBee S1 Pro (aka XBee 802.15.4 Pro) */ |
| johnb | 29:c6d037cceb02 | 54 | XBEEDEVICE_S1_PRO |
| johnb | 29:c6d037cceb02 | 55 | } XBeeDeviceModel_t; |
| johnb | 29:c6d037cceb02 | 56 | |
| johnb | 3:c3d96b94041a | 57 | private: |
| johnb | 3:c3d96b94041a | 58 | |
| johnb | 33:eccf4725930c | 59 | /** Common class initialisation, shared between constructors */ |
| johnb | 33:eccf4725930c | 60 | void init( void ); |
| johnb | 33:eccf4725930c | 61 | |
| johnb | 3:c3d96b94041a | 62 | #if defined XBEEAPI_CONFIG_USING_RTOS |
| johnb | 3:c3d96b94041a | 63 | /** Mutex for accessing the serial interface */ |
| johnb | 3:c3d96b94041a | 64 | rtos::Mutex m_ifMutex; |
| johnb | 3:c3d96b94041a | 65 | #endif |
| johnb | 3:c3d96b94041a | 66 | |
| johnb | 29:c6d037cceb02 | 67 | /** The model of XBee that this XBeeDevice is associated with */ |
| johnb | 29:c6d037cceb02 | 68 | XBeeDeviceModel_t m_model; |
| johnb | 29:c6d037cceb02 | 69 | |
| johnb | 3:c3d96b94041a | 70 | /** Track whether the XBee is in CMD mode or API mode */ |
| johnb | 3:c3d96b94041a | 71 | bool m_inAtCmdMode; |
| johnb | 3:c3d96b94041a | 72 | |
| johnb | 3:c3d96b94041a | 73 | /** Track whether or not the last byte received from the XBee was an escape (i.e. the |
| johnb | 3:c3d96b94041a | 74 | next incoming byte needs to be un-escaped) */ |
| johnb | 3:c3d96b94041a | 75 | uint16_t m_rxMsgLastWasEsc; |
| johnb | 3:c3d96b94041a | 76 | |
| johnb | 41:07cb97b44e81 | 77 | /** Serial interface for the XBee comms |
| johnb | 41:07cb97b44e81 | 78 | Use RawSerial rather than Serial so that we're OK if the RTOS is used */ |
| johnb | 41:07cb97b44e81 | 79 | RawSerial* m_if; |
| johnb | 33:eccf4725930c | 80 | |
| johnb | 33:eccf4725930c | 81 | /** Flag to indicate if the Serial object m_if was created by this class and |
| johnb | 33:eccf4725930c | 82 | hence needs deleting in the destructor */ |
| johnb | 33:eccf4725930c | 83 | bool m_serialNeedsDelete; |
| johnb | 3:c3d96b94041a | 84 | |
| johnb | 3:c3d96b94041a | 85 | /** Call-back function from MBED triggered when data is |
| johnb | 3:c3d96b94041a | 86 | received on the XBee's serial interface */ |
| johnb | 3:c3d96b94041a | 87 | void if_rx( void ); |
| johnb | 3:c3d96b94041a | 88 | |
| johnb | 3:c3d96b94041a | 89 | /** Helper function to determine whether or not there's a message to decode and to |
| johnb | 3:c3d96b94041a | 90 | offer it round any registered decoders */ |
| johnb | 3:c3d96b94041a | 91 | void checkRxDecode( void ); |
| johnb | 3:c3d96b94041a | 92 | |
| johnb | 3:c3d96b94041a | 93 | /** Write a byte to the XBee serial interface, taking care of any |
| johnb | 3:c3d96b94041a | 94 | escaping requirements (see m_escape) |
| johnb | 3:c3d96b94041a | 95 | |
| johnb | 3:c3d96b94041a | 96 | @param p_byte Byte to be written |
| johnb | 3:c3d96b94041a | 97 | @return Sum of the byte(s) written - to be addded to the checksum |
| johnb | 3:c3d96b94041a | 98 | */ |
| johnb | 3:c3d96b94041a | 99 | uint8_t xbeeWrite( uint8_t p_byte, bool p_doEscape = true ); |
| johnb | 3:c3d96b94041a | 100 | |
| johnb | 3:c3d96b94041a | 101 | /** Flag to indicate whether or not the dataflow is currentl being escaped */ |
| johnb | 3:c3d96b94041a | 102 | bool m_escape; |
| johnb | 3:c3d96b94041a | 103 | |
| johnb | 3:c3d96b94041a | 104 | /** Buffer of bytes received from the XBee so far */ |
| johnb | 3:c3d96b94041a | 105 | CircularBuffer<XBEEAPI_CONFIG_RX_BUFFER_SIZE> m_rxBuff; |
| johnb | 3:c3d96b94041a | 106 | |
| johnb | 3:c3d96b94041a | 107 | /** List of objects which are registered to de-code received frames */ |
| johnb | 3:c3d96b94041a | 108 | FixedLengthList<XBeeApiFrameDecoder*, XBEEAPI_CONFIG_DECODER_LIST_SIZE> m_decoders; |
| johnb | 3:c3d96b94041a | 109 | |
| johnb | 3:c3d96b94041a | 110 | public: |
| johnb | 3:c3d96b94041a | 111 | |
| johnb | 3:c3d96b94041a | 112 | /** Represent the status of an XBee message exchange */ |
| johnb | 3:c3d96b94041a | 113 | typedef enum { |
| johnb | 3:c3d96b94041a | 114 | /** Successful communication */ |
| johnb | 3:c3d96b94041a | 115 | XBEEDEVICE_OK = 0, |
| johnb | 3:c3d96b94041a | 116 | /** No response received from the XBee within the expected time */ |
| johnb | 3:c3d96b94041a | 117 | XBEEDEVICE_TIMEOUT = 1, |
| johnb | 3:c3d96b94041a | 118 | /** Data received from the XBee, but was of the wrong length */ |
| johnb | 3:c3d96b94041a | 119 | XBEEDEVICE_UNEXPECTED_LENGTH = 2, |
| johnb | 3:c3d96b94041a | 120 | /** Data received from the XBee was in an unexpected format */ |
| johnb | 3:c3d96b94041a | 121 | XBEEDEVICE_UNEXPECTED_DATA = 3, |
| johnb | 3:c3d96b94041a | 122 | /** XBee is currently in the wrong mode to support this request (e.g. requesting AT ASCII |
| johnb | 3:c3d96b94041a | 123 | communications when in API mode) */ |
| johnb | 3:c3d96b94041a | 124 | XBEEDEVICE_WRONG_MODE = 4, |
| johnb | 3:c3d96b94041a | 125 | } XBeeDeviceReturn_t; |
| johnb | 3:c3d96b94041a | 126 | |
| johnb | 12:58319a467943 | 127 | /** Represents the different types of addressing for XBee devices */ |
| johnb | 12:58319a467943 | 128 | typedef enum { |
| johnb | 12:58319a467943 | 129 | XBEE_API_ADDR_TYPE_16BIT = 0, |
| johnb | 12:58319a467943 | 130 | XBEE_API_ADDR_TYPE_64BIT = 1 |
| johnb | 12:58319a467943 | 131 | } XBeeApiAddrType_t; |
| johnb | 12:58319a467943 | 132 | |
| johnb | 3:c3d96b94041a | 133 | /** Constructor. Parameters are used to specify the particulars of the connection to the XBee |
| johnb | 3:c3d96b94041a | 134 | |
| johnb | 29:c6d037cceb02 | 135 | Objects using this constructor will default to be associated with an XBee S1 (see XBeeDeviceModel_t). |
| johnb | 29:c6d037cceb02 | 136 | This should be altered via setXBeeModel() if required |
| johnb | 29:c6d037cceb02 | 137 | |
| johnb | 3:c3d96b94041a | 138 | @param p_tx Serial interface TX pin |
| johnb | 3:c3d96b94041a | 139 | @param p_rx Serial interface RX pin |
| johnb | 3:c3d96b94041a | 140 | @param p_rts Pin to use for RTS (flow control). Will only be used if supported. Can specify NC to disable. |
| johnb | 3:c3d96b94041a | 141 | @param p_rts Pin to use for CTS (flow control). Will only be used if supported. Can specify NC to disable. |
| johnb | 3:c3d96b94041a | 142 | */ |
| johnb | 3:c3d96b94041a | 143 | XBeeDevice( PinName p_tx, PinName p_rx, PinName p_rts, PinName p_cts ); |
| johnb | 3:c3d96b94041a | 144 | |
| johnb | 33:eccf4725930c | 145 | /** Constructor. Parameters are used to specify the particulars of the connection to the XBee |
| johnb | 33:eccf4725930c | 146 | |
| johnb | 33:eccf4725930c | 147 | Objects using this constructor will default to be associated with an XBee S1 (see XBeeDeviceModel_t). |
| johnb | 33:eccf4725930c | 148 | This should be altered via setXBeeModel() if required |
| johnb | 33:eccf4725930c | 149 | |
| johnb | 33:eccf4725930c | 150 | @param p_serialIf Pointer to the serial interface to be used to communicate with the XBee. |
| johnb | 33:eccf4725930c | 151 | The referenced object must remain valid for as long as the XBeeDevice object is |
| johnb | 33:eccf4725930c | 152 | being used. Must not be NULL. |
| johnb | 33:eccf4725930c | 153 | */ |
| johnb | 41:07cb97b44e81 | 154 | XBeeDevice( RawSerial* p_serialIf ); |
| johnb | 33:eccf4725930c | 155 | |
| johnb | 29:c6d037cceb02 | 156 | /** Destructor */ |
| johnb | 3:c3d96b94041a | 157 | virtual ~XBeeDevice( void ); |
| johnb | 3:c3d96b94041a | 158 | |
| johnb | 29:c6d037cceb02 | 159 | /** Determine what type of XBee model this object is associated with */ |
| johnb | 29:c6d037cceb02 | 160 | XBeeDeviceModel_t getXBeeModel() const; |
| johnb | 29:c6d037cceb02 | 161 | |
| johnb | 29:c6d037cceb02 | 162 | /** Set the type of XBee model this object is associated with */ |
| johnb | 29:c6d037cceb02 | 163 | void setXBeeModel( const XBeeDeviceModel_t p_model ); |
| johnb | 29:c6d037cceb02 | 164 | |
| johnb | 5:b40a6fd3a334 | 165 | /** Transmit the specified frame to the XBee. This method does not block waiting for a response, but returns and |
| johnb | 5:b40a6fd3a334 | 166 | expects that any response will be dealt with by an appropriately registered decoder |
| johnb | 5:b40a6fd3a334 | 167 | |
| johnb | 5:b40a6fd3a334 | 168 | The XBee represents frames as: |
| johnb | 5:b40a6fd3a334 | 169 | |
| johnb | 5:b40a6fd3a334 | 170 | -------------------------------------------------------------------------- |
| johnb | 5:b40a6fd3a334 | 171 | | Start Delimiter | Length | API identifier | ID specific data | Checksum | |
| johnb | 5:b40a6fd3a334 | 172 | | 1 byte | 2 bytes | 1 byte | x bytes | 1 byte | |
| johnb | 5:b40a6fd3a334 | 173 | | 0x7e | MSB LSB | APIID | ... ... ... | CKSUM | |
| johnb | 5:b40a6fd3a334 | 174 | -------------------------------------------------------------------------- |
| johnb | 5:b40a6fd3a334 | 175 | |
| johnb | 5:b40a6fd3a334 | 176 | The method uses the XBeeApiFrame class methods to fill in the length, API ID & data. |
| johnb | 3:c3d96b94041a | 177 | |
| johnb | 3:c3d96b94041a | 178 | \param p_cmd Frame to be transmitted |
| johnb | 3:c3d96b94041a | 179 | */ |
| johnb | 16:8095c43a2a6e | 180 | void SendFrame( XBeeApiFrame* const p_cmd ); |
| johnb | 3:c3d96b94041a | 181 | |
| johnb | 3:c3d96b94041a | 182 | /** Set the XBee up in API mode. Note that this method needs to know something about the way in which the |
| johnb | 3:c3d96b94041a | 183 | attached XBee is configured (namely the guard time). This is configured via XBeeApiCmd.hpp, currently */ |
| johnb | 3:c3d96b94041a | 184 | XBeeDeviceReturn_t setUpApi( void ); |
| johnb | 3:c3d96b94041a | 185 | |
| johnb | 3:c3d96b94041a | 186 | /** Register an object as being interested in decoding messages from the XBee. Note that each |
| johnb | 3:c3d96b94041a | 187 | decoder MUST only be registered with ONE XBeeDevice. |
| johnb | 3:c3d96b94041a | 188 | |
| johnb | 3:c3d96b94041a | 189 | \param p_decoder Decoder to be registered |
| johnb | 3:c3d96b94041a | 190 | \returns true in the case that registration was successful, false otherwise (decoder list full, decoder already registered, etc) */ |
| johnb | 3:c3d96b94041a | 191 | bool registerDecoder( XBeeApiFrameDecoder* const p_decoder ); |
| johnb | 3:c3d96b94041a | 192 | |
| johnb | 3:c3d96b94041a | 193 | /** Remove a previous registration for decoding of messages. The decoder will be removed from |
| johnb | 3:c3d96b94041a | 194 | the list and no-longer called when XBee data is received |
| johnb | 3:c3d96b94041a | 195 | |
| johnb | 3:c3d96b94041a | 196 | \param p_decoder Decoder to be unregistered |
| johnb | 3:c3d96b94041a | 197 | \returns true in the case that unregistration was successful, false otherwise (decoder not in list) */ |
| johnb | 3:c3d96b94041a | 198 | bool unregisterDecoder( XBeeApiFrameDecoder* const p_decoder ); |
| johnb | 3:c3d96b94041a | 199 | |
| johnb | 3:c3d96b94041a | 200 | #if defined XBEEAPI_CONFIG_ENABLE_DEVELOPER |
| johnb | 3:c3d96b94041a | 201 | void dumpRxBuffer( Stream* p_buf, const bool p_hexView ); |
| johnb | 3:c3d96b94041a | 202 | #endif |
| johnb | 3:c3d96b94041a | 203 | |
| johnb | 3:c3d96b94041a | 204 | protected: |
| johnb | 3:c3d96b94041a | 205 | /** Send an ASCII frame to the XBee. This method blocks until a response is received |
| johnb | 3:c3d96b94041a | 206 | or a timeout occurs. |
| johnb | 3:c3d96b94041a | 207 | |
| johnb | 3:c3d96b94041a | 208 | Note that this is a protected method as it is here to support setUpApi() with regard |
| johnb | 3:c3d96b94041a | 209 | to getting the XBee into API mode. It's not intended to be used for general |
| johnb | 3:c3d96b94041a | 210 | communication with the XBee. |
| johnb | 3:c3d96b94041a | 211 | |
| johnb | 3:c3d96b94041a | 212 | \param p_dat ASCII data to be sent |
| johnb | 3:c3d96b94041a | 213 | \param p_len Length of the data pointed to by p_dat |
| johnb | 3:c3d96b94041a | 214 | \param p_wait_ms Time to wait for a response |
| johnb | 3:c3d96b94041a | 215 | */ |
| johnb | 3:c3d96b94041a | 216 | XBeeDeviceReturn_t SendFrame( const char* const p_dat, size_t p_len, int p_wait_ms = 1000 ); |
| johnb | 3:c3d96b94041a | 217 | |
| johnb | 3:c3d96b94041a | 218 | |
| johnb | 3:c3d96b94041a | 219 | |
| johnb | 3:c3d96b94041a | 220 | }; |
| johnb | 3:c3d96b94041a | 221 | |
| johnb | 3:c3d96b94041a | 222 | #endif |