search

skrollme / homebridge-eveatmo

Homebridge plugin which adds a Netatmo weatherstation as HomeKit device and tries to act like Elgato Eve Room/Weather
Apache License 2.0
69 stars 7 forks source link
homebridge homebridge-netatmo homebridge-plugin homekit netatmo netatmo-weather-station

readme

npm npm GitHub last commit

homebridge-eveatmo

This is a homebridge plugin which lets you integrate your non-HomeKit Netatmo Weatherstation and Indoor Air Quality monitor into HomeKit.

Whilst the original homebridge-netatmo-plugin goes a mostly HomeKit-standard approach (predefined services, characteristics, ...), this plugin tries to mimic the Elgato Eve devices as close as possible.

:rotating_light: Warning

Since Netatmo announced a change to their authentification-policies it was also necessary to update this plugin's authentication-mechanism. From 1.0.0 it is not recommended to use username/password auth anymore although it is technically still supported in the latest release (1.1.0).

You need to generate an OAuth _refreshtoken on your app's page at dev.netatmo.com instead. For more details see the instructions below or take a look at this issue: https://github.com/skrollme/homebridge-eveatmo/issues/62. Since some users have still unidentified problems with the new authentication-mechanism you can keep using the username/password auth, but it can be shut down by netatmo at any time.

Configuration

Because this plugin's base was taken from homebridge-netatmo (see above) you can adapt its config. Just use the plattform-code "eveatmo" and remove "ttl" and/or the other "refresh_" properties for the beginning.

You can also configure this plugin via ConfigUI-X's settings feature. 

"platforms": [
        {
            "platform": "eveatmo",
            "name": "eveatmo platform",
            "extra_co2_sensor": false,
            "co2_alert_threshold": 1000,
            "weatherstation": true,
            "airquality": false,
            "ttl": 540,
            "log_info_msg", true,
            "auth": {
                "client_id": "XXXXX Create at https://dev.netatmo.com/",
                "client_secret": "XXXXX Create at https://dev.netatmo.com/",
                "refresh_token": "a valid refresh token for the given client_id",
                "grant_type": "refresh_token"

                ... or if you use password-grant ...

                "client_id": "XXXXX Create at https://dev.netatmo.com/",
                "client_secret": "XXXXX Create at https://dev.netatmo.com/",
                "username": "your netatmo account's mail-address",
                "password": "your netatmo account's password",
                "grant_type": "password"
            }
        }
    ],

Control Accessories by device ID

Controlling devices can be done on a finer level by id. The id of a netatmo device or module basically is it's mac address.

In order to include or exclude a specific device, the corresponding id can be included in a whitelist resp. blacklist.

If the whitelist contains at least one entry, all other ids will be excluded.


    "platforms": [
        {
            "platform": "eveatmo",

            ...

            "whitelist": [
              "aa:bb:cc:11:22:33"
            ],
            "blacklist": [
              "01:02:03:04:05:06",
              "01:23:45:67:89:ab"
            ],

            ...

        }
    ],

Netatmo API authentication

There are two methods to authenticate against the Netatmo API, but first 4 steps are always the same:

  1. Register at http://dev.netatmo.com as a developer
  2. After successful registration create your own app by using the menu entry "CREATE AN APP"
  3. On the following page, enter a name for your app. Any name can be chosen. All other fields of the form (like _callbackurl, etc.) can be left blank.
  4. After successfully submitting the form the overview page of your app should show _clientid and _clientsecret.

"refresh_token" grant

This one is recommended by Netatmo because it is more secure since you do not have to store your username and password in homebridge's config file. The downside is, that it is a little bit less stable, especially when homebridge is not running constantly. This is because the plugin always gets a short-lived token to fetch data for some time. When the token expires, the plugin has to fetch a new one from the API.

  1. Do an initial auth with the newly created app via the "Token generator" on your app's page https://dev.netatmo.com/apps/ to get a _refreshtoken
  2. Add the _clientid, the _clientsecret and the _refreshtoken to the config's auth-section
  3. The plugin will use the _refreshtoken from the config to retrieve and refresh _authtokens. It will also store newly retrieved tokens in a file (netatmo-token.js) in your homebridge config directory. If you delete the netatmo-token.js file, you may have to regenerate a new _refreshtoken like in step 5) if your initial _refreshtoken (from the config.json) already has expired

"password" grant

This one is my preferred method, because in a single-user scenario and a most likely "at home and self-hosted"-setup it is totally fine for me. Netatmo deprecated this method but it is usable in cases where the user (here: homebridge) and the account (where the weatherstation is linked to) are the same. Since this is the normal use-case for this homebridge-plugin I use this as long it is possible.

  1. Add the _clientid, the _clientsecret, the username (your account email) and the password (your account password) to the config's auth-section

Retrieve _clientid, _clientsecret and _refreshtoken

Siri Voice Commands

Here are sample English voice commands:

Siri understands variations of each command:

Siri voice commands may vary by language. Since this plugin tries to mimic the Elgato Eve devices, you can search the Eve blog for articles listing voice commands in your language.

Blog posts with English commands:

Blog posts with German commands:

History

see HISTORY.md

Thanks and disclaimer

This plugin's basic structure and most of its basic code is a fork (ok, lets say "copy") of homebridge-netatmo. So big thanks to @planetk and all the other contributors of this project.

Also big thanks to @gomfunkel and @simont77 for this gist and its fork, @KhaosT for this gist, @mplewis for this gist and @0ff for this (almost) working Eve Weather imitating homebridge-plugin and once again special thanks to @simont77 for his endurance in digging deeper in Eve's custom characteristics and its protocols.

Thanks go also to the following direct contributors:

Since Netatmo announced some changes on what kind of authentication their API will support and I did not found a good solution to override the code of the netatmo-dependency to continue working, this module contains an altered full-copy of the module. All credits for the original code go to the respective authors.

What else

Like this and want to express your feelings? Please buy me a beer :beers: ...

Donate

Cheers go to: