Revision 53:7b65422d7a32, committed 2014-07-28

Comitter:

johnb

Date:

Mon Jul 28 13:27:58 2014 +0000

Parent:

52:0950b05d5270

Child:

54:9f5b7652943e

Commit message:

Comments & clean-up

Changed in this revision

--- a/Base/XBeeApiFrame.hpp	Mon Jul 28 12:48:33 2014 +0000
+++ b/Base/XBeeApiFrame.hpp	Mon Jul 28 13:27:58 2014 +0000
@@ -68,10 +68,13 @@
     \returns Length of the frame payload excluding overhead */
 #define MSG_LEN_IN_BUFFER( _b ) ((((uint16_t)_b[ XBEE_CMD_POSN_LEN_HI ]) << 8U) + _b[XBEE_CMD_POSN_LEN_LO])
 
+/** The number of 'overhead' (i.e. those not included in the frame payload) bytes at the start of an API frame (namely the start delimiter & 2 length bytes) */
 #define XBEE_API_FRAME_OVERHEAD_START 3U
+
+/** The number of 'overhead' (i.e. those not included in the frame payload) bytes at the end of an API frame (namely the checksum) */
 #define XBEE_API_FRAME_OVERHEAD_END   1U
 
-/** The number of 'overhead' bytes in an API frame (i.e. those not included in the frame payload, namely the start delimiter, 2 length bytes & checksum */
+/** The total number of 'overhead' bytes in an API frame */
 #define XBEE_API_FRAME_OVERHEAD (XBEE_API_FRAME_OVERHEAD_START + XBEE_API_FRAME_OVERHEAD_END)
 
 /* Forward declare this as XBeeDevice is dependent upon XBeeApiFrameDecoder */
@@ -83,6 +86,7 @@
 class XBeeApiFrame
 {
     private:
+        /** Length of the frame header which precedes the data - currently a single byte which is the API ID */ 
         static const   uint8_t m_cmdHeaderLen = 1;
 
     protected:
@@ -105,7 +109,8 @@
                       const uint8_t* const p_data,
                       const size_t         p_dataLen );
 
-        /** Return the length of the API-specific structure represented by this frame.  i.e. the API frame without the overhead - see XBEE_API_FRAME_OVERHEAD */
+        /** Return the length of the API-specific structure represented by this frame.  i.e. the API frame without the overhead - see XBEE_API_FRAME_OVERHEAD.
+            The value includes both the data which is returned by getDataPtr and the byte used to identify the type of the packet, as returned by getApiId */
         virtual uint16_t getCmdLen( void ) const;
     
         /** Retrieve the API identifier for this frame */

--- a/Base/XBeeDevice.hpp	Mon Jul 28 12:48:33 2014 +0000
+++ b/Base/XBeeDevice.hpp	Mon Jul 28 13:27:58 2014 +0000
@@ -145,7 +145,9 @@
    
      /** Represents the different types of addressing for XBee devices */
      typedef enum {
+         /** 16-bit addressing */
          XBEE_API_ADDR_TYPE_16BIT = 0,
+         /** 64-bit addressing */
          XBEE_API_ADDR_TYPE_64BIT = 1    
      } XBeeApiAddrType_t;
 
@@ -227,6 +229,9 @@
      */
      void setIgnoreBadChecksum( const bool p_shouldIgnore );
      
+     /** Retrieve the number of packets which have failed the checksum test (see setIgnoreBadChecksum() )
+         \returns Rolling counter of the number of failed checksum tests 
+     */
      uint16_t getBadChecksumCount( void ) const;
 
      /** Retrieve the number of bytes received from the serial data stream which have been discarded
@@ -244,6 +249,11 @@
 #endif
 
 #if defined XBEEAPI_CONFIG_USING_RTOS && defined XBEEAPI_CONFIG_RTOS_USE_DISPATCHER
+     /** Function used (when using the MBED RTOS) to set up a thread to dispatch received data outside 
+         of the interrupt context.  Handling received data within the interrupt context is likely to
+         result in problems due to limited stack availability.
+         Must be called once and once only (even if using multiple XBee devices)
+     */
      bool setupDispatchTask();
 #endif
 

--- a/RXTX/XBeeApiRxFrame.hpp	Mon Jul 28 12:48:33 2014 +0000
+++ b/RXTX/XBeeApiRxFrame.hpp	Mon Jul 28 13:27:58 2014 +0000
@@ -54,22 +54,23 @@
         /** Indicate whether or not the message was PAN broadcase */
         bool m_panBroadcast;
    
-    /* TODO: doc */
+        /* TODO: doc */
         bool m_dataIsMallocd;   
 
-    /* TODO: doc */
+        /* TODO: doc */
         uint8_t* m_mallocdData; 
     public:
         /** Constructor */
         XBeeApiRxFrame();
         
-    /** Constructor */
+        /* TODO: doc */
+        /** Constructor */
         XBeeApiRxFrame( XBeeApiIdentifier_e p_id,
                         const uint8_t* const p_data,
                         const size_t         p_dataLen );
 
-    /** Deep copy */
-    /* TODO: doc */
+        /** Deep copy */
+        /* TODO: doc */
         bool deepCopyFrom( const XBeeApiRxFrame& p_frame );
        
         /** Destructor */

--- a/RXTX/XBeeApiRxFrameCircularBuffer.hpp	Mon Jul 28 12:48:33 2014 +0000
+++ b/RXTX/XBeeApiRxFrameCircularBuffer.hpp	Mon Jul 28 13:27:58 2014 +0000
@@ -36,12 +36,19 @@
 class XBeeApiRxFrameCircularBuffer : public XBeeApiRxFrameDecoder
 {
     protected:
+        /* TODO: doc */
         size_t          m_bufferSize;
+        /* TODO: doc */
         size_t          m_head;
+        /* TODO: doc */
         size_t          m_tail; 
-    size_t          m_count;
-    XBeeApiRxFrame* m_framesBuffer;
+        /* TODO: doc */
+        size_t          m_count;
+        /* TODO: doc */
+        XBeeApiRxFrame* m_framesBuffer;
+
     public:
+        /* TODO: doc */
         /** Constructor */
         XBeeApiRxFrameCircularBuffer( size_t p_bufferSize, XBeeDevice* p_device = NULL );
         
@@ -49,17 +56,21 @@
         virtual ~XBeeApiRxFrameCircularBuffer( void ); 
 
         /* Callback which is invoked when a frame is successfully decoded
-       \param p_frame The frame content
+           \param p_frame The frame content
         */       
         virtual void frameRxCallback( XBeeApiRxFrame* p_frame );
 
-    size_t getFrameCount() const;
+        /* TODO: doc */
+        size_t getFrameCount() const;
 
-    void clear();
+        /* TODO: doc */
+        void clear();
 
-    void pop();
+        /* TODO: doc */
+        void pop();
 
-    const XBeeApiRxFrame* getTailPtr() const;
+        /* TODO: doc */
+        const XBeeApiRxFrame* getTailPtr() const;
 };
 
 #endif
\ No newline at end of file

--- a/RXTX/XBeeApiRxFrameDecoder.hpp	Mon Jul 28 12:48:33 2014 +0000
+++ b/RXTX/XBeeApiRxFrameDecoder.hpp	Mon Jul 28 13:27:58 2014 +0000
@@ -51,7 +51,7 @@
         virtual ~XBeeApiRxFrameDecoder( void ); 
 
         /* Callback which is invoked when a frame is successfully decoded
-       \param p_frame The frame content
+           \param p_frame The frame content
         */       
         virtual void frameRxCallback( XBeeApiRxFrame* p_frame ) = 0;
 };

--- a/RXTX/XBeeApiTxFrame.hpp	Mon Jul 28 12:48:33 2014 +0000
+++ b/RXTX/XBeeApiTxFrame.hpp	Mon Jul 28 13:27:58 2014 +0000
@@ -41,24 +41,28 @@
         /** Destination address of the frame */
         uint64_t          m_addr;
         
-       /** Whether or not an acknowledgement of the frame is requested */ 
-       bool              m_ack;
-       /** Whether or not the frame is a PAN broadcast */
-       bool              m_panBroadcast;
-       /** Buffer to house data relating to the frame header */
-       uint8_t           m_buffer[XBEE_API_TX_FRAME_BUFFER_SIZE];
-
-       uint8_t           m_bufferLen;
+        /** Whether or not an acknowledgement of the frame is requested */ 
+        bool              m_ack;
+       
+        /** Whether or not the frame is a PAN broadcast */
+        bool              m_panBroadcast;
+        
+        /** Buffer to house data relating to the frame header */
+        uint8_t           m_buffer[XBEE_API_TX_FRAME_BUFFER_SIZE];
 
-       /** Called by XBeeDevice in order to offer frame data to the object for
-           decoding
+        /* TODO: doc */
+        uint8_t           m_bufferLen;
+
+        /** Called by XBeeDevice in order to offer frame data to the object for
+            decoding
            
-           \param p_data Pointer to the content of the received data
-           \param p_len Length of the data pointed to by p_data
-       */
-       virtual bool decodeCallback( const uint8_t* const p_data, size_t p_len );
+            \param p_data Pointer to the content of the received data
+            \param p_len Length of the data pointed to by p_data
+        */
+        virtual bool decodeCallback( const uint8_t* const p_data, size_t p_len );
 
-       void updateBuffer( void );
+        /* TODO: doc */
+        void updateBuffer( void );
 
     public:
        /** Enum for capturing the possible status of an XBee message TX 
@@ -82,38 +86,51 @@
            XBEE_API_TX_STATUS_LAST = 4  
        } XBeeApiTxStatus_e;
     
-       XBeeApiTxFrame( XBeeDevice* p_device = NULL,
-                       const uint8_t* p_data = NULL,
-                       const size_t   p_dataLen = 0,
-                       const uint64_t p_addr = XBEE_BROADCAST_ADDR,
-                       const XBeeDevice::XBeeApiAddrType_t p_type = XBeeDevice::XBEE_API_ADDR_TYPE_16BIT );
-       virtual ~XBeeApiTxFrame( void );
-       
-       void setDestAddrType( const XBeeDevice::XBeeApiAddrType_t p_type );
-       void setDestAddr( uint64_t p_addr );
-       void setDestAddrBroadcast( void );
-       void setPanBroadcast( const bool p_bc );
-       
-       virtual uint16_t getCmdLen( void ) const;
-       virtual void getDataPtr( const uint16_t p_start, const uint8_t**  p_buff, uint16_t* const p_len ) const;
+        /* TODO: doc */
+        XBeeApiTxFrame( XBeeDevice* p_device = NULL,
+                        const uint8_t* p_data = NULL,
+                        const size_t   p_dataLen = 0,
+                        const uint64_t p_addr = XBEE_BROADCAST_ADDR,
+                        const XBeeDevice::XBeeApiAddrType_t p_type = XBeeDevice::XBEE_API_ADDR_TYPE_16BIT );
+        /* TODO: doc */
+        virtual ~XBeeApiTxFrame( void );
        
-       virtual uint8_t getFrameId( void ) const;
-       
-       /** Callback function which is invoked when a response to the TX request is received from
-           the XBee.
-           
-           \param p_status Status of the TX attempt */
-       virtual void frameTxCallback( const XBeeApiTxStatus_e p_status );
+        /* TODO: doc */
+        void setDestAddrType( const XBeeDevice::XBeeApiAddrType_t p_type );
+
+        /* TODO: doc */
+        void setDestAddr( uint64_t p_addr );
+
+        /* TODO: doc */
+        void setDestAddrBroadcast( void );
+
+        /* TODO: doc */
+        void setPanBroadcast( const bool p_bc );
+        
+        /* TODO: doc */
+        virtual uint16_t getCmdLen( void ) const;
+
+        /* TODO: doc */
+        virtual void getDataPtr( const uint16_t p_start, const uint8_t**  p_buff, uint16_t* const p_len ) const;
        
-       /** Set the frame payload
+        /* TODO: doc */
+        virtual uint8_t getFrameId( void ) const;
+       
+        /** Callback function which is invoked when a response to the TX request is received from
+            the XBee.
+            
+            \param p_status Status of the TX attempt */
+        virtual void frameTxCallback( const XBeeApiTxStatus_e p_status );
        
-           \param p_buff Pointer to the buffer containing the data.  Note that this buffer is not copied, so
-                         must retain the appropriate content until transmission is complete
-           \param p_len Length of the data pointed to be p_buff.  Must be 100 or less.
-           \returns true in the case that the operation was successful, false in the case that it was not
-                    (content too long, etc)
-       */
-       bool setDataPtr( const uint8_t* const p_buff, const uint16_t p_len );
+        /** Set the frame payload
+       
+            \param p_buff Pointer to the buffer containing the data.  Note that this buffer is not copied, so
+                          must retain the appropriate content until transmission is complete
+            \param p_len Length of the data pointed to be p_buff.  Must be 100 or less.
+            \returns true in the case that the operation was successful, false in the case that it was not
+                     (content too long, etc)
+        */
+        bool setDataPtr( const uint8_t* const p_buff, const uint16_t p_len );
 };
 
 #endif
\ No newline at end of file

--- a/Remote/XBeeDeviceRemoteAt.hpp	Mon Jul 28 12:48:33 2014 +0000
+++ b/Remote/XBeeDeviceRemoteAt.hpp	Mon Jul 28 13:27:58 2014 +0000
@@ -30,7 +30,10 @@
 #include "XBeeApiFrame.hpp"
 #include "XBeeApiCmdAt.hpp"
 
-/** */
+/** Class used to provide a command interface to a remove XBee via the Remote AT interface.
+    The class inherits from XBeeApiCmdAt, hence the interface for the local and remote
+    XBees is generally the same.
+*/
 class XBeeDeviceRemoteAt : public XBeeApiCmdAt
 {
     protected:
@@ -42,23 +45,32 @@
         */
         virtual bool decodeCallback( const uint8_t* const p_data, size_t p_len );
 
+        /* TODO: doc */
         virtual void SendCmd_uint8_t( const uint8_t        p_frameId,
                                       const uint8_t* const p_data,
                                       const uint8_t&       p_val );
+        /* TODO: doc */
         virtual void SendCmd_uint16_t( const uint8_t        p_frameId,
                                        const uint8_t* const p_data,
                                        const uint16_t&       p_val );
+        /* TODO: doc */
         virtual void SendCmd_uint32_t( const uint8_t        p_frameId,
                                        const uint8_t* const p_data,
                                        const uint32_t&       p_val );
+        /* TODO: doc */
         virtual void SendReq( const uint8_t             p_frameId,
                               const uint8_t*            p_data );
 
+        /* TODO: doc */
         virtual size_t getResponseStatusPos( void ) const;
 
+        /** Keep track of whether we're applying changes when the AT command is sent
+            or not */
         bool     m_applyChanges;
 
     public:
+    
+        /* TODO: doc */
         /** Constructor */
         XBeeDeviceRemoteAt( XBeeDevice* p_device,
                             const uint16_t& p_addr16Bit,
@@ -68,6 +80,13 @@
         /** Destructor */
         virtual ~XBeeDeviceRemoteAt( void ); 
         
+        /** Control whether or not changes are applied when the command is sent or not.
+            There are three possibilities for appling changes on the remote:
+            1) Use this method, specifying a 'true' parameter so that changes are applied as soon as a command is sent
+            2) Use requestApplyChanges() to apply all pending changes
+            3) Use requestWriteSettings() followed by requestReset() to write the settings to non-volatile memory and reset the device
+        
+            \param Specified whether or not the settings should be applied when the command is sent to the remote device */
         void setApplyChanges( const bool p_apply );
 };
 

--- a/Utility/XBeeApiCmdAt.cpp	Mon Jul 28 12:48:33 2014 +0000
+++ b/Utility/XBeeApiCmdAt.cpp	Mon Jul 28 13:27:58 2014 +0000
@@ -186,8 +186,8 @@
                                                                       CMD_RESPONSE_GET_D6,
                                                                       CMD_RESPONSE_GET_D7 };
 
-#define XBEE_CMD_POSN_FRAME_ID XBEE_CMD_POSN_ID_SPECIFIC_DATA
-#define XBEE_CMD_POSN_STATUS (7U)
+#define XBEE_CMD_POSN_FRAME_ID    (XBEE_CMD_POSN_ID_SPECIFIC_DATA)
+#define XBEE_CMD_POSN_STATUS      (7U)
 #define XBEE_CMD_POSN_PARAM_START (8U)
 
 #define XBEE_CMD_RESPONS_HAS_DATA( _p_len ) ((_p_len > ( XBEE_CMD_POSN_PARAM_START + 1 ))
@@ -410,8 +410,8 @@
     uint8_t sampleCount = p_data[ p_start ];
 #endif
     
-    uint16_t channelMask = (((uint16_t)p_data[ p_start + 1 ]) << 8) |
-                           ((uint16_t)p_data[ p_start + 2 ]);
+    const uint16_t channelMask = (((uint16_t)p_data[ p_start + 1 ]) << 8) |
+                                 ((uint16_t)p_data[ p_start + 2 ]);
     const uint8_t* dataPtr = &( p_data[ p_start + 3 ] );
     const uint16_t dioMask = channelMask & DIO_CHANNEL_MASK;
     uint16_t adcMask = (channelMask & ADC_CHANNEL_MASK) >> 9U;