Lessons · Lesson S3 · Sensors · 40 min
Smart sensors, distance and camera
Measure distance with a time-of-flight sensor, then read where a coloured target sits in a camera module's view. About 40 minutes, with a distance cone and a camera frame you can move.
Two ways a machine sees
Imagine you shout into a dark cave and time how long the echo takes. The longer the wait, the farther the wall. Bats are famous for finding their way with sound like this. A camera does something else: it takes in light, like your eyes, and then something has to decide what the picture contains.
Both ideas are in a small module you can wire to an ESP32. In this lesson you will use:
- a distance sensor that times a flash of light to tell you how far away something is,
- a camera module that finds a colour you taught it, and tells you where in its view it sits.
Neither module hands you raw data to sort through. They do the hard part inside and send a short answer over the two I2C wires from lesson K5: a number of millimetres, or the position of a box.
Distance: time of flight
A time-of-flight sensor (ToF) sends out light and detects how long it takes to come back, then turns that time into a distance [1]. The VL53L0X is one. Its light is invisible, and the beam is narrow, so it reads the surface straight in front of it [1]. A sonar, which bounces sound instead, covers a wider cone [1].
Three things worth knowing:
- Range. Adafruit’s guide gives about 50 to 1200 mm [1]. Think “a few centimetres up to about a metre”. Expect the number to wobble a little: depending on light and distance it is within about 3 to 12% [1].
- Out of range. When nothing can be measured, the reading cannot be trusted, and the example sketch says “out of range” [3][4].
- Its address. On the I2C wires the sensor answers at
0x29by default [2][3]. Your K5 scanner will find it there.
What about the cheap ultrasonic sensor? The HC-SR04 is popular, but its echo output is 5 V, and that cannot go straight into a board like yours [6]. It needs a voltage divider or a level shifter first. This lesson skips it and uses the I2C sensor, which needs neither.
Wire it and read it
Power it from 3V3, even though the board accepts up to 5 V [2]. Same reason as in K5: its power pin sets the level of the I2C signals, and the ESP32’s pins are made for 3.3 V.
| Distance breakout | ESP32 DevKitC |
|---|---|
| Vin | 3V3 |
| GND | GND |
| SDA | GPIO 21 |
| SCL | GPIO 22 |
GPIO 21 and 22 are the default I2C pins on the generic ESP32 [7]. Add an LED on GPIO 16 through a 220 Ω resistor, as in lesson K2, to show “something is near”.
Install the library Adafruit VL53L0X from the Library Manager, as in K5 [3]. If it offers to install other libraries with it, click “Install all”. Take off the little protective plastic cover from the sensor first [3]. Then upload:
// Tinker Mission, lesson S3: distance with a time-of-flight sensor (VL53L0X breakout)
// Wiring (power the breakout from 3V3, see lesson K5):
// Vin -> 3V3 GND -> GND SDA -> GPIO 21 SCL -> GPIO 22
// LED: GPIO 16 -> 220 ohm resistor -> LED long leg; LED short leg -> GND
// Open the serial monitor at 115200 baud. The LED lights when something is closer than NEAR_MM.
// Needs the library "Adafruit VL53L0X" (Library Manager).
#include <Wire.h>
#include "Adafruit_VL53L0X.h"
const int SDA_PIN = 21; // usual I2C data pin of the ESP32 DevKitC
const int SCL_PIN = 22; // usual I2C clock pin of the ESP32 DevKitC
const int LED_PIN = 16; // LED that shows "something is close"
const int NEAR_MM = 200; // closer than this = "near" (200 mm = 20 cm)
const unsigned long READ_INTERVAL = 100; // one reading every 100 ms
Adafruit_VL53L0X lox = Adafruit_VL53L0X();
unsigned long lastRead = 0;
void setup() {
Serial.begin(115200);
pinMode(LED_PIN, OUTPUT);
Wire.begin(SDA_PIN, SCL_PIN); // start the I2C bus on these two pins
if (!lox.begin()) { // looks for the sensor at its address (0x29 by default)
Serial.println("Sensor not found. Check power, SDA and SCL wires.");
while (true) {
delay(1000); // nothing else to do: stop here
}
}
Serial.println("Sensor ready. Move your hand in front of it.");
}
void loop() {
unsigned long now = millis();
if (now - lastRead >= READ_INTERVAL) {
lastRead = now;
VL53L0X_RangingMeasurementData_t measure;
lox.rangingTest(&measure, false); // ask for one measurement
if (measure.RangeStatus != 4) { // status 4 means the reading cannot be trusted
int distance = measure.RangeMilliMeter;
Serial.print("Distance (mm): ");
Serial.println(distance);
digitalWrite(LED_PIN, distance < NEAR_MM ? HIGH : LOW);
} else {
Serial.println("Out of range");
digitalWrite(LED_PIN, LOW);
}
}
}
Download the sketch folder (.zip)
Open the serial monitor at 115200 baud. Move your hand in and out. You should see something like this:
Sensor ready. Move your hand in front of it.
Distance (mm): 412
Distance (mm): 188
Distance (mm): 87
Out of range
How it works: lox.rangingTest(&measure, false) takes one measurement, and the reading is in measure.RangeMilliMeter [4]. A RangeStatus of 4 marks a bad reading, so the sketch only trusts the others [4]. The LED lights under 200 mm (20 cm).
Camera: where is the colour?
A vision module like the HuskyLens has a small camera and a processor inside. You teach it something (a face, a line, a colour). It then reports where it sees it. In colour recognition mode, it draws a box around the colour you taught it [10].
Your ESP32 asks and gets back a block with these numbers [5]:
xCenterandyCenter: the middle of the box,widthandheight: its size,ID: which learned colour it is. The first one you taught is ID 1 [5].
An ID of 0 means “something detected, but not learned” [5].
Error from centre. The camera’s screen is 320 by 240 pixels [8], so the middle across is about 160. Subtract it:
error = xCenter - 160
A negative error means the target’s x is smaller than 160, a positive one means bigger, and zero means centred. Move your target and watch which way x grows on your own camera. This number is what a robot uses to turn towards a target: you met the other half in A2, where a number turns into a servo angle.
Try it below, with the cone on one tab and the camera frame on the other.
Simulation of the distance sketch, not a real sensor.
A real reading wobbles a little, by a few per cent. Range: about 50 to 1200 mm.
Simulation of the camera frame, not the real camera.
x bigger than the middle
error = xCenter − 160
Which way x grows on your own camera: move the target and watch.
This is the starting state: the controls need JavaScript.
Wire the camera and read it
Two things to settle before you connect the camera.
Power. The HuskyLens accepts 3.3 to 5 V. Its typical current is 320 mA at 3.3 V, or 230 mA at 5 V, measured in face recognition with the fill light off [8]. That is a lot more than an LED or a small sensor draws, so do not feed it from the board’s 3V3 pin. The maker says you can power it through either its USB port or its 4-pin connector, and that it uses USB first if both are plugged in [11]. The simplest way is its own USB cable into a charger or power bank, with only GND and the two signal wires (through the level shifter, below) going to the ESP32. Make sure the supply is strong enough, or the camera misbehaves [11].
Signals: always through a level shifter. The camera’s I2C pins are labelled T (SDA) and R (SCL) on its 4-pin connector [8]. The camera is made to work with 5 V boards too, and the maker does not say what voltage these two wires sit at when it runs on 5 V from USB. Your ESP32’s pins are made for 3.3 V, so do not take the risk: put a small I2C level shifter in between, the kind with a low-voltage side (LV) and a high-voltage side (HV), as in lesson K5. A 4-channel BSS138-type board is the usual one; buy it with its pins already soldered. Wire it like this:
| Level shifter | Connect to |
|---|---|
| LV | ESP32 3V3 |
| HV | ESP32 5V |
| GND (both sides) | ESP32 GND and camera - |
| HV side, channel 1 | camera T (SDA) |
| HV side, channel 2 | camera R (SCL) |
| LV side, channel 1 | GPIO 21 |
| LV side, channel 2 | GPIO 22 |
Leave the camera’s + (VCC) wire unconnected: wrap its end in tape so it cannot touch anything. The camera gets its power from its own USB cable.
On the camera itself, set the protocol: General Settings > Protocol Type > I2C, then dial to “Save & Return” and confirm “Yes”, or the setting is not kept [9]. Auto-detection is the default [9], and the maker’s I2C example sets I2C [12].
No library to install. The maker’s library [5][12] stops with an error on recent versions of the ESP32 board package, so this sketch comes with a fixed copy in a folder called src. Download the whole sketch folder from this lesson (if it arrives as a ZIP, unzip it first), keep the folder name l-s3-color-track, keep src next to the .ino file, and open l-s3-color-track.ino from there. Copying only the code below will not work.
Teach it a colour. Dial the function button until “Color Recognition” shows at the top. Point the “+” at a plain, brightly coloured object until a white frame selects it. Long press the learning button while you move closer and farther, then release [10]. If a message asks whether to continue, just wait for the countdown to end [10]. The first colour you learn becomes ID 1 [10]. Colour recognition is greatly affected by the light in the room, so keep it the same [10]. Then upload:
// Tinker Mission, lesson S3: where is the coloured target? (HuskyLens, colour recognition, I2C)
// Wiring: through an I2C level shifter (LV = 3V3 side, HV = 5V side): camera SDA/SCL -> HV, LV -> GPIO 21 (SDA) / 22 (SCL), all GND together.
// Power: the camera needs about 230-320 mA, so power it separately (see the lesson).
// On the camera: General Settings > Protocol Type > I2C, switch to colour recognition, teach it a colour.
// Open the serial monitor at 115200 baud.
// The HuskyLens code is in this sketch's src/ folder (fixed copy of DFRobot's library): no ZIP to install.
#include <Wire.h>
#include "src/HUSKYLENS/HUSKYLENS.h"
const int SDA_PIN = 21; // usual I2C data pin of the ESP32 DevKitC
const int SCL_PIN = 22; // usual I2C clock pin of the ESP32 DevKitC
const int TARGET_ID = 1; // the first colour you taught the camera
const int CENTER_X = 160; // the screen is 320 wide, so the middle is 160
const int DEAD_BAND = 20; // closer than this to the middle counts as "centred"
const unsigned long LOOK_INTERVAL = 100; // look every 100 ms
HUSKYLENS huskylens;
unsigned long lastLook = 0;
void setup() {
Serial.begin(115200);
Wire.begin(SDA_PIN, SCL_PIN); // start the I2C bus on these two pins
while (!huskylens.begin(Wire)) { // try to talk to the camera
Serial.println("Camera not found. Check wires and Protocol Type = I2C.");
delay(1000); // nothing else to do yet: try again
}
huskylens.writeAlgorithm(ALGORITHM_COLOR_RECOGNITION); // colour mode
Serial.println("Camera ready.");
}
void loop() {
unsigned long now = millis();
if (now - lastLook >= LOOK_INTERVAL) {
lastLook = now;
if (!huskylens.requestBlocks(TARGET_ID)) {
Serial.println("No answer from the camera.");
} else if (huskylens.available() == 0) {
Serial.println("Target not seen.");
} else {
HUSKYLENSResult block = huskylens.read(); // the first box found
int error = block.xCenter - CENTER_X; // negative = x smaller than the middle
Serial.print("x=");
Serial.print(block.xCenter);
Serial.print(" y=");
Serial.print(block.yCenter);
Serial.print(" error=");
Serial.print(error);
if (error < -DEAD_BAND) {
Serial.println(" x smaller than the middle");
} else if (error > DEAD_BAND) {
Serial.println(" x bigger than the middle");
} else {
Serial.println(" centred");
}
}
}
}
Download the sketch folder (.zip)
Serial monitor at 115200 baud. Move the object across the camera’s view:
x=142 y=118 error=-18 centred
x=250 y=120 error=90 x bigger than the middle
Target not seen.
How it works: huskylens.begin(Wire) tries to connect and says whether it did [5]. writeAlgorithm(ALGORITHM_COLOR_RECOGNITION) switches the mode [5]. requestBlocks(1) asks only for boxes of ID 1, available() counts them, and read() hands one over [5].
Make your own changes
Change one thing, then watch.
- Move the near line. In the distance sketch, change
NEAR_MMto 100, then 400. At which distance does your LED start to flicker? - Widen the dead band. In the camera sketch, change
DEAD_BANDfrom 20 to 60. What happens to the word “centred”? - Steer a servo. Using A2, add a servo on its own supply and nudge its angle by
error / 20each time you see the target. Which way does it turn? If it chases the wrong way, flip the sign. What happens if you divide by 5 instead? (Careful: too big a number makes it overshoot and swing.)
When it does not work
- “Sensor not found”. Check
3V3,GND, SDA to GPIO 21 and SCL to GPIO 22. Run the K5 scanner: you should see0x29[2][3]. Remove the sensor’s protective plastic cover [3]. - Always “Out of range”. Something is too far or too close for the sensor. Try your hand about 20 cm away [1][4].
- “Camera not found”. Check the wires and the level shifter (LV to 3V3, HV to 5V, camera on the HV side), that Protocol Type is I2C and was saved [9][12], and its power [11]. The K5 scanner should show the camera at
0x32[13].beginreturns false when it cannot connect [5]. - “No answer from the camera”. The camera did not reply in time. The wait has a limit, 100 ms by default [5]. Check the wires.
- “Target not seen”. The camera has not learned a colour (see “Teach it a colour”), or the colour is not in its view. ID 0 is “detected, not learned” and the sketch only asks for ID 1 [5].
- Two sensors at 0x29. Two devices cannot share an address. See K5 and the Adafruit guide for how to change one [3].
- Nothing in the serial monitor. Set it to 115200 baud.
Check yourself
Three small questions. Nothing is saved, take your time.
A time-of-flight distance sensor works out how far away something is by measuring what?
- How bright the room is
- How long a pulse of light takes to bounce back to the sensor
- How hot the object is
Show the answer
How long a pulse of light takes to bounce back to the sensor. The sensor sends out light and detects how long it takes to return, the "time of flight" [1]. A longer trip means a farther object.
A camera module reports a coloured target at x = 250, on a screen that runs from 0 to 320. With the middle at 160, what is the error from centre (x minus the middle)?
- -90, because the middle minus x is negative
- 250, the same as x
- +90, because 250 minus 160 is 90, a positive number
Show the answer
+90, because 250 minus 160 is 90, a positive number. Error = x minus the middle: 250 - 160 = +90. The camera's screen is 320 pixels wide [8], so the middle is 160. A positive error means x is bigger than the middle (160).
Which ESP32 pin should power the distance sensor breakout, and why?
- 3V3, because the breakout should get the same power as the logic level of the microcontroller, which is 3.3 V on the ESP32
- 5V, because more voltage gives a longer range
- Any GPIO, because a breakout needs almost no power
Show the answer
3V3, because the breakout should get the same power as the logic level of the microcontroller, which is 3.3 V on the ESP32. The breakout takes 3 to 5 V and its own regulator brings it down, and Adafruit advises giving it the same power as the microcontroller's logic level [2]. That keeps SDA and SCL at 3.3 V (lesson K5).
In short
- A time-of-flight sensor times light that bounces back, and turns it into a distance [1]. Its beam is narrow [1].
- Power the VL53L0X breakout from
3V3, keep SDA on GPIO 21 and SCL on GPIO 22. It answers at0x29by default [2][3]. - Readings with
RangeStatus4 cannot be trusted [4]. - A camera module reports a box:
xCenter,yCenter,width,heightand anID[5]. - The screen is 320 pixels wide [8], so
error = xCenter - 160tells you where the target is relative to the middle. - The HuskyLens takes 3.3 to 5 V and about 230 to 320 mA [8]: power it separately, not from the 3V3 pin, and connect its SDA and SCL through a level shifter. Set Protocol Type to I2C [9].
Next steps: servo-based projects (A2), or the colour-target turret mission.
Sources
Show the 13 sources
- Adafruit, “Adafruit VL53L0X Time of Flight Micro-LIDAR Distance Sensor Breakout: Overview” (time of flight; invisible laser source; narrow cone unlike sonar; about 50 to 1200 mm range; 3 to 12% ranging accuracy depending on light and distance) — https://learn.adafruit.com/adafruit-vl53l0x-micro-lidar-distance-sensor-breakout/overview
- Adafruit, “Adafruit VL53L0X Time of Flight Micro-LIDAR Distance Sensor Breakout: Pinouts” (Vin takes 3 to 5 V through an on-board regulator; give it the same power as the microcontroller’s logic level; default I2C address 0x29) — https://learn.adafruit.com/adafruit-vl53l0x-micro-lidar-distance-sensor-breakout/pinouts
- Adafruit, “Adafruit VL53L0X Time of Flight Micro-LIDAR Distance Sensor Breakout: Arduino Code” (install “Adafruit VL53L0X” from Manage Libraries; example under File > Examples; serial monitor at 115200; “out of range”; remove the protective plastic cover; default address 0x29 and how to change it) — https://learn.adafruit.com/adafruit-vl53l0x-micro-lidar-distance-sensor-breakout/arduino-code
- Adafruit, Adafruit_VL53L0X library, example “vl53l0x.ino” (rangingTest, RangeMilliMeter, RangeStatus 4 treated as out of range) — https://raw.githubusercontent.com/adafruit/Adafruit_VL53L0X/master/examples/vl53l0x/vl53l0x.ino
- HuskyLens, HUSKYLENSArduino repository, README “HUSKYLENS Arduino API” (HUSKYLENSResult with xCenter, yCenter, width, height, ID; ID 1 = first learned item, 0 = detected but not learned; begin(Wire); writeAlgorithm and ALGORITHM_COLOR_RECOGNITION; requestBlocks(ID), available(), read(); default time-out 100 ms) — https://raw.githubusercontent.com/HuskyLens/HUSKYLENSArduino/master/README.md
- Adafruit, “Distance Measurement with Ultrasound” (the HC-SR04’s 5 V echo output cannot be connected directly to a 3.3 V board; some simple electronics fix it) — https://learn.adafruit.com/distance-measurement-ultrasound-hcsr04
- Espressif, Arduino-ESP32 documentation, “I2C” (on the generic ESP32 the default I2C pins are GPIO21 for SDA and GPIO22 for SCL) — https://docs.espressif.com/projects/arduino-esp32/en/latest/api/i2c.html
- DFRobot, “HuskyLens K210 AI Vision Sensor (SEN0305)” wiki, main page (supply voltage 3.3 to 5.0 V; typical current 320 mA at 3.3 V and 230 mA at 5.0 V in face recognition mode, fill light off; UART and I2C interfaces; 2.0-inch IPS screen, 320 by 240; I2C pins T = SDA and R = SCL on the 4-pin connector) — https://wiki.dfrobot.com/HUSKYLENS_V1.0_SKU_SEN0305_SEN0336
- DFRobot, HuskyLens wiki, “General Settings” (Protocol Type: UART at three speeds, I2C or Auto-detection, default Auto-detection) — https://wiki.dfrobot.com/sen0305/docs/22610
- DFRobot, HuskyLens wiki, “Function Introduction-Color Recognition” (select the mode with the function button; point the “+” at the colour; long press the learning button, then release; IDs follow the order learned; colour recognition is greatly affected by ambient light) — https://wiki.dfrobot.com/sen0305/docs/22645
- DFRobot, HuskyLens wiki, “Board Overview” (power through the USB port or the 4-pin connector, USB used first if both are connected; make sure the supply voltage and rate are enough; function and learning buttons) — https://wiki.dfrobot.com/sen0305/docs/22602
- DFRobot, HuskyLens wiki, “Example Code for Arduino-Read Position Data(I2C)” (unzip the HUSKYLENS library into the Arduino libraries folder, folder named HUSKYLENS; set Protocol Type to I2C or use auto-detection; begin(Wire) example) — https://wiki.dfrobot.com/sen0305/docs/22766
- HuskyLens, HUSKYLENSArduino repository, “HUSKYLENS/HUSKYLENS.h” (the library talks to the camera at I2C address 0x32) — https://raw.githubusercontent.com/HuskyLens/HUSKYLENSArduino/master/HUSKYLENS/HUSKYLENS.h