Revision 26:f5df80e990f4, committed 2014-02-05

Comitter:

johnb

Date:

Wed Feb 05 21:31:10 2014 +0000

Parent:

25:db6874b7ac4b

Child:

27:6356ef5fe39b

Commit message:

Doc updates for XBeeApiCmdAt and XBeeApiCmdAtBlocking

Changed in this revision

--- a/Utility/XBeeApiCmdAt.hpp	Wed Feb 05 21:05:10 2014 +0000
+++ b/Utility/XBeeApiCmdAt.hpp	Wed Feb 05 21:31:10 2014 +0000
@@ -36,18 +36,38 @@
 
 #include <stdint.h>
 
+#define XBEE_API_CMD_SET_HEADER_LEN 3U
+
+/** Class to access the configuration interface of the XBee.
+    Requests to the XBee are non-blocking meaning that code
+    which utilises this class must deal with the fact that
+    there will be a delay between requesting the data from
+    the XBee and the data being available via the API.  See
+    XBeeApiCmdAtBlocking for a blocking version.
+    
+    Parameters from the XBee are cached in the object so
+    subsequent requests do not need have the overhead of
+    communication with the XBee */
 class XBeeApiCmdAt : public XBeeApiFrameDecoder
 {
     public:
-       typedef uint16_t panId_t;
-       typedef uint8_t  channel_t;
+        /** Type to represent the ID of a PAN (Personal Area Network) */
+        typedef uint16_t panId_t;
+        /** Type to represent a wireless channel number */
+        typedef uint8_t  channel_t;
     
     protected:
+        /** Indicates whether or not m_hwVer contains data retrieved from the XBee */
         bool m_haveHwVer;
+        /** Indicates whether or not m_fwVer contains data retrieved from the XBee */
         bool m_haveFwVer;
+        /** Indicates whether or not m_chan contains data retrieved from the XBee */
         bool m_haveChan;
+        /** Indicates whether or not m_PANId contains data retrieved from the XBee */
         bool m_havePANId;
+        /** Indicates whether or not m_EDA contains data retrieved from the XBee */
         bool m_haveEDA;
+        /** Indicates whether or not m_CE contains data retrieved from the XBee */
         bool m_haveCE;
         
         uint16_t m_hwVer;
@@ -61,29 +81,63 @@
         bool m_CE;
         bool m_CEPend;
 
+        /** Template class to create an XBeeApiFrame which can be used to change
+            the value of one of the XBee parameters.  This class is used by the
+            setXXX methods in XBeeApiCmdAt */
         template< typename T >
         class XBeeApiCmdAtSet : public XBeeApiFrame {
-            uint8_t m_buffer[ 3 + sizeof( T ) ];
+            uint8_t m_buffer[ XBEE_API_CMD_SET_HEADER_LEN + sizeof( T ) ];
             public:
+                /** Constructor
+                   
+                    \param p_data Pointer to a buffer of length 3 bytes containing a 
+                                  single byte frame ID followed by 2 bytes identifying
+                                  the command, e.g. '0', 'V', 'R' would set up a version
+                                  request with a frame identifier of 48 (ASCII value of 
+                                  '0').
+                    \param p_val New value for the parameter 
+                */
                 XBeeApiCmdAtSet( const uint8_t* const p_data,
                                  const T p_val );
-            virtual ~XBeeApiCmdAtSet();
+                /** Destructor */
+                virtual ~XBeeApiCmdAtSet();
         };
 
+       /* Implement XBeeApiCmdDecoder interface */
+       virtual bool decodeCallback( const uint8_t* const p_data, size_t p_len );
+
     public:
 
-       XBeeApiCmdAt( );
-       virtual ~XBeeApiCmdAt( void ) {};
+        /** Constructor */
+        XBeeApiCmdAt( );
+       
+        /** Destructor */
+        virtual ~XBeeApiCmdAt( void ) {};
        
-       bool requestHardwareVersion( void );
-       bool requestFirmwareVersion( void );
-       bool requestChannel( void );
-       bool requestCoordinatorEnabled( void );
-       bool requestEndDeviceAssociationEnabled( void );
-       bool requestPanId( void );
+        /** Request the hardware version identifier from the XBee.
+            As the data is retrieved asynchronously to this call,
+            once the response is received it can be accessed via
+            getHardwareVersion() */
+        bool requestHardwareVersion( void );
+        bool requestFirmwareVersion( void );
+        bool requestChannel( void );
+        bool requestCoordinatorEnabled( void );
+        bool requestEndDeviceAssociationEnabled( void );
+        bool requestPanId( void );
 
-       virtual bool getHardwareVersion( uint16_t* const p_ver );
-       virtual bool getFirmwareVersion( uint16_t* const p_ver );
+        /** Read the XBee's hardware version identifier.  
+       
+            This method does not initiate any communication with the
+            XBee - the identifier must previously have been requested 
+            via requestHardwareVersion().  The method is non-blocking. */
+        virtual bool getHardwareVersion( uint16_t* const p_ver );
+
+        /** Read the XBee's firmware version identifier.  
+       
+            This method does not initiate any communication with the
+            XBee - the identifier must previously have been requested 
+            via requestFirmwareVersion().  The method is non-blocking. */
+        virtual bool getFirmwareVersion( uint16_t* const p_ver );
        
        virtual bool getChannel( uint8_t* const p_chan );
        virtual bool setChannel( uint8_t const p_chan );
@@ -96,23 +150,45 @@
        
        virtual bool getPanId( panId_t* const p_id );       
        virtual bool setPanId( const panId_t p_id );       
-       
-       /* Implement XBeeApiCmdDecoder interface */
-       virtual bool decodeCallback( const uint8_t* const p_data, size_t p_len );
-
 };
 
+/** Class to access the configuration interface of the XBee.
+    In contrast to XBeeApiCmdAt, the getXXX methods block
+    until the data is received (or a timeout has occurred)
+    which means that the caller doesn't have to deal with the
+    asynchronous nature of the API provided by XBeeApiCmdAt.
+    
+    It's not necessary to use any of the requestXXX methods
+    (as the getXXX methods will take care of this, however
+    calling a requestXXX method will effectively pre-fetch the
+    data meaning that getXXX will not have to block */
 class XBeeApiCmdAtBlocking : public XBeeApiCmdAt
 {
     protected:
+        /** Timeout used for blocking methods in milliseconds */
         uint16_t m_timeout;
+        
+        /** Wait slice time while blocking.  The function will 
+            wait_ms(m_slice) until the XBee responds with the
+            data or m_timeout elapses */
         uint16_t m_slice;
 
     public:
+       /** Constructor 
+       
+            \param p_timeout Timeout to be used when waiting for 
+                             data from the XBee, specified in
+                             milliseconds
+            \param p_slice While waiting for data, blocking methods
+                           will call the OS wait_ms() function, using
+                           the value specified by p_slice */
        XBeeApiCmdAtBlocking( const uint16_t p_timeout = 1000, const uint16_t p_slice = 100);
        
+       /** Destructor */
        virtual ~XBeeApiCmdAtBlocking( void ) {};
+ 
        /* Implement XBeeApiCmdAt's virtual methods */
+       
        virtual bool getHardwareVersion( uint16_t* const p_ver );
        virtual bool getFirmwareVersion( uint16_t* const p_ver );
 
@@ -126,8 +202,7 @@
        virtual bool setEndDeviceAssociationEnabled( const bool p_en  );
        
        virtual bool getPanId( panId_t* const p_id );       
-       virtual bool setPanId( const panId_t p_id );       
-
+       virtual bool setPanId( const panId_t p_id );
 };
 
 #endif
\ No newline at end of file