Diff: AK9752.h

Revision:

1:2035a4a54d3f

Parent:

0:51fa46d39a3e

--- a/AK9752.h	Fri Jul 08 22:27:55 2016 +0000
+++ b/AK9752.h	Tue Nov 01 17:03:31 2016 +0000
@@ -3,6 +3,23 @@
 
 #include "mbed.h"
 
+/**
+ * Device driver for AK9752.
+ * @note AK9752 is an IR sensor with I2C interface.
+ * Example:
+ * @code
+ * #include "mbed.h"
+ * #include "ak9752_reg.h"
+ * #include "ak9752.h"
+ * 
+ * int main()
+ * {
+ *      // Coming soon
+ *      return 0;
+ * }
+ * @endcode
+ * 
+ */
 class AK9752
 {
 public:
@@ -28,9 +45,9 @@
      * Enum for operation mode of measurement.
      */
     typedef enum {
-        MODE_STANDBY = 0x00,
-        MODE_CONTINUOUS = 0x01,
-        MODE_SINGLE_SHOT = 0x02,
+        MODE_STANDBY = 0x00,        /**< MODE_STANDBY:      0x00 */
+        MODE_CONTINUOUS = 0x01,     /**< MODE_CONTINUOUS:   0x01 */
+        MODE_SINGLE_SHOT = 0x02,    /**< MODE_SINGLE_SHOT:  0x02 */
     } OperationMode;
 
     /**
@@ -55,149 +72,169 @@
     } FcIr;
     
     /**
-     * Structure for intterupt status.
+     * Structure for interrupt status.
      */
     typedef struct {
-        bool irh;
-        bool irl;
-        bool tmph;
-        bool tmpl;
-        bool dr;
+        bool irh;                   /**< IR Sensor crossed high threshold. */
+        bool irl;                   /**< IR Sensor crossed low threshold. */
+        bool tmph;                  /**< Tempearture Sensor crossed high threshold. */
+        bool tmpl;                  /**< Temperature Sensor crossed low threshold. */
+        bool dr;                    /**< Data Ready. */
     } InterruptStatus;
 
     /**
-     * Structure for threshold.
+     * Structure to hold threshold levels.
      */    
     typedef struct {
-        int16_t thirh;        /**< High Threshold level of IR. */
-        int16_t thirl;        /**< Low Threshold level of IR. */
+        int16_t thirh;        /**< High Threshold level for IR sensor. */
+        int16_t thirl;        /**< Low Threshold level of IR sensor. */
         int16_t thtmph;       /**< High Threshold level of temperature sensor. */
         int16_t thtmpl;       /**< Low Threshold level of temperature sensor. */
     } Threshold;
     
     /**
-     * Structure for measurement data.
+     * Structure to hold all sensor data: IR, temperature, and interrupt flags.
      */
     typedef struct {
-        InterruptStatus intStatus;
-        int16_t ir;
-        int16_t temperature;
-        bool dor;
+        InterruptStatus intStatus;  /**< Interrupt status object */
+        int16_t ir;             /**< IR Sensor Data (pA) */
+        int16_t temperature;    /**< Temperature Data (deg C) */
+        bool dor;               /**< Data Overrun: 1:data skip, 0:after ST2 read*/
     } SensorData;
-    
+
     /**
      * Constructor.
      *
-     * @param conn instance of I2C
-     * @param addr slave address of the device
+     * @param conn Instance of I2C
+     * @param addr Slave address of the device
      */
-//    AK9752(I2C *conn, SlaveAddress addr);
     AK9752();
 
+    /**
+     * Initialize AK9752 connection.
+     *
+     * @param conn Instance of I2C
+     * @param addr I2C slave address
+     */
     void init(I2C *conn, SlaveAddress addr);
 
     /**
      * Checks AK9752 connection.
-     * @return Returns SUCCESS if connection is confirmed, otherwise returns other value.
+     *
+     * @return SUCCESS if connection is confirmed, otherwise returns other value.
      */
     Status checkConnection();
 
     /**
      * Gets interrupt enable/disable status.
-     * @param intStatus interrupt status
+     *
+     * @param intStatus Interrupt enable status
+     *
      * @return SUCCESS if the interrupt status is obtained successfully, otherwise returns other value.
      */
     Status getInterruptEnable(InterruptStatus *intStatus);
        
     /**
      * Sets interrupt enable/disable status.
+     *
      * @param intStatus interrupt status
+     *
      * @return SUCCESS if the interrupt status is set successfully, otherwise returns other value.
      */
     Status setInterruptEnable(const InterruptStatus *intStatus);
     
     /**
-     * Gets sensor operation mode.
+     * Gets sensor operation mode: Standby, Continuous or Single-Shot.
+     *
      * @param mode Pointer to the operation mode.
      * @param fc_tmp Pointer to the tempearture sensor filter setting.
      * @param fc_ir Pointer to the IR sensor filter setting.
+     *
      * @return SUCCESS if operation mode is set successfully, otherwise returns other value.
      */
     Status getOperationMode(OperationMode *mode, FcTmp *fc_tmp, FcIr *fc_ir);
        
     /**
-     * Sets sensor operation mode.
-     * @param mode operation mode to be set.
-     * @param fc_tmp filter cut-off frequency setting for temperature sensor
-     * @param fc_ir filter cut-off frequency setting for ir sensor
+     * Sets sensor Operation mode: Standby, Continuous or Single-Shot.
+     *
+     * @param mode Operation mode to be set.
+     * @param fc_tmp Filter cut-off frequency setting for temperature sensor.
+     * @param fc_ir Filter cut-off frequency setting for IR sensor.
+     *
      * @return SUCCESS if operation mode is set successfully, otherwise returns other value.
      */
     Status setOperationMode(OperationMode mode, FcTmp fc_tmp = FCTMP_NOFILTER, FcIr fc_ir = FCIR_NOFILTER);
        
     /**
-     * Sets threshold.
+     * Sets threshold of IR/temperature sensor.
+     *
      * @param th Pointer to the threshold structure to be set.
+     *
      * @return SUCCESS if threshold is set successfully, otherwise returns other value.
      */
     Status setThreshold(const Threshold *th);
     
     /**
-     * Gets threshold.
+     * Gets threshold of IR/temperature sensor.
+     *
      * @param th Pointer to the threshold structure to store the read data.
+     *
      * @return SUCCESS if threshold is read successfully, otherwise returns other value.
      */
     Status getThreshold(Threshold *th);
     
     /**
-     * Resets the device.
+     * Resets the AK9752.
+     *
      * @return SUCCESS if the device is reset successfully, otherwise returns other value.
      */
     Status reset();
     
     /**
-     * Gets sensor data.
+     * Retrieves all sensor data: IR & Temperature data, and ST1, ST2, & INTCAUSE 
+     * registers.
+     *
      * @param data Pointer to the SensorData structure object to store the read data.
+     *
      * @return SUCCESS if data is obtained successfully, otherwise returns other value.
      */
     Status getSensorData(SensorData *data);
     
     /**
-     * Reads register(s).
+     * Reads indicated AK9752 register(s).
+     *
      * @param registerAddress Register address to be read.
-     * @param buf Buffer to store the read data.
+     * @param buf Buffer to store the register data.
      * @param length Length in bytes to be read.
+     *
      * @return SUCCESS if data is read successfully, otherwise returns other value.
      */
     Status read(char registerAddress, char *buf, int length);
     
     /**
-     * Writes data into register(s).
+     * Writes data into AK9752 register(s).
+     *
      * @param registerAddress Register address to be written.
      * @param buf Data to be written.
      * @param length Length in bytes to be written.
+     *
      * @return SUCCESS if data is written successfully, otherwise returns other value.
      */
     Status write(char registerAddress, const char *buf, int length);
     
 private:
     /**
-     * Holds a pointer to an I2C object. 
+     * I2C connection. 
      */
     I2C *connection;
     
     /**
-     * Holds the slave address. 
+     * Slave address.
      */
     SlaveAddress slaveAddress;
 
 //    const static uint8_t IR_DATA_LEN = 7;    /**<! Data length of IR sensor. From ST1 to ST2. */
     
-    /**
-     * Gets sensor measurement data, from ST1 to ST2.
-     * @param buf Buffer to store the read data.
-     * @return SUCCESS if data is read successfully, otherwise returns other value.
-     */
-    Status getData(char *buf);
 };
 
 #endif // __AK9752_H__
\ No newline at end of file