Diff: mcp4728.h

Revision:

3:2a2eafba8a1d

Parent:

2:366e996af95c

Child:

4:f45f4ff5a51a

--- a/mcp4728.h	Tue Jan 12 15:03:38 2016 +0000
+++ b/mcp4728.h	Tue Jan 12 15:45:23 2016 +0000
@@ -9,7 +9,7 @@
 #include "I2CInterface.h" 
 #include "DACInterface.h" 
 
-#define VERSION_MCP4728_HDR "0.44"
+#define VERSION_MCP4728_HDR "0.45"
 
 /** MCP4728 class.
  *  Used for interfacing with a mcp4728 12-Bit QUAD  Digital-to-Analog Converter.
@@ -26,8 +26,6 @@
  */
 class MCP4728 : public DACInterface {
    
-    int lastreadresult;
-    char rbdata[24] ; //array for reading the status will be removed after debugging 
     public:
     /** The device supports two types of power modes: normal and power-down. In normal mode the device
      * operates a normal digital to analog conversion. In power-down mode all digitial to analog  
@@ -83,7 +81,7 @@
      * 
      * @param i2cinterface pointer to the   I2C interface (proto type) 
      * @param device_address_bits The 3bit address bits of the device.
-     * @Vdd the voltage on the Vdd pin ( power) 
+     * @param Vdd the voltage on the Vdd pin ( power) is used to calculate voltage is Vref is set to external 
      */
     MCP4728(I2CInterface* i2cinterface,  int device_address_bits, float Vdd );
     
@@ -95,25 +93,56 @@
      *       0 on success,
      *   non-0 on failure
      */
-     int update(bool checkall);    
+     int update(bool checkall);   
+      
      virtual int update() { return update(false);}
+     
+     
     /** format a string with the channel status 
-    * will do a call to the update() function 
     * @param ch :  the channel nr
-    * @param updatereq  , if true the function update(true) is called , 
-    *    else the class status table is used . 
-    * @param eprom if true the values in the eprom else the values of the DAC channel 
+    * @param updatereq: if true the function update(true) is called else the class status table is used . 
+    * @param eprom: if true the values in the eprom are used  else the values of the DAC channel 
     * @param str a pointer to an array of char  by example chanstatstr[100] 100 is minuimum.
     * @param dimension of the str array  ( so sizeoff(chanstatstr)  
     */
     int StatusString(int ch,bool updatereq ,bool eprom,  char *str , int length);
     
-    /**returns the last value of the DAC register obtained by the last read command.*/
+    /**gives the last value of the DAC register obtained by the last update  command.
+        Implementation of the getDACvalue of the DACInterface 
+       @param value by reference , the DAC value for the channel
+       @param ch  the channel nr 0..3  
+       @return the I2C result of the last update command 
+    */
     virtual int getDACvalue(int &value, int ch=0);
+   /** gives the last value of the DAC output voltage obtained by the last update  command.
+       Use the channel status bits and eventual Vdd value  to convert  the DAC value to a voltage.
+       Implementation of the getVoltagevalue of the DACInterface 
+       @param voltage by reference , the DAC output voltage for the channel
+       @param ch  the channel nr 0..3  
+       @return the I2C result of the last update command 
+    */
     virtual int getVoltage(float &voltage, int ch=0);
     
-    /** set the dac value for a certain channel. */
+    /** set the dac value for a certain channel. 
+        Implementation of the setDACvalue of the DACInterface 
+        It also sets the DAC configuration bits  ( Vref, power mode , gain ) 
+        ( For version 0.4x  this is internal, normal power , gain x2 ) 
+        @param value  the DAC value to be set 
+        @param ch  the channel nr 0..3  
+        @return the I2C result of the last update command 
+    */
     virtual int setDACvalue( int value, int ch=0);
+    
+    
+    /** gives the last value of the DAC output voltage obtained by the last update  command.
+       Use the channel configuration setings and eventual Vdd value  to convert the voltage to a DAC value.
+       Then it calls setDACValue  so it sets also the channel configuration. 
+       Implementation of the setVoltagevalue of the DACInterface 
+       @param voltage by reference , the request  DAC output voltage for the channel
+       @param ch  the channel nr 0..3  
+       @return the I2C result of the last update command 
+    */
+    
     virtual int setVoltage (float voltage, int ch=0);
     
     
@@ -124,21 +153,41 @@
     /** The full i2c device address. */
     int _device_address;
     char _adrbytes;
-    
+    /** calculates the voltage based on the value and the channel configuration bits 
+        @param value : the value of the DAC register 
+        @param gain  : the gain setting  x1 or x2 
+        @param vref  : use internal or external reference 
+        @return   : the voltage based on the parameters 
+    */
     float dig2volt( short int value,GainMode gain,  VrefMode  vref); 
+
+    /** calculates the nearest DAC register setting to get the requested voltage output 
+        given the DAC configuration.  There is no "under/ overflow"  check
+        @param  voltage the requested voltage
+        @param gain  : the gain setting  x1 or x2 
+        @return   : the DAC value based  the parameters to get the requested output voltage 
+    */
     short int volt2dig( float voltage,GainMode gain,  VrefMode  vref);
+
+    /** holds the Vdd value , used to calculate the voltage in case of vref = external */
     float Vdd;
+    /** holds the  status of the last update request */
+    int lastupdateresult;
     
-    
+    /** array for reading the status will be removed after debugging so don't use for future development */
+    char rbdata[24] ; 
 
-    /** used for read back the setting  */
+    /** used setting the configuration bits for each channel
+        These values are the "requested" values so not the actual values. 
+        These values are not updated after a update request !! 
+     */
     MCP4728ChCfg ChCfg[4]; 
-    
+    /** structure to store all channel status / config bits */ 
     typedef struct MCP4728ChStatus{
          GainMode gain;
          VrefMode  vref;
          PowerMode pwr;
-         bool bussy;
+         bool busy;
          bool por;
          short int dacvalue;
          short int promvalue;
@@ -148,8 +197,8 @@
          
     } MCP4728Chstatus;
     
-    
-    MCP4728ChStatus chstat[4]; // for readback .
+    /** storage of the channel status and configuration bits */ 
+    MCP4728ChStatus chstat[4];