ESPProvision is a provisioning library written in Swift. It provides mechanism to provide network credentials and/or custom data to an ESP32, ESP32-S2 or ESP8266 devices.
- Search for available BLE devices.
- Scan device QR code to provide reference to ESP device.
- Create reference of ESPDevice manually.
- Data Encryption
- Data transmission through BLE and SoftAP.
- Provision device.
- Scan for available Wi-Fi networks.
- Console logs
- Support for security version 2.
- iOS 13.0+ / macOS 10.12+
- Xcode 13+
- Swift 5.1+
- Enable Hotspot Configuration capability in Xcode.
- Enable Access WiFI Information capability in Xcode.
CocoaPods is a dependency manager for Cocoa projects. For usage and installation instructions, visit their website. To integrate ESPProvision into your Xcode project using CocoaPods, specify it in your Podfile
:
pod 'ESPProvision'
The Swift Package Manager is a tool for automating the distribution of Swift code and is integrated into the swift
compiler.
Once you have your Swift package set up, adding ESPProvision as a dependency is as easy as adding it to the dependencies
value of your Package.swift
.
dependencies: [
.package(url: "https://github.com/espressif/esp-idf-provisioning-ios.git", from: "2.1.1")
]
If you are using Xcode, then you should add this SwiftPM package as dependency of your xcode project: Apple Docs
ESPProvision provides a simpler mechanism to communicate with an ESP-32, ESP32-S2 and ESP8266 devices. It gives an efficient search and scan model to listen and return devices which are in provisioning mode. ESProvision embeds security protocol and allow for safe transmission of data by doing end to end encryption. It supports BLE and SoftAP as mode of transmission which are configurable at runtime. Its primarily use is to provide home network credentials to a device and ensure device connectivity status is returned to the application.
ESPDevice
object is virtual representation of ESP-32/ESP32-S2/ESP8266 devices. It provides interface to interact with devices directly in a simpler manner. ESPProvisionManager
is a singleton class that encompasses APIs for managing these objects. ESPDevice
instances can be obtained from any of the following techniques :
ESPProvision supports searching of BLE devices which are currently in provisioning mode. It returns list of devices that are discoverable and matches the parameter criteria.
ESPProvisionManager.shared.searchESPDevices(devicePrefix:"Prefix", transport:.ble, security:.secure) { deviceList, _ in
}
Transport parameter is medium of data transmission, ESPProvision support .softAP and .ble transport. Security parameter describe if connection needed to be secure or unsecure. SoftAP search is not supported in iOS currently.
Device information can be extracted from scanning valid QR code. User of this API decides the camera preview layer frame by providing UIView
as parameter. It return single ESPDevice
instance on success. Supports both SoftAP and BLE.
ESPProvisionManager.shared.scanQRCode(scanView: scannerView) { espDevice, _ in
}
ESPDevice
can be also created by passing necessary parameters as argument of below function.
ESPProvisionManager.shared.createESPDevice(deviceName: deviceName, transport: transport, security: security){ espDevice, _ in
}
The main feature of ESPProvision library is to provision ESP devices. Once we get instance of ESPDevice
from above APIs we need to establish session with the device before we can transmit/receive data from it. This can be achieved by calling connect
as shown below :
espDevice.connect(delegate: self) { status in
}
Delegate is required to get Proof of Possession from user, if device has pop capability.
Return proof of possession for the device as shown below from delegate class :
func getProofOfPossesion(forDevice: ESPDevice, completionHandler: @escaping (String) -> Void) {
completionHandler(proofOfPossession)
}
For security version 2, provide username as shown below from delegate class :
func getUsername(forDevice: ESPProvision.ESPDevice, completionHandler: @escaping (String?) -> Void) {
completionHandler(username)
}
If status is connected then application can proceed to scan list of available networks visible to device. This list can be used to give option to the user to choose network of their own choice.
espDevice.scanWifiList { wifiList, _ in
}
User can choose to apply Wi-Fi settings from the above list or choose other Wi-Fi network to provision the device.
espDevice.provision(ssid: ssid, passPhrase: passphrase) { status in
}
-
Since iOS 13, apps that want to access SSID (Wi-Fi network name) are required to have the location permission. Add key
NSLocationWhenInUseUsageDescription
in Info.plist with proper description. This permission is required to verify iOS device is currently connected with the SoftAP. -
Since iOS 14, apps that communicate over local network are required to have the local network permission. Add key
NSLocalNetworkUsageDescription
in Info.plist with proper description. This permission is required to send/receive provisioning data with the SoftAP devices.
ESPProvision is released under the Apache License Version 2.0.