A comprehensive WiFi configuration system for ESP32 devices using Bluetooth Low Energy (BLE) and iOS.
WiFiSet provides a seamless way to configure WiFi credentials on ESP32 devices using an iOS app over Bluetooth Low Energy. No need for SoftAP mode, web servers, or complicated provisioning flows - just simple BLE communication between your iPhone and ESP32.
The system consists of two main components:
- ESP32 Library (PlatformIO): A reusable library that handles BLE advertising, WiFi scanning, credential storage, and WiFi connection management
- iOS SDK (Swift Package): A SwiftUI-based library with BLE communication and pre-built UI components for device discovery and WiFi configuration
- BLE-based WiFi configuration (no SoftAP required)
- Automatic WiFi network scanning and list broadcasting
- Persistent credential storage using ESP32 NVS
- Simple callback-based API
- Auto-reconnect on boot with saved credentials
- Real-time connection status updates
- Complete abstraction of BLE complexity
- Device discovery and BLE connection management
- WiFi network list display with signal strength indicators
- Secure credential entry and validation
- Keychain storage for WiFi passwords
- SwiftUI views ready to drop into any project
- Real-time ESP32 connection status monitoring
- Support for credential updates
- Custom binary protocol for efficient BLE communication
- Low bandwidth usage
- Support for all WiFi security types (Open, WEP, WPA/WPA2, WPA3)
- MTU negotiation for optimal performance
- See PROTOCOL.md for complete specification
WiFiSet/
├── README.md # This file
├── PROTOCOL.md # BLE protocol specification
├── .gitignore # Root gitignore
├── iOS/
│ └── WiFiSet/ # Xcode project
│ ├── WiFiSet.xcodeproj/ # Xcode project
│ ├── WiFiSet/ # Demo iOS app
│ └── WiFiSetSDK/ # Swift Package library
└── ESP32/
├── library/ # PlatformIO library
│ ├── examples/ # Example usage
│ └── src/ # Library source code
└── example/ # Standalone test project
-
Install the Library
Add to your
platformio.ini:lib_deps = WiFiSetESP32Or install locally:
cd your-project cp -r WiFiSet/ESP32/library .pio/libdeps/your-env/WiFiSetESP32 -
Basic Usage
#include <WiFiSetESP32.h> WiFiSetESP32 wifiSet("MyESP32Device"); void setup() { Serial.begin(115200); // Set up callbacks wifiSet.onWiFiConnected([](IPAddress ip) { Serial.printf("WiFi connected! IP: %s\n", ip.toString().c_str()); }); wifiSet.onCredentialsReceived([](const String& ssid, const String& password) { Serial.printf("New credentials received: %s\n", ssid.c_str()); }); // Start the library (begins BLE advertising) wifiSet.begin(); } void loop() { wifiSet.loop(); // Must be called regularly // Your application code here if (wifiSet.isConnected()) { // Do something when connected to WiFi } }
-
Build and Flash
cd ESP32/example pio run --target upload pio device monitor
For detailed ESP32 documentation, see ESP32/library/README.md
-
Add WiFiSetSDK to Your Project
The WiFiSetSDK is a local Swift Package within the Xcode project:
- Open your Xcode project
- File → Add Package Dependencies → Add Local
- Select
iOS/WiFiSet/WiFiSetSDKfolder - Add WiFiSetSDK to your app target
-
Configure Info.plist
Add Bluetooth permission:
<key>NSBluetoothAlwaysUsageDescription</key> <string>This app uses Bluetooth to configure WiFi on your ESP32 device</string>
-
Basic Usage
import SwiftUI import WiFiSetSDK struct ContentView: View { var body: some View { DeviceScannerView() } }
That's it! The SDK provides complete UI flows for:
- Device scanning and discovery
- WiFi network selection
- Credential entry
- Connection status monitoring
-
Run on Physical Device
BLE requires a physical iOS device (not simulator):
- Connect your iPhone
- Select it as the build target
- Build and run (Cmd+R)
For detailed iOS documentation, see iOS/WiFiSet/WiFiSetSDK/README.md
- ESP32 starts up and checks for saved WiFi credentials in NVS
- If credentials exist, ESP32 automatically connects to WiFi
- If no credentials or connection fails, ESP32 starts BLE advertising
- iOS app scans for nearby ESP32 devices
- User selects the ESP32 device to configure
- ESP32 scans for WiFi networks and sends the list over BLE
- iOS app displays available networks with signal strength
- User selects a network and enters the password
- iOS app sends credentials to ESP32 over BLE
- ESP32 saves credentials to NVS and attempts to connect
- ESP32 sends connection status updates back to iOS app
- On subsequent boots, ESP32 automatically connects using saved credentials
WiFiSet uses a custom binary protocol over BLE for efficient communication. The protocol supports:
- WiFi network list transmission (SSID, signal strength, security type, channel)
- Credential configuration (SSID and password)
- Connection status monitoring (state, IP address, signal strength)
- Error reporting
For complete protocol specification, see PROTOCOL.md
- Unit tests for protocol encoding/decoding
- Example project with serial monitor output
- Test with nRF Connect app (iOS/Android) to verify BLE service
- Hardware testing with actual WiFi networks
- Unit tests for protocol, keychain, and BLE components
- SwiftUI previews for all views
- Manual testing with ESP32 hardware
- Flash ESP32 with example project
- Run iOS demo app on iPhone
- Complete full workflow: scan → connect → view networks → configure → verify connection
- BasicUsage - Minimal example with callbacks
- example - Full featured example with detailed logging
- WiFiSet Demo App - Complete demo application using WiFiSetSDK
- ESP32 (any variant with BLE support)
- PlatformIO or Arduino IDE
- ESP32 Arduino framework
- ESP32 BLE Arduino library (2.0.0+)
- iOS 17.0 or later (uses
.navigationDestination(item:)API) - Xcode 15.0 or later
- Physical iOS device (BLE not available in simulator)
- Swift 5.9+
Future enhancements being considered:
- BLE encryption and pairing
- Multiple credential storage (store multiple networks)
- Network priority management
- Connection diagnostics and logs
- OTA firmware updates over BLE
- Android SDK
- Web-based configuration fallback
- IPv6 support
- Enterprise WiFi (802.1X) support
Contributions are welcome! Please feel free to submit pull requests or open issues for bugs and feature requests.
MIT License
Copyright (c) 2025 Matt Long
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
- ESP32 Arduino framework by Espressif Systems
- Apple CoreBluetooth framework
- SwiftUI framework
For questions, issues, or feature requests:
- Open an issue on GitHub
- Check the PROTOCOL.md for protocol details
- See platform-specific READMEs for detailed documentation
This version uses unencrypted BLE communication, which is acceptable for local device configuration scenarios. Users should:
- Verify device identity before sending credentials
- Use in controlled environments
- Be aware that WiFi passwords are transmitted in plain text over BLE
Credentials are encrypted at rest (Keychain on iOS, NVS on ESP32).
Future versions may include BLE encryption and pairing requirements for enhanced security.