BH1750 Arduino Library

repository·master·Indexed 42 days ago

https://github.com/claws/bh1750

An Arduino library for digital light sensor breakout boards using the BH1750FVI IC. It supports I2C communication and provides various measurement modes, including Continuous and One-Time modes with precision levels ranging from 0.5 lx to 4 lx. Key functionality includes readLightLevel() for retrieving light intensity in lux, setMTreg() for adjusting the Measurement Time Register, and measurementReady() to check for completed measurement cycles.

Tokens
1.7K
Snippets
6
Records
11
Agent score
5%

What's inside BH1750

  1. Configure the MTreg (Measurement Time Register)

    master
    The measurement time frame can be adjusted via the MTreg register. This is useful for compensating for environmental influences or using overlay windows. You can choose a value between 32 and 254. The default value is 69. Note that changing this value will change the measurement time accordingly.
  2. Understand BH1750 measurement modes and precision

    master

    The BH1750 supports six measurement modes divided into two categories: Continuous (sensor continuously measures) and One-Time (sensor measures once then enters Power Down mode).

    Each mode offers three precision levels:

    • Low Resolution Mode: 4 lx precision, 16ms measurement time. (Range: 0.0 to 54612.5 lx)
    • High Resolution Mode: 1 lx precision, 120ms measurement time. (Range: 0.0 to 54612.5 lx)
    • High Resolution Mode 2: 0.5 lx precision, 120ms measurement time. (Range: 0.0 to 27306.25 lx)

    Note on One-Time Mode: When using One-Time mode, the sensor enters Power Down mode after a measurement. The library automatically reconfigures the sensor when you next attempt a measurement, so manual reconfiguration is typically unnecessary.

  3. Install the BH1750 Arduino library

    master

    You can install the BH1750 library using the Arduino Library Manager or manually.

    Using Library Manager (Arduino >= 1.5.x):

    1. Search for BH1750 in the Arduino Library Manager.
    2. Click install.

    Manual Installation (Arduino >= 1.5.x):

    1. Download the library as a ZIP file from the repository.
    2. In the Arduino IDE, go to Sketch -> Include library -> Add .ZIP library and select the downloaded archive.

    Manual Installation (Arduino < 1.5.x):

    1. Download the library as a ZIP file.
    2. Extract the archive to <Your User Directory>/My Documents/Arduino/libraries/.
    3. Rename the extracted folder to BH1750.
    4. Restart the Arduino IDE.
  4. Wire the BH1750 sensor to an Arduino

    master

    The BH1750 uses the I2C communication protocol. You must configure the I2C bus in your user code (e.g., using Wire.begin()) as the library does not do this automatically.

    Standard Connections:

    • VCC: 3V3 or 5V
    • GND: GND
    • SCL: SCL (A5 on Nano/Uno/Leonardo; Pin 21 on Mega/Due; selectable on ESP8266)
    • SDA: SDA (A4 on Nano/Uno/Leonardo; Pin 20 on Mega/Due; selectable on ESP8266)
    • ADD: Used to set the I2C address:
      • Connect to GND (or leave unconnected if voltage < 0.7 * VCC): Address is 0x23.
      • Connect to VCC: Address is 0x5C.
  5. Use the BH1750 library to measure light levels

    master

    To use the library, include Wire.h and BH1750.h. You must initialize the I2C bus with Wire.begin() before calling lightMeter.begin().

    By default, the library uses Continuous High Resolution Mode. You can change the measurement mode by passing an argument to lightMeter.begin(mode).

    Error Codes: readLightLevel() returns a float. If an error occurs, it returns:

    • -1: No valid data was transmitted from the sensor.
    • -2: Device is not configured.
    #include <Wire.h>
    #include <BH1750.h>
    
    BH1750 lightMeter;
    
    void setup(){
      Serial.begin(9600);
    
      // Initialize the I2C bus (BH1750 library doesn't do this automatically)
      Wire.begin();
    
      lightMeter.begin();
      Serial.println(F("BH1750 Test"));
    }
    
    void loop() {
      float lux = lightMeter.readLightLevel();
      Serial.print("Light: ");
      Serial.print(lux);
      Serial.println(" lx");
      delay(1000);
    }
  6. Configure the MTreg register

    master

    The setMTreg(byte MTreg) method allows you to set the MTreg value, which affects measurement accuracy.

    Valid values:

    • Minimum: 31 (defined as BH1750_MTREG_MIN)
    • Default: 69 (defined as BH1750_DEFAULT_MTREG)
    • Maximum: 254 (defined as BH1750_MTREG_MAX)
  7. Configure BH1750 measurement modes

    master

    The BH1750 sensor supports several measurement modes via the Mode enum. You can set the mode during initialization using begin(mode, ...) or change it later using configure(mode).

    Available modes:

    • UNCONFIGURED: No active state.
    • CONTINUOUS_HIGH_RES_MODE: 1 lux resolution, ~120ms measurement time.
    • CONTINUOUS_HIGH_RES_MODE_2: 0.5 lux resolution, ~120ms measurement time.
    • CONTINUOUS_LOW_RES_MODE: 4 lux resolution, ~16ms measurement time.
    • ONE_TIME_HIGH_RES_MODE: Single measurement at 1 lux resolution.
    • ONE_TIME_HIGH_RES_MODE_2: Single measurement at 0.5 lux resolution.
    • ONE_TIME_LOW_RES_MODE: Single measurement at 4 lux resolution.
    // Change mode after initialization
    lightSensor.configure(BH1750::CONTINUOUS_LOW_RES_MODE);
  8. Read light intensity with readLightLevel()

    master

    Use readLightLevel() to retrieve the current light intensity in lux. This method returns a float value representing the measured light level.

    float lux = lightSensor.readLightLevel();
  9. Initialize the BH1750 sensor with begin()

    master

    To use the BH1750 sensor, instantiate the BH1750 class and call the begin() method. The begin() method initializes the I2C communication and sets the initial measurement mode.

    Note: You are responsible for configuring the I2C bus (e.g., calling Wire.begin()) in your user code before calling begin(), as the library does not do this automatically.

    BH1750 lightSensor(0x23); // Initialize with I2C address 0x23
    
    void setup() {
      Wire.begin(); // Must be called before sensor.begin()
      if (!lightSensor.begin(BH1750::CONTINUOUS_HIGH_RES_MODE)) {
        // Handle initialization failure
      }
    }
  10. Check if a measurement is ready with measurementReady()

    master

    The measurementReady() method checks if the sensor has completed its current measurement cycle. This is useful when using ONE_TIME modes or when you want to avoid blocking execution.

    • maxWait: A boolean parameter. If true, it may wait longer for the measurement to complete.
    if (lightSensor.measurementReady()) {
      float lux = lightSensor.readLightLevel();
    }
  11. Reference: BH1750 Mode Enum

    master

    The Mode enum defines the operational states of the BH1750 sensor, determining resolution and measurement timing.

    enum Mode {
      UNCONFIGURED = 0,
      CONTINUOUS_HIGH_RES_MODE = 0x10,
      CONTINUOUS_HIGH_RES_MODE_2 = 0x11,
      CONTINUOUS_LOW_RES_MODE = 0x13,
      ONE_TIME_HIGH_RES_MODE = 0x20,
      ONE_TIME_HIGH_RES_MODE_2 = 0x21,
      ONE_TIME_LOW_RES_MODE = 0x23
    };