GY-63_MS5611/libraries/MAX44007/README.md

215 lines
6.5 KiB
Markdown
Raw Normal View History

2022-01-04 15:06:58 -05:00
[![Arduino CI](https://github.com/RobTillaart/Max44007/workflows/Arduino%20CI/badge.svg)](https://github.com/marketplace/actions/arduino_ci)
[![Arduino-lint](https://github.com/RobTillaart/Max44007/actions/workflows/arduino-lint.yml/badge.svg)](https://github.com/RobTillaart/Max44007/actions/workflows/arduino-lint.yml)
[![JSON check](https://github.com/RobTillaart/Max44007/actions/workflows/jsoncheck.yml/badge.svg)](https://github.com/RobTillaart/Max44007/actions/workflows/jsoncheck.yml)
2023-10-04 04:40:31 -04:00
[![GitHub issues](https://img.shields.io/github/issues/RobTillaart/Max44007.svg)](https://github.com/RobTillaart/Max44007/issues)
2022-01-04 15:06:58 -05:00
[![License: MIT](https://img.shields.io/badge/license-MIT-green.svg)](https://github.com/RobTillaart/Max44007/blob/master/LICENSE)
[![GitHub release](https://img.shields.io/github/release/RobTillaart/Max44007.svg?maxAge=3600)](https://github.com/RobTillaart/Max44007/releases)
2023-10-04 04:40:31 -04:00
[![PlatformIO Registry](https://badges.registry.platformio.org/packages/robtillaart/library/Max44007.svg)](https://registry.platformio.org/libraries/robtillaart/Max44007)
2022-01-04 15:06:58 -05:00
# Max44007 I2C LUX sensor
Library for Max44007 I2C lux sensor.
## Description
2023-10-04 04:40:31 -04:00
The Max44007 ambient light sensor is an I2C sensor, that has a 22 bit
2022-01-04 15:06:58 -05:00
dynamic range from 0.025 lux to 104,448 lux.
This library is experimental and created by changing some key values in the
2023-10-04 04:40:31 -04:00
very similar MAX44009 library. As there was no hardware available the library
is not tested yet. If you do, please share the results (open an issue on GitHub).
Note: version 0.2.0 simplified the constructor interface and removed **configure()**.
#### Related
- https://github.com/RobTillaart/Max44007 (range 0.025 lux to 104,448 lux)
- https://github.com/RobTillaart/Max44009 (range 0.045 lux to 188,000 lux)
2022-01-04 15:06:58 -05:00
## Schema breakout Max44007
```cpp
2022-11-16 10:03:33 -05:00
// breakout Max44007
2022-01-04 15:06:58 -05:00
//
2022-11-16 10:03:33 -05:00
// +--------+
// VCC |o |
// GND |o |
// SCL |o o| ADDRESS
// SDA |o o| -INT
// +--------+
2022-01-04 15:06:58 -05:00
//
2022-11-16 10:03:33 -05:00
// ADDRESS:
// 0 = 0x5A
// 1 = 0x5B
2022-01-04 15:06:58 -05:00
//
2022-11-16 10:03:33 -05:00
// 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
2022-01-04 15:06:58 -05:00
//
```
## Interface
2023-10-04 04:40:31 -04:00
```cpp
#include "Max44007.h"
```
2022-01-04 15:06:58 -05:00
2023-10-04 04:40:31 -04:00
### Constructor
2022-01-04 15:06:58 -05:00
2023-10-04 04:40:31 -04:00
- **Max44007(const uint8_t address = MAX44007_DEFAULT_ADDRESS, TwoWire \*wire = &Wire)** Constructor.
Optional address and optional I2C interface.\
2022-01-04 15:06:58 -05:00
- **bool isConnected()** returns true if the device address configured is available on I2C bus.
2023-10-04 04:40:31 -04:00
NOTE: The user must call **Wire.begin()** or **Wire.begin(SDA, SCL)** in **setup()**.
2022-01-04 15:06:58 -05:00
2023-10-04 04:40:31 -04:00
### Basic
2022-01-04 15:06:58 -05:00
2023-10-04 04:40:31 -04:00
- **float getLux()** read the sensor and return the value in LUX. If the value is negative, an error has occurred.
2022-01-04 15:06:58 -05:00
- **int getError()** returns last error.
```cpp
2022-11-16 10:03:33 -05:00
// ERROR CODES
2022-01-04 15:06:58 -05:00
#define Max44007_OK 0
#define Max44007_ERROR_WIRE_REQUEST -10
#define Max44007_ERROR_OVERFLOW -20
#define Max44007_ERROR_HIGH_BYTE -30
#define Max44007_ERROR_LOW_BYTE -31
```
### Configure thresholds
check datasheet for details
2023-10-04 04:40:31 -04:00
- **bool setHighThreshold(float value)** sets the upper threshold for the interrupt
generation (INT pulls LOW). Works only if INTE bit is set by **enableInterrupt()**.
2022-01-04 15:06:58 -05:00
Function returns false if the value is out of range.
- **float getHighThreshold()** returns the value set.
2023-10-04 04:40:31 -04:00
- **bool setLowThreshold(float value)** sets the lower threshold for the interrupt
generation (INT pulls LOW). Works only if INTE bit is set by **enableInterrupt()**.
2022-01-04 15:06:58 -05:00
Function returns false if the value is out of range.
- **float getLowThreshold()** returns the value set.
2023-10-04 04:40:31 -04:00
- **void setThresholdTimer(uint8_t value)** Time the threshold needs to be exceeded,
2022-01-04 15:06:58 -05:00
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
2023-10-04 04:40:31 -04:00
- **void setConfiguration(uint8_t)** writes directly to configuration register.
2022-01-04 15:06:58 -05:00
**warning** Use with care.
- **uint8_t getConfiguration()** reads the current configuration register.
### Configure sample mode
2023-10-04 04:40:31 -04:00
Check datasheet for details
2022-01-04 15:06:58 -05:00
CCR = Current Divisor Ratio.
TIM = Integration time.
2023-10-04 04:40:31 -04:00
- **void setAutomaticMode()** in automatic mode the Max44007 determines the CDR and TIM
2022-01-04 15:06:58 -05:00
parameters.
2023-10-04 04:40:31 -04:00
- **void setContinuousMode()** continuous mode uses more power than a "single" conversion.
2022-01-04 15:06:58 -05:00
Advantage is that the latest data is always available fast.
2023-10-04 04:40:31 -04:00
- **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
2022-01-04 15:06:58 -05:00
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)
2022-11-16 10:03:33 -05:00
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
2022-01-04 15:06:58 -05:00
```
### Test functions
2023-10-04 04:40:31 -04:00
Function for the conversion math, not meant to be used directly,
2022-01-04 15:06:58 -05:00
but by making them public they become testable.
2023-10-04 04:40:31 -04:00
- **float convertToLux(uint8_t dataHigh, uint8_t dataLow)** convert intern register
format to a LUX value.
2022-01-04 15:06:58 -05:00
## Examples
**Max44007\examples\Max44007_test01**
- use for e.g. UNO (use voltage convertor!)
**Max44007\examples\Max44007_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
2023-10-04 04:40:31 -04:00
to an Arduino UNO or other 5 Volt device directly.
Use a level convertor to solve this.
2022-01-04 15:06:58 -05:00
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 ;)
2023-10-04 04:40:31 -04:00
Pull ups on I2C bus are recommended.
2022-01-04 15:06:58 -05:00
## Future
2023-10-04 04:40:31 -04:00
#### Must
2022-01-04 15:06:58 -05:00
- follow MAX44009
2023-10-04 04:40:31 -04:00
#### Should
#### Could
- merge MAX44007 / MAX44009 library in the future. (shared base class?)
#### Wont
## Support
If you appreciate my libraries, you can support the development and maintenance.
Improve the quality of the libraries by providing issues and Pull Requests, or
donate through PayPal or GitHub sponsors.
Thank you,
2022-01-04 15:06:58 -05:00