Revision 2:96d9bfe25b03, committed 2016-05-05

Comitter:

coisme

Date:

Thu May 05 17:55:23 2016 +0000

Parent:

1:bc877c37027c

Commit message:

Documentation done.

Changed in this revision

--- a/mcp342x.cpp	Fri Apr 29 23:53:18 2016 +0000
+++ b/mcp342x.cpp	Thu May 05 17:55:23 2016 +0000
@@ -214,4 +214,5 @@
     currentConfig.measurementTrigger = NONE;
     
     return status;
-}
\ No newline at end of file
+}
+

--- a/mcp342x.h	Fri Apr 29 23:53:18 2016 +0000
+++ b/mcp342x.h	Thu May 05 17:55:23 2016 +0000
@@ -3,6 +3,70 @@
 
 #include "mbed.h"
 
+/**
+ * Device driver for MCP3426, MCP3427, and MCP3428.
+ * @note MCP342x is Analog-to-Digital Converter (ADC) IC with I2C interface.
+ *
+ * Example:
+ * @code
+ * #include "mbed.h"
+ * #include "mcp342x.h"
+ *
+ * #define I2C_SPEED_100KHZ    100000
+ * #define I2C_SPEED_400KHZ    400000
+ * #define PIN_SERIAL_TX   P0_4
+ * #define PIN_SERIAL_RX   P0_5 
+ *
+ * int16_t getAdcData(MCP342X *mcp3428, MCP342X::AdcChannel ch, MCP342X::SampleSetting s) {
+ *     // Configure channel and trigger.
+ *     mcp3428->setChannel(ch);
+ *     mcp3428->setSampleSetting(s);
+ *     mcp3428->trigger();
+ *
+ *     // polling data
+ *     MCP342X::Data data;
+ *     do {
+ *         wait_ms(WAIT_ADC_MS);
+ *         mcp3428->getData(&data);
+ *     } while(data.st == MCP342X::DATA_NOT_UPDATED);
+ *
+ *     return data.value;
+ * }
+ *
+ * int main(void) {
+ *     // Instanciate I2C
+ *     I2C i2c(I2C_SDA0, I2C_SCL0);
+ *     i2c.frequency(I2C_SPEED_400KHZ);
+ *
+ *     // Serial output for debug. (optional)
+ *     Serial serial(PIN_SERIAL_TX, PIN_SERIAL_RX);
+ *
+ *     // Instanciate MCP342x
+ *     // Suppose that the slave address of MCP342x on your board is .
+ *     MCP342X mcp342x(&i2c, MCP342X::SLAVE_ADDRESS_68H);
+ *
+ *     // Sets MCP342x one-shot measurement mode.
+ *     mcp342x.setSampleSetting(MCP342X::ONE_SHOT); 
+ *
+ *     while(true) {
+ *         // Supposes that the device is MCP3428, which has 4 channels.
+ *         const uint8_t CHANNEL_NUM = 4;
+ *         // Sampling setting. Ch1 is 12-bit, Ch2 is 14-bit, Ch3 is 16-bit, Ch4 is 16-bit.
+ *         const MCP342X::SampleSetting sampleSetting[CHANNEL_NUM] = 
+ *                 {MCP342X::SAMPLE_240HZ_12BIT, MCP342X::SAMPLE_60HZ_14BIT,
+ *                  MCP342X::SAMPLE_15HZ_16BIT, MCP342X::SAMPLE_15HZ_16BIT};
+ *         // Data buffer.
+ *         int16_t data[CHANNEL_NUM];
+ *         // Measures each channel.
+ *         for (int i=0; i < CHANNEL_NUM; i++) {
+ *             mcp342x.getAdcData(&data[i], (MCP342X::AdcChannel)i, sampleSetting[i]);
+ *         }
+ *         // Prints out the ADC results.
+ *         serial.printf("%d, %d, %d, %d\r\n", data[0], data[1], data[2], data[3]);
+ *     }
+ * }
+ * @endcode
+ */
 class MCP342X
 {
 public:
@@ -10,14 +74,14 @@
      * Slave addresses.
      */
     typedef enum {
-        SLAVE_ADDRESS_68H,     /**< When Adr0 pin = L and Adr1 pin = L, or Adr0 pin = float and Adr1 pin = float. */
-        SLAVE_ADDRESS_69H,     /**< When Adr0 pin = L and Adr1 pin = float. */
-        SLAVE_ADDRESS_6AH,     /**< When Adr0 pin = L and Adr1 pin = H. */
-        SLAVE_ADDRESS_6CH,     /**< When Adr0 pin = H and Adr1 pin = L. */
-        SLAVE_ADDRESS_6DH,     /**< When Adr0 pin = H and Adr1 pin = float. */
-        SLAVE_ADDRESS_6EH,     /**< When Adr0 pin = H and Adr1 pin = H. */
-        SLAVE_ADDRESS_6BH,     /**< When Adr0 pin = float and Adr1 pin = L. */
-        SLAVE_ADDRESS_6FH,     /**< When Adr0 pin = float and Adr1 pin = H. */
+        SLAVE_ADDRESS_68H = 0x68,     /**< When Adr0 pin = L and Adr1 pin = L, or Adr0 pin = float and Adr1 pin = float. */
+        SLAVE_ADDRESS_69H = 0x69,     /**< When Adr0 pin = L and Adr1 pin = float. */
+        SLAVE_ADDRESS_6AH = 0x6A,     /**< When Adr0 pin = L and Adr1 pin = H. */
+        SLAVE_ADDRESS_6CH = 0x6C,     /**< When Adr0 pin = H and Adr1 pin = L. */
+        SLAVE_ADDRESS_6DH = 0x6D,     /**< When Adr0 pin = H and Adr1 pin = float. */
+        SLAVE_ADDRESS_6EH = 0x6E,     /**< When Adr0 pin = H and Adr1 pin = H. */
+        SLAVE_ADDRESS_6BH = 0x6B,     /**< When Adr0 pin = float and Adr1 pin = L. */
+        SLAVE_ADDRESS_6FH = 0x6F,     /**< When Adr0 pin = float and Adr1 pin = H. */
     } SlaveAddress;
     
     /**
@@ -68,10 +132,10 @@
      * ADC channel selection.
      */
     typedef enum {
-        ADC_CH1,                 /**< Channel 1, default. */
-        ADC_CH2,                 /**< Channel 2 */
-        ADC_CH3,                 /**< Channel 3, MCP3428 only, treated as channel 1 by the MCP3426/MCP3427. */
-        ADC_CH4,                 /**< Channel 4, MCP3428 only, treated as channel 2 by the MCP3426/MCP3427. */
+        ADC_CH1 = 0,                 /**< Channel 1, default. */
+        ADC_CH2 = 1,                 /**< Channel 2 */
+        ADC_CH3 = 2,                 /**< Channel 3, MCP3428 only, treated as channel 1 by the MCP3426/MCP3427. */
+        ADC_CH4 = 3,                 /**< Channel 4, MCP3428 only, treated as channel 2 by the MCP3426/MCP3427. */
     } AdcChannel;
     
     /**
@@ -85,18 +149,18 @@
     } PgaSetting;
     
     /**
-     * AD result data.
+     * ADC result.
      */
     typedef struct {
         DataStatus st;
-        int16_t value;
+        int16_t value;  /**< ADC value. The value takes from -2^11 to (2^11 - 1) when 12 bit sample mode, from -2^13 to (2^13 - 1) when 14 bit sample mode, from -2^15 to (2^15 - 1) when 16bit sample mode. */
     } Data;
     
     /**
      * Constructor.
      *
-     * @param conn instance of I2C
-     * @param addr slave address of the device
+     * @param conn Pointer to an instance of I2C.
+     * @param addr Slave address of the device.
      */
     MCP342X(I2C *conn, SlaveAddress addr);
 
@@ -127,7 +191,7 @@
     ConversionMode getConversionMode();
 
     /**
-     * Sets sample setting.
+     * Sets sample setting, i.e. sampling frequency and resolution bits.
      * @param s Sample setting to be set.
      * @return SUCCESS when succeeded. Other value will be returned when error.
      */
@@ -140,14 +204,14 @@
     SampleSetting getSampleSetting();
     
     /**
-     * Sets gain of Programmable Gain Amplifier (PGA).
+     * Sets the gain of Programmable Gain Amplifier (PGA).
      * @param s PGA seeting to be set.
      * @return SUCCESS when succeeded. Other value will be returned when error.
      */
     Status setPgaSetting(PgaSetting s);
     
     /**
-     * Gets the current PGA setting.
+     * Gets the current Programmable Gain Amplifier (PGA) setting.
      * @return Current PGA setting.
      */
     PgaSetting getPgaSetting();
@@ -159,17 +223,11 @@
     Status getData(Data *pt);
     
     /**
-     * Trigger AD conversion.
+     * Trigger AD conversion. In continuous measurement mode, this function has no effect.
      * @return SUCCESS when succeeded. Other value will be returned when error.
      */
     Status trigger();
     
-    /**
-     * Gets the data conversion time.
-     * @return Conversion time based on the current sample setting in milli-second unit.
-     */
-     float getDataConversionTime();
-    
 private:
     typedef struct {
         MeasurementTrigger   measurementTrigger;