From: Brendan Le Foll <brendan.le.foll@intel.com>
Date: Mon, 1 Sep 2014 14:31:55 +0000 (+0100)
Subject: doc: improve & complete documentation on many sensors
X-Git-Tag: v0.1.8~2
X-Git-Url: http://review.tizen.org/git/?p=contrib%2Fupm.git;a=commitdiff_plain;h=e3177c260c1987f1c2a7d78ae1be36fc7340fc9c

doc: improve & complete documentation on many sensors

Signed-off-by: Brendan Le Foll <brendan.le.foll@intel.com>
---

diff --git a/README.md b/README.md
index fab2595..5fe9467 100644
--- a/README.md
+++ b/README.md
@@ -25,7 +25,9 @@ may also create more complex structures in order to interface with them.
 
 Temperature Sensors:
   * upm::MAX31723
+  * upm::MAX31855
   * upm::TH02
+  * upm::GroveTemp
 
 Compass/Gyro/Magnometer Sensors:
   * upm::Hmc5883l
@@ -34,10 +36,11 @@ Compass/Gyro/Magnometer Sensors:
 Atmospheric Pressure Sensors:
   * upm::GY65
 
-Proximity Sensors:
+Light/Proximity Sensors:
   * upm::MAXDS3231M
   * upm::MAX44000
   * upm::HCSR04
+  * upm::GroveLight
 
 Gas Sensors:
   * upm::MQ2
@@ -51,16 +54,21 @@ Displays:
   * upm::ST7735
   * upm::SSD1308
   * upm::SSD1327
+
+LED controllers/segment displays:
   * upm::TM1637
+  * upm::MY9221
 
 RFID:
   * upm::SM130
 
 Wireless Communication:
   * upm::NRF24l01
+  * upm::NRF8001
 
-Servo
+Servo/motors:
   * upm::ES08A
+  * upm::stepmotor
 
 Digital potentiometer
   * upm::MAX5487
diff --git a/TODO b/TODO
new file mode 100644
index 0000000..2fdf5f6
--- /dev/null
+++ b/TODO
@@ -0,0 +1,27 @@
+Easy:
+MAX7221 - SPI 8 digit LED
+- https://mbed.org/components/MAX7221/
+- 
+SCA61T - inclinometer SPI
+- https://mbed.org/components/SCA61T-Inclinometer/
+DS1721 - i2c temperature/thermostat
+- https://mbed.org/components/DS1721/
+MPL3115A2 - i2c altimeter
+- https://mbed.org/components/MPL3115A2/
+- http://www.ebay.co.uk/itm/Barometric-Pressure-Altitude-Temperature-Sensor-I2C-MPL3115A2-/221499210102?pt=UK_BOI_Electrical_Test_Measurement_Equipment_ET&hash=item339261b976
+TEMT6200 - Ambient light sensor
+- https://mbed.org/components/TEMT6200/
+CMPS03 - i2c digital compass
+- https://mbed.org/components/CMPS03-Digital-Compass/
+- http://www.ebay.co.uk/itm/Magnetic-Compass-CMPS03-/221437925374?pt=UK_BOI_Electrical_Test_Measurement_Equipment_ET&hash=item338eba97fe
+- http://www.robot-italy.com/it/cmps03-robot-compass-module.html
+
+Medium
+E-ink sharp 1.3" LCD
+- https://mbed.org/components/13-SHARP-Memory-LCD/
+LCD-S401
+- https://mbed.org/components/Lumex-LCD-S401/
+
+Hard:
+RA8875 - 480x272 SPI 4 wire
+- https://mbed.org/components/RA8875-Based-Display/
diff --git a/docs/images/grovegas.jpeg b/docs/images/grovegas.jpeg
new file mode 100644
index 0000000..fdc0f8b
Binary files /dev/null and b/docs/images/grovegas.jpeg differ
diff --git a/docs/images/grovergblcd.jpeg b/docs/images/grovergblcd.jpeg
new file mode 100644
index 0000000..75edc63
Binary files /dev/null and b/docs/images/grovergblcd.jpeg differ
diff --git a/docs/images/lcm1602.jpeg b/docs/images/lcm1602.jpeg
new file mode 100644
index 0000000..9a16198
Binary files /dev/null and b/docs/images/lcm1602.jpeg differ
diff --git a/docs/images/lpd8806.jpeg b/docs/images/lpd8806.jpeg
new file mode 100644
index 0000000..68dc12e
Binary files /dev/null and b/docs/images/lpd8806.jpeg differ
diff --git a/docs/images/max31723.jpeg b/docs/images/max31723.jpeg
index 41bbca6..8165d69 100644
Binary files a/docs/images/max31723.jpeg and b/docs/images/max31723.jpeg differ
diff --git a/docs/images/max31855.jpeg b/docs/images/max31855.jpeg
new file mode 100644
index 0000000..bf33a04
Binary files /dev/null and b/docs/images/max31855.jpeg differ
diff --git a/docs/images/max44000.jpeg b/docs/images/max44000.jpeg
new file mode 100644
index 0000000..48044bf
Binary files /dev/null and b/docs/images/max44000.jpeg differ
diff --git a/docs/images/mq9.jpeg b/docs/images/mq9.jpeg
new file mode 100644
index 0000000..e782a73
Binary files /dev/null and b/docs/images/mq9.jpeg differ
diff --git a/docs/images/ssd1308.jpeg b/docs/images/ssd1308.jpeg
new file mode 100644
index 0000000..d297475
Binary files /dev/null and b/docs/images/ssd1308.jpeg differ
diff --git a/docs/images/ssd1327.jpeg b/docs/images/ssd1327.jpeg
new file mode 100644
index 0000000..e6a339a
Binary files /dev/null and b/docs/images/ssd1327.jpeg differ
diff --git a/src/gas/README.txt b/src/gas/README.txt
index a1d475d..fab9cf4 100644
--- a/src/gas/README.txt
+++ b/src/gas/README.txt
@@ -1,4 +1,4 @@
-Grove - Gas Sensor(MQ-2)：Combustible Gas、Smoke [middle sensitivity]
+Grove - Gas Sensor(MQ-2)：Combustible Gas Smoke [middle sensitivity]
 Grove - Gas Sensor(MQ-3)：Alcohol and Benzine [HIGH sensitivity] Long warmup
 Grove - Gas Sensor(MQ-5)：LPG, Natural Gas, Town Gas [high sensitivity]
 Grove - Gas Sensor(MQ-9)：LPG, CO, CH4 [low sensitivity]
diff --git a/src/gas/gas.h b/src/gas/gas.h
index 22453a4..efb12b1 100644
--- a/src/gas/gas.h
+++ b/src/gas/gas.h
@@ -38,7 +38,7 @@ namespace upm {
 /**
  * @brief C++ API for Gas sensors
  *
- * This file defines the Gas Analog sensors
+ * This file defines the Gas Analog sensors virtual functions
  */
 class Gas {
     public:
diff --git a/src/gas/mq2.h b/src/gas/mq2.h
index 53683f8..fb2046a 100644
--- a/src/gas/mq2.h
+++ b/src/gas/mq2.h
@@ -31,7 +31,13 @@ namespace upm {
     /**
      * @brief C++ API for MQ2 gas sensor
      *
+     * The Grove - Gas Sensor (MQ2) module is useful for gas leakage detecting
+     * (in home and industry). It can detect LPG, i-butane, methane, alcohol,
+     * Hydrogen, smoke and other combustible gases. It's a medium sensitivity
+     * sensor with a detect concentration of 300-10000ppm.
+     *
      * @snippet mq2-example.cxx Interesting
+     * @image html grovegas.jpeg
      */
     class MQ2 : public Gas {
         public:
diff --git a/src/gas/mq3.h b/src/gas/mq3.h
index 15b6b0a..c4f9ada 100644
--- a/src/gas/mq3.h
+++ b/src/gas/mq3.h
@@ -31,7 +31,13 @@ namespace upm {
     /**
      * @brief C++ API for MQ3 gas sensor
      *
+     * The Grove MQ3 Gas Sensor module is useful for gas leakage detecting (in
+     * home and industry). It can detect Alcohol Vapour and Benzine. It's
+     * highly sensitive but has a long warmup time of about 1minute. It's
+     * detect rate is of 0.04-4mg/L Alcohol.
+     *
      * @snippet mq3-example.cxx Interesting
+     * @image html grovegas.jpeg
      */
     class MQ3 : public Gas {
         public:
diff --git a/src/gas/mq5.h b/src/gas/mq5.h
index b890099..fc931db 100644
--- a/src/gas/mq5.h
+++ b/src/gas/mq5.h
@@ -31,7 +31,13 @@ namespace upm {
     /**
      * @brief C++ API for MQ5 gas sensor
      *
+     * The Grove - Gas Sensor (MQ5) module is useful for gas leakage detecting
+     * (in home and industry). It can detect LPG, natural gas, town gas and so
+     * on. It is highly sensitive and has a detection concentration of
+     * 300-10000ppm.
+     *
      * @snippet mq5-example.cxx Interesting
+     * @image html grovegas.jpeg
      */
     class MQ5 : public Gas {
         public:
diff --git a/src/gas/mq9.h b/src/gas/mq9.h
index 9017c5b..67ede9e 100644
--- a/src/gas/mq9.h
+++ b/src/gas/mq9.h
@@ -31,7 +31,12 @@ namespace upm {
     /**
      * @brief C++ API for MQ9 gas sensor
      *
+     * The Grove MQ9 Gas Sensor module is useful for gas leakage detecting (in
+     * home and industry). It can detect Carbon Monoxide, Coal Gas and
+     * Liquefied Gas. It's sensitivty is 10-1000ppmCO 100-10000PPm Gas.
+     *
      * @snippet mq9-example.cxx Interesting
+     * @image html mq9.jpeg
      */
     class MQ9 : public Gas {
         public:
diff --git a/src/lcd/jhd1313m1.h b/src/lcd/jhd1313m1.h
index 994483f..aafffe9 100644
--- a/src/lcd/jhd1313m1.h
+++ b/src/lcd/jhd1313m1.h
@@ -32,7 +32,14 @@ namespace upm {
  * @brief C++ API for Jhd1313m1 i2c controller for HD44780 based displays with
  * an RGB backlight such as the Grove RGB i2c LCD display
  *
+ * The Jhd1313m1 has two i2c addreses, one belongs to a controller very similar
+ * to the upm::Lcm1602 LCD driver which controls the HD44780 based display and the
+ * other controls solely the backlight. This module was tested with the Seed
+ * [Grove LCD RGB Backlight v2.0 display]
+ * (http://www.seeedstudio.com/depot/Grove-LCD-RGB-Backlight-p-1643.html?cPath=34_36)
+ *
  * @snippet rgb-lcd.cxx Interesting
+ * @image html grovergblcd.jpeg
  */
 class Jhd1313m1 : public I2CLcd {
     public:
diff --git a/src/lcd/lcm1602.h b/src/lcd/lcm1602.h
index 386def9..0dfdd03 100644
--- a/src/lcd/lcm1602.h
+++ b/src/lcd/lcm1602.h
@@ -37,9 +37,13 @@ namespace upm {
  *
  * This supports all sizes of HD44780 displays from 16x2 to 4x20, the
  * controller has no idea of the actual display hardware so will let you write
- * further than you can see
+ * further than you can see. These displays with such controllers are available
+ * from various manufacturers with different i2c addresses. The adafruit
+ * [TC1602A-01T](https://www.adafruit.com/datasheets/TC1602A-01T.pdf) seems to
+ * the best documented example.
  *
  * @snippet lcm-lcd.cxx Interesting
+ * @image html lcm1602.jpeg
  */
 class Lcm1602 : public I2CLcd {
     public:
diff --git a/src/lcd/ssd1308.h b/src/lcd/ssd1308.h
index d125df0..abc51c0 100644
--- a/src/lcd/ssd1308.h
+++ b/src/lcd/ssd1308.h
@@ -148,7 +148,15 @@ typedef enum {
 /**
  * @brief C++ API for SSD1308 i2c controlled OLED displays
  *
- * @snippet lcm-lcd.cxx Interesting
+ * The [SSD1308](http://garden.seeedstudio.com/images/4/46/SSD1308_1.0.pdf) is
+ * a 128x64 Dot matrix OLED/PLED segment driver with controller. This
+ * implementation was tested using the
+ * [Grove LED 128×64 Display module]
+ * (http://www.seeedstudio.com/wiki/Grove_-_OLED_Display_0.96%22)
+ * which is an OLED monochrome display
+ *
+ * @snippet oled-1308.cxx Interesting
+ * @image html ssd1308.jpeg
  */
 class SSD1308 : public I2CLcd {
     public:
diff --git a/src/lcd/ssd1327.h b/src/lcd/ssd1327.h
index 8b016e3..f5bc132 100644
--- a/src/lcd/ssd1327.h
+++ b/src/lcd/ssd1327.h
@@ -145,10 +145,23 @@ typedef enum {
     PAGE          =  2
 } displayAddressingMode;
 
+/**
+ * @brief C++ API for SSD1327 i2c controlled OLED displays
+ *
+ * The [SSD1327](http://garden.seeedstudio.com/images/8/82/SSD1327_datasheet.pdf)
+ * is a 96x96 Dot matrix OLED/PLED segment driver with controller. This
+ * implementation was tested using the
+ * [Grove LED 96×96 Display module]
+ * (http://www.seeedstudio.com/wiki/Grove_-_OLED_Display_1.12%22)
+ * which is an OLED monochrome display
+ *
+ * @snippet oled-1327.cxx Interesting
+ * @image html ssd1327.jpeg
+ */
 class SSD1327 : public I2CLcd {
     public:
         /**
-         * SSD1308 Constructor, calls libmraa initialisation functions
+         * SSD1327 Constructor, calls libmraa initialisation functions
          *
          * @param bus i2c bus to use
          * @param address the slave address the lcd is registered on
diff --git a/src/lpd8806/lpd8806.h b/src/lpd8806/lpd8806.h
index a84b8e1..ee17650 100644
--- a/src/lpd8806/lpd8806.h
+++ b/src/lpd8806/lpd8806.h
@@ -36,8 +36,10 @@ namespace upm {
 /**
  * @brief C++ API for LPD8806 
  *
- * This file defines the LPD8806 C++ interface for liblpd8806
+ * The FastPixel lpd8806 is an RGB led strip controller.
  *
+ * @snippet lpd8806-example.cxx Interesting
+ * @image html lpd8806.jpeg
  */
 class LPD8806 {
     public:
diff --git a/src/max31723/max31723.h b/src/max31723/max31723.h
index c77594c..27214bd 100644
--- a/src/max31723/max31723.h
+++ b/src/max31723/max31723.h
@@ -43,8 +43,8 @@ namespace upm {
  * module](http://datasheets.maximintegrated.com/en/ds/MAX31723PMB1.pdf) from
  * the analog PMOD kit.
  *
+ * @snippet max31723.cxx Interesting
  * @image html max31723.jpeg
- *
  */
 class MAX31723 {
     public:
diff --git a/src/max31855/max31855.h b/src/max31855/max31855.h
index 27f2419..1990099 100644
--- a/src/max31855/max31855.h
+++ b/src/max31855/max31855.h
@@ -32,12 +32,17 @@ namespace upm {
 /**
  * @brief C++ API for MAX31855
  *
- * This file defines the max31855 SPI sensor
- *
- * @snippet examples/max31855.cxx Interesting
+ * The Maxim Integrated
+ * [MAX31855](http://datasheets.maximintegrated.com/en/ds/MAX31855.pdf)
+ * is a Cold-Junction Compensated Thermocouple-to-Digital Converter. This
+ * module was * tested on the Maxim Integrated 
+ * [MAX31855PMB1 PMOD module]
+ * (http://datasheets.maximintegrated.com/en/ds/MAX31855PMB1.pdf) from the
+ * analog PMOD kit.
  *
+ * @snippet max31855.cxx Interesting
+ * @image html max31855.jpeg
  */
- //! [Interesting]
 class MAX31855 {
     public:
         /**
@@ -64,6 +69,5 @@ class MAX31855 {
         mraa_spi_context m_sensor;
         mraa_gpio_context m_gpio;
 };
-//! [Interesting]
 
 }
diff --git a/src/max44000/max44000.h b/src/max44000/max44000.h
index 8bf5580..2e0bbb2 100644
--- a/src/max44000/max44000.h
+++ b/src/max44000/max44000.h
@@ -55,20 +55,16 @@ namespace upm {
 /**
  * @brief C++ API for MAX44000 chip (Ambient and Infrared Proximity Sensor)
  *
- * This file defines the MAX44000 C++ interface for libmax44000
- *
- * @snippet proximity.cxx Interesting
- *
- * PMOD pins for MAX44000PMB1 board
- *
- * ( -= J1 =- )
- * (1) - NUL
- * (2) - IRQ
- * (3) - SCL
- * (4) - SDA
- * (5) - GND
- * (6) - VCC
+ * The Maxim Integrated
+ * [MAX44000](http://datasheets.maximintegrated.com/en/ds/MAX44000.pdf)
+ * is Ambient and Infrared Proximity Sensor. This module was tested on the
+ * Maxim Integrated 
+ * [MAX44000PMB1 PMOD module]
+ * (http://datasheets.maximintegrated.com/en/ds/MAX44000PMB1.pdf) from the
+ * analog PMOD kit.
  *
+ * @snippet max44000.cxx Interesting
+ * @image html max44000.jpeg
  */
 class MAX44000 {
     public:
diff --git a/src/sm130/sm130.h b/src/sm130/sm130.h
index 0d773c1..61bcebb 100644
--- a/src/sm130/sm130.h
+++ b/src/sm130/sm130.h
@@ -44,7 +44,6 @@ namespace upm {
  * @brief C++ API for SM130 RFID reader module
  *
  * This file defines the SM130 C++ interface for libsm130
- *
  */
 class SM130 {