ESP32 BLE BMS Protector

A hardware-based security shield for Battery Management Systems (JBD/Xiaoxiang, Daly, and JK).

This project runs on an ESP32 (e.g., Seeed Studio XIAO ESP32-S3) and works by "squatting" on the BMS's single Bluetooth Low Energy (BLE) connection slot. Since BLE peripherals only allow one active controller at a time, the ESP32 keeps the connection occupied 24/7. This prevents any unauthorized third party from connecting to your BMS and controlling the charge/discharge MOSFETs.

When you need to connect your phone or laptop to check telemetry, you can temporarily release the lock using the built-in BOOT button or the secure Wi-Fi web portal.

---

Key Features

• Protocol-Agnostic Link-Layer Locking: Connects strictly at the Bluetooth link layer. Zero data packets or keep-alive commands are transmitted, ensuring maximum privacy and instant connection speed.
• WPA2 Access Point Security: Secure your configuration portal with a custom WPA2 password (minimum 8 characters) to prevent unauthorized users from unlocking your BMS.
• Circuit Digest Branding & Modern UI: Built with a responsive, light corporate UI matching bms_analyzer and featuring the official Circuit Digest logo.
• Hardware BOOT Button Controls: Use the onboard BOOT button without extra wiring:
  • Short press (< 2s): Toggle temporary release / re-lock.
  • Long press (> 5s): Trigger a full factory reset (indicated by rapid LED strobing).
• Multi-Brand Compatibility: Select JBD (Xiaoxiang), Daly, or JK BMS in the UI.
• Auto-Reconnection: Automatically detects BLE link drops and re-establishes the lock immediately.
• Visual Status LED: On-board LED indicates system state (Configuring, Locked, or Temporarily Released).

---

Hardware Requirements

1. Microcontroller: Seeed Studio XIAO ESP32-S3 or Seeed Studio XIAO ESP32-C3 (recommended for their compact form factor) or any standard ESP32 development board.
2. Power Supply: A 5V DC micro-USB / Type-C cable or a 5V Buck Converter connected directly to your battery bank.

---

Board Pins Auto-Detection

The firmware auto-detects board pinouts at compile time:

Board Type	Boot Button Pin	Onboard LED Pin	Active LOW LED
XIAO ESP32-S3	GPIO 0 (BOOT)	GPIO 21 (D10)	Yes (Low = ON)
XIAO ESP32-C3	GPIO 9 (D9)	GPIO 8 (D8)	Yes (Low = ON)
Generic ESP32	GPIO 0	GPIO 2	No (High = ON)

---

Installation & Compilation (Arduino IDE)

1. Install ESP32 Board Manager:
   • In Arduino IDE, open File > Preferences.
   • Add this URL to Additional Boards Manager URLs:
     https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json
   • Go to Tools > Board > Boards Manager, search for esp32 and install the package.
2. Select Board:
   • Select XIAO_ESP32S3, XIAO_ESP32C3, or ESP32 Dev Module under Tools > Board > ESP32.
3. Upload:
   • Open BMS_Protector.ino in Arduino IDE.
   • Connect your board and select the correct serial Port.
   • Click Upload (Ctrl + U).

---

Step-by-Step Usage Guide

Step 1: Initial Setup Mode

1. Upon initial boot, the ESP32 starts an open Wi-Fi Access Point called BMS-Shield-Setup.
2. Connect your phone or laptop to BMS-Shield-Setup.
3. Open your browser and navigate to http://192.168.4.1 (or let the captive portal load).
4. Select your BMS brand (JBD, Daly, or JK).
5. (Optional but recommended) Enter an Access Point Password (minimum 8 characters) to secure the AP.
6. Click Scan for BLE Devices, select your BMS, and click Select / Save.
7. The ESP32 saves the settings and reboots.

Step 2: Active Protection (Locked Mode)

1. On boot, the LED blinks slowly while connecting to your BMS.
2. Once connected, the LED stays Solid ON. The protector is now holding the BLE link layer connection.
3. Your BMS will now be hidden or refuse connections from unauthorized devices trying to scan or control it.

Step 3: Temporary Release (Unlock Mode)

When you need to connect your official BMS app or PC analyzer:

• Via BOOT Button: Short press (< 2s) the onboard BOOT button.
• Via Wi-Fi: Connect to BMS-Shield-XXXX (enter your WPA2 password if set), go to http://192.168.4.1, and click Release Lock.
• Result: The ESP32 disconnects from BLE, and the LED blinks rapidly. You have 5 minutes (or your configured duration) to connect with your normal app.
• Re-locking: The protector automatically re-locks the BMS once the timer expires. You can also click Re-Lock Now in the Web UI or short-press the BOOT button to re-lock instantly.

Step 4: Factory Resetting / Reconfiguring

If you want to clear saved configurations or connect to a new BMS:

• Press and hold the BOOT button for 5+ seconds until the status LED begins rapidly strobing/flickering, then release.
• The ESP32 will clear all saved preferences and restart into BMS-Shield-Setup mode.