homebridge-ecobee3-sensors

Homebridge plugin for exposing wireless temperature and occupancy sensors of your Ecobee 3 Thermostat as HomeKit accesories. The thermostat itself is a HomeKit accessory, but the sensors are not visible in the Home app out of the box. This plugin fixes this problem, so you can have home automation rules based on room occupancy.

Homebridge runs on top of Node.js server and is an open-source implementation of the Apple HomeKit protocol. HomeKit provides the API between your Apple device (i.e. Watch or iPhone) and your home automation server (i.e. Raspberry Pi or Mac Mini). This Homebridge plugin relays the data from wireless room sensors provided by the Ecobee API and makes them available in HomeKit.

Installation

Make sure your systems matches the prerequisites. You need to have a C compiler and Node.js server.

Install Homebridge

Homebridge is a lightweight framework built on top of Node.js server that provides the HomeKit bridge for your Apple devices to connect to.

[sudo] npm install -g --unsafe-perm homebridge node-gyp
[sudo] npm install -g homebridge-ecobee3-sensors

Note Depending on your privileges -g flag may need root permissions to install packages to the global npm module directory.

Configure Homebridge

Homebridge is setup via config.json file sitting in the ~/.homebridge/ directory. To configure the plugin add a new entry into the platform section and name it whatever you like:

"platforms": [
  {
    "platform": "Ecobee 3 Sensors",
    "name": "Ecobee",
    "exclude_sensors": false,
    "exclude_humidity_sensors": false,
    "exclude_occupancy_sensors": false,
    "exclude_temperature_sensors": false,
    "exclude_thermostat": false
  }
]

Alternatively, you can use the example config.json included in the repository. It's a good starting point and the file doesn't require any modification.

Run Homebridge

Homebridge package creates a handy executable that can be used to start the home automation server.

homebridge

Authorization

Before you can use the plugin, you have to go through the authorization process which grants it access to your thermostat data.

1. Go to Ecobee login page

2. Login with your username and password

You need to register your thermostat first, so do this if you haven't yet.

3. Select MY APPS from the menu on the top right.

4. Click Add Application.

5. Enter the authorization code

The code is shown when Homebridge server starts and this plugin is loaded for the first time.

6. Wait a moment...

Ecobee servers are queried every 30 seconds whether the process is completed. Please, be patient. The time delay is a security mechanism of the API to prevent server overload.

Note: The authorization code expires after 10 minutes. If you're not able to complete the process a new code will be generated and the previous code won't be valid anymore.

Apple Device

Pairing

Open Home app and tap the '+' button to add new accessory. When you attempt to add your new bridge, it will ask for a "PIN" from the config.json file. Once the pairing is completed you will be asked to configure each of your sensors and place it in it's respective room.

Interacting

Once all of your sensors has been added to the HomeKit database, besides using the Home app or Control Center at the bottom of the screen, you should be able to tell Siri to get reading from the sensors.

Try "Hey Siri, what is the temperature in the Kitchen?". or "Hey Siri, is anyone in the Living Room?". HomeKit is a cloud service and iOS may need some time to synchronize your HomeKit database to iCloud and subsequently to all of your devices, so Siri may take a while to start working properly.

Troubleshooting

If you encouter a different problem than something posted below, please, open an issue.

Home app can't discover any nearby accessories

Make sure the Apple device and the Homebridge server are on the same subnet and connected to the same wifi router.

Sometimes, Homebridge server might think that, it has successfully paired with iOS, but iOS doesn't agree. Try to delete the persist/ directory in the ~/.homebridge/ configuration folder. This removes all pairings that normally persist from session to session.

rm -rf ~/.homebridge/persist/

From time to time it looks like iOS ignores HomeKit bridges with username that it has already paired with. Try to change the username in the bridge section of config.json to a new value never used before.

FAQ

Can I contribute my own feature?

Sure thing! All contributions are welcome. Just do a pull-request or open a new issue if you see something broken or something that needs improvement.

How frequently are the sensors updated?

The polling request to get new values of each sensor is scheduled every 30 seconds. However, this may be a bit too frequent since according to the Ecobee documentation, the shortest sensor update interval is every 3 minutes.

What are the prerequisites for installation?

Linux (Debian Based, Kernel 3.6 or newer)

• Install Node.js

  Node.js is an asynchronous event driven JavaScript server, ideal for building scalable, low-latency network applications. Homebridge is built on top of this server. It is being developed so quickly that package repositories of most distributions contain a very old version. Getting latest from the official website is recommended.

• Install a C compiler.

macOS (10.10 or newer)

• Install Node.js

  Node.js is an asynchronous event driven JavaScript server, ideal for building scalable, low-latency network applications. Homebridge is built on top of this server. It is being developed so quickly that package repositories of most distributions contain a very old version. Getting latest from the official website is recommended.

• Install XCode

  XCode comes with a C compiler that is needed to compile the bindings for the Curve25519 cypher, which ensures that all HomeKit communication is sercure.

Windows (8.1 or newer)

Pull request is welcomed here... Homebridge should run on Windows, but I don't have a machine to test.

Can I access my sensors without this plugin?

Yes. The sensors are visible in the Ecobee app. They're also accessible by Siri out of the box, although somewhat cumbersomly. See this link for a full list of available commands.

Can I use my own Ecobee developer API Key?

To run the plugin you don't need to have your own API key. Hovewer, if you plan to do your own development, it might be beneficial to get your own. To configure the plugin using own developer API key from Ecobee, add app_key field to config.json file "app_key": "ECOBEE_DEVELOPER_API_KEY_HERE".

To obtain your own Ecobee developer API api key, you need to do the following steps:

1. Go to Ecobee login page
2. Login with your username and password.
3. Select DEVLOPER from the menu on the top right.
4. Click CREATE NEW.
5. Fill in Application Name and Application Summary.
6. Click Authorization Method. and select ecobee PIN.
7. Click CREATE and copy your new developer API key.

On what devices was this plugin tested?

Here's a list of testing devices. The list is by no means exhaustive and the plugin will work with many more.

• Apple Device

  • iPhone 5S & 6 running iOS 10

• Homebridge Server

  • Raspberry Pi 3 & 2 (with USB dongle) running Raspbian Jessie Lite
  • Macbook Air (2015) & iMac (2012) running macOS 10.12

License

This work is licensed under the MIT license. See license for more details.