AoG ProTips: Inspecting Home Graph
By: Dave Smith
Tags: IoT, Actions On Google, Google Assistant

Missed our weekly video? Don’t worry, watch this week’s #AoGProTips 🎥

Google’s Home Graph provides contextual data about the home and its devices, creating a logical map of the home. This enables users to target devices by room or implicitly make commands when you are located in the same room. Most of the data is populated by your smart home Action, and accurate Home Graph data is critical to providing the best user experience through the Assistant.

In addition to the Report State and Request Sync methods that your cloud service invokes, the Home Graph API includes methods that are useful during development to validate the device capabilities and state data reported by your Action.

Let’s explore how we can use the Home Graph API to validate the SYNC response and debug Report State.

Obtain a service account key

The Home Graph API requires authorization to access the device data in your project. Use the following steps to create a new service account credential associated with your smart home Action project.

In the Google Cloud Platform Console, go to the Create service account key page. From the Service account list, select New service account. In the Service account name field, enter a name. From the Role list, select Service Accounts > Service Account Token Creator. For the Key type, select the JSON option. Click Create.

Download the JSON credentials to your computer as service-account.json .

Initialize a Home Graph client

The Google APIs Node.js Client library includes bindings for the Home Graph API, so we can build a simple Node.js script as a client interface with just a few lines of code. You can install the client library as a dependency using NPM:

$ npm install googleapis

Inside your script, use the following code to instantiate an authenticated client for the Home Graph API with your JSON service account credentials.

const {google} = require('googleapis');

const credentials = require('./service-account.json');

const auth = new google.auth.GoogleAuth({

credentials: credentials,

scopes: ['

}); // Create an authorized client for Home Graphconst auth = new google.auth.GoogleAuth({credentials: credentials,scopes: [' https://www.googleapis.com/auth/homegraph' }); const homegraph = google.homegraph({

version: 'v1',

auth: auth,

});

Note: Home Graph API bindings are also available in Java.

Inspect SYNC metadata

Using the sync method, you can verify the metadata in Home Graph for the devices associated with a given agentUserId provided by your smart home Action.

// Request set of devices for the given user

async function sync(homegraph, userId) {

const request = {

requestBody: {

agentUserId: userId,

}

}; return await homegraph.devices.sync(request);

}

This data is populated in Home Graph by SYNC intent response, and it’s a good way to verify that the types, traits, and attributes for each of your user’s devices are reported properly.

Query device state

Using the query method, you can request the state data stored in Home Graph for devices associated with your smart home Action. This data is provided by your Report State implementation, keeping Home Graph state in sync with your service. You should verify that the data for each device is not missing or incomplete.

// Request the current state of a given user's device

async function query(homegraph, userId, deviceId) {

const request = {

requestBody: {

agentUserId: userId,

inputs: [{

payload: {

devices: [{

id: deviceId

}]

}

}]

}

}; return await homegraph.devices.query(request);

}

Note that QUERY intent responses do not update Home Graph state. If you see incomplete state data in Home Graph, it means you need to modify how and when you call Report State to provide a more complete picture.

Report State Dashboard

An alternative way to visualize your Home Graph data is with the Report State Dashboard. The dashboard is a frontend web application written in Java that provides a graphical interface to review device states for a given agentUserId in your project.

Download the source from GitHub and follow the instructions in the README to get started.

Report State Dashboard UI

For more helpful tips on getting the most out of your actions, be sure to check out the rest of the AoG ProTips series — and share your tips with us on Twitter using the hashtag #AoGProTips.