homebridge-ecobee3-sensors
v0.1.12
Published
Homebridge plugin that exposes Ecobee sensors as HomeKit accessories
Downloads
86
Readme
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,
"exclude_equipment_sensors": 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:
- Go to Ecobee login page
- Login with your username and password.
- Select DEVLOPER from the menu on the top right.
- Click CREATE NEW.
- Fill in Application Name and Application Summary.
- Click Authorization Method. and select ecobee PIN.
- 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
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.