Wi-Fi: Provisioning Service

This sample demonstrates how to provision a Wi-Fi® device over a Bluetooth® Low Energy link.

Requirements

The sample supports the following development kit:

Hardware platforms

PCA

Board name

Build target

nRF7002 DK

PCA10143

nrf7002dk_nrf5340

nrf7002dk_nrf5340_cpuapp

nRF5340 DK

PCA10095

nrf5340dk_nrf5340

nrf5340dk_nrf5340_cpuapp

nRF52840 DK

PCA10056

nrf52840dk_nrf52840

nrf52840dk_nrf52840

The sample requires a smartphone (configurator) with Nordic Semiconductor’s nRF Wi-Fi Provisioner app installed in one of the following versions:

Overview

With this sample, you can provision a Wi-Fi device that lacks input or output capability using the Wi-Fi Provisioning Service library. The sample is divided into three parts:

  • Task and event handling component: Handles provisioning-related tasks and events.

  • Transport layer: Based on Bluetooth Low Energy and exchanges information between the device and the nRF Wi-Fi Provisioner app.

  • Configuration management component: Manages the provisioning data (in RAM and flash) accessed by multiple threads.

Configuration

See Configuring your application for information about how to permanently or temporarily change the configuration.

You can enable the WIFI_PROV_ADV_DATA_UPDATE Kconfig option to get the live update of the Wi-Fi status without setting up a Bluetooth connection. When periodic update is enabled, the update interval is controlled by the WIFI_PROV_ADV_DATA_UPDATE_INTERVAL Kconfig option.

Features

The sample implements advertisement feature to advertise over Bluetooth LE.

After powerup, the device checks if it is provisioned. If it is, it loads saved credentials and tries to connect to the specified access point.

Then, the device advertises over Bluetooth LE.

The advertising data contains several fields to facilitate provisioning. It contains the UUID of the Wi-Fi Provisioning Service and four bytes of service data, as described in the following table.

Byte 1

Byte 2

Byte 3

Byte 4

Version

Flag(LSB)

Flag(MSB)

RSSI

  • Version: 8-bit unsigned integer. The value is the version of the Wi-Fi Provisioning Service sample.

  • Flag: 16-bit little endian field. Byte 2 (first byte on air) is LSB, and Byte 3 (second byte on air) is MSB.

    • Bit 0: provisioning status. The value is 1 if the device is provisioned, otherwise it is 0.

    • Bit 1: connection status. The value is 1 if Wi-Fi is connected, otherwise it is 0.

    • Bit 2 - 15: RFU

  • RSSI: 8-bit signed integer. The value is the signal strength. It is valid only if the Wi-Fi is connected.

The advertising interval depends on the provisioning status. If the device is not provisioned, the interval is 100 ms. If it is provisioned, the interval is 1 second.

Building and running

This sample can be found under samples/wifi/provisioning in the nRF Connect SDK folder structure.

To build the sample with Visual Studio Code, follow the steps listed on the How to build an application page in the nRF Connect for VS Code extension documentation. See Building and programming an application for other building and programming scenarios and Testing and debugging an application for general information about testing and debugging in the nRF Connect SDK.

The sample generates header and source files based on protocol buffer definitions in .proto files during the build process. You must install a protocol buffer compiler to generate the files. See the Nanopb sample in the Zephyr documentation for more information.

Testing

After programming the sample to your development kit, complete the following steps to test it:

  1. Connect the kit to the computer using a USB cable. The kit is assigned a COM port (Windows) or ttyACM device (Linux), which is visible in the Device Manager.

  2. Connect to the kit with a terminal emulator (for example, PuTTY). See How to connect with PuTTY for the required settings.

  3. Observe the following output:

    wifi_prov: BT Advertising successfully started

  4. Open the nRF Wi-Fi Provisioner app.

  5. Enable Bluetooth if it is disabled.

  6. Search and connect to the device you want to provision. If the connection and pairing are established, observe the following output:

    wifi_prov: BT Connected: <configurator BT address>
wifi_prov: BT pairing completed: <configurator BT address>, bonded: 0

  7. Start an access point scan.

  8. Enter the password, if required.

  9. Establish a Wi-Fi connection.

  10. Observe the following output, if the connection is successful:

    wpa_supp: wlan0: CTRL-EVENT-CONNECTED - Connection to <AP MAC Address> completed [id=0 id_str=]

Dependencies

This sample uses the following nRF Connect SDK libraries:

This sample also uses a module that can be found in the following location in the nRF Connect SDK folder structure:

  • modules/lib/nanopb

In addition, it uses the following Zephyr libraries:

  • Bluetooth APIs:

    • include/bluetooth/bluetooth.h

    • include/bluetooth/conn.h

    • include/bluetooth/uuid.h

    • include/bluetooth/gatt.h

    • include/net/wifi.h

    • include/net/wifi_mgmt.h