This is the description of the Improv Wi-Fi protocol using Bluetooth Low Energy.

The protocol has two actors: the Improv service running on the gadget and the Improv client.

The Improv service will broadcast its presence via Bluetooth LE and receives Wi-Fi credentials from the client.

The Improv client detects the service via Bluetooth LE and will offer the user to send Wi-Fi credentials.

Improv Service

The Improv service runs on a gadget that needs to connect to the internet but has no credentials or is unable to establish a connection.

The Improv service can optionally require physical authorization to allow pairing, like pressing a button. It is up to the gadget to decide if and what interaction to pick. A gadget that does not require authorization should start in the "authorized" state.

If an Improv service has been authorized by a user interaction, the authorization should be automatically revoked after a timeout. This timeout is up to the gadget but we suggest 1 minute.

A user is able to send Wi-Fi credentials to an authorized service. The gadget will attempt to connect to the specified wireless network. If the connection is successful, the state changes to "provisioned", the gadget can optionally return a URL to the client to finish onboarding and the Improv service is stopped.

If the gadget is unable to connect an error is returned. If the gadget required authorization, the authorization reset timeout should start over.

The client is able to send an identify command to the Improv service if it is in the states "Require Authorization" and "Authorized". When received, and enabled, the gadget will identify itself, like playing a sound or flashing a light. It is up to the gadget to decide if and what interaction to pick.

Revision history

• 1.0 - Initial release
• 2.0 - Added Service Data 4677

GATT Services

Characteristic: Capabilities

Characteristic UUID: 00467768-6228-2272-4663-277478268005

This characteristic has binary encoded byte(s) of the device’s capabilities.

Characteristic: Current State

Characteristic UUID: 00467768-6228-2272-4663-277478268001

This characteristic will hold the current status of the provisioning service and will write and notify any listening clients for instant feedback.

Characteristic: Error state

Characteristic UUID: 00467768-6228-2272-4663-277478268002

This characteristic will hold the current error of the provisioning service and will write and notify any listening clients for instant feedback.

Characteristic: RPC Command

Characteristic UUID: 00467768-6228-2272-4663-277478268003

This characteristic is where the client can write data to call the RPC service.

Note: if the combined payload is over 20 bytes, it will require multiple BLE packets to transfer the data. Make sure that your code deals with this.

RPC Command: Send Wi-Fi settings

Submit Wi-Fi credentials to the Improv Service to attempt to connect to.

Requires the Improv service to be authorized.

Command ID: 0x01

Example: SSID = MyWirelessAP, Password = mysecurepassword

01 1E 0C {MyWirelessAP} 10 {mysecurepassword} CS

This command will generate an RPC result. The first entry in the list is an URL to redirect the user to. If there is no URL, omit the entry or add an empty string.

RPC Command: Identify

What a device actually does when an identify command is received is up to that specific device, but the user should be able to visually or audibly identify the device.

Command ID: 0x02

Does not require the Improv service to be authorized.

Should only be sent if the capability characteristic indicates that identify is supported.

This command has no RPC result.

Characteristic: RPC Result

Characteristic UUID: 00467768-6228-2272-4663-277478268004

This characteristic is where the client can read results from the RPC service if it has a result. Results are returned as a list of strings. An empty list is allowed.

Bluetooth LE Advertisement

The device MUST advertise the Service UUID.

Service UUID: 00467768-6228-2272-4663-277478268000

With version 2.0 of the specification:

• The Service Data and Service UUID MUST be advertised periodically and when the state changes.
• The Service Data and Service UUID MUST be in the same advertisement.
• The Service Data and Service UUID MUST NOT be in the scan response or require active scans.
• If the device cannot fit all of its advertising data in 31 bytes, it should cycle between advertising data.

Service Data format

Service Data UUID: 4677 (00004677-0000-1000-8000-00805f9b34fb)