Google Home UI Automator

Matter    Device SDK

Google Home UI Automator can help you automate your Google Home app (GHA) to commission, decommission Matter, or run a regression test on your commission.

This figure shows how to pair a Matter device to Google Home


To use Google Home UI Automator, have the following ready:

Python 3

It is recommended to use Python 3 environment to run the script. Google Home UI Automator requires python 3.11 or newer.

Android phone

  1. Turn on User Debugging mode on your Android phone. See Enable Developer options to turn on the debugging setting.
  2. Connect your Android phone to your computer.

Google Home app

  1. Install GHA on your Android phone. Make sure the GHA's version is or higher.
  2. Login to your Google Account in GHA.

Install Google Home UI Automator

There are two ways to install Google Home UI Automator, PyPI or from source code. We recommend installing with PyPI.

pip install google-home-ui-automator

Build from source code

To build from a source code, follow these steps in your terminal:

  1. Clone this repository:

    git clone
  2. Navigate to the cloned repository:

    cd ui-automator
  3. Run the following command:

    pip install .

Commission a Matter device

To commission a Matter device, enter the following command:

ui-automator --commission DEVICE_NAME,PAIRING_CODE,ROOM_NAME
Input value Description Example
DEVICE_NAME Selected Matter device. m5stack
PAIRING_CODE Pairing code of your Matter device. 34970112332
ROOM_NAME Assigned room. Office

This figure shows how to pair a Matter device to Google Home

Decommission a Matter device

To decommission a Matter device, enter the following command:

ui-automator --decommission DEVICE_NAME
Input value Description Example
DEVICE_NAME Displays name of commissioned Matter device on GHA. m5stack
This figure shows the icons for providing feedback and reporting
       issues in Google Home Playground.

Run a Regression Test

To run a regression test, enter the following code. You must include flag --regtest and --commission to run the regression test.

ui-automator --commission DEVICE_NAME,PAIRING_CODE,ROOM_NAME --regtest [--repeat REPEAT_TIMES] [--hub HUB_VERSION] [--dut MODEL,TYPE,PROTOCOL] [--fw DEVICE_FIRMWARE]

The regression test only supports the commissioning and decommissioning cycle. By default, the regression test will run until users use the keyboard to stop the process.

You can add the following for more in-depth test results:

Value Input value Description Example
--repeat REPEAT_TIMES Run regression test in limited times and repeated times. 5
--hub HUB_VERSION Hub version for controlling devices on GHA. 15.20221210.3.1
--dut Device under test.
MODEL Device model. X123123
TYPE Device type. LIGHT
PROTOCOL Device protocol. MATTER
--fw DEVICE_FIRMWARE Device firmware. 2.2.0

This figure shows the regression test summary


To submit your thoughts or feedback on how to improve your experience with the Google Home UI Automator, complete our Feedback Form.

Report issues

Report encountered issues using the issue tracker.