Wi-Fi Provisioning Service
This library implements a Bluetooth® GATT service for Wi-Fi® provisioning. It is to be used with the Wi-Fi: Bluetooth LE based provision sample. The Wi-Fi Provisioning Service forms a complete reference solution, together with the mobile application. For details, see the Wi-Fi: Bluetooth LE based provision sample documentation.
Overview
The service is divided into three parts:
GATT service interface: Defines GATT service and provides an interface for the configurator to exchange messages.
Task and event handling component: Handles provisioning-related tasks and events.
Configuration management component: Manages the provisioning data (in RAM and flash) accessed by multiple threads.
Service declaration
The Wi-Fi Provisioning Service is instantiated as a primary service. Set the service UUID value as defined in the following table.
Service name |
UUID |
Wi-Fi Provisioning Service |
|
Service characteristics
The UUID value of characteristics are defined in the following table.
Characteristic name |
UUID |
Information |
|
Operation Control Point |
|
Data Out |
|
The characteristic requirements of the Wi-Fi Provisioning Service are shown in the following table.
Characteristic name |
Requirement |
Mandatory properties |
Optional properties |
Security permissions |
|---|---|---|---|---|
Information |
Mandatory |
Read |
No security required |
|
Operation Control Point |
Mandatory |
Indicate, Write |
Encryption required |
|
Operation Control Point - Client Characteristic Configuration descriptor |
Mandatory |
Read, Write |
Encryption required |
|
Data Out |
Mandatory |
Notify |
Encryption required |
|
Data Out - Client Characteristic Configuration descriptor |
Mandatory |
Read, Write |
Encryption required |
The purpose of each characteristic is as follows:
Information: For client to getInfomessage from server.Operation Control Point: For client to sendRequestmessage to server, and server to sendResponsemessage to client.Data Out: For server to sendResultmessage to the client.
Task and event handling
The Wi-Fi Provisioning Service uses Protocol Buffers to define platform-independent message formats.
These definitions are available as .proto files in the code.
The service also uses nanopb to convert encoded platform-independent messages to and from C language.
The device performs actions according to messages it exchanges with a configurator (the peer that sends the message, such as a smartphone running the nRF Wi-Fi Provisioner app listed in Requirements).
Message types
The service uses four message types:
Info: Allows the configurator to know the capability of a device before the provisioning process happens.The configurator reads this message before sending any other messages. The info message contains a
versionfield.Request: Contains a command and configuration.The device takes action based on the command and applies the configuration if one is given.
The following table details the five commands that the service uses.
Command
Description
Notes
GET_STATUS
Get the status of the device, such as provisioning state, Wi-Fi connection state, and more
START_SCAN
Trigger an access point (AP) scan
scan_paramsis optionalSTOP_SCAN
Stop AP scan
SET_CONFIG
Store Wi-Fi configuration and connect to an AP
configis requiredFORGET_CONFIG
Erase the configuration and disconnect
Response: Contains the command to which it is responding, the operation result, and any other data.The device sends any additional data associated with this command to the configurator in a
Resultmessage.The
Responsemessage contains one of following response codes:SUCCESS: The operation is dispatched successfully.INVALID_ARGUMENT: The argument is invalid.INVALID_PROTO: The message cannot be encoded or decoded.INTERNAL_ERROR: The operation cannot be dispatched properly.
If the command is
GET_STATUS, the response includes some or all of the following fields:state: Describes the Wi-Fi connection state according to values defined in thecommon.protofile.provisioning_info: Includes Wi-Fi provisioning information stored in the non-volatile memory (NVM) of the device.connection_info: Includes Wi-Fi connection details.scan_info: Includes the parameters used for the AP scan.
Result: Carries asynchronous data about the operation status.If the command is
START_SCAN, the result message sent to the configurator contains information about the AP. EachResultcontains information related to one AP.If the command is
SET_CONFIG, when the Wi-Fi status changes (for example, from disconnected to connected), the configurator receives a result message with the new status. Meanwhile, the Wi-Fi credentials are stored in the non-volatile memory of the device.
See all definitions in the .subsys/bluetooth/services/wifi_prov/proto/common.proto file.
Operations
The message sequence is the same for all operations, with variations depending on the command:
The configurator sends an encoded
Requestmessage with a command to the device.The device carries out the command.
The device sends a
Responsemessage to the configurator.For some operations, the device also sends a
Resultmessage to the configurator with any additional data generated or reported.
See Message types for more information on the commands and additional parameters.
Configuration management
The configuration management component manages Wi-Fi configurations. It uses the Wi-Fi credentials library to handle the configurations in flash. The component has one slot in RAM to save the configurations.
You can save the configuration in flash or RAM during provisioning.
API documentation
include/bluetooth/services/wifi_provisioning.hsubsys/bluetooth/services/wifi_prov