import bh1750
The bh1750 module reads ROHM BH1750-compatible digital light sensors over I2C. It returns illuminance in lux and keeps the low-level power, measurement-mode, and MTreg sensitivity commands inside the native firmware module.
Quick example
import bh1750 light = bh1750.BH1750(21, 22) reading = light.read() print(reading["lux"]) light.configure(mode="high2") print(light.lux())
importbh1750
BH1750 ambient light sensor module.
The bh1750 module reads ROHM BH1750-compatible digital light sensors over I2C. It returns illuminance in lux and keeps the low-level power, measurement-mode, and MTreg sensitivity commands inside the native firmware module.
bh1750.BH1750(sda: int, scl: int, address: int = None, frequency: int = None, port: int = None) -> bh1750_sensor
bh1750.BH1750(sda: int, scl: int, address: int = None, frequency: int = None, port: int = None) -> bh1750_sensorCreate a BH1750 ambient light sensor object.
Use one object for the active BH1750 reader. The native module preserves the existing lightweight hardware backing and raises a clear error if an older object is used after a newer BH1750 object is created.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
sda |
int |
positional or keyword | Yes | GPIO pin used for I2C SDA. |
scl |
int |
positional or keyword | Yes | GPIO pin used for I2C SCL. |
address |
int |
positional or keyword | No | Optional I2C address. Defaults to 0x23. Some boards use 0x5c when the ADDR pin is high. |
frequency |
int |
positional or keyword | No | Optional I2C bus speed in hertz. Defaults to 100000. |
port |
int |
positional or keyword | No | Optional ESP-IDF I2C port number. Defaults to 0. |
bh1750_sensor bh1750_sensor object.
bh1750.BH1750().configure(mode="high", mtreg=69) -> bool
bh1750.BH1750().configure(mode="high", mtreg=69) -> boolSet default measurement mode and sensitivity.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
mode |
str |
positional or keyword | No | Optional value. Defaults to "high". |
mtreg |
int |
positional or keyword | No | Optional value. Defaults to 69. |
bh1750.BH1750().read(mode=None) -> dict
bh1750.BH1750().read(mode=None) -> dictRead ambient light and return lux plus measurement metadata.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
mode |
str |
positional or keyword | No | Optional value. Defaults to None. |
bh1750.BH1750().lux(mode=None) -> float
bh1750.BH1750().lux(mode=None) -> floatRead ambient light and return only the lux value.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
mode |
str |
positional or keyword | No | Optional value. Defaults to None. |
bh1750.BH1750().set_mtreg(mtreg) -> bool
bh1750.BH1750().set_mtreg(mtreg) -> boolSet the measurement-time register from 31 through 254.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
mtreg |
int |
positional or keyword | Yes | Required value. |
bh1750.BH1750().power(enabled=True) -> bool
bh1750.BH1750().power(enabled=True) -> boolPower the sensor on or down.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
enabled |
bool |
positional or keyword | No | Optional value. Defaults to True. |
bh1750.BH1750().reset() -> bool
bh1750.BH1750().reset() -> boolReset the BH1750 data register.
bh1750.BH1750().info() -> dict
bh1750.BH1750().info() -> dictReturn sensor state, I2C pins, address, mode, and MTreg.
bh1750.BH1750().close() -> bool
bh1750.BH1750().close() -> boolRelease the active I2C device and close this object.
bh1750.begin(sda: int, scl: int, address: int = None, frequency: int = None, port: int = None) -> bool
bh1750.begin(sda: int, scl: int, address: int = None, frequency: int = None, port: int = None) -> boolInitialize a BH1750 sensor on I2C.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
sda |
int |
positional or keyword | Yes | GPIO pin used for I2C SDA. |
scl |
int |
positional or keyword | Yes | GPIO pin used for I2C SCL. |
address |
int |
positional or keyword | No | Optional I2C address. Defaults to 0x23. Some boards use 0x5c when the ADDR pin is high. |
frequency |
int |
positional or keyword | No | Optional I2C bus speed in hertz. Defaults to 100000. |
port |
int |
positional or keyword | No | Optional ESP-IDF I2C port number. Defaults to 0. |
bool True when the sensor acknowledges the power-on and reset commands.
bh1750.configure(mode: str = None, mtreg: int = None) -> bool
bh1750.configure(mode: str = None, mtreg: int = None) -> boolSet the default light measurement mode and sensitivity.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
mode |
str |
positional or keyword | No | Optional measurement mode. Use "high", "high2", "low", "continuous_high", "continuous_high2", or "continuous_low". Defaults to "high". |
mtreg |
int |
positional or keyword | No | Optional measurement-time register value from 31 through 254. Defaults to 69. Higher values increase sensitivity and measurement time. |
bool True when the mode and MTreg value are accepted.
bh1750.read(mode: str = None) -> dict
bh1750.read(mode: str = None) -> dictRead ambient light.
The default "high" mode is a blocking one-shot read. It usually waits up to about 180 ms at the default MTreg value. The "low" mode is faster but lower resolution, and "high2" is better for low-light readings.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
mode |
str |
positional or keyword | No | Optional measurement mode for this read only. Use "high", "high2", "low", "continuous_high", "continuous_high2", or "continuous_low". |
dict Dict with ``ok``, ``lux``, ``raw``, ``mode``, ``resolution_lux``, ``measurement_time_ms``, ``mtreg``, and ``address`` fields.
bh1750.lux(mode: str = None) -> float
bh1750.lux(mode: str = None) -> floatRead ambient light in lux.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
mode |
str |
positional or keyword | No | Optional measurement mode for this read only. Use "high", "high2", "low", "continuous_high", "continuous_high2", or "continuous_low". |
float Float illuminance in lux.
bh1750.set_mtreg(mtreg: int) -> bool
bh1750.set_mtreg(mtreg: int) -> boolSet the BH1750 measurement-time register.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
mtreg |
int |
positional or keyword | Yes | Measurement-time register value from 31 through 254. The default is 69. Increase it for more sensitivity, or decrease it for faster lower-sensitivity reads. |
bool True when the sensor accepts the MTreg command bytes.
bh1750.power(enabled: bool = None) -> bool
bh1750.power(enabled: bool = None) -> boolPower the BH1750 sensor on or down.
| Name | Type | Pass as | Required | Description |
|---|---|---|---|---|
enabled |
bool |
positional or keyword | No | Optional power state. True powers the sensor on, False powers it down. Defaults to True. |
bool True when the command is acknowledged.
bh1750.reset() -> bool
bh1750.reset() -> boolReset the BH1750 data register.
bool True when the sensor acknowledges the reset command.
bh1750.info() -> dict
bh1750.info() -> dictReturn BH1750 module state.
dict Dict with initialization state, power state, I2C pins, address, frequency, port, mode, and MTreg.