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/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?

UserRevisionLine numberNew 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