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.

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.

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"

Settings/Status

Import programXBeeApiSimpleATCmdsExample

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

Import programXBeeApiRemoteATCmdsExample

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

Receive

Import programXBeeApiSimpleReceiveExample

Simple example of using XBeeApi to receive data packets via wireless

Import programXBeeApiReceiveCallbackExample

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

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

Remote I/O

Import programXBeeApiRemoteIOExample

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

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.

Committer:
johnb
Date:
Tue Feb 04 23:52:50 2014 +0000
Revision:
16:8095c43a2a6e
Parent:
12:58319a467943
Child:
29:c6d037cceb02
Flesh out XBeeApiTXFrame and add XBeeApiTxFrameEx

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 3:c3d96b94041a 48 private:
johnb 3:c3d96b94041a 49
johnb 3:c3d96b94041a 50 #if defined XBEEAPI_CONFIG_USING_RTOS
johnb 3:c3d96b94041a 51 /** Mutex for accessing the serial interface */
johnb 3:c3d96b94041a 52 rtos::Mutex m_ifMutex;
johnb 3:c3d96b94041a 53 #endif
johnb 3:c3d96b94041a 54
johnb 3:c3d96b94041a 55 /** Track whether the XBee is in CMD mode or API mode */
johnb 3:c3d96b94041a 56 bool m_inAtCmdMode;
johnb 3:c3d96b94041a 57
johnb 3:c3d96b94041a 58 /** Track whether or not the last byte received from the XBee was an escape (i.e. the
johnb 3:c3d96b94041a 59 next incoming byte needs to be un-escaped) */
johnb 3:c3d96b94041a 60 uint16_t m_rxMsgLastWasEsc;
johnb 3:c3d96b94041a 61
johnb 3:c3d96b94041a 62 /** Serial interface for the XBee comms */
johnb 3:c3d96b94041a 63 Serial m_if;
johnb 3:c3d96b94041a 64
johnb 3:c3d96b94041a 65 /** Call-back function from MBED triggered when data is
johnb 3:c3d96b94041a 66 received on the XBee's serial interface */
johnb 3:c3d96b94041a 67 void if_rx( void );
johnb 3:c3d96b94041a 68
johnb 3:c3d96b94041a 69 /** Helper function to determine whether or not there's a message to decode and to
johnb 3:c3d96b94041a 70 offer it round any registered decoders */
johnb 3:c3d96b94041a 71 void checkRxDecode( void );
johnb 3:c3d96b94041a 72
johnb 3:c3d96b94041a 73 /** Write a byte to the XBee serial interface, taking care of any
johnb 3:c3d96b94041a 74 escaping requirements (see m_escape)
johnb 3:c3d96b94041a 75
johnb 3:c3d96b94041a 76 @param p_byte Byte to be written
johnb 3:c3d96b94041a 77 @return Sum of the byte(s) written - to be addded to the checksum
johnb 3:c3d96b94041a 78 */
johnb 3:c3d96b94041a 79 uint8_t xbeeWrite( uint8_t p_byte, bool p_doEscape = true );
johnb 3:c3d96b94041a 80
johnb 3:c3d96b94041a 81 /** Flag to indicate whether or not the dataflow is currentl being escaped */
johnb 3:c3d96b94041a 82 bool m_escape;
johnb 3:c3d96b94041a 83
johnb 3:c3d96b94041a 84 /** Buffer of bytes received from the XBee so far */
johnb 3:c3d96b94041a 85 CircularBuffer<XBEEAPI_CONFIG_RX_BUFFER_SIZE> m_rxBuff;
johnb 3:c3d96b94041a 86
johnb 3:c3d96b94041a 87 /** List of objects which are registered to de-code received frames */
johnb 3:c3d96b94041a 88 FixedLengthList<XBeeApiFrameDecoder*, XBEEAPI_CONFIG_DECODER_LIST_SIZE> m_decoders;
johnb 3:c3d96b94041a 89
johnb 3:c3d96b94041a 90 public:
johnb 3:c3d96b94041a 91
johnb 3:c3d96b94041a 92 /** Represent the status of an XBee message exchange */
johnb 3:c3d96b94041a 93 typedef enum {
johnb 3:c3d96b94041a 94 /** Successful communication */
johnb 3:c3d96b94041a 95 XBEEDEVICE_OK = 0,
johnb 3:c3d96b94041a 96 /** No response received from the XBee within the expected time */
johnb 3:c3d96b94041a 97 XBEEDEVICE_TIMEOUT = 1,
johnb 3:c3d96b94041a 98 /** Data received from the XBee, but was of the wrong length */
johnb 3:c3d96b94041a 99 XBEEDEVICE_UNEXPECTED_LENGTH = 2,
johnb 3:c3d96b94041a 100 /** Data received from the XBee was in an unexpected format */
johnb 3:c3d96b94041a 101 XBEEDEVICE_UNEXPECTED_DATA = 3,
johnb 3:c3d96b94041a 102 /** XBee is currently in the wrong mode to support this request (e.g. requesting AT ASCII
johnb 3:c3d96b94041a 103 communications when in API mode) */
johnb 3:c3d96b94041a 104 XBEEDEVICE_WRONG_MODE = 4,
johnb 3:c3d96b94041a 105 } XBeeDeviceReturn_t;
johnb 3:c3d96b94041a 106
johnb 12:58319a467943 107 /** Represents the different types of addressing for XBee devices */
johnb 12:58319a467943 108 typedef enum {
johnb 12:58319a467943 109 XBEE_API_ADDR_TYPE_16BIT = 0,
johnb 12:58319a467943 110 XBEE_API_ADDR_TYPE_64BIT = 1
johnb 12:58319a467943 111 } XBeeApiAddrType_t;
johnb 12:58319a467943 112
johnb 3:c3d96b94041a 113 /** Constructor. Parameters are used to specify the particulars of the connection to the XBee
johnb 3:c3d96b94041a 114
johnb 3:c3d96b94041a 115 @param p_tx Serial interface TX pin
johnb 3:c3d96b94041a 116 @param p_rx Serial interface RX pin
johnb 3:c3d96b94041a 117 @param p_rts Pin to use for RTS (flow control). Will only be used if supported. Can specify NC to disable.
johnb 3:c3d96b94041a 118 @param p_rts Pin to use for CTS (flow control). Will only be used if supported. Can specify NC to disable.
johnb 3:c3d96b94041a 119 */
johnb 3:c3d96b94041a 120 XBeeDevice( PinName p_tx, PinName p_rx, PinName p_rts, PinName p_cts );
johnb 3:c3d96b94041a 121
johnb 3:c3d96b94041a 122 virtual ~XBeeDevice( void );
johnb 3:c3d96b94041a 123
johnb 5:b40a6fd3a334 124 /** Transmit the specified frame to the XBee. This method does not block waiting for a response, but returns and
johnb 5:b40a6fd3a334 125 expects that any response will be dealt with by an appropriately registered decoder
johnb 5:b40a6fd3a334 126
johnb 5:b40a6fd3a334 127 The XBee represents frames as:
johnb 5:b40a6fd3a334 128
johnb 5:b40a6fd3a334 129 --------------------------------------------------------------------------
johnb 5:b40a6fd3a334 130 | Start Delimiter | Length | API identifier | ID specific data | Checksum |
johnb 5:b40a6fd3a334 131 | 1 byte | 2 bytes | 1 byte | x bytes | 1 byte |
johnb 5:b40a6fd3a334 132 | 0x7e | MSB LSB | APIID | ... ... ... | CKSUM |
johnb 5:b40a6fd3a334 133 --------------------------------------------------------------------------
johnb 5:b40a6fd3a334 134
johnb 5:b40a6fd3a334 135 The method uses the XBeeApiFrame class methods to fill in the length, API ID & data.
johnb 3:c3d96b94041a 136
johnb 3:c3d96b94041a 137 \param p_cmd Frame to be transmitted
johnb 3:c3d96b94041a 138 */
johnb 16:8095c43a2a6e 139 void SendFrame( XBeeApiFrame* const p_cmd );
johnb 3:c3d96b94041a 140
johnb 3:c3d96b94041a 141 /** Set the XBee up in API mode. Note that this method needs to know something about the way in which the
johnb 3:c3d96b94041a 142 attached XBee is configured (namely the guard time). This is configured via XBeeApiCmd.hpp, currently */
johnb 3:c3d96b94041a 143 XBeeDeviceReturn_t setUpApi( void );
johnb 3:c3d96b94041a 144
johnb 3:c3d96b94041a 145 /** Register an object as being interested in decoding messages from the XBee. Note that each
johnb 3:c3d96b94041a 146 decoder MUST only be registered with ONE XBeeDevice.
johnb 3:c3d96b94041a 147
johnb 3:c3d96b94041a 148 \param p_decoder Decoder to be registered
johnb 3:c3d96b94041a 149 \returns true in the case that registration was successful, false otherwise (decoder list full, decoder already registered, etc) */
johnb 3:c3d96b94041a 150 bool registerDecoder( XBeeApiFrameDecoder* const p_decoder );
johnb 3:c3d96b94041a 151
johnb 3:c3d96b94041a 152 /** Remove a previous registration for decoding of messages. The decoder will be removed from
johnb 3:c3d96b94041a 153 the list and no-longer called when XBee data is received
johnb 3:c3d96b94041a 154
johnb 3:c3d96b94041a 155 \param p_decoder Decoder to be unregistered
johnb 3:c3d96b94041a 156 \returns true in the case that unregistration was successful, false otherwise (decoder not in list) */
johnb 3:c3d96b94041a 157 bool unregisterDecoder( XBeeApiFrameDecoder* const p_decoder );
johnb 3:c3d96b94041a 158
johnb 3:c3d96b94041a 159 #if defined XBEEAPI_CONFIG_ENABLE_DEVELOPER
johnb 3:c3d96b94041a 160 void dumpRxBuffer( Stream* p_buf, const bool p_hexView );
johnb 3:c3d96b94041a 161 #endif
johnb 3:c3d96b94041a 162
johnb 3:c3d96b94041a 163 protected:
johnb 3:c3d96b94041a 164 /** Send an ASCII frame to the XBee. This method blocks until a response is received
johnb 3:c3d96b94041a 165 or a timeout occurs.
johnb 3:c3d96b94041a 166
johnb 3:c3d96b94041a 167 Note that this is a protected method as it is here to support setUpApi() with regard
johnb 3:c3d96b94041a 168 to getting the XBee into API mode. It's not intended to be used for general
johnb 3:c3d96b94041a 169 communication with the XBee.
johnb 3:c3d96b94041a 170
johnb 3:c3d96b94041a 171 \param p_dat ASCII data to be sent
johnb 3:c3d96b94041a 172 \param p_len Length of the data pointed to by p_dat
johnb 3:c3d96b94041a 173 \param p_wait_ms Time to wait for a response
johnb 3:c3d96b94041a 174 */
johnb 3:c3d96b94041a 175 XBeeDeviceReturn_t SendFrame( const char* const p_dat, size_t p_len, int p_wait_ms = 1000 );
johnb 3:c3d96b94041a 176
johnb 3:c3d96b94041a 177
johnb 3:c3d96b94041a 178
johnb 3:c3d96b94041a 179 };
johnb 3:c3d96b94041a 180
johnb 3:c3d96b94041a 181 #endif