Projects / ESP32 colour name reader

ESP32 colour name reader

Intermediate2.5 hGuided buildReviewed

Build it step by step

0 of 7 done
  1. ESP32

    Wire the sensor and display

    Both to 3V3 and GND, SDA to GPIO21, SCL to GPIO22.

  2. ESP32

    Wire the button

    GPIO4 to GND.

  3. ESP32TCS3472512.2 mASSD1306

    Install the libraries

    Adafruit TCS34725, Adafruit SSD1306 and Adafruit GFX.

  4. ESP32TCS34725

    Upload the sketch

    The display shows a colour name and three numbers.

  5. ESP32

    White balance

    Hold white paper about 1 cm from the sensor and press the button.

  6. ESP32TCS34725

    Try coloured objects

    Hold each at the same distance.

  7. ESP32

    Adjust

    Re-balance when the room light changes.

In short

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

FromToWhy
TCS34725 VIN and OLED VCCESP32 3V3Power at 3.3 V
TCS34725 GND and OLED GNDESP32 GNDCommon ground
TCS34725 SDA and OLED SDAESP32 GPIO21Shared I2C data
TCS34725 SCL and OLED SCLESP32 GPIO22Shared I2C clock
White balance buttonESP32 GPIO4 and GNDPress 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.

CheckExpected
White paperWhite
Black cardBlack
Red objectRed
Green objectGreen
Blue objectBlue
Yellow objectYellow
Cover the sensorBlack

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 →

Ask Lark AI

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.