Phase 4 — BLE scan, GATT, and PASE commissioning

Layer: Native CHIP

After Wi‑Fi credentials are collected, ChipToolBluetoothManager finds the commissionable device over BLE and ChipClient.awaitPairDeviceOverBle drives the full Matter flow in one call: PASE, operational commissioning, network provisioning, and the shared post-commission steps used by RainMaker.

Call chain

Class: ChipToolBluetoothManager

Method	Purpose
getBluetoothDevice(discriminator, isShortDiscriminator, timeoutMs)	BLE scan filtered on Matter commissioning service UUID 0000FFF6-0000-1000-8000-00805F9B34FB and discriminator in advertisement service data
connect(context, device)	GATT connection, MTU request, service discovery; registers GATT with process-wide AndroidBleManager
connectionId	Passed to ChipDeviceController.pairDevice as the BLE connection handle

Default scan timeout in the activity is 35 seconds.

Class: ChipClient — ChipTool entry

Method	CHIP API	Notes
awaitPairDeviceOverBle(deviceId, bleGatt, connId, setupPinCode, networkCredentials)	chipDeviceController.pairDevice(...)	Single suspend until headless confirm calls onCommissioningFullyComplete()
generateDeviceId() (activity)	—	Random non-zero local Matter node id; RainMaker assigns the operational id via NOC issuer

awaitPairDeviceOverBle reuses the same buildCommissioningCompletionListener as the legacy GPS awaitCommissionDevice path, so RainMaker cluster reads, ACL writes, and the confirm Headless task behave identically.

Inside ChipClient (lazy init)

ChipDeviceController.loadJni() → AndroidChipPlatform(...) with shared AndroidBleManager → ChipDeviceController(ControllerParams) with user NOC from KeyStore → setNOCChainIssuer(EspNOCChainIssuer).

Completion semantics

• Success: awaitPairDeviceOverBle resumes only after Phase 7 (handleHeadlessTaskResult → onCommissioningFullyComplete()). The activity then shows success and finish().
• Failure: Exception → notifyCommissioningFailure → EventBus COMMISSIONING_ERROR with source: CHIP_TOOL + chipClient.onCommissioningFailed.

There is no ESPMatterCommissioningService or GPS sendCommissioningComplete in the ChipTool path.

What could go wrong

BLE scan timeout (device not advertising, wrong discriminator, radio off) → user sees “device not found”. GATT connect fails → same. PASE / wrong setup PIN → exception in pairDevice. Missing AndroidBleManager registration → pairing fails at CHIP layer.