Revision 2:2ebc9c0d4a54, committed 2014-04-02

Comitter:

sophtware

Date:

Wed Apr 02 12:22:45 2014 +0000

Parent:

1:a011ae93a350

Child:

3:7c7c1ea6fc33

Commit message:

Updated documentation.

Changed in this revision

--- a/Altitude.h	Wed Apr 02 11:12:00 2014 +0000
+++ b/Altitude.h	Wed Apr 02 12:22:45 2014 +0000
@@ -14,15 +14,21 @@
 
 #include "mbed.h"
 
-// Casting truncates, therefore negative numbers become positive.
-// This will only cast properly in the range -128 to 127.
+//! Casting truncates, therefore negative numbers become positive.
+//! This will only cast properly in the range -128 to 127.
 #define float_to_char(x) (((x)<0)?(-(char)(x)):((char)(x)))
 
+//! Altitude provides a wrapper around altitude data coming from the sensor. The class handles
+//! working with compressed data from the sensor and provides convenient functions for retreiving
+//! the data in various units (with room to add more if needed).
 class Altitude
 {
 public:
 
+    //! The size of the compressed data buffer from the sensor. Used in an I2C read.
     static const int size = 3;
+    
+    //! The units we support converting the sensor data to.
     enum unitsType { METERS, FEET };
 
     Altitude();
@@ -30,18 +36,25 @@
     Altitude(const char* compressed);
     Altitude(const char msb, const char csb, const char lsb);
 
+    //! Allows using the object directly in an I2C read operation.
     operator char*(void) { return _compressed; }
+    //! Same as calling altitude with METERS as the parameter.
     operator float(void) { return _altitude; }
 
+    //! Returns the altitude in the units you specifiy, defaulting to FEET if none specified.
     float altitude(unitsType units = FEET);
+    //! Call to decompress the sensor data after an I2C read.
     void setAltitude();
     void setAltitude(const char* compressed);
     void setAltitude(const char msb, const char csb, const char lsb);
     void setAltitude(float a, unitsType units = FEET);
 
+    //! Returns the altitude as a string in the units specified, defaulting to FEET if none specified.
     const char* print(unitsType units = FEET);
     
+    //! Converts meters to feet.
     static float MetersToFeet(float meters) { return meters * 3.28084; }
+    //! Converts feet to meters.
     static float FeetToMeters(float feet) { return feet / 3.28084; }
     
 private:

--- a/MPL3115A2.h	Wed Apr 02 11:12:00 2014 +0000
+++ b/MPL3115A2.h	Wed Apr 02 12:22:45 2014 +0000
@@ -99,20 +99,26 @@
 #define OFF_T               0x2C //  | 0x00 |         |     | 0x           |
 #define OFF_H               0x2D //  | 0x00 |         |     | 0x           |
 
+//! MPL3115A2 I2C Barometric Pressure and Tempurature Sensor Library
+//! This class wraps most of the function in the MPL3115A2 sensor leaving out the FIFO and interrupt system.
 class MPL3115A2
 {
 public:
+    //! Constructs an MPL3115A2 object and associates an I2C and optional Serial debug object.
     MPL3115A2(I2C *i2c, Serial *pc = NULL);
 
-    // Call this method in main to initialize the sensor.
+    //! Call from main to initialize the sensor, defaulting to Altitude mode.
     void init();
 
-    // Returns the fixed device ID number (usually equal to 0xC4).
+    //! Returns the fixed device ID number (usually equal to 0xC4).
     char  whoAmI() { return i2cRead(WHO_AM_I); } 
     
-    Altitude* readAltitude(Altitude* a);            // Returns the altitude object with altitude
-    Pressure* readPressure(Pressure* p);            // Returns the pressure object with barometric pressure
-    Temperature* readTemperature(Temperature* t);   // Returns the temperature object with temperature
+    //! Returns the passed in altitude object with altitude data.
+    Altitude* readAltitude(Altitude* a);            
+    //! Returns the passed in pressure object with barometric pressure data.
+    Pressure* readPressure(Pressure* p);            
+    //! Returns the passed in temperature object with temperature data.
+    Temperature* readTemperature(Temperature* t);
     
     // Use these methods to set the sensor's offsets to increase its accuracy. You can generally
     // find your current altitude with a smart phone or GPS. Same goes for the temperature. For
@@ -120,52 +126,71 @@
     // pressure from the web for your area is generally not close enough to help with calibration.
     // You may need to play with the setting to achieve good accuracy. I found the offset steps
     // were not 100% accurate to the datasheet and had to adjust accordingly. 
+    //! Returns the altitude offset stored in the sensor.
     char offsetAltitude() { return i2cRead(OFF_H); }
-    void setOffsetAltitude(const char offset) { i2cWrite(OFF_H, offset); }      // -128 to 127 meters
+    //! Sets the altitude offset stored in the sensor. The allowed offset range is from -128 to 127 meters.
+    void setOffsetAltitude(const char offset) { i2cWrite(OFF_H, offset); } 
+    //! Returns the pressure offset stored in the sensor.
     char offsetPressure() { return i2cRead(OFF_P); }
-    void setOffsetPressure(const char offset) { i2cWrite(OFF_P, offset); }      // 4 Pa per LSB
+    //! Sets the pressure offset stored in the sensor. The allowed offset range is from -128 to 127 where each LSB represents 4 Pa.
+    void setOffsetPressure(const char offset) { i2cWrite(OFF_P, offset); }
+    //! Returns the temperature offset stored in the sensor.
     char offsetTemperature() { return i2cRead(OFF_T); }
-    void setOffsetTemperature(const char offset) { i2cWrite(OFF_T, offset); }   // 0.0625ºC per LSB
+    //! Sets the temperature offset stored in the sensor. The allowed offset range is from -128 to 127 where each LSB represents 0.0625ºC.
+    void setOffsetTemperature(const char offset) { i2cWrite(OFF_T, offset); } 
     
-    void  setModeStandby(); // Puts the sensor into Standby mode. Required when using methods below.
-    void  setModeActive();  // Activates the sensor to start taking measurements.
+    //! Puts the sensor into Standby mode. Required when using methods below.
+    void  setModeStandby(); 
+    //! Activates the sensor to start taking measurements.
+    void  setModeActive();  
     
-    // When calling any of these methods, be sure to put the sensor in standby mode first.
-    void  setModeBarometer();           // Puts the sensor into barometric mode
-    void  setModeAltimeter();           // Puts the sensor into altimeter mode
-    void  setOversampleRate(char rate); // Sets the number of samples from 1 to 128.
-    void  enableEventFlags();           // Sets all the event flags.
+    //! Puts the sensor into barometric mode, be sure to put the sensor in standby mode first.
+    void  setModeBarometer();           
+    //! Puts the sensor into altimeter mode, be sure to put the sensor in standby mode first.
+    void  setModeAltimeter();           
+    //! Sets the number of samples from 1 to 128, be sure to put the sensor in standby mode first.
+    void  setOversampleRate(char rate); 
+    //! Sets all the event flags, be sure to put the sensor in standby mode first.
+    void  enableEventFlags();           
 
 private:
-    I2C *_i2c;          // The I2C object we use to communicate with the sensor. It is not part
-                        // of the class so that it can be shared with other peripherals on the 
-                        // bus.
-    Serial *_debug;     // Set this in the constructor if you want the class to output debug messages.
-                        // If you need to pair down your code, you can remove this and all the
-                        // references to it in the code.
+    //! The I2C object we use to communicate with the sensor. It is not part
+    //! of the class so that it can be shared with other peripherals on the 
+    //! bus.
+    I2C *_i2c;          
+                        
+    //! Set this in the constructor if you want the class to output debug messages.                        
+    //! If you need to pair down your code, you can remove this and all the
+    //! references to it in the code.
+    Serial *_debug;     
  
-    // Debug method that mimics the printf function, but will output nothing if _debug has not
-    // been set. This means you can safely us it in your code and nothing will happen if you don't
-    // assign the _debug object.
+    //! Debug method that mimics the printf function, but will output nothing if _debug has not
+    //! been set. This means you can safely us it in your code and nothing will happen if you don't
+    //! assign the _debug object.
     void debugOut(const char * format, ...);
 
-    // These are helper functions to SET or CLEAR bits. The mask should contain 1s in the position
-    // where the bits need to be set or cleared. One or more bits can be set or cleared this way.
+    //! This helper function is used to CLEAR bits. The mask should contain 1s in the position
+    //! where the bits need to be cleared. One or more bits can be cleared this way.
     void clearRegisterBit(const char regAddr, const char bitMask);
+    //! This helper function is used to SET bits. The mask should contain 1s in the position
+    //! where the bits need to be set. One or more bits can be set this way.
     void setRegisterBit(const char regAddr, const char bitMask);
 
-    // Helper functions to check if data is ready in a register for either temperature or pressure.
-    // The pressureDataReady function works for both altitude and barometric pressure depending on 
-    // the mode the sensor is in.
+    //! Helper functions to check if data is ready in a register for either temperature or pressure.
+    //! The mask passed in determines which register bit to look at.
     int dataReady(const char mask);
+    //! Blocks for about 1/2 a second while checking the data ready bit. Returns 0 on sucees.
+    //! This function works for both altitude and barometric pressure depending on the mode the sensor is in.
     int pressureDataReady() { return dataReady(0x04); }
+    //! Blocks for about 1/2 a second while checking the data ready bit. Returns 0 on sucees.
     int temperatureDataReady() { return dataReady(0x02); }
  
-    // Called to force the sensor to take another sample
+    //! Called to force the sensor to take another sample
     void toggleOneShot();                       
     
-    // Helper functions to read and write one value from the I2C bus using the sensor's address.
+    //! Helper functions to read one value from the I2C bus using the sensor's address.
     char i2cRead(char regAddr);
+    //! Helper functions to write one value from the I2C bus using the sensor's address.
     void i2cWrite(char regAddr, char value);
 };