Is TCS34725 RGB Color Sensor with IR Filter Compatible with Home Assistant (ESPHome)?
Variants covered by this page
IR filter variant TCS34725 RGB Color Sensor with IR Filter
White LED variant TCS34725 Color Sensor with White LED
Electrical Specifications
Always confirm pin assignments against the manufacturer datasheet before wiring.
Compatibility Overview
Color light sensor with IR blocking filter for measuring color temperature ambient light spectrum and surface reflection.
Wiring TCS34725 RGB Color Sensor with IR Filter to ESP32
| Module pin | ESP32 | Note |
|---|---|---|
| VIN | 3V3 | Adafruit's breakout carries a 3.3V regulator and I2C level shifting and accepts 3–5V. A board without a regulator is a 3.3V part: the chip is specified for 2.7–3.3V. |
| GND | GND | |
| SDA | GPIO21 | |
| SCL | GPIO22 | |
| LED | unconnected | Controls the onboard white LED; pulling it low switches the LED off. Tie it to GND for ambient readings. To switch it from Home Assistant, wire it to a free GPIO with a gpio output, and add that pin to the YAML. |
| INT | unconnected | Open-drain, active-low interrupt. ESPHome polls the sensor. |
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 | Red Channel (%) Green Channel (%) Blue Channel (%) Note: these entities come from the ESPHome configuration you flash — each one needs its matching component in that YAML before it appears. |
| Pairing Complexity | Intermediate |
| 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_tcs34725_esphome.yaml and run esphome run emb_esp32_tcs34725_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 0x29, and with the LED on, holding a red card over the sensor lifts Red well above Green and Blue, while a blue card does the opposite. All three channels pinned at 100% is saturation: the target is too close or too bright, or a fixed integration_time is too long. Channels that hardly change between cards mean room light is swamping the LED, or the LED is off. Nothing at 0x29 is the wiring.
ESPHome Configuration
Starting configuration for TCS34725 RGB Color Sensor with IR Filter on ESP32. Untested on hardware — verify wiring and pins against your own board.
# ESPHome configuration for TCS34725 RGB Color Sensor with IR Filter
# 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_tcs34725_esphome
friendly_name: "TCS34725 RGB Color Sensor with IR Filter"
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
sensor:
- platform: tcs34725
address: 0x29
red_channel:
name: "Red"
green_channel:
name: "Green"
blue_channel:
name: "Blue"
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
Percent. Each is that channel's count as a share of the clear channel, so they are not 0–255 colour values and do not add up to 100.
Optional, not in the config: add clear_channel:, illuminance: (lux) and color_temperature: (K) under the same platform.
Known Problems and Fixes
Percentages, not RGB
Red at 40% means the red photodiodes collected 40% of what the unfiltered clear photodiode did. The ratios between the three are the colour; the clear channel is the brightness. Driving an RGB light from it means normalising the three against the largest, not passing them straight through.
The LED is part of the reading
The white LED on the Adafruit board is a neutral 4150K source, and anything it lights adds that colour to every channel. For the colour temperature of a room, turn it off. For the colour of an object, keep it on and hide the target from room light — a short black tube holding it at a fixed distance works, because the readings change with distance.
Saturation reads as zero
Overexposed, the three colour channels show 100%, clear drops, and illuminance and colour temperature both report 0. The default integration_time: auto corrects itself on the next reading, so one bad value follows a lamp switching on. ESPHome recommends a 1s update interval where light changes quickly; at the config's 60s, that bad reading lasts a minute.
Lux and colour temperature are estimates
Both come from ams's published coefficients for a bare sensor in open air. Behind a window, set glass_attenuation_factor to the inverse of the glass's transmission — 2 for glass that passes half the light — or both numbers come out low.
0x29 is a crowded address
The TCS34725's address is fixed at 0x29, which it shares with the VL53L0X, VL53L1X and TSL2591. Two of them on one bus need a TCA9548A multiplexer, since this part has no strap and no reset pin to hold it off the bus.
Shares I²C address 0x29
These parts answer on the same address, and neither can be moved. They cannot share one I²C bus without a multiplexer:
- TSL2591 HDR Ambient Lux Sensor — hard conflict
- VL53L0X Time-of-Flight Distance Sensor — resolvable
Fixed at 0x29. 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 TCS34725 RGB Color Sensor with IR Filter? Submit a pull request or report corrections to our index.
Hardware Correction Reporter (emb-esp32-tcs34725-esphome)
Frequently Asked Questions
Does TCS34725 RGB Color Sensor with IR Filter work without an internet connection?
How is TCS34725 RGB Color Sensor with IR Filter powered and wired to the host board?
How does the host board reach Home Assistant (ESPHome)?
Alternatives
APDS9960 Proximity & Gesture Sensor
Red, green, blue and clear channels plus proximity and gesture sensing, at 0x39, clear of the 0x29 crowd.
AS7341 ↗
Eight narrow visible bands plus clear and near-infrared, on a core ESPHome platform, when three broad colour channels cannot tell two shades apart.
TSL2591 HDR Ambient Lux Sensor
If brightness was the goal rather than colour, a dedicated lux sensor with more range.
TCA9548A 8-Channel I2C Multiplexer
The multiplexer that lets this sensor share a bus with other 0x29 parts.