Skip to main content
Version: 031-rc11

Wi-Fi Provisioning Commands

Provision Pantavisor devices over BLE using the Improv Wi-Fi protocol. All commands require Linux with BLE support.

On the device side these commands talk to pvwificonnect, the core provisioning container shipped in the Pantavisor starter image. It advertises the Improv BLE service by default (no configuration needed) alongside its own setup access point, so a factory-fresh device can be joined to Wi-Fi either over Bluetooth or by joining its pvwificonnect AP.

The Improv BLE client is built into pvr, so this is the only tool you need — there is no separate provisioning binary to install. The same flow is also available in a browser at hub.pantacor.com/provision-wifi (Web Bluetooth: Chrome/Edge, not Firefox or Safari), which then hands you into claiming the device with its ID and challenge prefilled.

Prerequisites: BlueZ running (bluetoothd) and access to the adapter — membership in the bluetooth group, or root.

Addresses are MACs on Linux (AA:BB:CC:DD:EE:FF). Every subcommand below except device-scan takes the address as a positional argument.


pvr wifi device-scan​

Scan for nearby BLE devices advertising the Improv Wi-Fi service.

pvr wifi device-scan
pvr wifi device-scan --timeout=30s
pvr wifi device-scan --json

Flags:

FlagDescription
--timeoutScan duration. Default: 15s. 0 = forever
--jsonEmit one JSON object per device

pvr wifi provision​

Connect to an Improv BLE device and send Wi-Fi credentials.

pvr wifi provision <BLE_ADDRESS> --ssid MyWiFi
pvr wifi provision <BLE_ADDRESS> --ssid MyWiFi --password secret

--ssid is required. If --password is omitted, the command prompts interactively — preferred, since the flag leaks the password into shell history.

Flags:

FlagDescription
--ssidWi-Fi SSID
--passwordWi-Fi password (omit for interactive prompt)
--connect-timeoutBLE connect timeout. Default: 20s
--state-timeoutWi-Fi connection timeout. Default: 60s

pvr wifi identify​

Ask a device to identify itself (e.g. blink an LED or beep).

pvr wifi identify <BLE_ADDRESS>

Flags:

FlagDescription
--connect-timeoutBLE connect timeout. Default: 20s

pvr wifi device-info​

Read firmware and device information from an Improv device.

pvr wifi device-info <BLE_ADDRESS>

Output: firmware name, firmware version, hardware variant, device name.

Flags:

FlagDescription
--connect-timeoutBLE connect timeout. Default: 20s

pvr wifi hostname​

Get or set the device hostname.

pvr wifi hostname <BLE_ADDRESS> # get current hostname
pvr wifi hostname <BLE_ADDRESS> my-device # set hostname

Flags:

FlagDescription
--connect-timeoutBLE connect timeout. Default: 20s

pvr wifi wifi-scan​

Ask a device to scan for nearby Wi-Fi networks and report them.

pvr wifi wifi-scan <BLE_ADDRESS>

Flags:

FlagDescription
--connect-timeoutBLE connect timeout. Default: 20s

pvr wifi claim-info​

Read Pantavisor claim material from a device.

pvr wifi claim-info <BLE_ADDRESS>
pvr wifi claim-info <BLE_ADDRESS> --json

Outputs the device ID and claim challenge needed to claim the device on Pantacor Hub. This is a Pantacor extension to Improv (RPC 0x07, advertised as the pantavisor-claim capability), so it only works against pvwificonnect devices. Retries until the device has claim material — it only exists after the device's first rendezvous with the hub, which needs the Wi-Fi link to be up.

Flags:

FlagDescription
--connect-timeoutBLE connect timeout. Default: 20s
--retry-timeoutTotal retry duration. Default: 60s
--retry-intervalDelay between retries. Default: 5s
--jsonPrint result as JSON

Typical flow​

pvr wifi device-scan # find the device
pvr wifi identify AA:BB:CC:DD:EE:FF # confirm it is the right one
pvr wifi wifi-scan AA:BB:CC:DD:EE:FF # see what it can reach
pvr wifi provision AA:BB:CC:DD:EE:FF --ssid MyWiFi # prompts for password
pvr wifi claim-info AA:BB:CC:DD:EE:FF # device-id + challenge
pvr claim <device-id> --challenge=<challenge> # claim it on the hub

See pvr claim for the claiming step.

  • pvwificonnect — the device-side provisioning container: BLE, setup AP, captive portal, and its config.json
  • Improv Wi-Fi — protocol spec