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.
Diff: Base/XBeeDevice.hpp
- Revision:
- 48:48397bedf95d
- Parent:
- 42:81c789ba4c08
- Child:
- 53:7b65422d7a32
--- a/Base/XBeeDevice.hpp Sun Jul 06 22:10:28 2014 +0000 +++ b/Base/XBeeDevice.hpp Mon Jul 07 19:03:09 2014 +0000 @@ -115,6 +115,17 @@ /** List of objects which are registered to de-code received frames */ FixedLengthList<XBeeApiFrameDecoder*, XBEEAPI_CONFIG_DECODER_LIST_SIZE> m_decoders; + /** Option as to whether bad checksum should be ignored or not */ + bool m_ignoreBadCsum; + + /** Rolling counter of the number of messages which failed checksum verification when + this option is enabled. See getBadChecksumCount() */ + uint16_t m_badCsumCount; + + /** Rolling counter of the number of received serial data bytes which have been discarded + See getSerialBytesDiscardedCount() */ + uint16_t m_serialBytesDiscarded; + public: /** Represent the status of an XBee message exchange */ @@ -205,6 +216,29 @@ \returns true in the case that unregistration was successful, false otherwise (decoder not in list) */ bool unregisterDecoder( XBeeApiFrameDecoder* const p_decoder ); + /** Set whether or not the device should ignore checksums on messages that are incorrect. + By default the class will verify the checksums and discard frames which do not + pass this test, incrementing a rolling counter which can be retrieved via + getBadChecksumCount(). Setting the class to ignore bad checksums will result in all + frames being processed. + + \param p_shouldIgnore If set to true, frames with incorrect checksums will still be processed + If set to false, frames with incorrect checksums will not be processed + */ + void setIgnoreBadChecksum( const bool p_shouldIgnore ); + + uint16_t getBadChecksumCount( void ) const; + + /** Retrieve the number of bytes received from the serial data stream which have been discarded + Due to the fact that each API frame starts with a specific value, each time an API frame is + to be read, the first byte should be the frame header. If it is not then the class will + keep reading from the stream until the frame header is encountered in order to attempt to + re-synchronise with the stream. Reasons for becoming out-of-sync could include not + managing to process the data stream fast enough + + \returns A rolling counter of the number of bytes discarded so far */ + uint16_t getSerialBytesDiscardedCount( void ) const; + #if defined XBEEAPI_CONFIG_ENABLE_DEVELOPER void dumpRxBuffer( Stream* p_buf, const bool p_hexView ); #endif @@ -227,7 +261,14 @@ */ XBeeDeviceReturn_t SendFrame( const char* const p_dat, size_t p_len, int p_wait_ms = 1000 ); - + /** Verify the checksum of the frame pointed to. + The referenced frame should be in unescaped form + + \param p_data Pointer to a buffer where the first byte is the frame start delimiter + \param p_len Length of the p_data buffer in bytes + \returns true in the case that the checksum passed, false in the case that it does not. + */ + bool verifyFrameChecksum( const uint8_t* const p_data, size_t p_len ); };