Troubleshooting

Sample app

If you encounter any issues when using the Home APIs, you can collect logs for further debugging. Collecting logs from the mobile device requires Android Debug Bridge (adb). If you need assistance from Google, collect the logs from both the Android devices and the hub and open a ticket in the issue tracker with the relevant information and logs associated with it.

Collect Android logs

Your mobile device must be connected to your local machine for all steps involving adb.

Install adb

If you haven't already, set up Android Debug Bridge on your local machine:

Install "adb" on your computer.
Turn on Developer Options and USB Debugging on your Android phone.

Google Home Plugin for Android Studio

The Google Home Plugin for Android Studio is a helpful tool for collecting and analyzing logs, and was created specifically for Google Home platform developers. This plugin gives you access to Google Assistant Simulator, Cloud Logging, and other tools to simplify your smart home development process.

Use this tool in conjunction with adb to further analyze Matter device logs.

To learn more and to get the tool, see Google Home Plugin for Android Studio.

Version information

We recommend gathering all version information related to your setup whenever you decide to collect logs. This is required if you need to share issues with Google.

Get the ID of your mobile device:

adb devices

List of devices attached
device-id    device

Store this value in a variable called phoneid:
```
phoneid=device-id
```

Save various device information to variables:

containerinfo=$(adb -s $phoneid shell dumpsys package com.google.android.gms | grep "versionName" || true);
homemoduleinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.home " || true);
optionalhomemoduleinfo=$(adb -s $phoneid  shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.optional_home " || true);
policyhomemoduleinfo=$(adb -s $phoneid  shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.policy_home" || true);
threadinfo=$(adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "com.google.android.gms.threadnetwork" || true);
ghainfo=$(adb -s $phoneid shell dumpsys package com.google.android.apps.chromecast.app | grep versionName || true);
enabledfeatures=$((adb -s $phoneid shell dumpsys activity provider com.google.android.gms.chimera.container.GmsModuleProvider | grep "Enabled features" | grep -i "home") || true);
androidversion=$(adb -s $phoneid shell getprop ro.build.version.release || true);
androidapiversion=$(adb -s $phoneid shell getprop ro.build.version.sdk || true)

Save all variables to a file named _versions.txt:

Expand to show commands to save variables to a file

The entire block can be copied and pasted to a terminal at once.

versionfile=$logtimestamp"_versions.txt"
echo "Saving version info to $versionfile"

echo "Container version:" >> $versionfile
echo $containerinfo >> $versionfile
echo "" >> $versionfile

echo "Home Module version:" >> $versionfile
echo $homemoduleinfo >> $versionfile
echo "" >> $versionfile

echo "Optional Home Module version:" >> $versionfile
echo $optionalhomemoduleinfo >> $versionfile
echo "" >> $versionfile

echo "Policy Home Module version:" >> $versionfile
echo $policyhomemoduleinfo >> $versionfile
echo "" >> $versionfile

echo "Thread Module version:" >> $versionfile
echo $threadinfo >> $versionfile
echo "" >> $versionfile

echo "GHA version:" >> $versionfile
echo $ghainfo >> $versionfile
echo "" >> $versionfile

echo "Android version: " >> $versionfile
echo $androidversion >> $versionfile
echo "" >> $versionfile

echo "Android API version: " >> $versionfile
echo $androidapiversion >> $versionfile
echo "" >> $versionfile

echo "Found enabled features (blank if missing):" >> $versionfile
echo $enabledfeatures >> $versionfile
echo "" >> $versionfile

Verify the contents of _versions.txt:

cat _versions.txt

Expand to show sample file output

Container version:
versionName=23.19.12 (190400-530524295) versionName=22.46.17 (190408-491726958)

Home Module version:
com.google.android.gms.home [v230508900]

Optional Home Module version:


Policy Home Module version:
com.google.android.gms.policy_home [230508900] [230508900065.505615668.505615668] [Download:000003be/dl-Home.integ_230508900100400.apk] [download:/Home.integ/230508900100400:Home.integ:230508900100400]

Thread Module version:
com.google.android.gms.threadnetwork [v231912000]

GHA version:
versionName=3.2.32.1

Android version:
13

Android API version:
33

Found enabled features (blank if missing):

This file can now be provided to Google as needed for troubleshooting.

Collect logs

To collect logs, close all the apps that are running on the mobile device. Then:

Open a terminal window and clear the existing device logs:
```
adb logcat -b all -c
```
Start the log collection process:
```
adb logcat >> _logs.txt
```
Leave this terminal open. This will collect logs from your device as long as the process is running.
Run the sample app and capture all the user interface actions. Once you are done, stop the logcat process running on the terminal by pressing Ctrl+C (or Cmd+C on Mac).
Logs from this session are saved in a file named _logs.txt.

You can analyze the info on this file by various ways, including searching for keywords such as error, exception, or crash.

Log scripts

For your convenience, the sample app provides scripts to obtain the relevant logs and compiles them into a text file. To provide the best debugging experience, these logs should be attached to any bugs reported to facilitate root cause analysis by Google.

These logs are located in the scripts directory in the sample app source tree. To execute them, follow the steps below from the project root directory:

Get the ID of your mobile device:

adb devices -l

List of devices attached
device-id device

Run the get_logs.sh script:

 ./scripts/get_logs.sh device-id

Cleared previous logs from device.
Saving version information to home_api_sample_logs_20240605233243.txt...
Saving logs to home_api_sample_logs_20240605233243.txt...
(Press CTRL+C to stop the script)

Reproduce the issue.
Press CTRL+C to stop the script.

The script will generate a timestamped log file which contains all of the relevant information. Attach these to any reports for bugs that you encounter.

Cast hub device logs

You can view device logs for your Google hub by doing the following:

Set up Android Debug Bridge.
Get the IP address of your hub:
- From the hub, if it has a screen:
  1. Swipe down from the top of the screen
  2. Tap the Settings icon
  3. Find the device IP address: On a Nest Hub (2nd gen), go to Device information > Technical information > IP Address
- From GHA on your phone:
  1. Tap the device to bring up the device details page
  2. Tap the Settings icon to bring up the settings page
  3. Find the device IP address: go to Device information > Technical information > IP address
On a computer on the same Wi-Fi network as the device:
```
  adb connect ip-address
  adb logcat
```
To provide logs to someone, perform the operation that is failing and pipe the output to a text file:
```
  adb logcat -d > platform-logs.txt
```

Automations

Edge detection

Automations in the Google Home ecosystem feature edge detection, which is logic that ensures a starter only activates when there is an actual state change, as opposed to a state update which merely repeats the previous state of the device.

For example, if turning on a light is a starter, edge detection ensures the starter only activates if that light device goes from off to on, as opposed to from on to on (no change).

Automation doesn't behave as expected

After accounting for edge detection, if an automation doesn't behave as expected:

Check each device to make sure that it is functioning properly independent of your automation.
Have a look at the automation graph for your automation, comparing it against your automation DSL, to reveal any potentially incorrect assumptions on your part.
Observe device state in the Google Home app during the execution of your automation.
Check to make sure that all the devices referenced by the automation are present in the structure where you expect them to be. Deleting a device that an automation depends on can have unintended consequences. See Impact of device deletion on automations.

Automation runs when it shouldn't

If your automation runs when it shouldn't, examine the starter criteria. It may be necessary to add additional logic to ensure that a change in state is captured only once and triggers the automation only once.

Automation doesn't compile

Ensure that your app contains all the necessary imports, including each class corresponding to the different node types as well as the traits you're referencing.

Automation creation fails validation

If automation creation does not pass validation, a warning or error message provides information about the issue. For more information, refer to the ValidationIssueType reference.

List function throws exceptions

When calling the Automation API List function, read handlers may throw exceptions due to missing API features. To mitigate this, delete the affected automation.

To do this:

Ensure you have adb installed. See Install adb.

Retrieve the ID of the automation from the Android logs by invoking:

adb logcat -s GhpNative

Example logs:

adb logcat -s GhpNative level:debug | grep -A 10 -B 10 AutomationManagerTrait\.ListResponse

INTERACTION RESPONSE -> SendCommandsResponse:
1 {
1: "automation@global"
3 {
  1: "home.internal.traits.automation.AutomationManagerTrait.ListResponse"
  2:
  5 {
    1: "type.googleapis.com/home.internal.traits.automation.AutomationManagerTrait.ListResponse"
    1 {
        1: "1111-2222-3333-44444-55555" // Automation ID to delete
        2: "structure@2222-3333-4444-5555-6666"
...

If multiple automation IDs need to be deleted, you can use your terminal pager to control the output:

adb logcat -s GhpNative level:debug | less

Delete the automation using the automation's ID:

structure.deleteAutomation(new object : HasId(id = "1111-2222-3333-44444-55555"))

Discovery API logs a warning when a trait is unregistered

If the Discovery API logs a warning for Trait not found, this means the API is trying to use the trait for Discovery candidates, but it won't succeed because the trait was not registered during initialization. For example:

09-03 17:45:20.578 10646 10646 W AutomationSdk: trait_id: "home.matter.6006.clusters.fc43" and Exception occurred com.google.home.HomeException: 18: Trait not found: home.matter.6006.clusters.fc43
09-03 17:45:20.578 10646 10646 W AutomationSdk: While converting candidate: # com.google.home.platform.traits.AutomationCandidateNode@76f0b582

The trait identifier is home.matter.6006.clusters.fc43, which corresponds to RelativeHumidityControl. To determine the trait name from an ID, see the Trait index.

From this example, RelativeHumidityControl needs to be registered during app initialization. Refer to Registering traits to add your trait to the registry.

OAuth

If you have an existing OAuth client

If you already have a verified OAuth client for a published app, you can use your existing OAuth client to test the Home APIs.

Google Home Developer Console registration is not required to test and use the Home APIs. However, you will still need an approved Developer Console registration to publish your app, even if you have a verified OAuth client from another integration.

The following considerations apply:

There is a 100-user limit when using an existing OAuth client. For information about adding test users, refer to Set up the OAuth consent screen. Independent of OAuth verification, there is a Home APIs-imposed limit of 100 users who can grant permissions to your application. This limitation is lifted upon completion of Developer Console registration.
Developer Console registration should be sent for approval when you are ready to restrict device-type grants through OAuth in preparation for updating your app with the Home APIs.

Important: The Google Home Developer Console is not yet available for registration.

For Google Cloud apps that are still pending OAuth verification, users can't complete the OAuth flow until verification is complete. Attempts to grant permissions will fail with the following error:

Access blocked: <Project Name> has not completed the Google verification process.