Blueprint Advanced Protected Device WiFi Provisioning

Difficulty: Advanced

Estimated Time: 1 hour

Hardware Needed: WiFi Particle devices

---

Overview

This blueprint provides an example React application that uses WebBLE to provision network credentials for WiFi enabled Particle devices. This project is broken up into two parts: client, and src/main.cpp. The React client interacts with the device directly over WebBLE and is intended to be easily ported to React Native (mobile) by making use of Expo.

---

Tools & Materials

• Particle WiFi device (Photon 2, Muon, Argon)
• Chrome web browser
• NodeJS installation
• Particle CLI

---

Steps

1. Clone this repository:

   git clone https://github.com/particle-iot/blueprint-advanced-wifi-provisioning.git
   cd blueprint-advanced-wifi-provisioning

2. Start the React client In a terminal instance run the following commands:

   cd client
   npm install
   npm run web

3. Open in a Chrome browser Navigate to localhost:8081

---

Usage

1. Test the provisioning flow

   • With a nearby WiFi capable Particle device powered on, navigate to localhost:8081 in your Chrome browser (Web BLE may not be support on other browsers). Then, choose "Connect" and select your target device:

   • Once paired, click "Scan Networks". At this step, a command will be sent to the device to perform a Wi-Fi scan. Once successful, the list of nearby networks will be displayed in the UI.

   • Select the network SSID you'd like to connect your device to and you'll be prompted to enter the WiFi password. Once the password is sent to the device, wait a few seconds for the device to retry connecting to the network.

2. Validate the credentials

   You can test that the credentials were properly stored by running: particle wifi list in a terminal.

---

How It Works

The main UI lives in client/app/provisioner.jsx and is responsible for interacting with the Particle device over WebBLE.

You'll notice that it makes use of a serviceUUID, rxCharacteristicUUID, txCharacteristicUUID, versionCharacteristicUUID, and a mobileSecret. These values are defined in the firmware (src/main.cpp) and can be customized. It's best to update these fields so that your provisioning tool only works with your hardware.

In client/lib/particleUtils.ts you'll find most of the BLE logic. It makes heavy use of the @particle/ecjpake and @particle/device-os-protobuf libraries in order to properly communicate with Device OS.

All of the actual BLE interaction happens in a global context provider in client/hooks/useBluetooth.tsx. You might start here if you are interested in porting to a mobile environment by swapping WebBLE to a mobile friendly BLE library.

The client/components/bleButtons.tsx component conditionally renders the BLE interaction buttons based on the connection state.

The client/components/scanResults.tsx component renders the list of available SSIDs.

Finally, the client/components/connectDialog.tsx component renders the password input.

---

Topics Covered

• Particle CLI
• WiFi setup options

---

Extensions

You can deploy this application so that your users can directly provision their own devices.