Is OPT3001 Precision Ambient Light Sensor Compatible with Home Assistant (ESPHome)?
Electrical Specifications
Always confirm pin assignments against the manufacturer datasheet before wiring.
Compatibility Overview
Single-chip lux meter matching human eye spectral response for natural display backlight auto-brightness.
Wiring OPT3001 Precision Ambient Light Sensor to ESP32
| Module pin | ESP32 | Note |
|---|---|---|
| VDD | 3V3 | The OPT3001 runs from 1.6 to 3.6V. Its I/O pins tolerate 5.5V, but the supply does not. |
| GND | GND | |
| SDA | GPIO21 | |
| SCL | GPIO22 | |
| ADDR | GND | 0x44, as in the config. VDD gives 0x45, SDA 0x46, SCL 0x47. The pin is sampled on every transaction, so it must be tied, never left open. Some breakouts strap it already. |
| INT | unconnected | Open-drain interrupt output that needs a pull-up if used. ESPHome polls the sensor and does not use it. |
Host pins are the ones the configuration on this page uses. Move a pin here and change it in the YAML — they are documented together so they cannot disagree.
Technical Specification Matrix
| Feature / Attribute | Specification / Status |
|---|---|
| Hardware Protocol | I2C Bus / 3.3V |
| Bridge Required | NO |
| Border Router Needed | None |
| Hardware Capabilities & Peripherals | Illuminance (lux) Note: these entities come from the ESPHome configuration you flash — each one needs its matching component in that YAML before it appears. |
| Pairing Complexity | Plug-and-Play |
| Factory Reset Instruction | Hold BOOT button for 3s. |
Wire, Flash, Adopt, Check
Wire it up
Follow the wiring table above. The ESP32 pins there are the ones the configuration uses, so if you move one, change it in both places.
Flash the configuration
Create a new device in the ESPHome dashboard (the Home Assistant add-on) and paste the configuration below into it, or save it as emb_esp32_opt3001_esphome.yaml and run esphome run emb_esp32_opt3001_esphome.yaml. The first flash goes over USB. If it is not detected, hold BOOT button for 3s to put it in download mode. Every update after that is over the air.
Adopt it in Home Assistant
Settings → Devices & Services. A node on the same network shows up as a discovered ESPHome device within a minute of joining Wi-Fi; choose Configure and enter the API encryption key from your secrets.yaml. If discovery does not find it, add the ESPHome integration by hand with the node's IP address.
Check it works
The I2C scan at boot lists 0x44, Illuminance reads tens to hundreds of lux indoors, and it drops towards zero when you cover the sensor with a finger. A device at 0x45, 0x46 or 0x47 instead of 0x44 means ADDR is strapped differently, and the address: line needs to follow it. If readings fail or jump only when a temperature sensor shares the bus, two parts are fighting over 0x44.
ESPHome Configuration
Starting configuration for OPT3001 Precision Ambient Light Sensor on ESP32. Untested on hardware — verify wiring and pins against your own board.
# ESPHome configuration for OPT3001 Precision Ambient Light Sensor
# Host: ESP32. Pin numbers below are host-side defaults — any free
# GPIO will do, and you should change them to match your own wiring.
esphome:
name: emb_esp32_opt3001_esphome
friendly_name: "OPT3001 Precision Ambient Light Sensor"
esp32:
board: esp32dev
framework:
type: esp-idf
logger:
api:
encryption:
key: !secret api_encryption_key
ota:
- platform: esphome
password: !secret ota_password
wifi:
ssid: !secret wifi_ssid
password: !secret wifi_password
i2c:
id: i2c_main
sda: GPIO21
scl: GPIO22
scan: true
# ADDR to GND = 0x44, to VDD = 0x45, to SDA = 0x46, to SCL = 0x47.
sensor:
- platform: opt3001
address: 0x44
name: "Illuminance"
update_interval: 60s
Before you flash:
the !secret values come from your
secrets.yaml, and the GPIO numbers are host-side
defaults rather than properties of this part — change them to match how you actually wired it.
If the device is not found:
it is usually the I2C address, not the config. Many breakouts strap their address with
solder jumpers, so two boards of the same part can differ. This config leaves
scan: true on — the boot log lists every address
actually present on the bus, and you can copy the right one from there.
What Appears in Home Assistant
Lux, from 0.01 to 83,000, with the chip choosing its own range for every reading. The response is matched to the human eye, so it agrees with a lux meter rather than with a photodiode.
Known Problems and Fixes
0x44 is also the SHT3x and SHT4x
ESPHome's sht3xd and sht4x platforms both default to 0x44, and an SHT3x on its alternate strap moves to 0x45 — the OPT3001's second address. With a Sensirion sensor on the same bus, strap ADDR to SDA (0x46) or SCL (0x47) and change address: to match.
Each reading takes most of a second
The component starts a single-shot conversion with the 800ms integration time and automatic range on every update, then waits for the result. Polling faster than about once a second gains nothing. The long integration also averages out the 50Hz or 60Hz flicker of mains lighting.
Nothing to tune
Automatic full-scale ranging picks the best of twelve ranges for each measurement, so the platform offers only an address and an update interval. Unlike the TSL2591 or the TCS34725, there is no gain or integration time to get wrong.
Behind glass or a diffuser
The part rejects over 99% of infrared, so it stays eye-matched behind dark glass that lets infrared through. The glass still cuts the visible light by a fixed fraction. A multiply filter calibrated against a lux meter — or a phone app, in a pinch — restores the absolute number.
A 2mm part
The bare chip is a 2.0 × 2.0mm leadless package, which rules out hand-wiring it; buy it on a breakout. Check whether that breakout has a regulator before connecting 5V, since the chip itself stops at 3.6V.
Shares I²C address 0x44
These parts default to the same address. At least one can be re-strapped, so they can coexist once you change it:
- SHT40 High-Accuracy Temp Sensor — resolvable
- SHT31 Digital Temp & Humidity Sensor — resolvable
ADDR to GND, VDD, SDA or SCL selects 0x44–0x47. Check a full build in the planner · The ways out of an address conflict
Report a Pinout Error or Submit Tested Code Snippets
Found a pin mapping quirk or built a custom ESPHome YAML driver for OPT3001 Precision Ambient Light Sensor? Submit a pull request or report corrections to our index.
Hardware Correction Reporter (emb-esp32-opt3001-esphome)
Frequently Asked Questions
Does OPT3001 Precision Ambient Light Sensor work without an internet connection?
How is OPT3001 Precision Ambient Light Sensor powered and wired to the host board?
How does the host board reach Home Assistant (ESPHome)?
Alternatives
VEML7700 Ambient Light Lux Sensor
Automatic gain and integration time in ESPHome and a higher ceiling at 120,000 lux, but a single fixed address.
BH1750 Ambient Light Sensor
Cheaper and everywhere, with a 65,535 lux ceiling and a two-way address strap.
TSL2591 HDR Ambient Lux Sensor
Wide dynamic range with a separate infrared channel, if the IR content is itself of interest.
MAX44009 Wide-Range Lux Sensor
Reaches 188,000 lux, for a sensor looking at open sky.
LTR390 UV & Ambient Light Sensor
Adds a UV index alongside ambient light.