Practical case: ESP32 Secure Access Panel

Practical case: ESP32 Secure Access Panel — hero

Objective and use case

What you’ll build: A functional prototype of a secure access panel utilizing the ESP32’s built-in capacitive touch sensing, visual LED indicators, and acoustic buzzer feedback.

Why it matters / Use cases

  • Wear-free interfaces: Eliminates mechanical degradation, making it ideal for high-traffic access panels, cleanrooms, or outdoor keypads exposed to the elements.
  • Secure building automation: Demonstrates the fundamental logic of sequence validation and state management required in frontline commercial security systems.
  • Integrated user feedback: Combines visual (LED) and acoustic (buzzer) signals for a robust HMI, ensuring users know input was registered with sub-50ms response latency.
  • Non-blocking state machines: Manages asynchronous human input without halting the microcontroller, maintaining constant system responsiveness.

Expected outcome

  • Reliable touch detection and software debouncing utilizing the ESP32’s internal capacitive hardware.
  • A non-blocking state machine capable of processing sequential inputs and rejecting invalid codes instantly.
  • Synchronized, low-latency GPIO actuation driving LED and buzzer feedback based on access state.

Audience: Embedded Systems Engineers, IoT Developers; Level: Intermediate

Architecture/flow: ESP32 Capacitive Touch Pins → Software Debounce Filter → Non-blocking Sequence Validator → GPIO Actuation (LED/Buzzer)

Educational validation note

Before publication, this case passed the Prometeo automated validation gate with status PASS. For this ESP32 DevKitC profile, the project was checked as a PlatformIO project: the validator extracted platformio.ini and src/main.cpp, created a temporary project and ran pio run against platform = espressif32, board = esp32dev and framework = arduino. It also checked article structure, copy/paste-safe ASCII command options, and unsupported stacks such as direct ESP-IDF or non-scoped ESP32 boards.

Published validation evidence

  • Automatic result: PASS.
  • Parsed structure: 3 sections, 2 tables and 2 code blocks detected before publication.
  • Checked code: 1 PlatformIO config + 1 ESP32 source/pio run.
  • Supported catalog: the article text was checked against Prometeo’s validation-capable device profiles, and unsupported stacks block publication.
  • Report findings: no blocking findings.

This validation confirms syntax and tool compatibility for the published code, but it does not replace physical testing on your exact ESP32 DevKitC board, wiring, power supply and local WiFi environment.

Educational safety note

This project is an educational prototype, not a certified product. Before powering the setup, verify the pinout of your exact ULX3S board revision, keep FPGA I/O signals at 3.3 V, never connect 5 V directly to I/O pins, disconnect power before changing wiring, and use suitable external supplies for loads, motors or servos while sharing ground only when the wiring requires it.

Conceptual block diagram

High-level view: what enters the system, what each block processes, and what comes out.

Functional architecture

ESP32 Capacitive Touch Pins

Software Debounce Filter

Non-blocking Sequence Validator

GPIO Actuation (LED/Buzzer)

Conceptual signal and responsibility flow between device blocks.

Validation path

Source code

PlatformIO build

Flash

Serial monitor

Conceptual summary of the tools used to check the published material.

Prerequisites

To successfully complete this tutorial, you will need:
* Basic understanding of C++ programming (variables, arrays, conditional logic, and functions).
* Visual Studio Code installed with the PlatformIO IDE extension.
* Familiarity with breadboard prototyping and basic electronic components.
* A micro-USB or USB-C cable (depending on your specific ESP32 DevKitC variant) capable of both power and data transfer.

Materials

You must use the exact components listed below to ensure the provided code and wiring instructions work without modification:
* Microcontroller: ESP32 DevKitC (Standard 38-pin or 30-pin version).
* Input: Capacitive touch pads. (You can use dedicated commercial touch pad modules, or easily create your own using copper tape, aluminum foil, or metallic coins soldered to jumper wires).
* Output (Visual): 1x Standard 5mm Status LED (e.g., Red or Green) and 1x 220Ω to 330Ω current-limiting resistor.
* Output (Audio): 1x Piezo buzzer (passive type preferred for variable tones, though an active buzzer will work for simple beeps).
* Prototyping: 1x Solderless breadboard and assorted male-to-male jumper wires.

Hardware Setup Note: Ensure your computer has the appropriate USB-to-UART bridge drivers installed (typically CP210x or CH34x, depending on the manufacturer of your ESP32 DevKitC) so that PlatformIO can communicate with the board.

Setup/Connection

The ESP32 features dedicated internal touch-sensing hardware on several GPIO pins. These pins measure the capacitance of the connected circuit. When a human finger touches the pad, the capacitance changes, which the ESP32 detects as a drop in the raw analog value.

Because the ESP32 handles the capacitance measurement internally, you do not need external pull-up or pull-down resistors for the touch pads. Connect the components according to the table below.

Pin Mapping Table

Component ESP32 DevKitC Pin Details & Connections
Touch Pad 1 (Key 1) GPIO 4 (Touch 0) Connect directly to the metallic pad/coin.
Touch Pad 2 (Key 2) GPIO 2 (Touch 2) Connect directly to the metallic pad/coin.
Touch Pad 3 (Key 3) GPIO 15 (Touch 3) Connect directly to the metallic pad/coin.
Status LED Anode (+) GPIO 21 Connect via a 220Ω resistor to GPIO 21.
Status LED Cathode (-) GND Connect directly to the ESP32 Ground (GND) pin.
Piezo Buzzer (+) GPIO 22 Connect to GPIO 22.
Piezo Buzzer (-) GND Connect to the ESP32 Ground (GND) pin.

Constructing the Touch Pads: If you do not have commercial touch pads, cut three identical squares of copper tape or use three identical coins. Solder or firmly tape a jumper wire to each. Space them at least 2 centimeters apart on your desk or breadboard to prevent cross-capacitance (where touching one pad accidentally triggers an adjacent one).

Validated Code

The following files constitute the complete, compilable project. The project is managed via PlatformIO.

platformio.ini

Create or overwrite the platformio.ini file in the root of your project directory with the following configuration. This ensures the correct board and framework are targeted.

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200

src/main.cpp

Create or overwrite the main.cpp file in your src directory with the following code. The logic implements a non-blocking state machine, handles touch debouncing, and manages the access validation sequence.

Public preview of the validated file. The complete source is shown to members and in PDF/Print.

#include <Arduino.h>

// --------------------------------------------------------
// Pin Definitions
// --------------------------------------------------------
const int TOUCH_PAD_1 = 4;  // GPIO 4  (Touch 0)
const int TOUCH_PAD_2 = 2;  // GPIO 2  (Touch 2)
const int TOUCH_PAD_3 = 15; // GPIO 15 (Touch 3)
const int LED_PIN     = 21; // Status LED
const int BUZZER_PIN  = 22; // Piezo Buzzer

// --------------------------------------------------------
// System Configuration & Thresholds
// --------------------------------------------------------
// A typical untouched ESP32 pin reads ~50-80. 
// A touched pin drops below 20. Adjust this if your pads differ.
const int TOUCH_THRESHOLD = 30; 

// Access Control Sequence Configuration
const int SEQUENCE_LENGTH = 4;
const int SECRET_PIN[SEQUENCE_LENGTH] = {1, 2, 3, 2}; // The correct access code
int inputSequence[SEQUENCE_LENGTH];
int inputIndex = 0;

// State Machine Variables
enum SystemState { LOCKED, INPUTTING, UNLOCKED };
SystemState currentState = LOCKED;

unsigned long unlockTimestamp = 0;
const unsigned long UNLOCK_DURATION = 5000; // Keep unlocked for 5 seconds

// Debouncing Variables
bool pad1_wasTouched = false;
bool pad2_wasTouched = false;
bool pad3_wasTouched = false;

// --------------------------------------------------------
// Function Prototypes
// --------------------------------------------------------
void processTouch();
void handleKeyPress(int keyNumber);
void evaluateSequence();
void triggerSuccess();
void triggerFailure();
void lockSystem();
void playTone(int frequency, int duration);

// --------------------------------------------------------
// Setup
// --------------------------------------------------------
void setup() {
    Serial.begin(115200);
    while (!Serial) { delay(10); } // Wait for serial connection

    Serial.println("\n--- Capacitive Touch Access Panel Initialized ---");

    pinMode(LED_PIN, OUTPUT);
    pinMode(BUZZER_PIN, OUTPUT);

    lockSystem(); // Ensure system starts in locked state
}

// --------------------------------------------------------
// Main Loop
// --------------------------------------------------------
void loop() {
    // Handle state timeouts (Auto-lock)
    if (currentState == UNLOCKED) {
        if (millis() - unlockTimestamp >= UNLOCK_DURATION) {
            Serial.println("Auto-locking system due to timeout.");
            lockSystem();
        }
    } else {
        // Only process touch inputs if the system is not currently unlocked
        processTouch();
    }

    // Small delay to yield to the underlying RTOS
    delay(10); 
}

// --------------------------------------------------------
// Touch Processing & Debouncing
// --------------------------------------------------------
void processTouch() {
    // Read raw capacitance values
    int val1 = touchRead(TOUCH_PAD_1);
    int val2 = touchRead(TOUCH_PAD_2);
    int val3 = touchRead(TOUCH_PAD_3);

    // Evaluate Pad 1
    bool pad1_isTouched = (val1 < TOUCH_THRESHOLD);
    if (pad1_isTouched && !pad1_wasTouched) {
        handleKeyPress(1);
    }
    pad1_wasTouched = pad1_isTouched;

    // Evaluate Pad 2
    bool pad2_isTouched = (val2 < TOUCH_THRESHOLD);
    if (pad2_isTouched && !pad2_wasTouched) {
        handleKeyPress(2);
    }
// ... continues for members in the complete validated source ...

🔒 Part of the validated code is premium. With the 7-day pass or the monthly membership you can view the complete validated source.

#include <Arduino.h>

// --------------------------------------------------------
// Pin Definitions
// --------------------------------------------------------
const int TOUCH_PAD_1 = 4;  // GPIO 4  (Touch 0)
const int TOUCH_PAD_2 = 2;  // GPIO 2  (Touch 2)
const int TOUCH_PAD_3 = 15; // GPIO 15 (Touch 3)
const int LED_PIN     = 21; // Status LED
const int BUZZER_PIN  = 22; // Piezo Buzzer

// --------------------------------------------------------
// System Configuration & Thresholds
// --------------------------------------------------------
// A typical untouched ESP32 pin reads ~50-80. 
// A touched pin drops below 20. Adjust this if your pads differ.
const int TOUCH_THRESHOLD = 30; 

// Access Control Sequence Configuration
const int SEQUENCE_LENGTH = 4;
const int SECRET_PIN[SEQUENCE_LENGTH] = {1, 2, 3, 2}; // The correct access code
int inputSequence[SEQUENCE_LENGTH];
int inputIndex = 0;

// State Machine Variables
enum SystemState { LOCKED, INPUTTING, UNLOCKED };
SystemState currentState = LOCKED;

unsigned long unlockTimestamp = 0;
const unsigned long UNLOCK_DURATION = 5000; // Keep unlocked for 5 seconds

// Debouncing Variables
bool pad1_wasTouched = false;
bool pad2_wasTouched = false;
bool pad3_wasTouched = false;

// --------------------------------------------------------
// Function Prototypes
// --------------------------------------------------------
void processTouch();
void handleKeyPress(int keyNumber);
void evaluateSequence();
void triggerSuccess();
void triggerFailure();
void lockSystem();
void playTone(int frequency, int duration);

// --------------------------------------------------------
// Setup
// --------------------------------------------------------
void setup() {
    Serial.begin(115200);
    while (!Serial) { delay(10); } // Wait for serial connection

    Serial.println("\n--- Capacitive Touch Access Panel Initialized ---");

    pinMode(LED_PIN, OUTPUT);
    pinMode(BUZZER_PIN, OUTPUT);

    lockSystem(); // Ensure system starts in locked state
}

// --------------------------------------------------------
// Main Loop
// --------------------------------------------------------
void loop() {
    // Handle state timeouts (Auto-lock)
    if (currentState == UNLOCKED) {
        if (millis() - unlockTimestamp >= UNLOCK_DURATION) {
            Serial.println("Auto-locking system due to timeout.");
            lockSystem();
        }
    } else {
        // Only process touch inputs if the system is not currently unlocked
        processTouch();
    }

    // Small delay to yield to the underlying RTOS
    delay(10); 
}

// --------------------------------------------------------
// Touch Processing & Debouncing
// --------------------------------------------------------
void processTouch() {
    // Read raw capacitance values
    int val1 = touchRead(TOUCH_PAD_1);
    int val2 = touchRead(TOUCH_PAD_2);
    int val3 = touchRead(TOUCH_PAD_3);

    // Evaluate Pad 1
    bool pad1_isTouched = (val1 < TOUCH_THRESHOLD);
    if (pad1_isTouched && !pad1_wasTouched) {
        handleKeyPress(1);
    }
    pad1_wasTouched = pad1_isTouched;

    // Evaluate Pad 2
    bool pad2_isTouched = (val2 < TOUCH_THRESHOLD);
    if (pad2_isTouched && !pad2_wasTouched) {
        handleKeyPress(2);
    }
    pad2_wasTouched = pad2_isTouched;

    // Evaluate Pad 3
    bool pad3_isTouched = (val3 < TOUCH_THRESHOLD);
    if (pad3_isTouched && !pad3_wasTouched) {
        handleKeyPress(3);
    }
    pad3_wasTouched = pad3_isTouched;
}

// --------------------------------------------------------
// Logic Handling
// --------------------------------------------------------
void handleKeyPress(int keyNumber) {
    // Provide immediate acoustic feedback
    playTone(1000, 100); 

    Serial.print("Key Pressed: ");
    Serial.println(keyNumber);

    // Update state
    currentState = INPUTTING;

    // Store the input
    inputSequence[inputIndex] = keyNumber;
    inputIndex++;

    // Check if we have collected enough inputs
    if (inputIndex >= SEQUENCE_LENGTH) {
        evaluateSequence();
    }
}

void evaluateSequence() {
    Serial.println("Evaluating entered sequence...");
    bool isMatch = true;

    for (int i = 0; i < SEQUENCE_LENGTH; i++) {
        if (inputSequence[i] != SECRET_PIN[i]) {
            isMatch = false;
            break;
        }
    }

    if (isMatch) {
        triggerSuccess();
    } else {
        triggerFailure();
    }

    // Reset input index for the next attempt
    inputIndex = 0;
}

// --------------------------------------------------------
// Output & Feedback Generators
// --------------------------------------------------------
void triggerSuccess() {
    Serial.println("ACCESS GRANTED.");
    currentState = UNLOCKED;
    unlockTimestamp = millis();

    // Visual indicator: LED ON
    digitalWrite(LED_PIN, HIGH);

    // Acoustic indicator: Success Melody
    playTone(1200, 150);
    delay(50);
    playTone(1500, 150);
    delay(50);
    playTone(2000, 300);
}

void triggerFailure() {
    Serial.println("ACCESS DENIED. Incorrect PIN.");

    // Acoustic indicator: Error Tone
    playTone(300, 400);
    delay(100);
    playTone(300, 400);

    // Return to locked state immediately
    lockSystem();
}

void lockSystem() {
    currentState = LOCKED;
    inputIndex = 0; // Clear any partial inputs
    digitalWrite(LED_PIN, LOW); // LED OFF indicates locked
    Serial.println("System LOCKED. Ready for input.");
}

// Helper function for the buzzer
void playTone(int frequency, int duration) {
    tone(BUZZER_PIN, frequency, duration);
    // The tone function in Arduino is non-blocking, but for this HMI 
    // we want the beep to complete before proceeding in feedback sequences.
    delay(duration); 
}

Build/Flash/Run commands

To compile, upload, and monitor the project, open the terminal in Visual Studio Code (Terminal -> New Terminal) and ensure you are in the root directory of your project (where platformio.ini is located).

Use the following commands:

Command Action
pio run Compiles the C++ source code and checks for syntax/linking errors.
pio run --target upload Compiles and flashes the compiled firmware to the ESP32 DevKitC.
pio device monitor Opens the serial monitor to view real-time logs from the ESP32.

Numbered Workflow:
1. Connect the ESP32 DevKitC to your computer via USB.
2. Execute pio run to verify the code compiles cleanly.
3. Execute pio run --target upload to flash the board. (Note: On some ESP32 DevKitC models, you may need to hold down the “BOOT” button on the board when the terminal displays “Connecting…” to allow the flash process to begin).
4. Execute pio device monitor to interact with the device and view the serial output.

Step-by-step Validation

Perform the following physical checks while observing the serial monitor to validate the prototype’s functionality.

  • Checkpoint 1: Baseline Initialization
    • Action: Reset the ESP32 (press the EN button) while observing the serial monitor.
    • Expected Observation: The serial monitor prints “— Capacitive Touch Access Panel Initialized —” followed by “System LOCKED. Ready for input.” The status LED should remain off.
    • Pass Condition: Clean boot sequence with no boot loops or crashes.
  • Checkpoint 2: Single Touch Detection & Debounce
    • Action: Firmly tap Touch Pad 1 once and release it immediately.
    • Expected Observation: The buzzer emits a short 100ms beep. The serial monitor logs “Key Pressed: 1”.
    • Pass Condition: Only a single press is registered per physical tap. If multiple presses register, the TOUCH_THRESHOLD may need adjustment.
  • Checkpoint 3: Incorrect Sequence Rejection
    • Action: Tap the pads in an incorrect sequence (e.g., Pad 1, Pad 1, Pad 1, Pad 1).
    • Expected Observation: Upon the 4th tap, the serial monitor logs “Evaluating entered sequence…” followed by “ACCESS DENIED. Incorrect PIN.” The buzzer plays two low, long error tones. The LED remains off.
    • Pass Condition: The system correctly identifies a mismatch and returns to the “System LOCKED” state.
  • Checkpoint 4: Correct Sequence Authorization
    • Action: Tap the pads in the correct sequence defined in the code (Pad 1, Pad 2, Pad 3, Pad 2).
    • Expected Observation: The serial monitor logs “ACCESS GR

Find this product and/or books on this topic on Amazon

Go to Amazon

As an Amazon Associate, I earn from qualifying purchases. If you buy through this link, you help keep this project running.

Quick Quiz

Question 1: What is the primary objective of the project described in the article?




Question 2: Which microcontroller is utilized for its built-in capacitive touch sensing in this project?




Question 3: Why are wear-free interfaces considered ideal for high-traffic access panels?




Question 4: What type of feedback is integrated to ensure users know their input was registered?




Question 5: What is the target response latency for the integrated user feedback?




Question 6: What software mechanism is used to manage asynchronous human input without halting the microcontroller?




Question 7: What does the non-blocking state machine instantly reject according to the expected outcomes?




Question 8: What type of debouncing is utilized alongside the ESP32's internal capacitive hardware?




Question 9: Which of the following environments is explicitly mentioned as ideal for wear-free interfaces?




Question 10: What fundamental logic is demonstrated for frontline commercial security systems?




Carlos Núñez Zorrilla
Carlos Núñez Zorrilla
Electronics & Computer Engineer

Telecommunications Electronics Engineer and Computer Engineer (official degrees in Spain).

Follow me:


Practical case: ESP32 BLE Presence Beacon

Practical case: ESP32 BLE Presence Beacon — hero

Objective and use case

What you’ll build: A standalone Bluetooth Low Energy (BLE) room presence beacon that broadcasts occupancy status, toggled via a physical pushbutton and displayed locally via a status LED.

Why it matters / Use cases

  • Meeting room & facility management: Detects if conference rooms, phone booths, or restrooms are occupied without complex wired sensor networks.
  • Privacy control: Acts as a digital “Do Not Disturb” sign for personal offices or recording studios, broadcasting status to nearby smartphones or BLE gateway hubs.
  • Low-power connectionless architecture: Utilizes BLE advertisement payloads for state broadcasting, allowing infinite passive scanners to read data simultaneously without the power overhead of establishing formal BLE GATT connections.

Expected outcome

  • The ESP32 successfully initializes a BLE server and continuously broadcasts connectionless state payloads.
  • Pressing the hardware button instantly toggles the local LED and updates the BLE advertisement packet with sub-100ms latency.
  • Remote dashboards or BLE hubs accurately track room availability simply by listening to the passive BLE advertisements.

Audience: IoT Developers, Smart Building Engineers; Level: Intermediate

Architecture/flow: Physical Pushbutton → ESP32 GPIO Interrupt → Update State → Toggle Local LED & Modify BLE Advertisement Payload → Passive Broadcast to BLE Scanners.

Educational validation note

Before publication, this case passed the Prometeo automated validation gate with status PASS. For this ESP32 DevKitC profile, the project was checked as a PlatformIO project: the validator extracted platformio.ini and src/main.cpp, created a temporary project and ran pio run against platform = espressif32, board = esp32dev and framework = arduino. It also checked article structure, copy/paste-safe ASCII command options, and unsupported stacks such as direct ESP-IDF or non-scoped ESP32 boards.

Published validation evidence

  • Automatic result: PASS.
  • Parsed structure: 3 sections, 4 tables and 2 code blocks detected before publication.
  • Checked code: 1 PlatformIO config + 1 ESP32 source/pio run.
  • Supported catalog: the article text was checked against Prometeo’s validation-capable device profiles, and unsupported stacks block publication.
  • Report findings: no blocking findings.

This validation confirms syntax and tool compatibility for the published code, but it does not replace physical testing on your exact ESP32 DevKitC board, wiring, power supply and local WiFi environment.

Educational safety note

This project is an educational prototype, not a certified product. Before powering the setup, verify the pinout of your exact ULX3S board revision, keep FPGA I/O signals at 3.3 V, never connect 5 V directly to I/O pins, disconnect power before changing wiring, and use suitable external supplies for loads, motors or servos while sharing ground only when the wiring requires it.

Conceptual block diagram

High-level view: what enters the system, what each block processes, and what comes out.

Functional architecture

Physical Pushbutton

ESP32 GPIO Interrupt

Update State

Toggle Local LED & Modify BLE Advertiseme…

Passive Broadcast to BLE Scanners

Conceptual signal and responsibility flow between device blocks.

Validation path

Source code

PlatformIO build

Flash

Serial monitor

Conceptual summary of the tools used to check the published material.

Prerequisites

Before beginning this practical case, ensure you have the following ready:
* A basic understanding of C++ programming and microcontroller GPIO logic (input/output).
* Visual Studio Code installed on your computer with the PlatformIO IDE extension enabled.
* A smartphone (Android or iOS) with a BLE scanning application installed. We recommend LightBlue or BLE Scanner.
* The appropriate USB drivers for your ESP32 board installed on your host OS (typically CP210x or CH34x drivers, depending on the specific DevKitC manufacturer).

Materials

Component Description / Exact Model Quantity
Microcontroller Core ESP32 DevKitC + pushbutton/contact input + status LED 1
Resistor 330 Ω (Ohm) resistor (for the status LED current limiting) 1
Breadboard Standard 400-tie or 830-tie solderless breadboard 1
Jumper Wires Assorted male-to-male Dupont jumper wires 4-6
USB Cable Micro-USB or USB-C cable (data-capable, matching your DevKitC) 1

(Note: The “ESP32 DevKitC + pushbutton/contact input + status LED” constitutes the complete logical device model for this prototype. The pushbutton and LED may be discrete components placed on the breadboard or integrated into a custom carrier board).

Setup/Connection

This project requires wiring a physical pushbutton to act as our contact input and an external LED to act as our status indicator. We will use the ESP32’s internal pull-up resistor for the pushbutton to simplify wiring and reduce component count.

Wiring Logic

  1. Pushbutton: Connect one terminal of the normally-open pushbutton to GPIO 4. Connect the opposite terminal directly to one of the ESP32’s GND pins. When the button is pressed, it bridges GPIO 4 to Ground, creating a LOW signal. The ESP32’s internal pull-up resistor keeps the pin HIGH when unpressed.
  2. Status LED: Connect the anode (longer leg) of the LED to GPIO 5. Connect the cathode (shorter leg) to one end of the 330 Ω resistor. Connect the other end of the resistor to the ESP32’s GND.

Pinout Reference Table

Component Terminal ESP32 DevKitC Pin Signal Type Description
Pushbutton Terminal 1 GPIO 4 Digital Input Toggles room status (uses internal pull-up)
Pushbutton Terminal 2 GND Power (Ground) Pulls GPIO 4 LOW when pressed
Status LED Anode (+) GPIO 5 Digital Output Illuminates when room is “Occupied”
Status LED Cathode (-) GND (via 330Ω) Power (Ground) Current return path

Validated Code

The following code files are structured for the PlatformIO environment. The project requires two main files: platformio.ini for the build configuration and src/main.cpp for the application logic.

platformio.ini

Create or overwrite the platformio.ini file in the root of your PlatformIO project with the following configuration. This sets up the ESP32 DevKitC environment and specifies the serial monitor speed.

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200
; Force the use of standard C++11 and optimize for size
build_flags = 
    -std=gnu++11
    -Os

src/main.cpp

Create or overwrite the main.cpp file inside the src directory. This code implements a non-blocking debounce algorithm for the pushbutton and dynamically updates the BLE advertising payload without requiring a full device reset.

Public preview of the validated file. The complete source is shown to members and in PDF/Print.

/**
 * BLE Room Presence Beacon
 * Device: ESP32 DevKitC + pushbutton/contact input + status LED
 * Framework: Arduino via PlatformIO
 */

#include <Arduino.h>
#include <BLEDevice.h>
#include <BLEUtils.h>
#include <BLEServer.h>

// Hardware Pin Definitions
#define BUTTON_PIN 4
#define LED_PIN 5

// State Machine Variables
bool isOccupied = false;
int buttonState = HIGH;
int lastReading = HIGH;

// Non-blocking Debounce Variables
unsigned long lastDebounceTime = 0;
const unsigned long debounceDelay = 50; // 50 milliseconds

// BLE Global Pointer
BLEAdvertising *pAdvertising;

/**
 * Updates the BLE Advertisement payload based on the current room state.
 * Connectionless BLE requires us to stop advertising, update the payload,
 * and then restart advertising so scanners see the new data immediately.
 */
void updateBLEAdvertisement() {
    if (pAdvertising != nullptr) {
        pAdvertising->stop();
    }

    BLEAdvertisementData oAdvertisementData = BLEAdvertisementData();

    // Set standard BLE flags. 
    // 0x04 = BR_EDR_NOT_SUPPORTED (Indicates this is a BLE-only device)
    oAdvertisementData.setFlags(0x04); 

    // Dynamically change the advertised device name based on state.
    // This allows scanners to know the room status without connecting.
    if (isOccupied) {
        oAdvertisementData.setName("ROOM_INUSE");
    } else {
        oAdvertisementData.setName("ROOM_AVAIL");
    }

    pAdvertising->setAdvertisementData(oAdvertisementData);
    pAdvertising->start();
}

void setup() {
    // Initialize Serial Monitor for debugging
    Serial.begin(115200);
    while (!Serial) {
        ; // Wait for serial port to connect
    }
// ... continues for members in the complete validated source ...

🔒 Part of the validated code is premium. With the 7-day pass or the monthly membership you can view the complete validated source.

/**
 * BLE Room Presence Beacon
 * Device: ESP32 DevKitC + pushbutton/contact input + status LED
 * Framework: Arduino via PlatformIO
 */

#include <Arduino.h>
#include <BLEDevice.h>
#include <BLEUtils.h>
#include <BLEServer.h>

// Hardware Pin Definitions
#define BUTTON_PIN 4
#define LED_PIN 5

// State Machine Variables
bool isOccupied = false;
int buttonState = HIGH;
int lastReading = HIGH;

// Non-blocking Debounce Variables
unsigned long lastDebounceTime = 0;
const unsigned long debounceDelay = 50; // 50 milliseconds

// BLE Global Pointer
BLEAdvertising *pAdvertising;

/**
 * Updates the BLE Advertisement payload based on the current room state.
 * Connectionless BLE requires us to stop advertising, update the payload,
 * and then restart advertising so scanners see the new data immediately.
 */
void updateBLEAdvertisement() {
    if (pAdvertising != nullptr) {
        pAdvertising->stop();
    }

    BLEAdvertisementData oAdvertisementData = BLEAdvertisementData();

    // Set standard BLE flags. 
    // 0x04 = BR_EDR_NOT_SUPPORTED (Indicates this is a BLE-only device)
    oAdvertisementData.setFlags(0x04); 

    // Dynamically change the advertised device name based on state.
    // This allows scanners to know the room status without connecting.
    if (isOccupied) {
        oAdvertisementData.setName("ROOM_INUSE");
    } else {
        oAdvertisementData.setName("ROOM_AVAIL");
    }

    pAdvertising->setAdvertisementData(oAdvertisementData);
    pAdvertising->start();
}

void setup() {
    // Initialize Serial Monitor for debugging
    Serial.begin(115200);
    while (!Serial) {
        ; // Wait for serial port to connect
    }
    Serial.println("Initializing BLE Room Presence Beacon...");

    // Configure GPIO Pins
    pinMode(BUTTON_PIN, INPUT_PULLUP);
    pinMode(LED_PIN, OUTPUT);

    // Set initial hardware state
    digitalWrite(LED_PIN, LOW); // LED OFF = Available

    // Initialize the BLE environment with a default name
    BLEDevice::init("ROOM_AVAIL");
    pAdvertising = BLEDevice::getAdvertising();

    // Apply our custom advertisement data and start broadcasting
    updateBLEAdvertisement();

    Serial.println("Initialization Complete. Broadcasting as ROOM_AVAIL.");
}

void loop() {
    // Read the current physical state of the pushbutton
    int reading = digitalRead(BUTTON_PIN);

    // If the switch changed (due to noise or pressing)
    if (reading != lastReading) {
        lastDebounceTime = millis(); // Reset the debouncing timer
    }

    // Whatever the reading is at, it's been there for longer than the debounce delay,
    // so take it as the actual current state.
    if ((millis() - lastDebounceTime) > debounceDelay) {

        // If the button state has truly changed
        if (reading != buttonState) {
            buttonState = reading;

            // Only toggle the room state when the button is actively PRESSED (transition to LOW)
            if (buttonState == LOW) {
                isOccupied = !isOccupied;

                // Update the physical Status LED
                digitalWrite(LED_PIN, isOccupied ? HIGH : LOW);

                // Update the BLE Advertisement Payload
                updateBLEAdvertisement();

                // Print to Serial Monitor for validation
                Serial.print("State toggled! Room is now: ");
                Serial.println(isOccupied ? "OCCUPIED" : "AVAILABLE");
            }
        }
    }

    // Save the reading. Next time through the loop, it'll be the lastReading.
    lastReading = reading;
}

Build/Flash/Run commands

Use the PlatformIO Command Line Interface (CLI) to compile, upload, and monitor the ESP32. Ensure your terminal is open in the root directory of your project (where platformio.ini is located).

Action Command
Build Project pio run
Upload to ESP32 pio run --target upload
Open Serial Monitor pio device monitor

Execution Workflow:
1. Connect the ESP32 DevKitC to your computer via USB.
2. Run pio run to download the Espressif framework dependencies and compile the C++ source code. Ensure the build succeeds without errors.
3. Run pio run --target upload to flash the compiled firmware to the microcontroller.
4. Run pio device monitor to view the serial output. You should immediately see “Initializing BLE Room Presence Beacon…” followed by “Initialization Complete.”

Step-by-step Validation

To prove the system is functioning correctly, follow these structured checkpoints.

  1. Initial Power-Up and Serial Log Check
    • Action: Observe the terminal output after running pio device monitor.
    • Expected Observation: The terminal prints “Initialization Complete. Broadcasting as ROOM_AVAIL.”
    • Pass Condition: The ESP32 boots without kernel panics or boot loops, confirming the BLE stack initialized successfully.
  2. Hardware State Toggling
    • Action: Press the physical pushbutton once.
    • Expected Observation: The status LED illuminates. The serial monitor prints “State toggled! Room is now: OCCUPIED”.
    • Pass Condition: The non-blocking debounce logic correctly registers exactly one state change per physical press, and the LED reflects the isOccupied boolean.
  3. BLE Connectionless Advertisement Check (Available)
    • Action: Open your smartphone BLE scanner app (e.g., LightBlue). Clear the cache/refresh the scan list. Ensure the ESP32 LED is OFF.
    • Expected Observation: A device named “ROOM_AVAIL” appears in the scanner list.
    • Pass Condition: The smartphone successfully receives the advertisement packets containing the default name.
  4. Dynamic Payload Update Check (Occupied)
    • Action: Press the pushbutton on the ESP32 so the status LED turns ON. In the smartphone app, refresh the scan list.
    • Expected Observation: The device named “ROOM_AVAIL” disappears, and a new device named “ROOM_INUSE” appears (often with the same MAC address).
    • Pass Condition: The ESP32 successfully stopped the BLE server, updated the advertisement payload, and restarted broadcasting, proving dynamic connectionless state transmission.

Troubleshooting

Symptom Likely Cause Fix
Firmware upload fails with “Permission denied” or “COM port not found” Missing USB driver or insufficient OS permissions to access the serial port. Install CP210x/CH34x drivers. On Linux, add your user to the dialout group using sudo usermod -a -G dialout $USER.
Button press registers multiple times (double-toggling) Hardware switch bounce exceeding the software debounce delay window. Increase debounceDelay in main.cpp from 50 to 100 or 150 milliseconds.
Status LED never turns on LED polarity is reversed, or wired to the wrong GPIO pin. Ensure the longer leg (anode) goes to GPIO 5 and the shorter leg (cathode) goes to GND via the resistor.
Smartphone app does not see the name change The scanner app is caching the old BLE device name based on the MAC address. Force a hard refresh in the app, or restart the smartphone’s Bluetooth radio to clear the local BLE cache.

Improvements

Once the basic prototype is functioning, consider implementing the following architectural and hardware improvements to create a more robust device:

  • Power Management & Battery Operation:
    • Deep Sleep Integration: Instead of running the loop() continuously, configure the ESP32 to enter Deep Sleep. Use the ext0 wake-up source tied to the pushbutton. Upon waking, broadcast the new state for 5 seconds, then return to sleep. This reduces power consumption from ~100mA to ~10µA, allowing months of operation on a LiPo battery. Validation method: To verify this performance claim, place a digital multimeter in series with the ESP32 power supply to measure the current draw during the deep sleep phase; you should observe a drop to approximately 10µA to 15µA depending on the specific DevKitC’s onboard voltage regulator and USB-to-UART bridge.
    • Status LED Timeout: Instead of keeping the LED permanently illuminated when occupied, pulse it briefly every 10 seconds or turn it off entirely after a minute to save power.
  • Data Structure & Payload Efficiency:
    • Manufacturer Specific Data: Instead of changing the device name (which is heavily cached by iOS and Android), encode the occupancy state as a custom byte in the Manufacturer Specific Data field of the advertisement packet. This allows scanners to parse the exact state without relying on string comparisons and avoids OS-level name caching issues entirely.

Find this product and/or books on this topic on Amazon

Go to Amazon

As an Amazon Associate, I earn from qualifying purchases. If you buy through this link, you help keep this project running.

Quick Quiz

Question 1: What is the primary function of the device being built in this project?




Question 2: How is the occupancy status toggled locally on the device?




Question 3: What does the low-power connectionless architecture utilize for state broadcasting?




Question 4: Why is the connectionless architecture beneficial for this beacon?




Question 5: What happens instantly when the hardware button is pressed?




Question 6: What is the expected latency for updating the BLE advertisement packet after a button press?




Question 7: How do remote dashboards or BLE hubs track room availability?




Question 8: What microcontroller is mentioned for initializing the BLE server?




Question 9: What is one of the mentioned use cases for this BLE beacon?




Question 10: Why does the device avoid establishing formal BLE GATT connections?




Carlos Núñez Zorrilla
Carlos Núñez Zorrilla
Electronics & Computer Engineer

Telecommunications Electronics Engineer and Computer Engineer (official degrees in Spain).

Follow me:


Practical case: ESP32 Soil Moisture Monitor

Practical case: ESP32 Soil Moisture Monitor — hero

Objective and use case

What you’ll build: A continuous plant hydration monitor that measures soil moisture using an analog capacitive sensor, triggering local visual and audible alerts when watering is required.

Why it matters / Use cases

  • Agricultural prototyping: Serves as a foundational data-collection node for automated greenhouse irrigation systems, ensuring plants receive water based on objective metrics rather than schedules.
  • Hardware longevity: Demonstrates the practical advantage of capacitive sensing over legacy resistive sensors, eliminating rapid galvanic corrosion and soil contamination.
  • Preventing plant stress: Replaces guesswork with empirical, real-time soil dielectric measurements to prevent both overwatering (root rot) and underwatering.
  • Signal processing: Provides a tangible application for mapping raw, non-linear 12-bit Analog-to-Digital Converter (ADC) values into intuitive 0–100% moisture metrics.

Expected outcome

  • Continuous real-time serial output displaying both raw 12-bit ADC values (0–4095) and calculated moisture percentages (0–100%) at a ~1Hz polling rate.
  • Immediate visual alert (status LED illumination) and audible cues triggered within milliseconds of the moisture level dropping below the defined threshold.

Audience: IoT hobbyists and embedded developers; Level: Beginner to Intermediate

Architecture/flow: Capacitive Soil Sensor → Microcontroller ADC (12-bit analog read) → Moisture Percentage Mapping → GPIO Output (LED/Buzzer) & Serial Monitor

Educational validation note

Before publication, this case passed the Prometeo automated validation gate with status PASS. For this ESP32 DevKitC profile, the project was checked as a PlatformIO project: the validator extracted platformio.ini and src/main.cpp, created a temporary project and ran pio run against platform = espressif32, board = esp32dev and framework = arduino. It also checked article structure, copy/paste-safe ASCII command options, and unsupported stacks such as direct ESP-IDF or non-scoped ESP32 boards.

Published validation evidence

  • Automatic result: PASS.
  • Parsed structure: 3 sections, 2 tables and 2 code blocks detected before publication.
  • Checked code: 1 PlatformIO config + 1 ESP32 source/pio run.
  • Supported catalog: the article text was checked against Prometeo’s validation-capable device profiles, and unsupported stacks block publication.
  • Report findings: no blocking findings.

This validation confirms syntax and tool compatibility for the published code, but it does not replace physical testing on your exact ESP32 DevKitC board, wiring, power supply and local WiFi environment.

Educational safety note

This project is an educational prototype, not a certified product. Before powering the setup, verify the pinout of your exact ULX3S board revision, keep FPGA I/O signals at 3.3 V, never connect 5 V directly to I/O pins, disconnect power before changing wiring, and use suitable external supplies for loads, motors or servos while sharing ground only when the wiring requires it.

Conceptual block diagram

High-level view: what enters the system, what each block processes, and what comes out.

Functional architecture

ULX3S buttons

Sync/debounce

Mode selector

20 ms period generator

Pulse-width comparator

50 Hz PWM output

SG90 servo

Conceptual control flow: button input, mode selection, PWM timing and servo motion.

Validation path

Verilog source

Verilator lint/testbench

Yosys synthesis

nextpnr-ecp5

ecppack bitstream

Programmed ULX3S

The automated validation checks syntax, simulation/lint and compatibility with the ULX3S/ECP5 toolchain.

Prerequisites

To successfully complete this tutorial, students should have:
* A basic understanding of the difference between analog signals (continuous voltage levels) and digital signals (binary HIGH/LOW states).
* PlatformIO IDE installed (preferably as a Visual Studio Code extension) or the PlatformIO Core CLI.
* Familiarity with basic breadboarding techniques, including routing power rails and using current-limiting resistors for LEDs.
* Basic C/C++ programming knowledge (variables, if/else conditional logic, and functions).

Materials

You must use the following exact hardware configuration to ensure the provided code and pinouts work without modification:

  • ESP32 DevKitC + capacitive soil moisture sensor v1.2 + status LED + piezo buzzer
  • 1x 330Ω resistor (Color code: Orange-Orange-Brown, used for the status LED to prevent overcurrent).
  • 1x Standard Breadboard (830 tie-points recommended).
  • Assorted Dupont jumper wires (Male-to-Male and Male-to-Female depending on your specific sensor header).
  • 1x Micro-USB or USB-C cable (ensure it is a data-sync cable, not a charge-only cable).
  • A cup of dry soil and a cup of water (for calibration and testing).

Setup/Connection

Proper hardware connection is critical. The ESP32 operates at 3.3V logic levels. The capacitive soil moisture sensor v1.2 includes an onboard voltage regulator, but it is best practice to power it from the ESP32’s 3.3V pin to ensure its analog output never exceeds the ESP32’s maximum ADC input rating (3.3V). Supplying 5V to the sensor could result in analog signals that permanently damage the ESP32’s GPIO pins.

We use GPIO 34 for the analog input. The ESP32 has two internal ADCs. ADC2 is shared with the Wi-Fi radio and cannot be used reliably when Wi-Fi is active. ADC1 (which includes GPIO 34) functions independently of the Wi-Fi stack, making it the standard choice for robust sensor readings.

Wiring Table

Component Component Pin / Lead ESP32 DevKitC Pin Notes
Capacitive Sensor VCC / V+ 3V3 Power via 3.3V to protect ESP32 ADC.
Capacitive Sensor GND / G GND Common ground reference.
Capacitive Sensor AOUT / AU GPIO 34 Connected to ADC1_CH6.
Status LED Anode (Long Leg) GPIO 25 Connect via the 330Ω resistor.
Status LED Cathode (Short Leg) GND Common ground reference.
Piezo Buzzer Positive (+) GPIO 26 Driven via ESP32 hardware PWM (LEDC).
Piezo Buzzer Negative (-) GND Common ground reference.

Hardware Note: The piezo buzzer can be active or passive. The code provided uses a Pulse Width Modulation (PWM) signal, which will generate a specific tone on a passive buzzer, and will also successfully trigger an active buzzer by toggling its power rapidly.

Validated Code

The project uses PlatformIO. You will need to configure your environment file and your main application source file.

platformio.ini

Create or replace the contents of your platformio.ini file with the following configuration:

[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200

src/main.cpp

Copy the following C++ code into your src/main.cpp file. This code implements the continuous analog reading, performs linear interpolation to calculate the moisture percentage, and handles the logic for the hardware alerts.

Public preview of the validated file. The complete source is shown to members and in PDF/Print.

#include <Arduino.h>

// --------------------------------------------------------
// Hardware Pin Definitions
// --------------------------------------------------------
const int MOISTURE_PIN = 34; // ADC1 Channel 6
const int LED_PIN      = 25; // Digital Output for Status LED
const int BUZZER_PIN   = 26; // Digital Output for Piezo Buzzer

// --------------------------------------------------------
// PWM Configuration for Piezo Buzzer
// --------------------------------------------------------
const int PWM_FREQ       = 2000; // 2 kHz audio frequency
const int PWM_CHANNEL    = 0;    // ESP32 Hardware Timer Channel 0
const int PWM_RESOLUTION = 8;    // 8-bit resolution (0-255)

// --------------------------------------------------------
// Calibration Constants
// --------------------------------------------------------
// IMPORTANT: Capacitive sensors output a HIGHER voltage when dry 
// and a LOWER voltage when wet. These values represent the 12-bit 
// ADC readings (0-4095). You must calibrate these for your specific sensor.
const int DRY_VALUE = 3200;  // Expected ADC reading in completely dry air
const int WET_VALUE = 1400;  // Expected ADC reading submerged in water

// --------------------------------------------------------
// Application Logic Constants
// --------------------------------------------------------
const int ALARM_THRESHOLD_PERCENT = 30; // Trigger alert at or below 30% moisture

void setup() {
    // Initialize Serial Communication for debugging
    Serial.begin(115200);

    // Configure Digital Output Pins
    pinMode(LED_PIN, OUTPUT);
    digitalWrite(LED_PIN, LOW); // Ensure LED is off at boot

    // Configure LEDC PWM peripheral for the Buzzer
    // This allows us to generate a clean square wave for a passive piezo
    ledcSetup(PWM_CHANNEL, PWM_FREQ, PWM_RESOLUTION);
    ledcAttachPin(BUZZER_PIN, PWM_CHANNEL);
    ledcWrite(PWM_CHANNEL, 0); // Ensure buzzer is silent at boot

    Serial.println("=========================================");
    Serial.println(" ESP32 Soil Moisture Monitor Initialized ");
    Serial.println("=========================================");

    // Allow hardware to stabilize
    delay(1000); 
}
// ... continues for members in the complete validated source ...

🔒 Part of the validated code is premium. With the 7-day pass or the monthly membership you can view the complete validated source.

#include <Arduino.h>

// --------------------------------------------------------
// Hardware Pin Definitions
// --------------------------------------------------------
const int MOISTURE_PIN = 34; // ADC1 Channel 6
const int LED_PIN      = 25; // Digital Output for Status LED
const int BUZZER_PIN   = 26; // Digital Output for Piezo Buzzer

// --------------------------------------------------------
// PWM Configuration for Piezo Buzzer
// --------------------------------------------------------
const int PWM_FREQ       = 2000; // 2 kHz audio frequency
const int PWM_CHANNEL    = 0;    // ESP32 Hardware Timer Channel 0
const int PWM_RESOLUTION = 8;    // 8-bit resolution (0-255)

// --------------------------------------------------------
// Calibration Constants
// --------------------------------------------------------
// IMPORTANT: Capacitive sensors output a HIGHER voltage when dry 
// and a LOWER voltage when wet. These values represent the 12-bit 
// ADC readings (0-4095). You must calibrate these for your specific sensor.
const int DRY_VALUE = 3200;  // Expected ADC reading in completely dry air
const int WET_VALUE = 1400;  // Expected ADC reading submerged in water

// --------------------------------------------------------
// Application Logic Constants
// --------------------------------------------------------
const int ALARM_THRESHOLD_PERCENT = 30; // Trigger alert at or below 30% moisture

void setup() {
    // Initialize Serial Communication for debugging
    Serial.begin(115200);

    // Configure Digital Output Pins
    pinMode(LED_PIN, OUTPUT);
    digitalWrite(LED_PIN, LOW); // Ensure LED is off at boot

    // Configure LEDC PWM peripheral for the Buzzer
    // This allows us to generate a clean square wave for a passive piezo
    ledcSetup(PWM_CHANNEL, PWM_FREQ, PWM_RESOLUTION);
    ledcAttachPin(BUZZER_PIN, PWM_CHANNEL);
    ledcWrite(PWM_CHANNEL, 0); // Ensure buzzer is silent at boot

    Serial.println("=========================================");
    Serial.println(" ESP32 Soil Moisture Monitor Initialized ");
    Serial.println("=========================================");

    // Allow hardware to stabilize
    delay(1000); 
}

void loop() {
    // 1. Read the raw analog voltage from the sensor
    int rawAdcValue = analogRead(MOISTURE_PIN);

    // 2. Map the raw ADC value to a 0-100 percentage scale.
    // We invert the mapping parameters because DRY is high, WET is low.
    int moisturePercent = map(rawAdcValue, DRY_VALUE, WET_VALUE, 0, 100);

    // 3. Constrain the percentage to strictly 0-100.
    // This prevents negative numbers or values > 100% if the sensor 
    // reads slightly outside the hardcoded calibration range.
    moisturePercent = constrain(moisturePercent, 0, 100);

    // 4. Output telemetry to the Serial Monitor
    Serial.print("Raw ADC: ");
    Serial.print(rawAdcValue);
    Serial.print("\t | Moisture: ");
    Serial.print(moisturePercent);
    Serial.println("%");

    // 5. Evaluate the alert threshold
    if (moisturePercent <= ALARM_THRESHOLD_PERCENT) {
        // Condition: Soil is dangerously dry.
        // Action: Flash the LED and pulse the buzzer.

        digitalWrite(LED_PIN, HIGH);
        // Set PWM duty cycle to 50% (128 out of 255) to generate sound
        ledcWrite(PWM_CHANNEL, 128); 
        delay(500); // Wait 500ms

        digitalWrite(LED_PIN, LOW);
        // Set PWM duty cycle to 0% to silence buzzer
        ledcWrite(PWM_CHANNEL, 0);   
        delay(500); // Wait 500ms

    } else {
        // Condition: Soil moisture is adequate.
        // Action: Keep alerts turned off and delay before next reading.

        digitalWrite(LED_PIN, LOW);
        ledcWrite(PWM_CHANNEL, 0);
        delay(1000); // Poll sensor once per second
    }
}

Build/Flash/Run commands

To compile, upload, and monitor the code on your ESP32 DevKitC, use the PlatformIO CLI. Open your terminal in the root directory of your project (where platformio.ini is located) and execute the following commands.

Command Reference

Action Command Purpose
Build pio run Compiles the C++ source code and links the Arduino framework.
Upload pio run --target upload Flashes the compiled firmware binary to the ESP32.
Monitor pio device monitor Opens the serial monitor to view the telemetry output.

Execution Workflow

  1. Connect the ESP32 DevKitC to your computer via the USB cable. Ensure the CP210x or CH34x drivers are installed if your OS does not recognize the device automatically.
  2. Run pio run to verify that there are no syntax errors and that the environment is configured correctly.
  3. Run pio run --target upload to flash the device. If the terminal displays “Connecting…” and stalls, you may need to press and hold the “BOOT” button on the ESP32 DevKitC until the flashing process begins.
  4. Run pio device monitor to observe the serial output. You should immediately see the initialization banner followed by continuous ADC readings.

Step-by-step Validation

Follow these checkpoints to ensure your prototype is fully functional and correctly calibrated.

  1. Serial Communication Check:
    • Action: Open the serial monitor after flashing.
    • Expected Observation: The console prints “ESP32 Soil Moisture Monitor Initialized” followed by data lines every second.
    • Pass Condition: Text is legible (no garbled characters), confirming the 115200 baud rate is correct.
  2. Dry Air Baseline (0% Calibration):
    • Action: Hold the sensor in the open air, touching nothing.
    • Expected Observation: The Raw ADC value stabilizes (e.g., around 3100 to 3300).
    • Pass Condition: Note this number. Update the DRY_VALUE constant in the code to match this reading and re-flash the ESP32 if it deviates by more than 100 from the default.
  3. Water Submersion (100% Calibration):
    • Action: Submerge the capacitive sensor in a glass of water up to the marked safety line.
    • Expected Observation: The Raw ADC value drops significantly and stabilizes (e.g., around 1400).
    • Pass Condition: The serial monitor outputs 100%. Update the WET_VALUE constant in the code and re-flash if it does not reach 100%.
  4. Alert Logic Verification:
    • Action: Slowly remove the sensor from the water and wipe it completely dry.
    • Expected Observation: The moisture percentage drops. Once it hits 30% or lower, the LED flashes and the buzzer emits a 2000 Hz tone.
    • Pass Condition: Visual and audible alerts trigger synchronously exactly when the moisture reads <= 30%, verifying the logic threshold is functioning safely.

Find this product and/or books on this topic on Amazon

Go to Amazon

As an Amazon Associate, I earn from qualifying purchases. If you buy through this link, you help keep this project running.

Quick Quiz

Question 1: What type of sensor is used to measure soil moisture in this project?




Question 2: Why is capacitive sensing preferred over legacy resistive sensors in this project?




Question 3: What is the resolution of the Analog-to-Digital Converter (ADC) mentioned in the text?




Question 4: What is the range of the raw ADC values before they are mapped to moisture percentages?




Question 5: What is the polling rate for the real-time serial output?




Question 6: What happens when the moisture level drops below the defined threshold?




Question 7: What agricultural issue does empirical, real-time soil dielectric measurement help prevent?




Question 8: What does the project map the raw 12-bit ADC values into?




Question 9: What type of measurements replace guesswork to prevent plant stress?




Question 10: What is one of the use cases for this plant hydration monitor?




Carlos Núñez Zorrilla
Carlos Núñez Zorrilla
Electronics & Computer Engineer

Telecommunications Electronics Engineer and Computer Engineer (official degrees in Spain).

Follow me:


Practical case: ESP32 Local Network Monitor

Practical case: ESP32 Local Network Monitor — hero

Objective and use case

What you’ll build: A standalone Field Technician’s Local Network Monitor using an ESP32 configured as a Software Access Point (SoftAP). It broadcasts a secure, localized Wi-Fi network to serve a real-time, air-gapped diagnostic dashboard directly to a smartphone or tablet.

Why it matters / Use cases

  • Infrastructure-independent diagnostics: Allows technicians to connect directly to equipment in offline environments like remote agricultural fields, deep industrial basements, or new construction sites.
  • Safe machine fault logging: Interfaces with industrial fault relays so personnel can safely monitor machine states via browser, avoiding physical exposure to high-voltage control panels.
  • Isolated human-machine interface (HMI): Delivers a highly secure, air-gapped configuration portal that cannot be accessed from the public internet, drastically reducing cybersecurity attack surfaces.
  • Access control monitoring: Acts as a localized, temporary monitor for server rack doors or secure gates, logging open/close states instantly.

Expected outcome

  • The ESP32 reliably broadcasts a WPA2-secured Wi-Fi network (SSID: ESP32-FieldMonitor) with a client connection time of <2 seconds.
  • A fully mobile-responsive web dashboard loads without external internet, rendering diagnostic UI elements.
  • Real-time hardware status and fault logs update on the client browser with <50ms network latency.

Audience: Industrial IoT Developers, Field Technicians, Maintenance Engineers; Level: Intermediate

Architecture/flow: ESP32 (SoftAP Mode) → Broadcasts WPA2 SSID → Technician Smartphone Connects → ESP32 Web Server → Serves HTML/JS Dashboard & Streams Real-time GPIO Data.

Educational validation note

Before publication, this case passed the Prometeo automated validation gate with status PASS. For this ESP32 DevKitC profile, the project was checked as a PlatformIO project: the validator extracted platformio.ini and src/main.cpp, created a temporary project and ran pio run against platform = espressif32, board = esp32dev and framework = arduino. It also checked article structure, copy/paste-safe ASCII command options, and unsupported stacks such as direct ESP-IDF or non-scoped ESP32 boards.

Published validation evidence

  • Automatic result: PASS.
  • Parsed structure: 4 sections, 2 tables and 2 code blocks detected before publication.
  • Checked code: 1 PlatformIO config + 1 ESP32 source/pio run.
  • Supported catalog: the article text was checked against Prometeo’s validation-capable device profiles, and unsupported stacks block publication.
  • Report findings: no blocking findings.

This validation confirms syntax and tool compatibility for the published code, but it does not replace physical testing on your exact ESP32 DevKitC board, wiring, power supply and local WiFi environment.

Educational safety note

This project is an educational prototype, not a certified product. Before powering the setup, verify the pinout of your exact ULX3S board revision, keep FPGA I/O signals at 3.3 V, never connect 5 V directly to I/O pins, disconnect power before changing wiring, and use suitable external supplies for loads, motors or servos while sharing ground only when the wiring requires it.

Conceptual block diagram

High-level view: what enters the system, what each block processes, and what comes out.

Functional architecture

ESP32 (SoftAP Mode)

Broadcasts WPA2 SSID

Technician Smartphone Connects

ESP32 Web Server

Serves HTML/JS Dashboard & Streams Real-t…

Conceptual signal and responsibility flow between device blocks.

Validation path

Source code

PlatformIO build

Flash

Serial monitor

Conceptual summary of the tools used to check the published material.

Prerequisites

To successfully complete this tutorial, you will need:
* Basic understanding of C++ programming and microcontroller GPIO concepts.
* PlatformIO IDE installed (either as a Visual Studio Code extension or via the Command Line Interface).
* Basic knowledge of networking concepts, specifically Wi-Fi Access Points (SSID, WPA2) and IP addressing.
* A web browser on a Wi-Fi enabled device (smartphone, tablet, or laptop) to view the dashboard.


Materials

  • Microcontroller: ESP32 DevKitC (Exact model: ESP32 DevKitC V4, typically equipped with the ESP32-WROOM-32 module).
  • Input Device: Pushbutton or dry contact switch (this will simulate an external machine fault relay or door contact).
  • Visual Indicator: Standard 5mm Status LED (e.g., Blue or Green).
  • Passive Components: 1x 330Ω resistor (current limiting for the LED).
  • Prototyping: Standard standard breadboard and male-to-male jumper wires.
  • Connection: Micro-USB cable (must support both power and data transfer; charging-only cables will fail to flash the device).

(Note: Depending on your specific ESP32 DevKitC manufacturer, you may need to install CP210x or CH34x USB-to-UART drivers on your operating system to allow PlatformIO to recognize the device).


Setup/Connection

The hardware setup utilizes the ESP32’s internal pull-up resistors for the contact input, minimizing the need for external passive components. When the contact switch is open, the internal resistor pulls the pin HIGH. When the switch is closed, it connects the pin to Ground (LOW).

Wiring Table:

Component ESP32 DevKitC Pin Connection / Destination Description
Contact Switch GPIO 18 Terminal 1 of Switch Configured as INPUT_PULLUP.
Contact Switch GND Terminal 2 of Switch Pulls GPIO 18 LOW when closed.
Status LED GPIO 19 LED Anode (Long leg) Configured as OUTPUT.
Status LED GND LED Cathode (Short leg) via 330Ω Resistor Completes the LED circuit safely.

Important Hardware Notes:
1. Ensure you are using a 330Ω resistor in series with the Status LED to prevent drawing excessive current from the ESP32’s GPIO pin, which could damage the microcontroller.
2. Do not connect the contact switch to any external voltage source. It must act as a “dry contact” (a simple mechanical closure to Ground).


Validated Code

The project requires two files within your PlatformIO workspace. The platformio.ini file configures the build environment, while src/main.cpp contains the application logic.

PlatformIO Configuration

Create or overwrite the platformio.ini file in the root of your project directory with the following configuration. This ensures the correct board definition and serial monitor baud rate are used.

; platformio.ini
[env:esp32dev]
platform = espressif32
board = esp32dev
framework = arduino
monitor_speed = 115200

Application Source Code

Create or overwrite the src/main.cpp file with the following complete, compilable code.

Public preview of the validated file. The complete source is shown to members and in PDF/Print.

// src/main.cpp
#include <Arduino.h>
#include <WiFi.h>
#include <WebServer.h>

// Hardware Pin Definitions
#define CONTACT_PIN 18
#define STATUS_LED_PIN 19

// SoftAP Network Credentials
const char* ssid = "ESP32-FieldMonitor";
const char* password = "admin1234"; // WPA2 requires a minimum of 8 characters

// Initialize the WebServer on port 80
WebServer server(80);

// Global state variables
int currentContactState = HIGH;
int lastContactState = HIGH;

// HTML Dashboard stored in Program Memory (PROGMEM) to save RAM
const char dashboard_html[] PROGMEM = R"rawliteral(
<!DOCTYPE HTML>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Field Monitor Dashboard</title>
  <style>
    body {
      font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
      text-align: center;
      background-color: #e9ecef;
      margin: 0;
      padding: 20px;
    }
    .card {
      background: white;
      max-width: 400px;
      margin: 40px auto;
      padding: 30px;
      border-radius: 12px;
      box-shadow: 0 8px 16px rgba(0,0,0,0.1);
    }
    h2 {
      color: #343a40;
      margin-top: 0;
    }
    .status-box {
      font-size: 1.8em;
      font-weight: bold;
      margin: 20px 0;
      padding: 20px;
      border-radius: 8px;
      transition: background-color 0.3s, color 0.3s;
    }
    .loading { background-color: #f8f9fa; color: #6c757d; border: 2px dashed #6c757d; }
    .closed { background-color: #d4edda; color: #155724; border: 2px solid #28a745; }
    .open { background-color: #f8d7da; color: #721c24; border: 2px solid #dc3545; }
    .footer {
      margin-top: 20px;
      font-size: 0.85em;
      color: #6c757d;
    }
  </style>
</head>
<body>
  <div class="card">
    <h2>Machine Contact Status</h2>
    <div id="contact-state" class="status-box loading">Awaiting Data...</div>
    <div class="footer">Auto-refreshing every 500ms via JSON API</div>
  </div>

  <script>
    // Asynchronous function to fetch status from the ESP32
    function fetchStatus() {
      fetch('/api/status')
        .then(response => {
          if (!response.ok) {
            throw new Error('Network response was not ok');
          }
          return response.json();
        })
        .then(data => {
          const statusDiv = document.getElementById('contact-state');
          // data.contact is 0 when closed (LOW) due to INPUT_PULLUP
          if(data.contact === 0) {
            statusDiv.innerHTML = "CONTACT CLOSED";
            statusDiv.className = "status-box closed";
          } else {
            statusDiv.innerHTML = "CONTACT OPEN";
            statusDiv.className = "status-box open";
          }
// ... continues for members in the complete validated source ...

🔒 Part of the validated code is premium. With the 7-day pass or the monthly membership you can view the complete validated source.

// src/main.cpp
#include <Arduino.h>
#include <WiFi.h>
#include <WebServer.h>

// Hardware Pin Definitions
#define CONTACT_PIN 18
#define STATUS_LED_PIN 19

// SoftAP Network Credentials
const char* ssid = "ESP32-FieldMonitor";
const char* password = "admin1234"; // WPA2 requires a minimum of 8 characters

// Initialize the WebServer on port 80
WebServer server(80);

// Global state variables
int currentContactState = HIGH;
int lastContactState = HIGH;

// HTML Dashboard stored in Program Memory (PROGMEM) to save RAM
const char dashboard_html[] PROGMEM = R"rawliteral(
<!DOCTYPE HTML>
<html lang="en">
<head>
  <meta charset="UTF-8">
  <meta name="viewport" content="width=device-width, initial-scale=1">
  <title>Field Monitor Dashboard</title>
  <style>
    body {
      font-family: 'Segoe UI', Tahoma, Geneva, Verdana, sans-serif;
      text-align: center;
      background-color: #e9ecef;
      margin: 0;
      padding: 20px;
    }
    .card {
      background: white;
      max-width: 400px;
      margin: 40px auto;
      padding: 30px;
      border-radius: 12px;
      box-shadow: 0 8px 16px rgba(0,0,0,0.1);
    }
    h2 {
      color: #343a40;
      margin-top: 0;
    }
    .status-box {
      font-size: 1.8em;
      font-weight: bold;
      margin: 20px 0;
      padding: 20px;
      border-radius: 8px;
      transition: background-color 0.3s, color 0.3s;
    }
    .loading { background-color: #f8f9fa; color: #6c757d; border: 2px dashed #6c757d; }
    .closed { background-color: #d4edda; color: #155724; border: 2px solid #28a745; }
    .open { background-color: #f8d7da; color: #721c24; border: 2px solid #dc3545; }
    .footer {
      margin-top: 20px;
      font-size: 0.85em;
      color: #6c757d;
    }
  </style>
</head>
<body>
  <div class="card">
    <h2>Machine Contact Status</h2>
    <div id="contact-state" class="status-box loading">Awaiting Data...</div>
    <div class="footer">Auto-refreshing every 500ms via JSON API</div>
  </div>

  <script>
    // Asynchronous function to fetch status from the ESP32
    function fetchStatus() {
      fetch('/api/status')
        .then(response => {
          if (!response.ok) {
            throw new Error('Network response was not ok');
          }
          return response.json();
        })
        .then(data => {
          const statusDiv = document.getElementById('contact-state');
          // data.contact is 0 when closed (LOW) due to INPUT_PULLUP
          if(data.contact === 0) {
            statusDiv.innerHTML = "CONTACT CLOSED";
            statusDiv.className = "status-box closed";
          } else {
            statusDiv.innerHTML = "CONTACT OPEN";
            statusDiv.className = "status-box open";
          }
        })
        .catch(error => {
          console.error('Error fetching status:', error);
          const statusDiv = document.getElementById('contact-state');
          statusDiv.innerHTML = "CONNECTION LOST";
          statusDiv.className = "status-box loading";
        });
    }

    // Poll the API every 500 milliseconds
    setInterval(fetchStatus, 500);

    // Initial fetch immediately on load
    window.onload = fetchStatus;
  </script>
</body>
</html>
)rawliteral";

// Route Handler: Serve the main HTML dashboard
void handleRoot() {
  server.send(200, "text/html", dashboard_html);
  Serial.println("Dashboard accessed by a client.");
}

// Route Handler: Serve the JSON API for the dashboard to consume
void handleApiStatus() {
  // Construct a simple JSON string manually
  String jsonPayload = "{\"contact\": " + String(currentContactState) + "}";
  server.send(200, "application/json", jsonPayload);
}

// Route Handler: Handle 404 Not Found
void handleNotFound() {
  server.send(404, "text/plain", "404: Not Found");
}

void setup() {
  // Initialize Serial Monitor
  Serial.begin(115200);
  delay(1000); // Allow serial to stabilize
  Serial.println("\n--- ESP32 Field Monitor Initialization ---");

  // Configure Hardware Pins
  pinMode(CONTACT_PIN, INPUT_PULLUP);
  pinMode(STATUS_LED_PIN, OUTPUT);

  // Read initial state
  currentContactState = digitalRead(CONTACT_PIN);
  lastContactState = currentContactState;

  // Set initial LED state (ON when contact is closed/LOW)
  digitalWrite(STATUS_LED_PIN, (currentContactState == LOW) ? HIGH : LOW);

  // Configure Wi-Fi in Access Point (SoftAP) mode
  Serial.print("Configuring Access Point...");
  WiFi.softAP(ssid, password);

  IPAddress IP = WiFi.softAPIP();
  Serial.println(" Ready!");
  Serial.print("SoftAP SSID: ");
  Serial.println(ssid);
  Serial.print("SoftAP IP Address: ");
  Serial.println(IP);

  // Define Web Server Routing
  server.on("/", HTTP_GET, handleRoot);
  server.on("/api/status", HTTP_GET, handleApiStatus);
  server.onNotFound(handleNotFound);

  // Start the Web Server
  server.begin();
  Serial.println("HTTP Web Server started.");
}

void loop() {
  // Handle incoming HTTP client requests
  server.handleClient();

  // Read the physical contact state
  currentContactState = digitalRead(CONTACT_PIN);

  // Detect state changes to update the LED and log to Serial
  if (currentContactState != lastContactState) {
    // Debounce delay (basic implementation)
    delay(50);
    currentContactState = digitalRead(CONTACT_PIN);

    if (currentContactState != lastContactState) {
      if (currentContactState == LOW) {
        Serial.println("EVENT: Contact CLOSED (Active).");
        digitalWrite(STATUS_LED_PIN, HIGH); // Turn LED ON
      } else {
        Serial.println("EVENT: Contact OPEN (Inactive).");
        digitalWrite(STATUS_LED_PIN, LOW);  // Turn LED OFF
      }
      lastContactState = currentContactState;
    }
  }
}


Build/Flash/Run commands

Use the PlatformIO Core CLI to compile, upload, and monitor your project. Open your terminal in the project’s root directory (where platformio.ini is located) and execute the following commands.

Command Purpose
pio run Compiles the project and verifies all dependencies and syntax.
pio run --target upload Compiles and flashes the compiled firmware to the ESP32 DevKitC.
pio device monitor Opens the serial monitor to view runtime logs at 115200 baud.

Execution Workflow:
1. Connect the ESP32 DevKitC to your computer via the micro-USB cable.
2. Run pio run to ensure the code compiles without syntax errors.
3. Run pio run --target upload. (If the upload fails to connect, press and hold the BOOT button on the ESP32 DevKitC when you see “Connecting…” in the terminal).
4. Run pio device monitor to observe the initialization sequence and verify the SoftAP IP address.


Step-by-step Validation

Follow these checkpoints to ensure the prototype operates exactly as intended.

  1. Verify Serial Initialization
    • Action: Observe the terminal output immediately after running pio device monitor or pressing the EN (Reset) button on the ESP32.
    • Expected observation: The terminal prints “— ESP32 Field Monitor Initialization —“, followed by the SSID ESP32-FieldMonitor and the IP 192.168.4.1.
    • Pass condition: The ESP32 does not crash or enter a reboot loop.
  2. Verify SoftAP Broadcast
    • Action: Open the Wi-Fi settings on a smartphone or laptop.
    • Expected observation: A network named ESP32-FieldMonitor appears in the list of available networks.
    • Pass condition: You can successfully connect to the network using the password admin1234.
  3. Verify Web Dashboard Loading
    • Action: Open a web browser on the connected device and navigate to http://192.168.4.1.
    • Expected observation: The “Field Monitor Dashboard” loads, showing a styled card. The serial monitor logs “Dashboard accessed by a client.”
    • Pass condition: The UI renders correctly without broken CSS.
  4. Verify Physical Input and LED Output
    • *Action

Find this product and/or books on this topic on Amazon

Go to Amazon

As an Amazon Associate, I earn from qualifying purchases. If you buy through this link, you help keep this project running.

Quick Quiz

Question 1: What is the primary hardware component used to build the Local Network Monitor?




Question 2: How is the ESP32 configured to broadcast a localized Wi-Fi network?




Question 3: Why is the diagnostic dashboard considered 'air-gapped'?




Question 4: What is one major safety benefit of using this device for machine fault logging?




Question 5: Which of the following is a mentioned use case for the Local Network Monitor?




Question 6: What type of environments is the infrastructure-independent diagnostic feature designed for?




Question 7: How does the device help reduce cybersecurity attack surfaces?




Question 8: Which security protocol is used for the broadcasted Wi-Fi network?




Question 9: What device is typically used to view the real-time diagnostic dashboard?




Question 10: What can the device log instantly when acting as an access control monitor?




Carlos Núñez Zorrilla
Carlos Núñez Zorrilla
Electronics & Computer Engineer

Telecommunications Electronics Engineer and Computer Engineer (official degrees in Spain).

Follow me: