Setup: Google Actions Console

This application needs to be registered with Google as an Action. Make sure you do this with an account that is linked to your Google Home!

Prior to doing this, you must have done the following:

1. Get the application running.
2. Setup a Dynamic DNS address for your public IP. You will need this DNS address for the SSL certificate checks.
3. Forward port 443 through your router to the server at the port that the application is exposed on.
4. Proxy the application through nginx to provide SSL protection, and expose it on port 443 (or map that later in the router, your choice). I recommend looking at Lets Encrypt for the SSL certificate setup.

Register

To register your app, go to Google Actions Console.

1. Create a new project in Actions Console. You can name it anything you want.
2. Skip adding options if presented.
3. On the dashboard for your action, click on "Actions" under the "Build" header in the left hand menu.
4. Add an action, and scroll down until you find "Home Automation" template. Add this Action.
5. You'll be asked for a URL for your action. This should be the publicly accessible URL that you expose for the "smarthome" route. I.e., if proxying this application through nginx at https://mydomain.com/google/home, it would be https://mydomain.com/google/home/smarthome.
6. Back on the dashboard, click on "Invocation" in the menu, and enter a name for your action. This isn't really used, its just a requirement for Google. It has some requirements for this that are documented on that page.
7. Click on "Directory Information" under the "Deploy" menu item, and fill in everything required here. Again, none of this will ever be used because you aren't going to actually publish this Action for others to use, so most of what you put here doesn't matter.

Account Linking

Account linking sets up the OAuth 2 linking to this application.

1. In the Google Actions Console, click on "Account Linking" under "Advanced Options".
2. Select "No, I only want to allow account creation on my website".
3. For "Linking Type", select "OAuth" and "Authorization Code".
4. For "Client Information" you will need to add the following. a. "Client ID" and "Client Secret" should be the values in your appsettings.Production.json configuration file, specified in the "oauth:clients" configuration element. b. "Authorization URL" should be the the publicly accessible route to connect/authorize, for example https://mydomain.com/google/home/connect/authorize c. "TokenURL" should be the the publicly accessible route to connect/token, for example https://mydomain.com/google/home/connect/token
5. "Configure your client" allows you to specify requested OAuth scropes. You must add two: "api" and "offline_access"
6. "Testing instructions" can just be anything, like "Login" or "Test", etc.

Entering Test Mode

If all of this has been setup correctly, you should be able to click on "Actions" in the menu again, and click on "Test" in the upper right. This should expose the application in your Google Home app on your phone. Now when you go into the Google Home app and go to "Home Control" from the menu, and then click the "Add Device" button, you should see something like "[test] your app name" show up as a linking option. Click on this, and it should take you to the login screen for the app, where you put in the credentials you set in the appsettings.Production.json file. It'll ask you to allow Google to have access to some things, which you can just agree to, and then you should see your devices populate for assignment to rooms, etc.

At this point, you should be able to ask Google to "turn on the X" or whatever you setup in your googleDevices.json file, and see the configured MQTT message get sent.

Maintaining Test mode

To maintain test mode, and publish changes to your Action, Google supplies a command line utility called gactions CLI. This is now optional, as Google's Action Console will also let you start an app in test mode now.

Download the utility and put it somewhere you can execute it. Create the following script to call it, replacing YOURPROJECTID with your project id from the Google Actions Console:

#!/bin/sh
./gactions test --action_package action.json --project YOURPROJECTID --preview_mins 9999999

Set the script to be executable.

sudo chmod +x SCRIPTNAME

Now create an action.json file as well. You can generate a basic template for this from gactions itself, but for a smart home action its probably easier to just copy this and modify it replacing YOUR.PUBLIC.URL with the public root location of this application. For instance, if your public DDNS address is test.ddns.com, and you host this application through the proxy at /google/home on at that address, this would be https://test.ddns.com/google/home/smarthome:

{
  "actions": [
    {
      "description": "Home Automation",
      "name": "actions.devices",
      "fulfillment": {
        "conversationName": "automation"
      }
    }
  ],
  "conversations": {
    "automation": {
      "name": "automation",
      "url": "https://YOUR.PUBLIC.URL/smarthome"
    }
  },
  "locale": "en"
}

You will have to run the script created above at least once manually to complete the authentication flow (just run it and follow directions).

According to Google, this should now be optional as the default for putting an app in test mode is for it to remain there indefinitely. However, if you have problems with this, you can use this utility script to reenable it by script, etc.