Native Bridge
The Device commissioning guide covers the SDK APIs your app calls (startCommissioning, issueNodeNoC, confirmMatterNodeCommissioning). This page documents the native bridge — how React Native, platform Matter UI, the Connected Home IP (CHIP) stack, and Headless JS work together during commissioning.
Wire a Commission Adaptor (generateCSR, startEcosystemCommissioning, postMessage) before these flows run — use the Home app ESPMatterAdapter. These guides describe the reference architecture in esp-rainmaker-home; adapt file names and module boundaries to your project.
Layers
| Layer | Responsibility |
|---|---|
| Feature UI | Commissioning screen, progress, navigation on terminal success |
| Store / CDF | Active home, fabric prep, fabric.startCommissioning(qr) |
| Matter SDK (JS) | Cloud APIs: user NoC, node NoC, confirm commissioning |
| Native adaptor | ESPMatterCommissioningAdaptor → NativeModules.ESPMatterModule |
| Platform native | System Matter UI, CHIP ChipDeviceController, Headless JS tasks |
Commissioning always crosses these layers. The SDK orchestrates cloud calls; native code owns the radio, PASE session, and NOC install on the device.
Platform guides
| Platform | How it works | Guide |
|---|---|---|
| Android | ChipTool UI + ChipDeviceController; cloud via Headless JS | Android native bridge |
| iOS | MatterSupport + MTRDeviceController; cloud on main RN | iOS native bridge |
Phase-by-phase detail is in each bridge guide (phases 0–8).
Shared concepts
These terms appear across both platform guides:
| Term | Meaning |
|---|---|
| PASE | Password Authenticated Session Establishment — secure channel to an uncommissioned device |
| NOC | Node Operational Certificate — identity on the Matter fabric |
| CSR | Certificate Signing Request |
| CAT | Case Authenticated Tag — fabric permission tag used in ACLs |
| IPK | Identity Protection Key — fabric-wide key for CASE sessions |
| CHIP | Connected Home IP — Matter protocol stack (ChipDeviceController in native) |
Two different CSRs
- User NOC (fabric bootstrap) — The phone’s admin identity. Generated via
generateCSR()in secure storage (Android KeyStore / iOS Keychain), signed by RainMaker as a user operational cert. Used by the native commissioner on the fabric. - Device node NOC (during commission) — The Matter device’s identity. The device generates its own CSR during commissioning; RainMaker signs a node operational cert; CHIP installs it on the device.
Terminal success by platform
iOS
On iOS, there is a single terminal COMMISSIONING_COMPLETE with source: IOS_MATTER_FRAMEWORK. Intermediate NODE_NOC_REQUEST and COMMISSIONING_CONFIRMATION_REQUEST events are handled by the SDK — not terminal for your UI.
Android
On the default ChipTool build, terminal success is a single COMMISSIONING_COMPLETE with source: HEADLESS_JS after cloud confirm. Native failures from ChipToolCommissioningActivity use source: CHIP_TOOL.
If you build with MATTER_COMMISSIONING_METHOD=GooglePlayServices, an extra intermediate complete may appear:
| Event | Source | Meaning | UI action |
|---|---|---|---|
| COMMISSIONING_COMPLETE | GPS_SERVICE | Legacy GPS path — CHIP leg done, cloud pending | Ignore (not terminal) |
| COMMISSIONING_COMPLETE | HEADLESS_JS | Cloud confirmed, node registered | Success → refresh + navigate |
See Phase 8 — UI success for isMatterCommissioningTerminalComplete().
Where to start
- Read Matter adapters for the TypeScript interface contract.
- Read Device commissioning for
startCommissioningand manual flows. - Implement the platform guide:
- Android native bridge — Phase 0 through Phase 8
- iOS native bridge — Phase 0 through Phase 8