Chapter 2. API Reference
Table 12: Endpoints provided by Provisioning Service
Endpoint
Name
(BLE +
GATT
Server)
URI (SoftAP + HTTP Server
+ mDNS)
Description
prov-
session
http://<mdns-
hostname>.local/prov-session
Security endpoint used for session establishment
prov-scan http://wifi-prov.local/
prov-scan
Endpoint used for starting Wi-Fi scan and receiving scan results
prov-
config
http://<mdns-
hostname>.local/prov-config
Endpoint used for configuring Wi-Fi credentials on device
proto-ver http://<mdns-
hostname>.local/proto-ver
Endpoint for retrieving version info
Immediately after connecting, the client application may fetch the version / capabilities information from the proto-ver
endpoint. All communications to this endpoint are un-encrypted, hence necessary information (that may be relevant
for deciding compatibility) can be retrieved before establishing a secure session. The response is in JSON format
and looks like : prov: { ver: v1.1, cap: [no_pop] }, my_app: { ver: 1.345,
cap: [cloud, local_ctrl] },..... Here label prov provides provisioning service version (ver) and
capabilities (cap). For now, only no_pop capability is supported, which indicates that the service doesn’t require
proof of possession for authentication. Any application related version / capabilities will be given by other labels (like
my_app
in this example). These additional fields are set using
wifi_prov_mgr_set_app_info().
User side applications need to implement the signature handshaking required for establishing and authenticating secure
protocomm sessions as per the security scheme configured for use (this is not needed when manager is configured to
use protocomm security 0).
See Unified Provisioning for more details about the secure handshake and encryption used. Applications must use the
.proto files found under protocomm/proto, which define the Protobuf message structures supported by prov-session
endpoint.
Once a session is established, Wi-Fi credentials are configured using the following set of wifi_config commands,
serialized as Protobuf messages (the corresponding .proto files can be found under wifi_provisioning/proto) :
• get_status - For querying the Wi-Fi connection status. The device will respond with a status which will be
one of connecting / connected / disconnected. If status is disconnected, a disconnection reason will also be
included in the status response.
• set_config - For setting the Wi-Fi connection credentials
• apply_config - For applying the credentials saved during set_config and start the Wi-Fi station
After session establishment, client can also request Wi-Fi scan results from the device. The results returned is a list
of AP SSIDs, sorted in descending order of signal strength. This allows client applications to display APs nearby
to the device at the time of provisioning, and users can select one of the SSIDs and provide the password which is
then sent using the wifi_config commands described above. The wifi_scan endpoint supports the following protobuf
commands :
• scan_start - For starting Wi-Fi scan with various options :
– blocking (input) - If true, the command returns only when the scanning is finished
– passive (input) - If true scan is started in passive mode (this may be slower) instead of active mode
– group_channels (input) - This specifies whether to scan all channels in one go (when zero) or perform
scanning of channels in groups, with 120ms delay between scanning of consecutive groups, and the value
of this parameter sets the number of channels in each group. This is useful when transport mode is
SoftAP, where scanning all channels in one go may not give the Wi-Fi driver enough time to send out
beacons, and hence may cause disconnection with any connected stations. When scanning in groups, the
manager will wait for atleast 120ms after completing scan on a group of channels, and thus allow the
driver to send out the beacons. For example, given that the total number of Wi-Fi channels is 14, then
setting group_channels to 4, will create 5 groups, with each group having 3 channels, except the last one
which will have 14 % 3 = 2 channels. So, when scan is started, the first 3 channels will be scanned,
followed by a 120ms delay, and then the next 3 channels, and so on, until all the 14 channels have been
Espressif Systems 683
Submit Document Feedback
Release v4.4
To Next Page
Loading...