Chapter 2. API Reference
scanned. One may need to adjust this parameter as having only few channels in a group may slow down
the overall scan time, while having too many may again cause disconnection. Usually a value of 4 should
work for most cases. Note that for any other mode of transport, e.g. BLE, this can be safely set to 0, and
hence achieve the fastest overall scanning time.
– period_ms (input) - Scan parameter specifying how long to wait on each channel
• scan_status - Gives the status of scanning process :
– scan_finished (output) - When scan has finished this returns true
– result_count (output) - This gives the total number of results obtained till now. If scan is yet happening
this number will keep on updating
• scan_result - For fetching scan results. This can be called even if scan is still on going
– start_index (input) - Starting index from where to fetch the entries from the results list
– count (input) - Number of entries to fetch from the starting index
– entries (output) - List of entries returned. Each entry consists of ssid, channel and rssi information
Additional Endpoints In case users want to have some additional protocomm endpoints customized to their re-
quirements, this is done in two steps. First is creation of an endpoint with a specific name, and the second step is
the registration of a handler for this endpoint. See protocomm for the function signature of an endpoint handler.
A custom endpoint must be created after initialization and before starting the provisioning service. Whereas, the
protocomm handler is registered for this endpoint only after starting the provisioning service.
wifi_prov_mgr_init(config);
wifi_prov_mgr_endpoint_create("custom-endpoint");
wifi_prov_mgr_start_provisioning(security, pop, service_name, service_
,→key);
wifi_prov_mgr_endpoint_register("custom-endpoint", custom_ep_handler,␣
,→custom_ep_data);
When the provisioning service stops, the endpoint is unregistered automatically.
One can also choose to call wifi_prov_mgr_endpoint_unregister() to manually deactivate an endpoint
at runtime. This can also be used to deactivate the internal endpoints used by the provisioning service.
When / How To Stop Provisioning Service? The default behavior is that once the device successfully connects
using the Wi-Fi credentials set by the apply_config command, the provisioning service will be stopped (and BLE
/ SoftAP turned off) automatically after responding to the next get_status command. If get_status command is not
received by the device, the service will be stopped after a 30s timeout.
On the other hand, if device was not able to connect using the provided Wi-Fi credentials, due to incorrect SSID /
passphrase, the service will keep running, and get_status will keep responding with disconnected status and reason for
disconnection. Any further attempts to provide another set of Wi-Fi credentials, will be rejected. These credentials
will be preserved, unless the provisioning service is force started, or NVS erased.
If this default behavior is not desired, it can be disabled by calling wifi_prov_mgr_disable_auto_stop().
Now the provisioning service will only be stopped after an explicit call to
wifi_prov_mgr_stop_provisioning(), which returns immediately after scheduling a task for stopping
the service. The service stops after a certain delay and WIFI_PROV_END event gets emitted. This delay is specified
by the argument to wifi_prov_mgr_disable_auto_stop().
The customized behavior is useful for applications which want the provisioning service to be stopped some
time after the Wi-Fi connection is successfully established. For example, if the application requires the de-
vice to connect to some cloud service and obtain another set of credentials, and exchange this credentials
over a custom protocomm endpoint, then after successfully doing so stop the provisioning service by calling
wifi_prov_mgr_stop_provisioning() inside the protocomm handler itself. The right amount of de-
lay ensures that the transport resources are freed only after the response from the protocomm handler reaches the
client side application.
Application Examples
For complete example implementation see provisioning/wifi_prov_mgr
Espressif Systems 684
Submit Document Feedback
Release v4.4
To Next Page
Loading...