Practical case: ESP32 BLE Locator Beacon

// src/main.cpp
#include <Arduino.h>
#include <BLEDevice.h>
#include <BLEServer.h>
#include <BLEUtils.h>
#include <BLE2902.h>

// Hardware Pin Definitions
const int LED_PIN = 25;
const int BUZZER_PIN = 26;
const int BUTTON_PIN = 27;

// LEDC PWM Settings for the passive buzzer
const int PWM_CHANNEL = 0;
const int PWM_FREQ = 2000;
const int PWM_RESOLUTION = 8;

// BLE UUIDs - Generated unique identifiers for our custom service
#define SERVICE_UUID        "4fafc201-1fb5-459e-8fcc-c5c9c331914b"
#define CHARACTERISTIC_UUID "beb5483e-36e1-4688-b7f5-ea07361b26a8"

// Global State Variables
bool deviceConnected = false;
bool alarmActive = false;

// Timing variables for non-blocking alarm pattern
unsigned long previousMillis = 0;
const long interval = 250; // Toggle every 250 milliseconds
bool toggleState = false;

// BLE Server Callbacks: Handle connection and disconnection events
class MyServerCallbacks : public BLEServerCallbacks {
    void onConnect(BLEServer* pServer) {
        deviceConnected = true;
        Serial.println("BLE Device Connected.");
    }
    void onDisconnect(BLEServer* pServer) {
        deviceConnected = false;
        Serial.println("BLE Device Disconnected. Restarting advertising...");
        // Restart advertising so the device can be found again
        pServer->startAdvertising();
    }
};

// BLE Characteristic Callbacks: Handle incoming write requests from the smartphone
class MyCallbacks : public BLECharacteristicCallbacks {
    void onWrite(BLECharacteristic *pCharacteristic) {
        std::string value = pCharacteristic->getValue();

        if (value.length() > 0) {
            Serial.print("Received Value: ");
            for (int i = 0; i < value.length(); i++) {
                Serial.print(value[i], HEX);
                Serial.print(" ");
            }
            Serial.println();

            // Check if the received byte is 0x01 (Start Alarm) or 0x00 (Stop Alarm)
            if (value[0] == 0x01) {
                alarmActive = true;
                Serial.println("Alarm TRIGGERED via BLE!");
            } else if (value[0] == 0x00) {
                alarmActive = false;
                Serial.println("Alarm STOPPED via BLE.");
                // Ensure hardware is turned off immediately
                digitalWrite(LED_PIN, LOW);
                ledcWriteTone(PWM_CHANNEL, 0); 
            }
        }
    }
};

void setup() {
    Serial.begin(115200);
    Serial.println("Starting Tool Finder Beacon...");

    // Initialize Hardware Pins
    pinMode(LED_PIN, OUTPUT);
    digitalWrite(LED_PIN, LOW);

    // Configure Pushbutton with internal pull-up resistor
    pinMode(BUTTON_PIN, INPUT_PULLUP);

    // Configure PWM for the passive buzzer
    ledcSetup(PWM_CHANNEL, PWM_FREQ, PWM_RESOLUTION);
    ledcAttachPin(BUZZER_PIN, PWM_CHANNEL);
    ledcWriteTone(PWM_CHANNEL, 0); // Ensure buzzer is quiet on boot

    // Initialize BLE Device
    BLEDevice::init("ToolFinder-Beacon");

    // Create BLE Server
    BLEServer *pServer = BLEDevice::createServer();
    pServer->setCallbacks(new MyServerCallbacks());

    // Create BLE Service
    BLEService *pService = pServer->createService(SERVICE_UUID);

    // Create BLE Characteristic (Write capability)
    BLECharacteristic *pCharacteristic = pService->createCharacteristic(
                                           CHARACTERISTIC_UUID,
                                           BLECharacteristic::PROPERTY_WRITE
                                         );

    pCharacteristic->setCallbacks(new MyCallbacks());

    // Start the service
    pService->start();

    // Start advertising
    BLEAdvertising *pAdvertising = BLEDevice::getAdvertising();
    pAdvertising->addServiceUUID(SERVICE_UUID);
    pAdvertising->setScanResponse(true);
    pAdvertising->setMinPreferred(0x06);  // Functions that help with iPhone connections
    pAdvertising->setMinPreferred(0x12);
    BLEDevice::startAdvertising();

    Serial.println("BLE Advertising Started. Waiting for connections...");
}

void loop() {
    // 1. Check physical pushbutton to clear the alarm locally
    // Since we use INPUT_PULLUP, a pressed button reads as LOW
    if (digitalRead(BUTTON_PIN) == LOW) {
        if (alarmActive) {
            alarmActive = false;
            Serial.println("Alarm STOPPED via physical button press.");
            // Immediately turn off the hardware
            digitalWrite(LED_PIN, LOW);
            ledcWriteTone(PWM_CHANNEL, 0);

            // Simple debounce delay
            delay(300); 
        }
    }

    // 2. Handle the Alarm Pattern (Non-blocking)
    if (alarmActive) {
        unsigned long currentMillis = millis();

        if (currentMillis - previousMillis >= interval) {
            previousMillis = currentMillis;
            toggleState = !toggleState;

            if (toggleState) {
                digitalWrite(LED_PIN, HIGH);
                ledcWriteTone(PWM_CHANNEL, 2500); // 2.5 kHz tone
            } else {
                digitalWrite(LED_PIN, LOW);
                ledcWriteTone(PWM_CHANNEL, 0);    // Silence
            }
        }
    } else {
        // Ensure hardware remains off when alarm is inactive
        digitalWrite(LED_PIN, LOW);
        ledcWriteTone(PWM_CHANNEL, 0);
    }

    // Small delay to yield to FreeRTOS background tasks (BLE stack)
    delay(10);
}