ESP32 Starter Kit: Interactive Guide

Open src/main.cpp — the whole firmware is this pump, run thousands of times per second:

Every module gets a turn — inputs → decisions → outputs → comms — and none of them is ever allowed to wait. There is no delay() anywhere in this path: a module that has nothing to do returns instantly. That one rule is why the siren, the sensors, and (later) the web server can all share a single core without stepping on each other.

Try it: keep pio device monitor open and press BTN1. The printed line comes from leds::toggle(), called by dispatchButtons(), called from this loop — while the heartbeat never misses a beat. That's the loop working.

Open src/buttons.cpp — this is poll(), the most instructive 14 lines in the repo:

Three ideas fused: active-LOW (with INPUT_PULLUP the pin rests HIGH and a press pulls it to GND — hence == LOW), debouncing (a real button's contacts bounce for a few ms; ignore changes until the reading holds steady), and edge detection (events[i] is true for exactly one loop pass per press — hold the button forever and it still fires once).

Try it: in src/buttons.cpp set kDebounceMs = 1, reflash, and press buttons until one double-fires (checkpoint box 2 breaks!). Then try 500 — feel the lag. Restore 30.

Open src/leds.cpp, function loop() — three unrelated rhythms run side by side, each with its own last-time variable:

This is why millis() beats delay(): the pattern if (now - lastX >= interval) lets any number of independent rates coexist. A single delay(500) for the heartbeat would freeze the chase, the buttons, and everything else. Also worth a look above: kColors[] — the RGB palette is a data table, not a pile of if-statements.

Try it: change the heartbeat's 500 to 100 and reflash — the chase speed doesn't change. Then add your own color to kColors[] (e.g. {128, 0, 255, "purple"}) and BTN4 through to it. Revert when done.

Open src/display.cpp. In begin(), one line decides the firmware's whole personality:

If the OLED never ACKs on the I²C bus, begin() returns false and every module quietly falls back to phase-1 behavior — a missing part becomes a mode, not a crash. The drawing itself is the standard framebuffer idiom: you never draw "to the screen", you draw to a RAM buffer and ship it in one transfer. The < 250 guard is the same non-blocking timer pattern as the LEDs — redrawing faster would just waste loop time.

Try it: change 250 to 1000, reflash, and turn the pot — the numbers now visibly stutter. Then pull the OLED's SDA wire and reboot: the serial banner says phase-1 (no OLED) and BTN4 cycles colors again. Reconnect and revert.

Open src/sensors.cpp — 45 lines, and the densest file in the repo:

The "magic line" is an exponential moving average: each new reading only moves the value 20% of the way — jitter cancels out, real changes still get through. The < 0 ? part self-seeds it on the first sample (it starts at −1, an impossible ADC value). And note the DHT11 line: those sensors fail reads routinely, so a failed read keeps the last good value instead of flashing nan on the display. The simSensors guard at the top is what makes the whole sim console work — two lines of guard turn the firmware into its own simulator.

Try it: change 0.8f / 0.2f to 0.5f / 0.5f — the light bar gets twitchy. Try 0.98f / 0.02f — now cover the LDR and watch it crawl. Restore 0.8/0.2. Bonus: type sim light 300 in the serial console and watch the real sensor get ignored.

Open include/state.h (the five states) and src/alarm.cpp. Every transition in the whole alarm goes through one choke-point:

State + entry timestamp = timed transitions. Because every state change stamps alarmSince, any state can express "after N seconds, move on" as one comparison — that's the entire exit-delay countdown. And because every change passes through setState(), the serial log narrates the machine for free. This shape — an enum, a switch, one mutator — is the backbone of most embedded firmware you'll ever read.

Try it: in include/config.h set kExitDelayMs = 3000 for faster testing, and change kAlarmCode to your own PIN. No PIR wired yet? Test the whole machine from the console: arm, wait, sim motion, watch TRIGGERED → SIREN, then disarm with the buttons: 3·1·2·4.

Still in src/alarm.cpp — the kit's two buzzers need opposite treatment, and both are here:

The active buzzer has its own oscillator — a HIGH pin is a fixed beep. The passive one is a bare speaker: tone() (LEDC PWM under the hood) must generate the frequency, which is why it can sweep and warble. Note beep() never waits — it books a deadline and returns; the top of loop() reaps it. One more line worth finding: app.pirMotion = now > kPirWarmupMs && … — the HC-SR501 emits garbage for its first minute, so the code simply refuses to listen until then. The datasheet is part of the program.

Try it: retune the siren — swap 2400 / 1600 for your own pair (try 900/600 for a European two-tone). Then a puzzle: the ARMING chirp line (now - app.alarmSince) % 1000 < 30 is subtly fragile — can you see why? (Hint: what if no loop pass lands inside the 30 ms window?) The lastX pattern used everywhere else can't miss.

Open src/relays.cpp, loop() — the same idea in two shapes, back to back:

A sensor value hovering exactly at one threshold would flip the relay on and off every loop pass — audible, and hard on the hardware. Hysteresis opens a dead band: the value must travel past the far edge to switch back. As a second seatbelt, drive() enforces kRelayMinDwellMs (30 s) between physical switches — software rules protecting a mechanical part. The lamp rule right between the two excerpts is also worth reading: it's one boolean that reads exactly like the English sentence describing it.

Try it (the best demo in the project): in config.h set kDarkHysteresis = 0 and kRelayMinDwellMs = 1000, reflash, then hover the light level around the threshold from the console — alternate sim light 1195 / sim light 1205 (with sim motion to satisfy the lamp rule). Hear the chatter. Restore both values and it's gone. Now you know why every thermostat on Earth has a dead band.

Open src/net.cpp. Most tutorials connect like this: while (WiFi.status() != WL_CONNECTED) delay(500); — freezing the whole device until the router answers. This firmware refuses:

Same edge-detection idea as the buttons, applied to the radio: compare the current status with the remembered one, and run connect-time work exactly once on the rising edge. The alarm keeps arming, the sensors keep reading, and the network joins whenever it joins. Two more patterns worth finding in this file: #if __has_include("secrets.h") at the top compiles the whole module down to three empty stubs when there are no credentials (that's why phases 1–4 never mention WiFi), and notify() never touches the network — it queues the message and lets loop() send it later, rate-limited.

Try it: change kHostname in config.h and your dashboard moves to http://<newname>.local. Then kill your router's WiFi mid-session and watch the serial log: the device shrugs, keeps running, reconnects alone. That resilience is this loop.

Open src/mqttlink.cpp. The most elegant two lines in the whole project are the connect call:

The extra connect arguments are a Last Will & Testament: you tell the broker, in advance, what to announce if you die. Pull the ESP32's power and the broker itself publishes offline — Home Assistant greys the device out with zero polling. The reconnect logic above it is the same non-blocking shape as WiFi's (third time you've seen it now). The one part not worth reading line-by-line is publishDiscovery(): it publishes one retained JSON config per entity so HA auto-creates them — JSON inside C strings inside Jinja templates. Trust the summary.

Try it: drop the publish interval from 10000 to 2000 and watch the HA entities update faster. Then run the LWT experiment for real: pull the USB cable and watch HA grey out. That's the broker keeping your promise.