Mission
Build this
Build an ultrasonic doorway storyteller with a visible count and one greeting wave per completed passage.
Borrowed parts are labelled below and have a fallback. The registered device ID is fixed; sensing and behaviour decisions remain yours.
Bill of materials
Parts
| Source | Part | Fallback |
|---|---|---|
| ● kit | HC-SR04 ultrasonic sensor | — |
| ● kit | 1 kΩ and 2 kΩ Echo-divider resistors | — |
| ● kit | Four-digit seven-segment display | — |
| ● kit | SG90 servo | — |
Disconnect USB before rewiring. Motors, the relay, and the servo need appropriate power and a shared ground. Never drive an actuator from the ESP32 3V3 pin.
Your invitation
A doorway is full of unfinished stories
A person approaches. They stop to read a sign. A child runs ahead. Two friends walk shoulder to shoulder. Someone turns around halfway through. The sensor sees only changing distance; the Gate Keeper must decide which stories deserve one count.
You will teach it what a completed passage looks like, wave once for every accepted event, and keep an honest record of the situations it cannot untangle.
“Something came near me twice. Was that two visitors, or one visitor who changed their mind?”
How it listens
The sensor asks one question with a tiny echo
The HC-SR04 sends a short burst of ultrasound—too high for human hearing—and waits for the echo. The longer the round trip takes, the farther away the reflecting surface is.
A brief sound pulse leaves the sensor.
Clothes, a bag, or a wall sends some sound back.
The Echo pulse stays high during the journey.
Your code turns travel time into centimetres.
Sound travels roughly 34 centimetres in one millisecond, but it travels to the visitor and back. Distance is therefore half the journey. The calculation is simple. Deciding what the distance sequence means is the real project.
Why does the Echo wire need two resistors?
The HC-SR04 sends a 5 V Echo signal. ESP32 pins accept only 3.3 V. A 1 kΩ resistor from Echo to GPIO 34 and a 2 kΩ resistor from GPIO 34 to ground divide that voltage to about 3.3 V.
The divider is not an optional accuracy improvement. It protects the input pin from a voltage that can damage it.
The central idea
A near reading is not yet a passage
No visitor in the counting zone.
Distance enters the near region.
The object remains present across several readings.
The near region empties. Accept one event.
This sequence is a state machine: a small memory of where the story has reached. Without it, twenty near readings from one slow visitor become twenty people.
The Gate Keeper stores aggregate events. It does not know faces, phones, or identities. Its failures should remain visible as counting limitations, never invitations to collect more personal data.
Wiring
Protect the listening pin before asking for an echo
Test distance in Serial Monitor first. Add the display next. Let the servo wave only after one complete clear-near-clear sequence produces exactly one count.
The power rule: The HC-SR04 uses 5 V, but its Echo signal must pass through the 1 kΩ/2 kΩ divider before GPIO 34. Run the display at 3V3. Give the servo a separate 5 V supply and join all grounds.
Bench referenceOpen the exact wiring map
| ESP32 pin | Part | Part marking | Carries |
|---|---|---|---|
5V / VIN | HC-SR04 | VCC | 5V power — sensor supply |
GPIO 5 | HC-SR04 | TRIG | Digital in/out — 3.3 V trigger pulse from ESP32 |
GPIO 34 | HC-SR04 | ECHO via divider | Digital in/out — 1 kΩ from ECHO to GPIO 34 and 2 kΩ from GPIO 34 to GND reduces 5 V to about 3.3 V |
GND | HC-SR04 | GND | Ground |
3V3 | TM1637 display | VCC | 3V3 power — safe logic level for the ESP32 |
GND | TM1637 display | GND | Ground |
GPIO 18 | TM1637 display | CLK | Digital in/out — display clock |
GPIO 19 | TM1637 display | DIO | Digital in/out — display data |
GPIO 26 | SG90 servo | signal (orange) | PWM to actuator — waves once per accepted passage |
external 5 V | SG90 servo | power (red) | 5V power — separate supply |
GND | SG90 servo | ground (brown) | Ground — join servo and ESP32 grounds |
Never connect HC-SR04 Echo directly to the ESP32. Unplug USB before changing the divider or servo wiring.
- 5V power
- Digital in/out
- Ground
- 3V3 power
- PWM to actuator
Mount the sensor firmly. A sensor that turns when the servo waves changes its own distance scene and may count its greeting.
Define the doorway
Where does a passage begin and end?
The fixed wall or open space beyond the counting zone.
A person or object has entered the zone, but no count yet.
The candidate left the zone in a way your rule accepts.
Your team decides:
- How many near readings begin a candidate?
- How long can someone stop before the story resets?
- What happens when two people never create a clear gap?
- When is an uncertain passage better left uncounted?
Your doorway rehearsal
Write the awkward script before tuning the rule
- Measure the empty doorway.
Record distance variation and choose the candidate region from evidence.
- Write at least thirty passages.
Include ordinary walks, stops, pairs, bags, turnarounds, and someone hovering near the edge.
- Tune on the first performance.
Record expected and observed count for every scene, then change the rule once.
- Freeze the rule.
Run a fresh performance without tuning. This second result is the one you report.
| Scene | Expected | Observed | What confused it? |
|---|---|---|---|
| single walk | 1 | ___ | ___ |
| stop and continue | 1 | ___ | ___ |
| turn around | team decides | ___ | ___ |
| side-by-side pair | 2 | ___ | ___ |
When the gate gets confused
Every false count has a story behind it
One visitor becomes several counts
The code counts readings instead of completed passages. Require clear-near-clear and add a short recovery state.
Two people become one
They never created a clear gap. Record this as a physical limit or add a second sensing position for the stretch route.
Soft clothing disappears at an angle
Ultrasound reflects away or is absorbed. Change sensor angle and test multiple body orientations.
Distance suddenly becomes zero or enormous
No usable echo returned. Reject the sample instead of treating it as a visitor.
The greeting causes another count
The servo moved the sensor, structure, or nearby reflector. Stiffen the mount and ignore only the known greeting interval.
Choose your gate
What kind of counter team will you become?
The passage playwrights
Make the state machine the main work. Give stops, returns, and timeouts explicit endings.
The stress testers
Design increasingly awkward doorway scenes and publish where the fixed rule finally fails.
The direction builders
Add a second sensing position and test whether event order can distinguish entering from leaving.
A calm way through the build
Collect four small wins
gk-01says hello.Join the garden before counting.
- A fixed wall has a stable distance.
Protect Echo and reject missing echoes.
- One clear-near-clear story counts once.
Build state memory before adding the display.
- The frozen rule survives a fresh script.
Add the greeting arm and evaluate without retuning.
The garden handshake
Share what you found
These names are the rigid part of the project. They let another team find your work without knowing what you called the variables in your code.
Accepted passages
garden/entrance/counter/gk-01/countUnit: events
Current distance
garden/entrance/counter/gk-01/distanceUnit: centimetres
Listen beyond your own device.
garden/greenhouse-1/climate-node/gm-01/temperatureTemperature can explain changes in sound speed only slightly at this scale. Use the connection for a bounded display or greeting behaviour, not to rewrite the passage count.
Finish line
Ready to introduce to the garden
gk-01 stays online and publishes accepted count and current distance.
The reject feed stays clear after the final code starts.
The device reads Juliet’s temperature topic.
Each accepted passage produces one non-blocking wave and one display update.
The build log contains the fixed script, expected and observed counts, one tuning run, one untouched evaluation run, and ambiguous cases.
The Echo divider is fitted, the sensor mount is stable, the servo is safely powered, and the device label can be scanned.
A trustworthy counter is not one that claims every person. It is one whose definition of a passage survives contact with real human behaviour.