Android Native Bridge
How Matter commissioning runs on Android with the in-app ChipTool flow: ChipToolCommissioningActivity for onboarding payload parsing, Wi‑Fi credentials, and BLE discovery; ChipDeviceController (Connected Home IP / CHIP) for PASE, commissioning, and NOC install; bridged to React Native via ESPMatterModule and Headless JS for RainMaker cloud APIs.
In one line: The app owns BLE scan, GATT, and Wi‑Fi network credentials; CHIP runs pairDevice over BLE; Headless JS issues the node NOC and confirms commissioning with the cloud.
Paths and class names below match the Espressif RainMaker Home app (MATTER_COMMISSIONING_METHOD=ChipTool by default). Your module names may differ; keep the same responsibilities at each layer.
| Layer | Class / module | Role |
|---|---|---|
| ChipTool UI | ChipToolCommissioningActivity | Parse QR/manual code, Wi‑Fi dialog, BLE scan/connect, progress UI |
| BLE transport | ChipToolBluetoothManager + AndroidBleManager | Matter service 0xFFF6 scan, GATT, register connection with CHIP |
| CHIP | ChipClient → ChipDeviceController (JNI) | pairDevice (PASE + commission + network), NOC issuer, post-commission metadata |
| RN bridge | ESPMatterModule + Headless JS | Fabric hand-off, events, issueNodeNoC / confirmMatterNodeCommissioning |
Build-time back-end selection
ESPMatterModule.startEcosystemCommissioning routes by BuildConfig.MATTER_COMMISSIONING_METHOD (Gradle property MATTER_COMMISSIONING_METHOD, default ChipTool):
| Value | Native entry | When to use |
|---|---|---|
| ChipTool | ChipToolCommissioningActivity | Default — works without Google Play services Matter APIs |
| GooglePlayServices | MatterCommissioningActivity + ESPMatterCommissioningService | Legacy path using GPS Home system UI (not documented in phases 3–4 below) |
Phases (0–8)
Follow these in order. Phases 3–4 describe the ChipTool path.
| Phase | Doc | Summary |
|---|---|---|
| 0 | Screen boot and event listener | Register listener, start fabric prep |
| 1 | Fabric bootstrap | Convert home, issue user NOC |
| 2 | Hand off to native | startEcosystemCommissioning → ChipTool activity |
| 3 | ChipTool commissioning UI | Payload parse, Wi‑Fi credentials, permissions |
| 4 | BLE scan, GATT, and PASE | ChipToolBluetoothManager + awaitPairDeviceOverBle |
| 5 | Device node NOC | Headless JS + cloud node cert |
| 6 | Device commissioned + metadata | RM metadata, ACL, trigger cloud confirm |
| 7 | Cloud confirm | Headless JS confirm with cloud |
| 8 | UI success | Terminal HEADLESS_JS success → toast, sync, home |
Start at Phase 0.
For shared terms (PASE, NOC, terminal vs intermediate events), see Native Bridge.