Diff: OneWire_Masters/DS2465/DS2465.hpp

Revision:

47:307dc45952db

Parent:

35:5d23395628f6

Child:

48:6f9208ae280e

--- a/OneWire_Masters/DS2465/DS2465.hpp	Wed Apr 06 10:06:06 2016 -0500
+++ b/OneWire_Masters/DS2465/DS2465.hpp	Thu Apr 07 10:26:26 2016 -0500
@@ -4,14 +4,19 @@
 #include "OneWire_Masters/OneWireMaster.h"
 #include "OneWire_Masters/ISha256MacCoprocessor.hpp"
 
-namespace mbed
-{
-  class I2C;
-}
+namespace mbed { class I2C; }
 
 class DS2465 : public OneWireMaster, public ISha256MacCoprocessor
 {
 public:
+  /// Delay required after writing an EEPROM segment.
+  static const unsigned int eepromSegmentWriteDelayMs = 10;
+  /// Delay required after writing an EEPROM page such as the secret memory.
+  static const unsigned int eepromPageWriteDelayMs = 8 * eepromSegmentWriteDelayMs;
+  /// Delay required for a SHA computation to complete.
+  static const unsigned int shaComputationDelayMs = 2;
+
+  /// Page region to use for swapping.
   enum PageRegion
   {
     REGION_FULL_PAGE = 0x03,
@@ -19,6 +24,7 @@
     REGION_SECOND_HALF = 0x02
   };
   
+  /// Starting memory addresses.
   enum MemoryAddr
   {
     ADDR_SPAD = 0x00,
@@ -38,52 +44,122 @@
     ADDR_USER_MEM_PAGE_1 = 0xA0
   };
   
+  /// Represents a DS2465 configuration.
   struct Config
   {    
     bool c1WS, cSPU, cPDN, cAPU;
     
+    /// Byte representation that is read from the DS2465.
     std::uint8_t readByte() const;
+    /// Byte respresentation that is written to the DS2465.
     std::uint8_t writeByte() const;
     
+    /// Reset to the power-on default config.
     void reset();
     Config() { reset(); }
   };
   
+  /// @param I2C_interface Configured I2C communication interface for DS2465.
+  /// @param I2C_address I2C bus address of the DS2465 in mbed format.
   DS2465(mbed::I2C & I2C_interface, std::uint8_t I2C_address);
   
   // Const member functions should not change the settings of the DS2465 or affect the state of the 1-Wire bus.
   // Read pointer, scratchpad, MAC output register, and command register on the DS2465 are considered mutable.
 
-  //Misc. Functions
-  OneWireMaster::CmdResult detect();
-  OneWireMaster::CmdResult reset(void);                                      // Resets DS2465 (NOTE: This is NOT a 1-Wire Reset)
+  /// Performs a soft reset on the DS2465. This is NOT a 1-Wire Reset.
+  OneWireMaster::CmdResult reset(void);
+  
+  /// Write a new configuration to the DS2465.
+  /// @param[in] config New configuration to write.
+  /// @param verify Verify that the configuration was written successfully.
   OneWireMaster::CmdResult writeConfig(const Config & config, bool verify);
+  
+  /// Read the current DS2465 configuration.
+  /// @returns The cached current configuration.
   Config currentConfig() const;
 
   // DS2465 Memory Commands
+  
+  /// Read memory from the DS2465
+  /// @param addr Address to begin reading from.
+  /// @param[out] buf Buffer to hold read data.
+  /// @param bufLen Length of buffer, buf, and number of bytes to read.
+  /// @param skipSetPointer Assume that the read pointer is already set to the correct address.
   OneWireMaster::CmdResult readMemory(std::uint8_t addr, std::uint8_t * buf, std::size_t bufLen, bool skipSetPointer = false) const;
+  
+  /// Write to SRAM memory on the DS2465
+  /// @param addr Address to begin writing to.
+  /// @param[in] buf Buffer containing the data to write.
+  /// @param bufLen Length of buffer, buf, and number of bytes to write.
   OneWireMaster::CmdResult writeMemory(std::uint8_t addr, const std::uint8_t * buf, std::size_t bufLen) { return cWriteMemory(addr, buf, bufLen); }
+  
+  /// Write data to the scratchpad area of the DS2465
+  /// @param[in] buf Buffer containing the data to write.
+  /// @param bufLen Length of buffer, buf, and the number of bytes to write.
   OneWireMaster::CmdResult writeScratchpad(const std::uint8_t * buf, std::size_t bufLen) const { return cWriteMemory(ADDR_SPAD, buf, bufLen); }
-  OneWireMaster::CmdResult copyScratchpad(bool destSecret, unsigned int pageNum, bool notFull, unsigned int segmentNum);
+  
+  /// Copy the scratchpad contents to an EEPROM memory page.
+  /// @param pageNum Page number to copy to.
+  OneWireMaster::CmdResult copyScratchpadToPage(unsigned int pageNum) { return copyScratchpad(false, pageNum, false, 0); }
+  
+  /// Copy the scratchpad contents to an EEPROM memory segment.
+  /// @param pageNum Page number to copy to.
+  /// @param segmentNum Segment number to copy to.
+  OneWireMaster::CmdResult copyScratchpadToSegment(unsigned int pageNum, unsigned int segmentNum) { return copyScratchpad(false, pageNum, true, segmentNum); }
+  
+  /// Copy the scratchpad contents to the secret EEPROM memory page.
+  OneWireMaster::CmdResult copyScratchpadToSecret() { return copyScratchpad(true, 0, false, 0); }
   
   // 1-Wire Master Commands
   virtual OneWireMaster::CmdResult OWInitMaster(void);
-  virtual OneWireMaster::CmdResult OWReset(void);                                   // Issues a 1-Wire Reset Pulse
+  virtual OneWireMaster::CmdResult OWReset(void);
   virtual OneWireMaster::CmdResult OWTouchBit(std::uint8_t & sendrecvbit, OWLevel after_level);
   virtual OneWireMaster::CmdResult OWReadByte(std::uint8_t & recvbyte, OWLevel after_level);
   virtual OneWireMaster::CmdResult OWWriteByte(std::uint8_t sendbyte, OWLevel after_level);
   virtual OneWireMaster::CmdResult OWReadBlock(std::uint8_t *rx_buf, std::uint8_t rx_len);
   virtual OneWireMaster::CmdResult OWWriteBlock(const std::uint8_t *tran_buf, std::uint8_t tran_len);
-  OneWireMaster::CmdResult OWWriteBlock(bool tx_mac, const std::uint8_t *tran_buf, std::uint8_t tran_len);
   virtual OneWireMaster::CmdResult OWSetSpeed(OWSpeed new_speed);
-  virtual OneWireMaster::CmdResult OWSetLevel(OWLevel new_level);
+  virtual OneWireMaster::CmdResult OWSetLevel(OWLevel new_level); // The DS2465 only supports enabling strong pullup following a 1-Wire read or write operation.
   virtual OneWireMaster::CmdResult OWTriplet(SearchDirection & search_direction, std::uint8_t & sbr, std::uint8_t & tsb);
   
-  //DS2465 Coprocessor Commands
-  OneWireMaster::CmdResult computeNextMasterSecret(bool swap, unsigned int pageNum, PageRegion region);
-  OneWireMaster::CmdResult computeWriteMac(bool regwrite, bool swap, unsigned int pageNum, unsigned int segmentNum) const;
-  OneWireMaster::CmdResult computeSlaveSecret(bool swap, unsigned int pageNum, PageRegion region);
-  OneWireMaster::CmdResult computeAuthMac(bool swap, unsigned int pageNum, PageRegion region) const;
+  /// Write the last computed MAC to the 1-Wire bus
+  OneWireMaster::CmdResult OWWriteBlockMac();
+  
+  // DS2465 Coprocessor Commands
+  
+  /// Compute Next Master Secret with scratchpad data.
+  OneWireMaster::CmdResult computeNextMasterSecret() { return computeNextMasterSecret(false, 0, REGION_FULL_PAGE); }
+  
+  /// Compute Next Master Secret with page swapping.
+  /// @param pageNum Page number to swap in.
+  /// @param region Region of the page to swap in.
+  OneWireMaster::CmdResult computeNextMasterSecretSwap(unsigned int pageNum, PageRegion region) { return computeNextMasterSecret(true, pageNum, region); }
+  
+  /// Compute Write MAC with scratchpad data.
+  /// @param regwrite True if writing to a register or false if regular memory.
+  OneWireMaster::CmdResult computeWriteMac(bool regwrite) const { return computeWriteMac(regwrite, false, 0, 0); }
+  
+  /// Compute Write MAC with page swapping.
+  /// @param regwrite True if writing to a register or false if regular memory.
+  /// @param pageNum Page number to swap in.
+  /// @param segmentNum Segment number to swap in.
+  OneWireMaster::CmdResult computeWriteMacSwap(bool regwrite, unsigned int pageNum, unsigned int segmentNum) const { return computeWriteMac(regwrite, true, pageNum, segmentNum); }
+  
+  /// Compute Slave Secret (S-Secret) with scratchpad data.
+  OneWireMaster::CmdResult computeSlaveSecret() { return computeSlaveSecret(false, 0, REGION_FULL_PAGE); }
+  
+  /// Compute Slave Secret (S-Secret) with page swapping.
+  /// @param pageNum Page number to swap in.
+  /// @param region Region of the page to swap in.
+  OneWireMaster::CmdResult computeSlaveSecretSwap(unsigned int pageNum, PageRegion region) { return computeSlaveSecret(true, pageNum, region); }
+  
+  /// Compute Authentication MAC with scratchpad data.
+  OneWireMaster::CmdResult computeAuthMac() const { return computeAuthMac(false, 0, REGION_FULL_PAGE); }
+  
+  /// Compute Authentication MAC with page swapping.
+  /// @param pageNum Page number to swap in.
+  /// @param region Region of the page to swap in.
+  OneWireMaster::CmdResult computeAuthMacSwap(unsigned int pageNum, PageRegion region) const { return computeAuthMac(true, pageNum, region); }
   
   // ISha256MacCoprocessor Commands
   virtual ISha256MacCoprocessor::CmdResult setMasterSecret(const Secret & secret);
@@ -91,17 +167,30 @@
   virtual ISha256MacCoprocessor::CmdResult computeAuthMac(const DevicePage & devicePage, const DeviceScratchpad & challenge, const AuthMacData & authMacData, Mac & mac) const;
   virtual ISha256MacCoprocessor::CmdResult computeSlaveSecret(const DevicePage & devicePage, const DeviceScratchpad & deviceScratchpad, const SlaveSecretData & slaveSecretData);
   
-private:
-  static const unsigned int eepromWriteDelayMs = 10;
-  static const unsigned int shaComputationDelayMs = 2;
-  
+private:  
   mbed::I2C & m_I2C_interface;
   std::uint8_t m_I2C_address;
   Config m_curConfig;
 
-  OneWireMaster::CmdResult cWriteMemory(std::uint8_t addr, const std::uint8_t * buf, std::size_t bufLen) const;
+  /// Polls the DS2465 status waiting for the 1-Wire Busy bit (1WB) to be cleared.
+  /// @param[out] pStatus Optionally retrive the status byte when 1WB cleared.
+  /// @returns Success or TimeoutError if poll limit reached.
   OneWireMaster::CmdResult pollBusy(std::uint8_t * pStatus = NULL);
+  
+  /// Ensure that the desired 1-Wire level is set in the configuration.
+  /// @param level Desired 1-Wire level.
   OneWireMaster::CmdResult configureLevel(OWLevel level);
+  
+  /// Const version of writeMemory() for internal use.
+  OneWireMaster::CmdResult cWriteMemory(std::uint8_t addr, const std::uint8_t * buf, std::size_t bufLen) const;
+  
+  // Legacy implementations
+  OneWireMaster::CmdResult OWWriteBlock(bool tx_mac, const std::uint8_t *tran_buf, std::uint8_t tran_len);
+  OneWireMaster::CmdResult copyScratchpad(bool destSecret, unsigned int pageNum, bool notFull, unsigned int segmentNum);
+  OneWireMaster::CmdResult computeNextMasterSecret(bool swap, unsigned int pageNum, PageRegion region);
+  OneWireMaster::CmdResult computeWriteMac(bool regwrite, bool swap, unsigned int pageNum, unsigned int segmentNum) const;
+  OneWireMaster::CmdResult computeSlaveSecret(bool swap, unsigned int pageNum, PageRegion region);
+  OneWireMaster::CmdResult computeAuthMac(bool swap, unsigned int pageNum, PageRegion region) const;
 };
 
 #endif