HoneywellDeveloperApiKey

From Domoticz
Jump to: navigation, search

This page describes how to setup the Honeywell hardware for the Honeywell thermostat devices like the Lyric T6. According to the Honeywell Developers API page there is a limitation on the number of requests for each API key. For this reason it's necessary to sign up for your own API key and configure Domoticz to use this key instead of the default embedded one.

Configuring the API key will be available in one of upcoming beta releases.

How to get your own API key and API secret

1. Sign up at the honeywell developer home: https://developer.honeywell.com
2. Create a new app (eg domoticz), use as callback url: 'none'
3. Click on the app name to see the generated consumer key and consumer secret

How to get the access token and refresh token

The access token and refresh token is only valid for the submitted API key. Whenever you change the API key, make sure to replace the access token and refresh token.

4. Open a browser and visit the following url after replacing the APIKEY in the url
https://api.honeywell.com/oauth2/authorize?response_type=code&client_id=[[YOURAPIKEY]]&redirect_uri=none

5. Login with the credentials you have used to register the Honeywell device. After giving permissions to read out the thermostat device your browser will be redirected to the non-existing 'none' website.

6. Take a closer look at the address bar of your browser. The url in the address bar should be like: http://api.honeywell.com/oauth2/app/none?code=CODEVALUE&scope=
Copy paste the code value as you will need this code in step 8.

7. Base64 encode the following string (without quotes) "[[APIKey]]:[[APISecret]]" . This can be done from the Linux command line by using
echo -n "[[APIKey]]:[[APISecret]]" | base64

8. Finally make the last webrequest to the Honeywell API to retrieve the Access Token and Refresh Token. Make sure to replace the Base64 encoded string and the CODE:
curl -X POST -H 'Authorization: Basic [[BASE64-ENCODED-STRING]]' -H 'Content-Type: application/x-www-form-urlencoded' -H 'Accept: application/json' -d 'grant_type=authorization_code&code=[[CODE]]&redirect_uri=none' https://api.honeywell.com/oauth2/token

If all is fine the server will respond with a json like this one:
{"access_token":"494hiudfhiuhdfi84949df","refresh_token":"jdfoijodfoUHdud83834","expires_in":"1799", "token_type":"Bearer"}

Now you have all the keys to configure the Honeywell thermostat in domoticz.


Background info

The honeywell hardware currently adds the following devices to Domoticz. The state of the devices is polled every 300 seconds.
1) Temperature indoor
2) Temperature outdoor
3) Target setpoint of the heating
4) On/Off switch for the device
5) Away (based on geofencing, true if all participants left the area)
6) Operating state of the system (at the moment of the poll which is every 300 seconds)

An example of the raw json output of the Honeywell API.

[{
    "locationID": 1234567,
    "name": "Home",
    "country": "Canada",
    "zipcode": "1000 AA",
    "devices": \[
      {
        "displayedOutdoorHumidity": 95,
        "vacationHold": {
          "enabled": false
        },
        "currentSchedulePeriod": {
          "day": "Saturday",
          "period": "P1"
        },
        "scheduleCapabilities": {
          "availableScheduleTypes": [
            "None",
            "Geofenced",
            "TimedEmea"
          ],
          "schedulableFan": false
        },
        "scheduleType": {
          "scheduleType": "Timed",
          "scheduleSubType": "EMEA"
        },
        "scheduleStatus": "Resume",
        "allowedTimeIncrements": 10,
        "settings": {
          "hardwareSettings": {
            "brightness": 3,
            "maxBrightness": 5
          },
          "temperatureMode": {
            "air": true
          },
          "specialMode": {}
        },
        "deviceClass": "Thermostat",
        "deviceType": "Thermostat",
        "deviceID": "LCC-XXXXXXXXXX",
        "userDefinedDeviceName": "Thermostaat",
        "name": "Thermostaat",
        "isAlive": true,
        "isUpgrading": false,
        "isProvisioned": true,
        "macID": "XXXXXXXXXXX",
        "deviceSettings": {},
        "service": {
          "mode": "Up"
        },
        "deviceRegistrationDate": "2018-11-10T18:01:45.44",
        "units": "Celsius",
        "indoorTemperature": 19.5,
        "outdoorTemperature": 2.5,
        "allowedModes": [
          "Heat",
          "Off"
        ],
        "deadband": 0,
        "hasDualSetpointStatus": false,
        "minHeatSetpoint": 16,
        "maxHeatSetpoint": 24,
        "minCoolSetpoint": -18,
        "maxCoolSetpoint": -18,
        "changeableValues": {
          "mode": "Heat",
          "heatSetpoint": 16.5,
          "coolSetpoint": 10,
          "thermostatSetpointStatus": "NoHold",
          "nextPeriodTime": "22:30:00",
          "heatCoolMode": "Heat",
          "endHeatSetpoint": null,
          "endCoolSetpoint": null
        },
        "operationStatus": {
          "mode": "EquipmentOff",
          "fanRequest": false,
          "circulationFanRequest": false
        }
      }
    ],
    "users": [
      {
        "userID": 1234567,
        "username": "spam@spam.no",
        "firstname": "XXXXX",
        "lastname": "XXXXX",
        "created": 1541852903,
        "deleted": -62135596800,
        "activated": true,
        "connectedHomeAccountExists": true,
        "locationRoleMapping": [
          {
            "locationID": 1234567,
            "role": "Adult",
            "locationName": "Home",
            "status": 1
          }
        ],
        "isOptOut": "True",
        "isCurrentUser": true
      }
    ],
    "timeZone": "W. Europe Standard Time",
    "ianaTimeZone": "Europe/Berlin",
    "daylightSavingTimeEnabled": true,
    "geoFences": [
      {
        "geoFenceID": 1234567,
        "latitude": 2.0403,
        "longitude": 1.103261,
        "radius": 549,
        "geoOccupancy": {
          "withinFence": 1,
          "outsideFence": 0
        }
      }
    ],
    "geoFenceEnabled": true,
    "predictiveAIREnabled": false,
    "comfortLevel": 0,
    "geoFenceNotificationEnabled": false,
    "geoFenceNotificationTypeId": 13,
    "configuration": {
      "faceRecognition": {
        "enabled": false,
        "maxPersons": 2,
        "maxEtas": 2,
        "maxEtaPersons": 1,
        "schedules": [
          {
            "time": [
              {
                "start": "15:00:00",
                "end": "17:00:00"
              }
            ],
            "days": [
              "Sunday",
              "Monday",
              "Tuesday",
              "Wednesday",
              "Thursday",
              "Friday",
              "Saturday"
            ]
          }
        ]
      }
    }
  }]