ESP32 Bluejammer Detector: Build a BLE Spam & Interference Analyzer

If you are searching for an esp32 bluejammer, you are likely looking to either disrupt local Bluetooth signals or detect the increasingly common BLE spam attacks (like those popularized by Flipper Zero). Let's get the legal and technical reality out of the way immediately: true RF jamming—blasting 2.4GHz noise to drop all Bluetooth connections—is a federal crime under FCC Part 15 regulations. Furthermore, a $5 microcontroller cannot generate the raw RF noise required to jam a spectrum; it lacks the power amplifier and wideband oscillator hardware.

However, what hobbyists often call a 'bluejammer' is actually a BLE Protocol Spammer. These tools exploit the Bluetooth Low Energy advertising protocol by flooding the 2.4GHz spectrum with thousands of fake pairing requests (Apple, Windows, Android), causing target devices to freeze their UI or drain their batteries. Building an ESP32 BLE Spam & Interference Detector is a legal, highly educational defensive project. It allows you to monitor your facility or lab for protocol-level denial-of-service (DoS) attacks and unauthorized advertising floods.

Decision Tree: Which ESP32 BLE Tool Do You Actually Need?

Before ordering parts, define your exact goal. The hobbyist space is full of misleading terminology. Use this decision matrix to determine your build path.

Default Recommendation: If you are a hobbyist, student, or IT admin wanting to understand Bluetooth interference, build the detector outlined below. It targets the ESP32-WROOM-32 DevKit V1 (38-pin variant) and uses native Bluedroid BLE libraries to count advertising packets per second.

Parts List & Pin Mapping

This build relies on the ESP32's native Bluetooth stack. We are using the Bluedroid stack (built into the Arduino ESP32 core) rather than NimBLE to avoid external library dependency headaches, though we will cover NimBLE debugging below.

Required Components

• Microcontroller: ESP32-WROOM-32 DevKit V1 (Specifically the 38-pin variant. 30-pin variants have different GND/3V3 alignments).
• Display: 0.96-inch SSD1306 OLED (I2C, 4-pin, 128x64 resolution, 0x3C address).
• Alert: 5V Active Piezo Buzzer (Do not use a passive buzzer; active buzzers have a built-in oscillator and only need a HIGH signal).
• Wiring: 22 AWG solid core hook-up wire or standard Dupont jumper cables.

Pin Mapping Table

Step-by-Step Build: Wiring and Bench Testing

1. Flash the ESP32 First: Before wiring the I2C display, flash the code (provided in the next section) to your ESP32. This prevents I2C bus lockups that can occur if the ESP32 boots and toggles GPIO 21/22 while the OLED is partially powered.
2. Wire the OLED: Connect VCC to 3V3, GND to GND, SCL to GPIO 22, and SDA to GPIO 21. Bench Tip: If your OLED module lacks onboard pull-up resistors (common on cheap Amazon/eBay clones), you will need to solder 10kΩ resistors between SDA-VCC and SCL-VCC. If you skip this, the I2C bus will float, and the screen will remain blank.
3. Wire the Buzzer: Connect the buzzer's negative lead to GND and the positive lead to GPIO 25. The ESP32 can source up to 40mA per GPIO, which is sufficient for most small 5V active piezo buzzers. If you are using a high-current siren, use a 2N2222 NPN transistor to switch the load.
4. Verify I2C Address: Run a standard I2C Scanner sketch first. 90% of 0.96-inch OLEDs use address 0x3C, but some variants use 0x3D. If your scanner returns 0x3D, you must change the SCREEN_ADDRESS macro in the code below.

Complete Compilable Code: BLE Spam & Interference Detector

This code targets the ESP32 Arduino Core (v2.x or v3.x). It initializes a continuous BLE scan, counts the number of advertising packets received per second, and triggers an alarm if the count exceeds the threshold. Normal office environments see 5–20 advertisements per second; a BLE spam attack will push this well over 100.

#include <BLEDevice.h>
#include <BLEUtils.h>
#include <BLEScan.h>
#include <BLEAdvertisedDevice.h>
#include <Wire.h>
#include <Adafruit_GFX.h>
#include <Adafruit_SSD1306.h>

#define SCREEN_WIDTH 128
#define SCREEN_HEIGHT 64
#define OLED_RESET -1
#define SCREEN_ADDRESS 0x3C
#define BUZZER_PIN 25
#define SPAM_THRESHOLD 50 // Ads per second to trigger alarm
#define SCAN_TIME 1 // Seconds

class MyAdvertisedDeviceCallbacks: public BLEAdvertisedDeviceCallbacks {
    void onResult(BLEAdvertisedDevice advertisedDevice) override {
        advCount++;
    }
};

Adafruit_SSD1306 display(SCREEN_WIDTH, SCREEN_HEIGHT, &Wire, OLED_RESET);
volatile int advCount = 0;
unsigned long lastCheck = 0;
bool alarmState = false;

void setup() {
    Serial.begin(115200);
    pinMode(BUZZER_PIN, OUTPUT);
    digitalWrite(BUZZER_PIN, LOW);

    if(!display.begin(SSD1306_SWITCHCAPVCC, SCREEN_ADDRESS)) {
        Serial.println(F("SSD1306 allocation failed"));
        for(;;); // Halt execution if display fails
    }
    
    display.clearDisplay();
    display.setTextSize(1);
    display.setTextColor(SSD1306_WHITE);
    display.setCursor(0,0);
    display.println("Initializing BLE...");
    display.display();

    BLEDevice::init("");
    BLEScan* pBLEScan = BLEDevice::getScan();
    pBLEScan->setAdvertisedDeviceCallbacks(new MyAdvertisedDeviceCallbacks());
    pBLEScan->setActiveScan(false); // Passive scan saves power and reduces overhead
    pBLEScan->setInterval(100);
    pBLEScan->setWindow(99);
    
    pBLEScan->start(SCAN_TIME, false);
    lastCheck = millis();
}

void loop() {
    if (millis() - lastCheck >= 1000) {
        int currentCount = advCount;
        advCount = 0;
        lastCheck = millis();
        
        // Restart scan for the next window
        BLEScan* pBLEScan = BLEDevice::getScan();
        pBLEScan->start(SCAN_TIME, false);

        if (currentCount > SPAM_THRESHOLD) {
            triggerAlarm(currentCount);
        } else {
            clearAlarm(currentCount);
        }
    }
}

void triggerAlarm(int count) {
    digitalWrite(BUZZER_PIN, HIGH);
    display.clearDisplay();
    display.setCursor(0,0);
    display.setTextSize(2);
    display.println("ALARM!");
    display.setTextSize(1);
    display.print("BLE Spam Detected\nAds/sec: ");
    display.println(count);
    display.display();
    alarmState = true;
}

void clearAlarm(int count) {
    if (alarmState) {
        digitalWrite(BUZZER_PIN, LOW);
        alarmState = false;
    }
    display.clearDisplay();
    display.setCursor(0,0);
    display.setTextSize(1);
    display.println("Monitoring BLE...");
    display.print("Ads/sec: ");
    display.println(count);
    display.display();
}

Debugging: First Three Things to Check When It Fails

Embedded BLE development on the ESP32 is notorious for memory leaks and task watchdog panics. If your build fails, follow this exact diagnostic path.

1. The I2C Timeout / Blank Screen

Symptom: The serial monitor prints SSD1306 allocation failed or the screen remains completely dark.

Ranked Causes:

1. Wrong I2C Address: Your OLED is 0x3D, but the code expects 0x3C. Run an I2C scanner sketch to verify.
2. Missing Pull-ups: The I2C bus is floating. Solder 10kΩ pull-up resistors to SDA and SCL.
3. Wiring Swap: SDA and SCL are reversed. GPIO 21 is SDA, GPIO 22 is SCL.

2. The Watchdog Task Panic

Exact Error String: Guru Meditation Error: Core 1 panic'ed (Interrupt wdt timeout)

The Fix: This happens when you attempt to execute blocking code (like display.display() or delay()) directly inside the onResult BLE callback. The callback runs on a high-priority FreeRTOS task; blocking it starves the WiFi/BT stack and triggers the hardware watchdog. The code provided above avoids this by only incrementing a volatile int inside the callback and handling all I2C writes in the main loop().

3. BLE Scan Fails to Start

Exact Error String: E (142) BT_BTM: BTM_BLE_SCAN_FAILED

The Fix: This occurs if you call pBLEScan->start() before the BLE stack has fully initialized, or if you attempt to start a scan while a previous scan is still running in continuous mode. Ensure BLEDevice::init("") is called before configuring the scan parameters, and use non-blocking scan restarts as shown in the loop() function.

Extending and Simplifying the Build

Once you have the baseline detector running on your bench, you can adapt it to your specific operational needs.

How to Simplify (Headless Mode)

If you want to mount this in a ceiling tile or server rack where a screen is impractical, strip out the Adafruit_SSD1306 and Wire libraries entirely. Rely solely on the serial output or map the buzzer to trigger only on critical thresholds. This reduces the firmware footprint by roughly 40KB and eliminates I2C bus lockups in high-EMI environments.

How to Extend (Data Logging & MAC Tracking)

To turn this into a forensic tool, add a micro-SD card module (SPI on GPIO 23/19/18/5). Inside the onResult callback, extract the MAC address using advertisedDevice.getAddress().toString().c_str(). Log the MAC, RSSI, and timestamp to the SD card. Warning: Writing to an SD card inside the BLE callback will cause the WDT panic mentioned above. Instead, push the MAC string into a FreeRTOS xQueue, and have a secondary task on Core 0 handle the SD card writes.

For further reading on ESP32 Bluetooth architecture and memory management, refer to the official Espressif Bluetooth API Reference. Understanding the difference between the Bluedroid and NimBLE stacks is critical if you eventually need to lower the RAM footprint of your detector to run alongside a WiFi MQTT uplink.