Build it step by step
0 of 7 doneWire the sensor and display
Both to 3V3 and GND, SDA to GPIO21, SCL to GPIO22.
Wire the button
GPIO4 to GND.
Install the libraries
Adafruit TCS34725, Adafruit SSD1306 and Adafruit GFX.
Upload the sketch
The display shows a colour name and three numbers.
White balance
Hold white paper about 1 cm from the sensor and press the button.
Try coloured objects
Hold each at the same distance.
Adjust
Re-balance when the room light changes.
How do you build an ESP32 colour name reader?
An ESP32 reads a TCS34725 colour sensor, white-balances on white paper and shows the name of the nearest of eight colours on an OLED. You need ESP32 DevKit V1, TCS34725 colour sensor, SSD1306 OLED Display, Tactile push button 6 mm and Breadboard 830 Tie Points. It takes 7 steps and about 150 minutes.
- Level
- Intermediate
- Time
- About 150 min
- Parts
- 5
Parts list
Tick what you already own. It saves to My Garage, so “Build with what I have” knows.
Wiring
| From | To | Why |
|---|---|---|
| TCS34725 VIN and OLED VCC | ESP32 3V3 | Power at 3.3 V |
| TCS34725 GND and OLED GND | ESP32 GND | Common ground |
| TCS34725 SDA and OLED SDA | ESP32 GPIO21 | Shared I2C data |
| TCS34725 SCL and OLED SCL | ESP32 GPIO22 | Shared I2C clock |
| White balance button | ESP32 GPIO4 and GND | Press with white paper in front of the sensor |
Code
The TCS34725 measures how much red, green and blue light reaches it, plus a clear channel that counts all the light. The numbers you get depend a lot on the lamp in the room and on the sensor itself, so the same red object gives different values at different times. The fix used in cameras is white balance: show the sensor something you know is white, and work out gains that make its three channels equal. The program does this when you press the button, and it also remembers the clear reading of the white paper as a brightness reference. After that it turns the corrected red, green and blue into a hue, which is the position on the colour wheel, and picks the name from ranges of hue. Low saturation means the colour is grey or white or black, so the clear channel ratio decides which. Hold the objects at a steady distance, because moving the sensor closer or further changes the clear reading.
Runs on a virtual ESP32 Dev Module in your browser, with sliders for the sensors. Happy with it? Verify and upload to your real board from the same page (Chrome or Edge on a computer).
#include <Wire.h>
#include <Adafruit_TCS34725.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>
Adafruit_TCS34725 tcs(TCS34725_INTEGRATIONTIME_154MS, TCS34725_GAIN_4X);
Adafruit_SSD1306 oled(128, 64, &Wire, -1);
const int BTN = 4;
float gainR = 1, gainG = 1, gainB = 1; // white balance gains
float whiteClear = 1000; // clear reading of the white reference
const char* nameOf(float r, float g, float b, float clearRatio) {
float mx = max(r, max(g, b)), mn = min(r, min(g, b));
float sat = mx > 0 ? (mx - mn) / mx : 0;
if (clearRatio < 0.12) return "Black";
if (sat < 0.28) return clearRatio > 0.45 ? "White" : "Black";
float h;
if (mx == r) h = 60 * fmod(((g - b) / (mx - mn)), 6);
else if (mx == g) h = 60 * (((b - r) / (mx - mn)) + 2);
else h = 60 * (((r - g) / (mx - mn)) + 4);
if (h < 0) h += 360;
if (h < 15 || h >= 345) return "Red";
if (h < 40) return "Orange";
if (h < 75) return "Yellow";
if (h < 170) return "Green";
if (h < 260) return "Blue";
return "Purple";
}
void setup() {
pinMode(BTN, INPUT_PULLUP);
Wire.begin(21, 22);
if (!oled.begin(SSD1306_SWITCHCAPVCC, 0x3C)) { while (true) {} }
if (!tcs.begin()) { while (true) {} }
}
void loop() {
uint16_t r, g, b, c;
tcs.getRawData(&r, &g, &b, &c);
if (digitalRead(BTN) == LOW) { // learn white: make all three channels equal
float mx = max((float)r, max((float)g, (float)b));
if (r > 0 && g > 0 && b > 0) {
gainR = mx / r; gainG = mx / g; gainB = mx / b;
whiteClear = c;
}
delay(300);
}
float rr = r * gainR, gg = g * gainG, bb = b * gainB;
float ratio = c / whiteClear;
const char* name = nameOf(rr, gg, bb, ratio);
oled.clearDisplay();
oled.setTextColor(SSD1306_WHITE);
oled.setTextSize(3);
oled.setCursor(0, 8);
oled.print(name);
oled.setTextSize(1);
oled.setCursor(0, 48);
oled.print("R "); oled.print((int)rr); oled.print(" G "); oled.print((int)gg); oled.print(" B "); oled.print((int)bb);
oled.display();
delay(200);
}Test checklist
What you should see at each check. If a reading is far off, stop and use the troubleshooting list.
| Check | Expected |
|---|---|
| White paper | White |
| Black card | Black |
| Red object | Red |
| Green object | Green |
| Blue object | Blue |
| Yellow object | Yellow |
| Cover the sensor | Black |
If it does not work
Everything reads the same colour
Press the button with white paper in front of the sensor, and keep the distance steady.
Colours jump between names
Use steady light and avoid direct sunlight or a flickering lamp.
Orange and yellow are confused
Adjust the hue limits for your light.
Sensor not found
Check SDA and SCL and that the module has 3.3 V.
Bright objects read dark
Lower the gain to 1X in the tcs line.
Still stuck? Find the fault step by step with your multimeter →
Common questions
What parts do I need for the ESP32 colour name reader?
ESP32 DevKit V1, TCS34725 colour sensor, SSD1306 OLED Display, Tactile push button 6 mm and Breadboard 830 Tie Points.
How long does the ESP32 colour name reader take to build?
About 150 minutes for a intermediate maker, in 7 steps.
How do I know the ESP32 colour name reader works?
White paper: White. Black card: Black. Red object: Red.
Everything reads the same colour: what should I check?
Press the button with white paper in front of the sensor, and keep the distance steady.
Colours jump between names: what should I check?
Use steady light and avoid direct sunlight or a flickering lamp.
Orange and yellow are confused: what should I check?
Adjust the hue limits for your light.
Sensor not found: what should I check?
Check SDA and SCL and that the module has 3.3 V.
