Intent-based Commissioning for Matter

While the Matter SDK provides a Task-based API to start Matter commissioning with varying parameters, observing the result, and optionally adding credentials, there are situations where an entry point of only a QR code is needed. For example, from a generalized camera application that wishes to provide a shortcut to start commissioning when a QR code is seen in the viewfinder.

Before continuing, make sure all Prerequisites have been met.

Matter QR codes

Matter QR codes take the general form of MT:Y3.13OTB00KA0648G00, where the MT: prefix is a constant, and the suffix is a base 38-encoded string using the alphabet [A-Z0-9.-]. The suffix must always be at least 19 characters, but may be longer as well.

Determining whether a QR code represents a Matter QR code can be done with the following regex in Java:

fun isMatterQrCode(value: String): Boolean {
  return value.matches(Regex("""MT:[A-Z0-9.-]{19,}"""))
}

For example, the following QR code represents MT:Y3.13OTB00KA0648G00:

Intent Format

This QR code format may be used as a URI to start the commissioning flow by sending an Intent with ACTION_VIEW, the URI specified in the data, and the target package set to Google Play Services:

fun startCommissioning(context: Context, qrCodeString: String): Boolean {
  val intent =
    Intent(Intent.ACTION_VIEW)
      .setData(Uri.parse(qrCodeString))
      .setPackage("com.google.android.gms")

  try {
    context.startActivity(intent)
    return true
  } catch (ex: ActivityNotFoundException) {
    // Supporting Play Services version not available.
    return false
  }
}

Sample app

This sample app shows how to start commissioning a Matter device when a Matter-compliant QR code is seen in the viewfinder of the camera.

Download the Intent-based Commissioning sample app

The code in this sample app leverages the following Android libraries:

• CameraX
• Barcode Scanning

The following documents are also useful to understand the code written for this sample app:

• Getting Started with CameraX
• Scan Barcodes with ML Kit on Android

Usage

When the app starts, the camera preview is shown on the screen. When a QR code for a Matter device is detected, a dialog is shown to confirm whether commissioning for that Matter device should be performed:

If commissioning is confirmed, then the "App Picker" supported by the Google Home Mobile SDK is launched.

The App Picker initially shows a set of default commissioning applications (for example, the Google Home app as shown on the first screenshot). If one taps on "Choose other app", then other applications that support the Google Home Mobile SDK commissioning flow are shown (see the second screenshot).

The selected application is then launched to perform the commissioning of the device.