Skip to content

Home

Jump to bottom
Michael Hallock edited this page Jul 15, 2018 · 16 revisions

HomeAutio.Mqtt.GoogleHome is a configurable bridge between MQTT and Google Actions Smart Home API fulfillment for home automation purposes. It allows someone to setup their own Smart Home Google Action fulfillment without the need for a cloud based service provider. It provides basic functionality of SYNC, QUERY, and EXECUTE intents, backed by MQTT. It also provides an OAuth implementation to fulfill that Google Action's requirement.

MQTT

All configuration is in the appsettings.json file as "broker" settings. Username and password can be null if not using authentication.

It makes some opinionated assumptions on how MQTT is used:

  1. Device command and state are represented as discrete topics (i.e., "device/blah/set" for changing state, and "device/blah" for reporting state). They don't have to follow this exact scheme, but the two topics MUST be discrete.
  2. State topics are retained. This allows the app to bootstrap its internal state representation.
  3. No complex payloads (i.e., JSON), only simple values. Devices publish multiple state / commands it supports as discrete topics.

When the app starts up, it will subscribe to all "state" topics in the config, and bootstrap its internal state based on any of those topics that are sent due to being "retained". These states will be monitored, and used to return responses for QUERY intents.

Any "EXECUTE" intents sent will find mapped "command" topics in the config to determine where to send updated values from Google Actions.

Note: If you can't guarantee the above MQTT assumptions talking directly to your device handlers, one would have to put something in between and publish to intermediate topics that "translate" to the device specific topics you need. This is beyond the scope of this project.

OAuth

This application contains a basic OAuth 2 server. All configuration is in the appsettings.json file as "oauth" settings. It implements the Authorization Code flow.

Google Action Account Linking

When setting up the "Account linking" in the "Actions on Google" console, follow these instructions.

  1. Select "OAuth" and "Authorization Code".
  2. "Client ID" to the same value used in the config file for oauth.clientId.
  3. "Client secret" to the same value used in the config file for oauth.clientSecret.
  4. "Authorization URL" to your public URL of your application + "/connect/authorize".
  5. "Token URL" to your public URL of your application + "/connect/token".
  6. "Scopes" to "api".

Note: The URLs are the ones exposed by this app. You will need to translate these as appropriate when proxying this app in nginx for SSL, etc. As an example, if your public URL is "https://test.com", and you are proxying this app in nginx as "/google", these URLs would be "https://test.com/google/connect/authorize" and "https://test.com/google/connect/token".

Configuration

The appsettings.json file contains basic application setup that needs to happen.

Configuration Setting Purpose
deviceConfigFile File path to the Google Device configuration file.
googleHomeAgentUserId The unique ID to identify your application to Google Actions.
googleHomeHomeGraphApiKey Your Google Home Graph API key, used for REQUEST_SYNC calls.
brokerIp MQTT Broker IP address.
brokerPort MQTT Broker port, usually 1883.
brokerUsername MQTT Broker username, if applicable.
brokerPassword MQTT Broker password, if applicable.
oauth.authority The URL of your application. Used by the OAuth implementation to validate tokens have been issued from the internal OAuth server.
oauth.requireSSL Turn on/off the OAuth server requiring communication over SSL.
oauth.clientId The Client ID issued by your Actions to Google.
oauth.clientSecret The Client secret you will provide to the Goolge Actions config (Generating a GUID is sufficient).
oauth.resourceName The OAuth resource name. Can probably be left alone.
oauth.subjectId OAuth subject ID, basically only used internally, and can be any GUID.
oauth.username The username that you will login with during account linking in the Google Home App
oauth.password The password that you will login with during account linking in the Google Home App
oauth.redirectUri The "allowed" redirect URI to satisfy the OAuth server's security checks. Should be of the form "https://oauth-redirect.googleusercontent.com/r/YOUR_PROJECT_ID".
oauth.signingCert.file File path to an external certificate if you want to use your own cert for signing. Note, if null, the app will generate a cert at first run called "tempkey.rsa" in the app root
oauth.signingCert.passPhrase Pass phrase to use for decryption of signing cert private key, if needed
Clone this wiki locally