NestDeveloperApiKey

In order to access the Nest API you need to register yourself as a developer. This sounds more complicated than it really is. You need to do this in order to be able to use the 'Nest Thermostat/Protect OAuth' hardware device in Domoticz.

The process of getting it set up comes down to the following steps:

• Create a product at the Nest website
• Assign permissions to the product
• Obtain an OAuth PIN
• Configure Domoticz

Setting up the product

• Register for a regular Nest account at https://home.nest.com/ (you most likely already have this if you have a working Nest device, you can skip this step then).
• Log on to https://developers.nest.com/ and go to the Developer Console (or directly go to https://console.developers.nest.com/nl/auth/new ). You'll now end up at a page called 'OAuth Clients'.
• Click the 'Create new OAuth Client' button.
• Enter the following information:
  • OAuth Client Name: Make something up, for example 'Domoticz Plugin myusername'. Note that this client name must be unique.
  • Description: Example: 'Nest plugin for Domoticz.'
  • Categories: Example: HVAC, Home Automation
  • Users: Individual
  • Support URL: http://www.domoticz.com
  • Default OAuth Redirect URI: <leave blank>
  • Additional OAuth Redirect URIs: <leave blank>

Permissions

Just having a product defined does not grant it any kind of permissions to anything. That what this next part is about. You'll need to grant your new 'Product' permissions to access your Nest devices. For each permission you'll need to provide an explanation of what it does. Can be short but is mandatory. If you are lazy, you can just copy the description above.

Currently the plugin does not require/use all of the permissions mentioned below. It is however advised to add them anyway. Should any functionality be added to the plugin things might break because of missing permissions. If you add permissions later you will need to re-authorize the plugin (get a new API key and such). However if you insist on giving as little privileges as possible, the currently necessary permissions are marked with an asterisk (*).

Set up the permissions as follows:

• Thermostat
  • Thermostat read/write*
  • Energy read
• Camera
  • Camera + Images read/write
• Smoke+CO Alarm
  • Smoke+CO Alarm read*
• Security
  • Security State read
• Other Permissions
  • Away read/write*
  • ETA read
  • ETA write
  • Structure read/write*
  • Postal code read

Finish the process by clicking the 'Create product' button.

Linking to Domoticz

Now that your product is created you'll automatically be taken to the overview page. The important part is the OAuth section on the bottom. You'll be provided with the following information:

• Client ID
• Client Secret
• Authorization URL

Obtaining the PIN

• Copy the Authorization URL to your clipboard
• Open a new browser tab and visit this URL. You'll be asked for your Nest credentials.
• Next you'll be asked to provide authorization to the app you just created. Note that the permissions shown are the ones that you selected.
• After your approval you'll be shown a PIN code. This is a one-time code that will be used by Domoticz to get an API key for permanent use.

Configuring Domoticz

• Open Domoticz
• Go to the setup/hardware configuration page.
• Select the Nest Thermostat/Protect OAuth device.
• Enter the following information:
  • Product Id: the Client ID from above
  • Product Secret: the Client Secret from above
  • OAuth PIN: the PIN code that you obtained.
  • API Key: this can be left blank.

Warning: When copy-pasting the information please take extra care not to copy any extra characters like spaces, newlines or tabs. Otherwise you'll get errors.

As soon as you click Add Domoticz will start the plugin and it notices that it does not have an API key. However it has been provided all the information to obtain one, and that's exactly what it will do. Using the information provided it fetches an API key and stores it. You can confirm that this happened successfully by checking the log or the hardware page: the API key field is now filled in while the others are blank.