GY-63_MS5611/libraries/Max44009/readme.md

[![Arduino CI](https://github.com/RobTillaart/MAX44009/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
[![Arduino-lint](https://github.com/RobTillaart/Max44009/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/Max44009/actions/workflows/arduino-lint.yml)
[![JSON check](https://github.com/RobTillaart/Max44009/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/Max44009/actions/workflows/jsoncheck.yml)
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/MAX44009/blob/master/LICENSE)
[![GitHub release](https://img.shields.io/github/release/RobTillaart/MAX44009.svg?maxAge=3600)](https://github.com/RobTillaart/MAX44009/releases)


# MAX44009 I2C LUX sensor

Library for MAX44009 / GY-49 I2C lux sensor.


## Description

a.k.a. GY-49

The MAX44009 ambient light sensor is an I2C sensor, that has a 22 bit 
dynamic range from 0.045 lux to 188,000 lux.

Relates to https://github.com/RobTillaart/Max44007 


## Schema breakout max44009 / GY-49


```cpp
//       breakout MAX44009 / GY-49
//
//          +--------+
//      VCC |o       |
//      GND |o       |
//      SCL |o      o| ADDRESS
//      SDA |o      o| -INT
//          +--------+
//
//  ADDRESS:
//  0 = 0x4A
//  1 = 0x4B
//
//  INT:
//  Connect the INT pin to an pull up resistor
//  0 = interrupt
//  1 = no interrupt
//  connect to an LED or an interrupt pin of an Arduino
//
```


## Interface

- **enum class Boolean { True, False }** enum class to prevent bool to be implicitly casted to int.


### Constructor 
  
- **Max44009(uint8_t address, uint8_t dataPin, uint8_t clockPin)** Constructor with dataPin (sda) and clockPin (scl) for ESP32 and ESP8266.
- **Max44009(uint8_t address, begin = Boolean::True)** Constructor for other boards e.g. UNO.
- **Max44009(begin = Boolean::True)** Constructor with default I2C address 0x4A == 74.
- **void configure(uint8_t address, TwoWire \*wire, begin = Boolean::True)** Change I2C interface and address.
- **bool isConnected()** returns true if the device address configured is available on I2C bus.


### Basic 

- **float getLux()** read the sensor and return the value in LUX. If the value is negative, an error has occurred. 
- **int getError()** returns last error.

```cpp
// ERROR CODES
#define MAX44009_OK                     0
#define MAX44009_ERROR_WIRE_REQUEST    -10
#define MAX44009_ERROR_OVERFLOW        -20
#define MAX44009_ERROR_HIGH_BYTE       -30
#define MAX44009_ERROR_LOW_BYTE        -31
```


### Configure thresholds

check datasheet for details

- **bool setHighThreshold(float value)** sets the upper threshold for the interrupt 
generation (INT pulls LOW). Works only if INTE bit is set by **enableInterrupt()**. 
Function returns false if the value is out of range.
- **float getHighThreshold()** returns the value set.
- **bool setLowThreshold(float value)** sets the lower threshold for the interrupt 
generation (INT pulls LOW). Works only if INTE bit is set by **enableInterrupt()**. 
Function returns false if the value is out of range.
- **float getLowThreshold()** returns the value set.
- **void setThresholdTimer(uint8_t value)** Time the threshold needs to be exceeded, 
defined in steps of 100ms. 2 seems to be a practical minimum.
- **uint8_t getThresholdTimer()** returns the value set.


### Configure interrupts

check datasheet for details

- **void enableInterrupt()** enables the upper and lower threshold interrupts.
- **void disableInterrupt()** disables the threshold interrupts.
- **bool interruptEnabled()** returns 1 if the interrupt mode is enabled.
- **uint8_t getInterruptStatus()** returns 1 if an interrupt has occurred.


### Configure flags

check datasheet for details

- **void setConfiguration(uint8_t)** writes directly to configuration register. 
**warning** Use with care.
- **uint8_t getConfiguration()** reads the current configuration register.


### Configure sample mode

Check datasheet for details.

CCR = Current Divisor Ratio.

TIM = Integration time.

- **void setAutomaticMode()** in automatic mode the MAX44009 determines the CDR and TIM 
parameters.
- **void setContinuousMode()** continuous mode uses more power than a "single" conversion. 
Advantage is that the latest data is always available fast.
- **void clrContinuousMode()** uses less power so better for LOW power configurations. 
- **void setManualMode(uint8_t CDR, uint8_t TIM)** Set the Current Divisor Ratio and the 
integration time manually. Effectively disable automatic mode.
- **int getIntegrationTime()** returns the set integration time in milliseconds

```
    CDR = Current Divisor Ratio
    CDR = 1 ==> only 1/8th is measured

    TIM = Time Integration Measurement (table)
    000   800ms
    001   400ms
    010   200ms
    011   100ms
    100    50ms       manual only
    101    25ms       manual only
    110    12.5ms     manual only
    111     6.25ms    manual only
```


### Test functions

Function for the conversion math, not meant to be used directly, 
but by making them public they become testable.

- **float convertToLux(uint8_t datahigh, uint8_t datalow)** convert intern register 
format to a LUX value. 


## Examples

**Max44009\examples\max44009_test01**
- use for e.g. UNO (use voltage convertor!)

**Max44009\examples\max44009_test02**
- will **not** compile for UNO
- use for e.g. ESP32


## Notes

Please be aware this is a **3.3 Volt device** so it should not be connected
to an Arduino UNO or other 5 Volt device directly. 
Use a level convertor to solve this.

Do not forget to connect the address pin as you cannot read the sensor
in a reliable way. As the line will float it will sometimes have the
right address and sometimes not. (been there ;)


## Future

- improve documentation
- merge MAX44007 library in the future. (shared base class?)


#### MAX44007

The MAX44007 is an almost identical sensor that uses a step size of 0.025.
This implies that this library is not useable 1 to 1 for the MAX44007, however some parts will work/