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.

Diff: Base/XBeeDevice.hpp

Revision:
48:48397bedf95d
Parent:
42:81c789ba4c08
Child:
53:7b65422d7a32
diff -r 5d3608835668 -r 48397bedf95d Base/XBeeDevice.hpp
--- 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 );
 
 };