esp_prov library
Provision Espressif devices over Bluetooth LE.
final prov = EspProvisioning();
await for (final device in prov.scan()) {
final session = await device.connect(
credentials: const ProvCredentials.security2(
username: 'wifiprov',
password: 'abcd1234',
),
);
// session.wifi.scan(), session.wifi.provision(...)
}
Classes
- CustomEndpoint
-
An application endpoint the firmware registered with
wifi_prov_mgr_endpoint_create/network_prov_mgr_endpoint_create. - DeviceInfo
-
What the device reports on the
proto-verendpoint. - DiscoveredDevice
- A device found by a ProvScanner.
- EspDevice
- A provisioning device found by EspProvisioning.scan.
- EspProvisioning
- Scans for provisioning devices and opens sessions with them.
- EspSession
- An authenticated provisioning session with one device.
- ProvCredentials
-
Credentials for the security scheme the device declares in
proto-ver. - ProvCtrl
-
Control commands on the
prov-ctrlendpoint. - ProvEndpoints
- Names of the protocomm endpoints every provisioning firmware exposes.
- ProvNoCredentials
- See ProvCredentials.none.
- ProvPopCredentials
- See ProvCredentials.pop.
- ProvQrPayload
-
The JSON payload printed by provisioning firmware as a QR code, e.g.
{"ver":"v1","name":"PROV_1A2B3C","username":"wifiprov","pop":"abcd1234", "transport":"ble"}. - ProvScanner
- Discovers provisioning devices.
- ProvSecurity2Credentials
- See ProvCredentials.security2.
- ProvTransport
- A connected link to a provisioning device.
- Security0
- Security 0: no encryption. Data is sent in plain text.
- Security1
- Security 1: X25519 key exchange, optional proof of possession, and one continuous AES-256-CTR keystream for the session.
- Security2
- Security 2: SRP-6a (3072-bit, SHA-512) authentication and AES-256-GCM.
- SecurityScheme
-
A protocomm security scheme: handshake on
prov-session, then a stateful cipher for every later request and response. - SerialQueue
- Runs asynchronous tasks one at a time, in submission order.
- ThreadApplying
- The dataset is being sent and applied.
- ThreadAttached
- Terminal: the device attached.
- ThreadAttaching
- The device is attaching to the network.
- ThreadFailed
- Terminal: provisioning did not succeed.
- ThreadNetwork
-
A Thread network found by
ThreadProvisioner.scan. - ThreadProvisioner
-
Thread scan and provisioning (
network_provisioningfirmware only). - ThreadProvisionState
-
Progress of
ThreadProvisioner.provision. - UniversalBleDevice
- A provisioning device seen by UniversalBleScanner.
- UniversalBleScanner
-
A ProvScanner backed by
universal_ble. - UniversalBleTransport
-
A ProvTransport over a
universal_bleconnection. - WifiApplying
- Credentials are being sent and applied.
- WifiAttemptFailed
- One connection attempt failed; the device will retry.
- WifiConnected
- Terminal: the device joined the network.
- WifiConnecting
- The device is joining the network.
- WifiFailed
- Terminal: provisioning did not succeed.
- WifiNetwork
-
An access point found by
WifiProvisioner.scan. - WifiProvisioner
-
Wi-Fi scan and provisioning over
prov-scanandprov-config. - WifiProvisionState
-
Progress of
WifiProvisioner.provision.
Enums
- ProvStatus
-
Status codes a protocomm device returns (constants.proto
Status). - ThreadFailureReason
- Why Thread provisioning ended without attaching.
- WifiAuthMode
-
Wi-Fi authentication mode (network_constants.proto
WifiAuthMode). - WifiFailureReason
- Why Wi-Fi provisioning ended without a connection.
Constants
- defaultServiceUuid → const String
- Service UUID ESP-IDF protocomm_ble uses when the application sets none.
- exampleServiceUuid → const String
- Service UUID the ESP-IDF provisioning examples set (esp_prov's fallback).
Exceptions / Errors
- CryptoException
- Encryption or decryption failed, e.g. an AES-GCM tag mismatch.
- DeviceDisconnected
- The link to the device dropped.
- HandshakeFailed
-
The security handshake on
prov-sessionfailed. - MissingCredentials
- The device needs credentials and none (or not enough) were provided.
- PopMismatch
- The device rejected the proof of possession (Security 1) or the username/password proof (Security 2), or its own proof did not verify.
- ProvException
- Base class of every error this library throws on purpose.
- ProvStatusException
- The device answered a request with a non-success status.
- SchemeMismatch
- The credentials kind does not match the security scheme of the device.
- TransportException
- The transport failed: BLE error, timeout, or an unusable session.
- UnknownEndpoint
- The device does not expose the requested protocomm endpoint.
- UnsupportedCapability
- The device firmware does not advertise a capability the call needs.