Diff: xDotBridge/inc/CommProtocolPeerBrute.h

Revision:

70:6b3ca63792c2

Parent:

65:d546060aa03d

diff -r eb391644b346 -r 6b3ca63792c2 xDotBridge/inc/CommProtocolPeerBrute.h
--- a/xDotBridge/inc/CommProtocolPeerBrute.h	Fri Mar 24 08:15:37 2017 -0600
+++ b/xDotBridge/inc/CommProtocolPeerBrute.h	Mon Mar 27 09:16:33 2017 -0600
@@ -22,29 +22,120 @@
 const uint16_t PROTOCOL_NVM_SIZE = 54; // Bytes
 const uint16_t PROTOCOL_FLAG = 0x5A00;
 const uint16_t PROTOCOL_REV = 0x0002;
+
+/**
+ *  @class NvmProtocolObj
+ *  @brief This convenience class implements helps storing protocol settings to non-volatile memory
+ *
+ *  @details This class can translate to and from a byte array which can be stored then be easily stored
+ *           using any number of APIs.
+ */
 class NvmProtocolObj {
 public:
+    /**
+    * @brief NvmProtocolObj constructor
+    * @details Initializes internal values with defaults
+    */
     NvmProtocolObj();
+
+    /**
+    * @brief Set all internal variables to defaults.  This is automatically called from constructor.
+    */
     void setDefaults();
-    CmdResult fromBytes(uint8_t *data, uint8_t size);
+
+    /**
+    * @brief Saves internal state from a byte array
+    */
     CmdResult toBytes(uint8_t *data, uint8_t &size);
 
+    /**
+    * @brief Loads internal state from a byte array.  This byte array should typically have
+    *  previously generated by the toBytes function.
+    */
+    CmdResult fromBytes(uint8_t *data, uint8_t size);
+
+    /**
+    * @brief Accessor for protocol flag
+    */
     uint16_t getProtocolFlag();
+
+    /**
+    * @brief Checks if protocol flag is valid
+    */
     bool validProtocolFlag();
+
+    /**
+    * @brief Accessor for protocol rev
+    */
     uint16_t getProtocolRev();
+
+    /**
+    * @brief Checks if the revision of the protocol matches
+    */
     bool validProtocolRev();
 
+    /**
+     * @brief Accessor for network address.  Note value is returned via parameter.
+     * @param addr A STL vector which will be set to 4 byte address
+     */
     void getNetworkAddr(std::vector<uint8_t> &addr);
+
+    /**
+     * @brief A setter for network address
+     * @param addr The network address to be stored.  This value should be 4 bytes.
+     */
     void setNetworkAddr(const std::vector<uint8_t> &addr);
+
+    /**
+     * @brief Accessor for network session key.  Value return via parameter
+     * @param key A STL Vector which will be set with 16 byte key
+     */
     void getNetworkSessionKey(std::vector<uint8_t> &key);
+
+    /**
+     * @brief A setter for network session key
+     *
+     * @param key The network session key to be stored.  This value should be 16 bytes.
+     */
     void setNetworkSessionKey(const std::vector<uint8_t> &key);
+
+    /**
+     * @brief Accessor for data session key.  Value return via parameter
+     * @param key A STL Vector which will be set with 16 byte key
+     */
     void getDataSessionKey(std::vector<uint8_t> &key);
+
+    /**
+     * @brief A setter for data session key
+     * @param key The network session key to be stored.  This value should be 16 bytes.
+     */
     void setDataSessionKey(const std::vector<uint8_t> &key);
 
+    /**
+     * @brief A accessor for logical address
+     */
     uint16_t getLogicalAddr();
+
+    /**
+     * @brief A setter for logical address
+     * @param in Value for logical address
+     */
     void setLogicalAddr(uint16_t in);
+
+    /**
+     * @brief A accessor for LastMsgSeq
+     */
     uint32_t getLastMsgSeq();
+
+    /**
+     * @brief A setter for LastMsgSeq
+     * @param in Value for ter for LastMsgSeq
+     */
     void setLastMsgSeq(uint32_t in);
+
+    /**
+     * @brief A convenience method which increments LastMsgSeq
+     */
     void incLastMsgSeq();
 
     // TODO some day make these private with setters and getters
@@ -60,7 +151,7 @@
 };
 
 /**
- *  @class PeerBruteCommProtocol
+ *  @class CommProtocolPeerBrute
  *  @brief This class implements a peer-to-peer (P2P) brute force protocol.
  *
  *  @details The protocol consists of at a minimum one transmitter (TX) and one
@@ -79,7 +170,6 @@
  *  - When to sleep
  *
  */
-
 class CommProtocolPeerBrute
 {
 public:
@@ -99,11 +189,17 @@
     CommProtocolPeerBrute();
 
     /**
+     * Attempts to read values from NVM (xDot's eeprom) if failure saves defaults.  Then
+     * configures radio with settings.
+     * @return Success unless radio configuration error
+     */
+    CmdResult init();
+
+    /**
      * @brief Initialize radio with stored network network settings
      *
-     * @return Returns the result of all the commands
+     * @return Returns the result of all the radio commands
      */
-    CmdResult init();
     CmdResult configForSavedNetwork();
 
     /**
@@ -137,6 +233,10 @@
     CmdResult clearPair();
 
     // TX focused
+    /**
+     * @brief Accessor sequence number
+     * @return Integer value
+     */
     uint32_t getSeqNum();
     /**
      * @brief Transmit the msg attached
@@ -175,8 +275,6 @@
      */
     CmdResult listen (bool &msgPending);
 
-    CmdResult sampleDLC();
-
     /**
      * @brief Returns the last message received via listening
      *
@@ -184,15 +282,27 @@
      * @return Returns status of all commands completed
      */
     CmdResult recv (std::vector<uint8_t> &msg);
+
+    /**
+     * @brief Attempts to parse and return the last message received
+     *
+     * @details If the message is too short or if the flag is not correct will return an error.
+     *
+     * @param eui 4 byte value returned
+     * @param data Data field from alert message
+     * @param seqNum Transmitter's sequence number
+     * @return Returns status of all commands completed
+     */
     CmdResult recvAlert (std::vector<uint8_t> &eui, uint16_t &data, uint32_t &seqNum);
 
     /**
-     * @brief This fucntion enables the radio to listen for pair requests.
+     * @brief This function enables the radio to listen for pair requests.
      * @param waitTime The maximum time which radio waits for pair requests
      *
      * TODO determine if it is important to know who is paired
      *
-     * @return If pair message received then cmdSucess is returned otherwise timeout is returned.
+     * @return If pair message received then cmdSucess is returned otherwise
+     * timeout is returned.
      */
     CmdResult waitForPairing(float waitTime);
 
@@ -203,9 +313,13 @@
      */
     CmdResult sendPairAccepted();
 
+    /**
+     *
+     * @param waitTime
+     * @return
+     */
     CmdResult waitForAccept(float waitTime);
 
-
     // xDot Peer to Peer Specific
     /**
      * Convenience function to get the internal downlink count from radio