ESP32-S3 BLE GATT Server

A basic ESP32-S3 project implementing BLE (Bluetooth Low Energy) functionality using the NimBLE stack with GATT (Generic Attribute Profile) server capabilities.

Features

• ESP32-S3 support with optimized configuration
• NimBLE Bluetooth Low Energy stack
• Basic GATT server with custom service and characteristic
• Read/Write/Notify/Indicate operations
• WiFi connectivity with automatic reconnection
• Temperature Service with Environmental Sensing Service (0x181A)
• Temperature monitoring with current, max, and min values
• Configurable temperature units (Celsius/Fahrenheit)
• Automatic updates every 30 seconds
• VSCode integration with PlatformIO
• Serial debugging and monitoring

Hardware Requirements

• ESP32-S3 development board (ESP32-S3-DevKitC-1 or compatible)
• USB cable for programming and serial communication

Software Requirements

• VSCode
• PlatformIO IDE Extension

Setup Instructions

1. Clone the repository:

   git clone <repository-url>
   cd esp32_test

2. Configure WiFi credentials:

   • Open include/wifi_manager.h
   • Update WIFI_SSID with your WiFi network name
   • Update WIFI_PASSWORD with your WiFi password

3. Open in VSCode:

   • Open VSCode
   • Open the esp32_ble_project.code-workspace file
   • Install the recommended PlatformIO IDE extension if prompted

4. Build the project:

   • Open the PlatformIO terminal in VSCode (Ctrl+Shift+`)
   • Run: pio run

5. Upload to ESP32-S3:

   • Connect your ESP32-S3 board via USB
   • Run: pio run --target upload

6. Monitor serial output:

   • Run: pio device monitor
   • Or use the PlatformIO Serial Monitor in VSCode

WiFi Configuration

The ESP32-S3 supports WiFi connectivity with automatic reconnection.

Secure Configuration (Recommended)

To keep your WiFi credentials secure and out of version control:

1. Add credentials to platformio.ini (this file should be in .gitignore):

   [env:esp32-s3-devkitc-1-n16r8]
   platform = espressif32
   board = esp32-s3-devkitc-1
   framework = arduino
   build_flags = 
       -D CONFIG_BT_ENABLED=1
       -D CONFIG_BT_NIMBLE_ENABLED=1
       -D WIFI_SSID='"YourNetworkName"'
       -D WIFI_PASSWORD='"YourSecurePassword"'

   Note: The double quotes inside single quotes are required for proper string handling.

2. Alternative: Use a separate config file (also add to .gitignore): Create wifi_credentials.ini with your credentials, then include it in platformio.ini:

   extra_configs = wifi_credentials.ini

Simple Configuration (Development Only)

For quick testing, you can set credentials in include/wifi_manager.h, but never commit real credentials to version control:

#define WIFI_SSID        "YourSSID"
#define WIFI_PASSWORD    "YourPassword"

WiFi Features

• Automatic connection on startup
• Automatic reconnection if connection is lost
• Connection timeout and retry logic
• Status monitoring and reporting

WiFi Status Information

• IP address
• MAC address
• Signal strength (RSSI)
• Connection state

The WiFi manager will automatically attempt to connect during startup and maintain the connection. Status updates are printed to the serial monitor every 30 seconds.

BLE Service Details

Custom Service UUID:

12345678-1234-1234-1234-123456789abc

Custom Characteristic UUID:

87654321-4321-4321-4321-cba987654321

Environmental Sensing Service UUID:

0000181A-0000-1000-8000-00805f9b34fb (Standard BLE Environmental Sensing Service)

Temperature Characteristics:

• Current Temperature: 00002A6E-0000-1000-8000-00805f9b34fb (Read, Notify)
• Max Temperature: 00002A6F-0000-1000-8000-00805f9b34fb (Read, Notify)
• Min Temperature: 00002A70-0000-1000-8000-00805f9b34fb (Read, Notify)
• Temperature Config: 00002A71-0000-1000-8000-00805f9b34fb (Read, Write)
  • Write 0 for Celsius
  • Write 1 for Fahrenheit

Supported Operations:

• Read: Get current value from the characteristic
• Write: Send data to the characteristic
• Notify: Receive automatic updates when the value changes
• Indicate: Receive confirmed notifications

Usage

1. Flash and run the code on your ESP32-S3
2. Open serial monitor to see debug output
3. Connect using a BLE client (smartphone app, computer, etc.)
   • Device name: ESP32-S3-BLE-Device
   • Look for the Environmental Sensing Service (0x181A) or custom service UUID
4. Interact with the characteristics:
   • Read to get current value
   • Write to send data to the device
   • Enable notifications to receive periodic updates
5. Monitor temperature:
   • Read temperature characteristics to get current, max, and min values
   • Temperature updates automatically every 30 seconds
   • Configure units by writing to the Temperature Config characteristic (0=Celsius, 1=Fahrenheit)
   • Temperature values are sent as signed 16-bit integers (multiply by 100, e.g., 2250 = 22.50°C)

BLE Client Apps for Testing

Android:

• nRF Connect for Mobile
• BLE Scanner

iOS:

• LightBlue Explorer
• nRF Connect for Mobile

Windows/Mac/Linux:

• nRF Connect for Desktop
• Bluetility (Mac)

Project Structure

esp32_test/
├── .vscode/                    # VSCode configuration
│   └── settings.json
├── include/                    # Header files
│   ├── ble_server.h           # BLE server declarations
│   ├── temperature_service.h  # Temperature service declarations
│   └── wifi_manager.h         # WiFi manager declarations
├── src/                        # Source code
│   ├── main.cpp               # Main application
│   ├── ble_server.cpp         # BLE server implementation
│   ├── temperature_service.cpp # Temperature service implementation
│   └── wifi_manager.cpp       # WiFi manager implementation
├── docs/                       # Documentation
├── test/                       # Unit tests
├── platformio.ini             # PlatformIO configuration
├── esp32_ble_project.code-workspace  # VSCode workspace
├── .gitignore                 # Git ignore rules
└── README.md                  # This file

Configuration

The project is configured in platformio.ini with:

• Board: ESP32-S3-DevKitC-1
• Framework: ESP-IDF via Arduino
• BLE Stack: NimBLE (enabled, Bluedroid disabled)
• Monitor Speed: 115200 baud
• Upload Speed: 921600 baud

Troubleshooting

1. Build errors: Ensure PlatformIO Core is up to date
2. Upload issues: Check USB cable and driver installation
3. BLE not visible: Verify the device is advertising and not connected
4. Serial monitor issues: Check baud rate (115200) and port selection

Customization

To modify the BLE service:

1. Change UUIDs in main.cpp
2. Add more characteristics to the service
3. Implement custom read/write handlers
4. Add additional services

License

This project is open source and available under the MIT License.