lsm303: rename to lsm303dlh

There are a variety of LSM303 devices out there with various
incompatibilities and differing capabilities.  The current lsm303
driver in UPM only supports the LSM303DLH variant, so it has been
renamed to lsm303dlh to avoid confusion and to make it clear which
variant is actually supported.

All examples and source files have been renamed, including header
files.  In addition, the class name, LSM303, has been renamed to
LSM303DLH.  No other functionality or behavior has been changed.

Signed-off-by: Jon Trulson <jtrulson@ics.com>

docs/apichanges.md

@@ -4,11 +4,23 @@ API Changes                       {#apichanges}
 Here's a list of other API changes made to the library that break source/binary
 compatibility between releases:
 
+# current UPM master
+
+ * **The lsm303 driver has been renamed** There are a variety of
+ LSM303 devices out there with various incompatibilities and differing
+ capabilities.  The current lsm303 driver in UPM only supports the
+ LSM303DLH variant, so it has been renamed to lsm303dlh to avoid
+ confusion and to make it clear which variant is actually supported.
+
+    All examples and source files have been renamed, including header
+    files.  In addition, the class name, LSM303, has been renamed to
+    LSM303DLH.  No other functionality or behavior has been changed.
+
 # v1.2.0
 
  * **Note for all drivers ported to C** As a general note concerning
  all of the drivers that have been ported to C: **external constants
- have likely been renamed**.  Previously in C++, most these constants
+ have likely been renamed**.  Previously in C++, most of these constants
  were defined as enums in the *upm::classname* namespace.
 
     For drivers written in C, all of these constants are no longer in

examples/c++/lsm303dlh.cxx

@@ -25,19 +25,19 @@
 #include <iostream>
 
 //! [Interesting]
-#include "lsm303.hpp"
+#include "lsm303dlh.hpp"
 
 int
 main(int argc, char **argv)
 {
-	// Instantiate LSM303 compass on I2C
-    upm::LSM303 *sensor = new upm::LSM303(0);
+	// Instantiate LSM303DLH compass on I2C
+    upm::LSM303DLH *sensor = new upm::LSM303DLH(0);
 
     // Get the coordinate data
     sensor->getCoordinates();
-    int16_t* coor = sensor->getRawCoorData(); // in XYZ order. 
+    int16_t* coor = sensor->getRawCoorData(); // in XYZ order.
     // The sensor returns XZY, but the driver compensates and makes it XYZ
-    
+
     // Print out the X, Y, and Z coordinate data using two different methods
     std::cout << "coor: rX " << (int)coor[0]
               << " - rY " << (int)coor[1]

examples/java/CMakeLists.txt

@@ -86,7 +86,7 @@ add_example(Itg3200Sample itg3200)
 add_example(Joystick12Sample joystick12)
 add_example(LDT0028Sample ldt0028)
 add_example(LoLSample lol)
-add_example(LSM303Sample lsm303)
+add_example(LSM303DLHSample lsm303dlh)
 add_example(M24LR64ESample m24lr64e)
 add_example(MAX44000Sample max44000)
 add_example(MHZ16Sample mhz16)

examples/java/LSM303DLHSample.java

@@ -23,12 +23,12 @@
  */
 
 //NOT TESTED!!!
-public class LSM303Sample {
+public class LSM303DLHSample {
 
 	public static void main(String[] args) throws InterruptedException {
 		// ! [Interesting]
-		// Instantiate LSM303 compass on I2C
-		upm_lsm303.LSM303 sensor = new upm_lsm303.LSM303(0);
+		// Instantiate LSM303DLH compass on I2C
+		upm_lsm303dlh.LSM303DLH sensor = new upm_lsm303dlh.LSM303DLH(0);
 
 		// Get the coordinate data
 		sensor.getCoordinates();
@@ -56,4 +56,4 @@ public class LSM303Sample {
 		// ! [Interesting]
 	}
 
-}
+}

examples/javascript/lsm303dhl.js

@@ -22,15 +22,15 @@
 * WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
 */
 
-var accelrCompassSensor = require('jsupm_lsm303');
+var accelrCompassSensor = require('jsupm_lsm303dlh');
 
-// Instantiate LSM303 compass on I2C
-var myAccelrCompass = new accelrCompassSensor.LSM303(0);
+// Instantiate LSM303DLH compass on I2C
+var myAccelrCompass = new accelrCompassSensor.LSM303DLH(0);
 
 var successFail, coords, outputStr, accel;
 var myInterval = setInterval(function()
 {
-	// Load coordinates into LSM303 object
+	// Load coordinates into LSM303DLH object
 	successFail = myAccelrCompass.getCoordinates();
 	// in XYZ order. The sensor returns XZY,
 	// but the driver compensates and makes it XYZ

examples/python/lsm303dlh.py

@@ -25,11 +25,11 @@
 
 from __future__ import print_function
 import time, sys, signal, atexit
-from upm import pyupm_lsm303 as lsm303
+from upm import pyupm_lsm303dlh as lsm303dlh
 
 def main():
-    # Instantiate LSM303 compass on I2C
-    myAccelrCompass = lsm303.LSM303(0)
+    # Instantiate LSM303DLH compass on I2C
+    myAccelrCompass = lsm303dlh.LSM303DLH(0)
 
     ## Exit handlers ##
     # This stops python from printing a stacktrace when you hit control-C
@@ -47,7 +47,7 @@ def main():
     signal.signal(signal.SIGINT, SIGINTHandler)
 
     while(1):
-        # Load coordinates into LSM303 object
+        # Load coordinates into LSM303DLH object
         successFail = myAccelrCompass.getCoordinates()
         # in XYZ order. The sensor returns XZY,
         # but the driver compensates and makes it XYZ

src/lsm303dlh/CMakeLists.txt

@@ -1,4 +1,4 @@
-set (libname "lsm303")
+set (libname "lsm303dlh")
 set (libdescription "Triaxial Accelerometer/magnetometer")
 set (module_src ${libname}.cxx)
 set (module_hpp ${libname}.hpp)

src/lsm303dlh/javaupm_lsm303dlh.i

@@ -1,8 +1,8 @@
-%module javaupm_lsm303
+%module javaupm_lsm303dlh
 %include "../upm.i"
 
 %{
-    #include "lsm303.hpp"
+    #include "lsm303dlh.hpp"
 %}
 
 %typemap(jni) int16_t* "jshortArray"
@@ -18,15 +18,15 @@
     JCALL4(SetShortArrayRegion, jenv, $result, 0, 3, (jshort*)$1);
 }
 
-%include "lsm303.hpp"
+%include "lsm303dlh.hpp"
 
 %pragma(java) jniclasscode=%{
     static {
         try {
-            System.loadLibrary("javaupm_lsm303");
+            System.loadLibrary("javaupm_lsm303dlh");
         } catch (UnsatisfiedLinkError e) {
             System.err.println("Native code library failed to load. \n" + e);
             System.exit(1);
         }
     }
-%}
+%}

src/lsm303dlh/jsupm_lsm303dlh.i

@@ -1,4 +1,4 @@
-%module jsupm_lsm303
+%module jsupm_lsm303dlh
 %include "../upm.i"
 %include "../carrays_int16_t.i"
 
@@ -9,7 +9,7 @@
 }
 
 %{
-    #include "lsm303.hpp"
+    #include "lsm303dlh.hpp"
 %}
 
-%include "lsm303.hpp"
+%include "lsm303dlh.hpp"

src/lsm303dlh/lsm303dlh.cxx

@@ -31,11 +31,12 @@
 #include <unistd.h>
 #include <stdlib.h>
 
-#include "lsm303.hpp"
+#include "lsm303dlh.hpp"
 
 using namespace upm;
 
-LSM303::LSM303(int bus, int addrMag, int addrAcc, int accScale) : m_i2c(bus)
+LSM303DLH::LSM303DLH(int bus, int addrMag, int addrAcc, int accScale) :
+    m_i2c(bus)
 {
     m_addrMag = addrMag;
     m_addrAcc = addrAcc;
@@ -45,11 +46,11 @@ LSM303::LSM303(int bus, int addrMag, int addrAcc, int accScale) : m_i2c(bus)
 
     // scale can be 2, 4 or 8
     if (2 == accScale) {
-      setRegisterSafe(m_addrAcc, CTRL_REG4_A, 0x00);
+        setRegisterSafe(m_addrAcc, CTRL_REG4_A, 0x00);
     } else if (4 == accScale) {
-      setRegisterSafe(m_addrAcc, CTRL_REG4_A, 0x10);
+        setRegisterSafe(m_addrAcc, CTRL_REG4_A, 0x10);
     } else { // default; equivalent to 8g
-      setRegisterSafe(m_addrAcc, CTRL_REG4_A, 0x30);
+        setRegisterSafe(m_addrAcc, CTRL_REG4_A, 0x30);
     }
 
     // 0x10 = minimum datarate ~15Hz output rate
@@ -65,7 +66,7 @@ LSM303::LSM303(int bus, int addrMag, int addrAcc, int accScale) : m_i2c(bus)
 }
 
 float
-LSM303::getHeading()
+LSM303DLH::getHeading()
 {
     if (getCoordinates() != mraa::SUCCESS) {
         return -1;
@@ -80,37 +81,37 @@ LSM303::getHeading()
 }
 
 int16_t*
-LSM303::getRawAccelData()
+LSM303DLH::getRawAccelData()
 {
     return &accel[0];
 }
 
 int16_t*
-LSM303::getRawCoorData()
+LSM303DLH::getRawCoorData()
 {
     return &coor[0];
 }
 
 int16_t
-LSM303::getAccelX()
+LSM303DLH::getAccelX()
 {
-  return accel[X];
+    return accel[X];
 }
 
 int16_t
-LSM303::getAccelY()
+LSM303DLH::getAccelY()
 {
-  return accel[Y];
+    return accel[Y];
 }
 
 int16_t
-LSM303::getAccelZ()
+LSM303DLH::getAccelZ()
 {
-  return accel[Z];
+    return accel[Z];
 }
 
 mraa::Result
-LSM303::getCoordinates()
+LSM303DLH::getCoordinates()
 {
     mraa::Result ret = mraa::SUCCESS;
 
@@ -125,7 +126,7 @@ LSM303::getCoordinates()
     // convert to coordinates
     for (int i=0; i<3; i++) {
         coor[i] = (int16_t(buf[2*i] << 8))
-                |  int16_t(buf[(2*i)+1]);
+            |  int16_t(buf[(2*i)+1]);
     }
     // swap elements 1 and 2 to get things in natural XYZ order
     int16_t t = coor[2];
@@ -137,24 +138,24 @@ LSM303::getCoordinates()
 }
 
 int16_t
-LSM303::getCoorX() {
-  return coor[X];
+LSM303DLH::getCoorX() {
+    return coor[X];
 }
 
 int16_t
-LSM303::getCoorY() {
-  return coor[Y];
+LSM303DLH::getCoorY() {
+    return coor[Y];
 }
 
 int16_t
-LSM303::getCoorZ() {
-  return coor[Z];
+LSM303DLH::getCoorZ() {
+    return coor[Z];
 }
 
 // helper function that writes a value to the acc and then reads
 // FIX: shouldn't this be write-then-read?
 int
-LSM303::readThenWrite(uint8_t reg)
+LSM303DLH::readThenWrite(uint8_t reg)
 {
     m_i2c.address(m_addrAcc);
     m_i2c.writeByte(reg);
@@ -163,16 +164,16 @@ LSM303::readThenWrite(uint8_t reg)
 }
 
 mraa::Result
-LSM303::getAcceleration()
+LSM303DLH::getAcceleration()
 {
     mraa::Result ret = mraa::SUCCESS;
 
     accel[X] = (int16_t(readThenWrite(OUT_X_H_A)) << 8)
-             |  int16_t(readThenWrite(OUT_X_L_A));
+        |  int16_t(readThenWrite(OUT_X_L_A));
     accel[Y] = (int16_t(readThenWrite(OUT_Y_H_A)) << 8)
-             |  int16_t(readThenWrite(OUT_Y_L_A));
+        |  int16_t(readThenWrite(OUT_Y_L_A));
     accel[Z] = (int16_t(readThenWrite(OUT_Z_H_A)) << 8)
-             |  int16_t(readThenWrite(OUT_Z_L_A));
+        |  int16_t(readThenWrite(OUT_Z_L_A));
     //printf("X=%x, Y=%x, Z=%x\n", accel[X], accel[Y], accel[Z]);
 
     return ret;
@@ -180,7 +181,7 @@ LSM303::getAcceleration()
 
 // helper function that sets a register and then checks the set was succesful
 mraa::Result
-LSM303::setRegisterSafe(uint8_t slave, uint8_t sregister, uint8_t data)
+LSM303DLH::setRegisterSafe(uint8_t slave, uint8_t sregister, uint8_t data)
 {
     buf[0] = sregister;
     buf[1] = data;

src/lsm303dlh/lsm303dlh.hpp

@@ -32,11 +32,11 @@
 
 namespace upm {
 
-/* LSM303 Address definitions */
-#define LSM303_MAG 0x1E
-#define LSM303_ACC 0x19
+/* LSM303DLH Address definitions */
+#define LSM303DLH_MAG 0x1E
+#define LSM303DLH_ACC 0x19
 
-/* LSM303 Register definitions */
+/* LSM303DLH Register definitions */
 #define CTRL_REG1_A 0x20
 #define CTRL_REG2_A 0x21
 #define CTRL_REG3_A 0x22
@@ -61,14 +61,14 @@ namespace upm {
 #define Z 2
 
 /**
- * @brief LSM303 Accelerometer/Compass library
- * @defgroup lsm303 libupm-lsm303
+ * @brief LSM303DLH Accelerometer/Compass library
+ * @defgroup lsm303dlh libupm-lsm303dlh
  * @ingroup seeed adafruit stmicro i2c accelerometer compass
  */
 
 /**
- * @library lsm303
- * @sensor lsm303
+ * @library lsm303dlh
+ * @sensor lsm303dlh
  * @comname Triaxial Accelerometer/magnetometer
  * @altname Grove 6-Axis Accelerometer & Compass
  * @type accelerometer compass
@@ -76,36 +76,36 @@ namespace upm {
  * @web http://www.seeedstudio.com/wiki/Grove_-_6-Axis_Accelerometer%26Compass
  * @con i2c
  *
- * @brief API for the LSM303 Accelerometer & Compass
+ * @brief API for the LSM303DLH Accelerometer & Compass
  *
- * This module defines the LSM303DLH 3-axis magnetometer/3-axis accelerometer.
+ * This module defines the LSM303DLHDLH 3-axis magnetometer/3-axis accelerometer.
  * This module was tested with the Seeed Studio* Grove 6-Axis Accelerometer & Compass
  * module used over I2C. The magnetometer and acceleromter are accessed
  * at two seperate I2C addresses.
  *
- * @image html lsm303.jpeg
- * @snippet lsm303.cxx Interesting
+ * @image html lsm303dlh.jpeg
+ * @snippet lsm303dlh.cxx Interesting
  */
-class LSM303 {
+    class LSM303DLH {
     public:
-         /**
-         * Instantiates an LSM303 object
+        /**
+         * Instantiates an LSM303DLH object
          *
          * @param bus I2C bus to use
          * @param addrMag I2C address of the Magnetometer (default 0x1E)
          * @param addrAcc I2C address of the Accelerometer (default 0x19)
          * @param accScale Accelerometer scale, can be 2, 4 or 8 (default 8)
          */
-        LSM303 (int bus,
-                int addrMag=LSM303_MAG,
-                int addrAcc=LSM303_ACC,
-                int accScale=8);
+        LSM303DLH (int bus,
+                   int addrMag=LSM303DLH_MAG,
+                   int addrAcc=LSM303DLH_ACC,
+                   int accScale=8);
 
         /**
-         * LSM303 object destructor
+         * LSM303DLH object destructor
          * where is no more need for this here - I2c connection will be stopped
          * automatically when m_i2c variable will go out of scope
-         * ~LSM303 ();
+         * ~LSM303DLH ();
          **/
 
         /**
@@ -172,10 +172,10 @@ class LSM303 {
 
         mraa::I2c m_i2c;
         int m_addrMag;
-    int m_addrAcc;
+        int m_addrAcc;
         uint8_t buf[6];
         int16_t coor[3];
         int16_t accel[3];
-};
+    };
 
 }

src/lsm303dlh/pyupm_lsm303dlh.i

@@ -1,6 +1,6 @@
 // Include doxygen-generated documentation
 %include "pyupm_doxy2swig.i"
-%module pyupm_lsm303
+%module pyupm_lsm303dlh
 %include "../upm.i"
 %include "../carrays_int16_t.i"
 
@@ -12,7 +12,7 @@
 	resultobj = SWIG_NewPointerObj(SWIG_as_voidptr(result), SWIGTYPE_p_int16Array, 0 |  0 );
 }
 
-%include "lsm303.hpp"
+%include "lsm303dlh.hpp"
 %{
-    #include "lsm303.hpp"
+    #include "lsm303dlh.hpp"
 %}