Local execution

The Local Home SDK enhances your smart home integration with the Google Assistant by adding a local execution path to route smart home intents.

The SDK lets you write a local execution app, using TypeScript or JavaScript, that contains your smart home business logic. Google Home or Google Nest devices can load and run your app on-device. Your app communicates directly with your existing smart devices over Wi-Fi on a local area network (LAN) to fulfill user commands, over existing protocols.

Integration of the SDK offers performance improvements to your smart home Action, including lower latency and higher reliability. Local execution is supported for all device types and device traits, except those that use two-factor authentication.

Start building Try the sample

Understand how it works

After getting a SYNC response from your cloud fulfillment, the Local Home platform scans the user’s local area network using mDNS, UDP broadcast, or UPnP to discover smart devices connected to the Assistant.

The platform sends an IDENTIFY intent to determine if the device is locally controllable, by comparing the device ID in the IDENTIFY response to those returned by the earlier SYNC response. If the detected device is a hub or bridge, the platform sends a REACHABLE_DEVICES intent and treats the hub as the proxy device for communicating locally.

When it receives a response confirming a local device, the platform establishes a local execution path to the user’s Google Home or Google Nest device, and subsequently routes user commands for local execution.

When a user triggers a smart home Action that has a local execution path, the Assistant sends the EXECUTE intent to the Google Home or Google Nest device rather than the cloud fulfillment. The device then runs the local execution app to process the intent.

This figure shows the execution flow for local execution. The
            execution path captures a user's intent from a phone with the
            Google Assistant, then the user intent is processed by
            the Google Cloud, then it is executed locally on the Google Home
            device and the command is issued directly to the device hub or
            directly to the device. The developer cloud is available as a
            cloud fallback.
Figure 1. Adding a local execution path for your smart home Action.

Local execution app

The local execution app contains the business logic to process the intents sent by the Local Home platform and access your smart device via the local area network. No modification of your hardware is expected to integrate local execution. The app fulfills smart home Action requests by sending control commands to the smart device through application-layer protocols, including HTTPS, TCP, or UDP. In the event that the local execution path fails, your cloud fulfilment is used as a fallback execution path.

To support building the app, the Local Home SDK provides these two main classes:

  • DeviceManager: Provides methods to communicate with smart devices using TCP, UDP sockets, or HTTP/HTTPS requests.
  • App: Provides methods to attach handlers for intents that Google sends after discovering locally-controllable devices (IDENTIFY, REACHABLE_DEVICES) and to fulfill user commands (EXECUTE).

During development, you can build and test the app by loading it on your own hosting server or local development machine. In production, Google hosts your app in a secure JavaScript sandbox environment on the user’s Google Home or Google Nest device.

The Report State API and QUERY intent are not currently supported for local execution. Google relies on your cloud fulfillment to process these requests.

Implementation path

To utilize the Local Home SDK for your smart home integration, you need to perform these tasks:

1 Set up the scan config Configure the Actions console with the necessary parameters for the Assistant to discover locally controllable devices.
2 Update the SYNC response in your cloud fulfillment In your cloud fulfillment, modify the SYNC request handler to support the otherDeviceIds field that the platform uses to establish a local execution path. In that field, specify the IDs of devices that can be locally controlled.
3 Implement the local execution app Use the Local Home SDK to create a JavaScript app to handle the IDENTIFY and EXECUTE intents. For hub or bridge proxy devices, you should also handle the REACHABLE_DEVICES intent.
4 Test and debug your app Test your integration (or self-certify) by using the test suite for smart home.

To start using local execution, see Add local execution to your smart home Action.