Ambient Light Sensor

What it is

A light sensor, a resistor and a capacitor. The sensor is a phototransistor: light lets a current flow through it, about half a microamp per lux for a typical part, and the 4.7 kΩ resistor turns that current into a voltage. That voltage is SIGNAL. Dark, about 0 V; a lit room, a few tenths of a volt to about a volt; bright light, up to just under VCC.

Three things about it decide how a sketch should treat it. It is fast, switching in about 15 µs, so it sees the ripple in many mains lamps and a single reading jitters; averaging over 50 ms cures that. It sees near infrared best, peaking at 850 nm, so the same brightness to your eye reads very differently under different lamps. And the number is not a unit: any one sensor can be 30 % more or less sensitive than typical. Calibrate at runtime: read the two conditions you care about and put the threshold between them.

The page this replaces called the sensor an LDR, a resistor that changes with light, and said it was slow and saw green best. None of that is this board.

VCC sets the ceiling, not the reading

The light sets the current and the resistor sets the voltage, so in a room VCC changes nothing. What VCC does set is how high SIGNAL can go: about 0.4 V under it, where bright light flattens out.

Never 5V beside a 3.3 V board: bright light would take SIGNAL towards 4.6 V. The lux and room figures are a typical part under the datasheet's light, which stops at 100 lux; above that they are the same line extended. On an ESP32, a room under about 43 lux reads 0.

Which pin is which

Parts up, header at the bottom, reading left to right:

The back prints TK20 AMBIENT LIGHT instead of pin names. Turned over, the square pad is on the right, and it is still GND. There is no LED: test it by covering the sensor and shining a torch on it.

Wiring, in three lines

1. GND to your board's GND.
2. VCC to 5V on an Uno, 3V3 on an ESP32, ESP32-S3 or Pico.
3. SIGNAL to an analog pin: A0 on an Uno, GPIO 34 on an ESP32, GPIO 4 on an ESP32-S3, GP26 on a Pico. On an ESP32, use an ADC1 pin so Wi-Fi does not stop the reading.

Leave NC unconnected.

Example

// The analog pin SIGNAL is wired to.
// Uno: A0. ESP32: 34. ESP32-S3: 4. Pico: 26.
const int LIGHT_PIN = A0;

void setup() {
  Serial.begin(115200);
}

void loop() {
  // The mean of everything read in 50 ms: whole cycles of a
  // mains lamp's 100 or 120 Hz ripple, so the ripple cancels.
  long sum = 0;
  long n = 0;
  unsigned long start = millis();
  while (millis() - start < 50) {
    sum += analogRead(LIGHT_PIN);   // more light, higher
    n++;
  }
  Serial.println(sum / n);
  delay(200);
}

import sys
import time
from machine import ADC, Pin

# The GPIO number SIGNAL is wired to. ESP32: 34. ESP32-S3: 4. Pico: 26.
adc = ADC(Pin(4))
if sys.platform == "esp32":
    adc.atten(ADC.ATTN_11DB)      # the full range, to about 3.1 V

while True:
    total = 0
    n = 0
    start = time.ticks_ms()
    while time.ticks_diff(time.ticks_ms(), start) < 50:
        total += adc.read_u16()   # more light, higher
        n += 1
    print(total // n)
    time.sleep_ms(200)

Where to start

The handbook below is ten short articles, each with a working figure. The first reading is the whole build in three wires and a few lines, and not an LDR is what the part really is.

For a light that comes on at dusk, a night light is the project. If the numbers wobble, read the flicker under room lights; if an ESP32 reads 0, reading it on an ESP32.

And before plugging it into an ESP32, VCC sets the ceiling is the one page that protects the board.