Merge branch 'DHINESH-DEVEL' into 'main'

add methods to read light from the sensor

See merge request dhineshkumar/mcci_ltr_329als!1

README.md

@@ -12,6 +12,73 @@ It has the following design principles.
 
 4. There are no infinite delays that are not guarded by timeouts (whether blocking or non-blocking); all operations will eventually complete, even if the sensor hardware hangs.
 
+## Quick Intro
+
+This library uses the LTR-329ALS sensor to take light measurements in units of lux. Using it is easy:
+
+1. Create an object of type `Ltr_329als`.
+2. Call the `Ltr_329als::begin()` method to initialize it.
+3. Call the `Ltr_329als::startSingleMeasurement()` method to launch an asynchronous measurement.
+4. Poll the sensor using `Ltr_329als::queryReady()` until the measurement is ready or a hard error is indicated.
+5. Convert the measurement to lux using `Ltr_329als::getLux()`.
+
+See [sample code](#sample-code) below for details of the required steps.
+
+## Sample Code
+
+1. The header file
+
+   ```c++
+   #include <mcci_ltr_329als.h>
+   ```
+
+2. The namespace:
+
+   ```c++
+   using namespace Mcci_Ltr_329als;
+   ```
+
+3. The global object:
+
+   ```c++
+   // declare the global light-sensor instance object,
+   // and attach it to the default TwoWire bus.
+   Ltr_329als gLtr {Wire};
+   ```
+
+4. Code in `setup()`:
+
+   ```c++
+   // initialize the LTR
+   if (! gLtr.begin())
+        /* the light sensor isn't working */;
+   ```
+
+5. Code in `loop()`. Note that this is very simplistic, but it will always continue through to the bottom. Because `Ltr_329als::queryReady()` doesn't block, it is straightforward to refactor this so that the light sensor doesn't delay other processing.
+
+   ```c++
+   bool fHardError = false;
+   if (gLtr.startSingleMeasurement()) {
+        while (! gLtr.queryReady(fHardError)) {
+                if (fHardError) {
+                        break;
+                }
+        }
+   } else {
+        fHardError = true;
+   }
+
+   float lux;
+
+   if (fHardError) {
+        // print gLtr.getErrorName and do what's
+        // best for your app
+   } else {
+        lux = gLtr.getLux();
+        // do something with lux value
+   }
+   ```
+
 ## Meta
 
 ### License

examples/compile_test/compile_test.ino

@@ -0,0 +1,45 @@
+/* compile_test.ino	Fri Jul 29 2022 18:10:17 tmm */
+
+/*
+
+Module:	compile_test.ino
+
+Function:
+        Compile test for LTR-329ALS library
+
+Version:
+        V1.0.0	Fri Jul 29 2022 18:10:17 tmm	Edit level 1
+
+Copyright notice:
+        This file copyright (C) 2022 by
+
+                MCCI Corporation
+                3520 Krums Corners Road
+                Ithaca, NY  14850
+
+        An unpublished work.  All rights reserved.
+
+        This file is proprietary information, and may not be disclosed or
+        copied without the prior permission of MCCI Corporation.
+
+Author:
+        Terry Moore, MCCI Corporation	July 2022
+
+Revision History:
+   1.0.0  Fri Jul 29 2022 18:10:17  tmm
+        ticket: Module created.
+
+*/
+
+#include "mcci_ltr_329als.h"
+
+void setup()
+        {
+        }
+
+void loop()
+        {
+
+        }
+
+/**** end of compile_test.ino ****/

examples/ltr_329als_simple/ltr_329als_simple.ino

@@ -0,0 +1,156 @@
+/*
+
+Module: ltr_329als_simple.ino
+
+Function:
+        Simple example for LTR light sensors.
+
+Copyright and License:
+        See accompanying LICENSE file.
+
+Author:
+        Dhinesh Kumar Pitchai, MCCI Corporation   July 2022
+
+*/
+
+#include <mcci_ltr_329als.h>
+
+#include <Arduino.h>
+#include <Wire.h>
+#include <cstdint>
+
+/****************************************************************************\
+|
+|   Manifest constants & typedefs.
+|
+\****************************************************************************/
+
+using namespace Mcci_Ltr_329als;
+
+/****************************************************************************\
+|
+|   Read-only data.
+|
+\****************************************************************************/
+
+/****************************************************************************\
+|
+|   Variables.
+|
+\****************************************************************************/
+
+bool fLed;
+Ltr_329als gLtr {Wire};
+
+/****************************************************************************\
+|
+|   Code.
+|
+\****************************************************************************/
+
+void printFailure(const char *pMessage)
+    {
+    for (;;)
+        {
+        Serial.print(pMessage);
+        Serial.print(", error: ");
+        Serial.print(gLtr.getLastErrorName());
+        Serial.print("(");
+        Serial.print(std::uint8_t(gLtr.getLastError()));
+        Serial.print(")");
+        delay(2000);
+        }
+    }
+
+// format a uint64_t into a buffer and return pointer to first byte.
+char *formatUint64(char *pBuf, size_t nBuf, std::uint64_t v, unsigned base)
+    {
+    char *p;
+
+    if (pBuf == nullptr || nBuf == 0)
+        return nullptr;
+
+    p = pBuf + nBuf;
+    *--p = '\0';
+    while (p > pBuf)
+        {
+        unsigned digit;
+
+        digit = unsigned(v % base);
+        v = v / base;
+        --p;
+
+        if (digit < 10)
+            *p = '0' + digit;
+        else
+            *p = 'A' + digit - 10;
+
+        if (v == 0)
+            break;
+        }
+
+    if (p == pBuf && v != 0)
+        *p = '*';
+
+    return p;
+    }
+
+void setup()
+    {
+    Serial.begin(115200);
+
+    // wait for USB to be attached.
+    while (! Serial)
+        yield();
+
+    /* bring up the LED */
+    pinMode(LED_BUILTIN, OUTPUT);
+    digitalWrite(LED_BUILTIN, 1);
+    fLed = true;
+
+    Serial.println("LTR329-ALS01 Simple Test");
+    // let message get out.
+    delay(1000);
+
+    if (! gLtr.begin())
+        {
+        printFailure("gLtr.begin() failed");
+        }
+    }
+
+void loop()
+    {
+    bool fError;
+    float currentLux;
+
+    // toggle the LED
+    fLed = !fLed;
+    digitalWrite(LED_BUILTIN, fLed);
+
+    // start a measurement
+    if (! gLtr.startSingleMeasurement())
+        printFailure("gLtr.startSingleMeasurement() failed");
+
+    // wait for measurement to complete.
+    while (! gLtr.queryReady(fError))
+        {
+        if (fError)
+            printFailure("queryReady() failed");
+        }
+
+    // startSingleMeasurement/queryReady puts the sensor to sleep, so no work needed.
+
+    // get the results.
+    currentLux = gLtr.getLux();
+
+    // display the results by fetching then displaying.
+    Serial.print("light=");
+    Serial.print(currentLux);
+    Serial.print(" lux (gain=");
+    Serial.print(gLtr.getRawData().getGain());
+    Serial.print(", integration=");
+    Serial.print(gLtr.getRawData().getIntegrationTime());
+    Serial.println(")");
+
+    delay(2000);
+    }