Evohome2mqtt
This node.js application is a bridge between the Evohome system and a mqtt server. Your thermostats will be polled every x seconds and the status(es) get published to your (local) mqtt server. As with a bridge it also works the other way around. You can set the temperature for a thermostat with a message to mqtt.
It's intended as a building block in heterogenous smart home environments where an MQTT message broker is used as the centralized message bus. See MQTT Smarthome on Github for a rationale and architectural overview.
Installation
Using evohome2mqtt is really easy, but it requires at least Node.js v6 or higher. (This app is tested against v12).
sudo npm install -g evohome2mqtt
Usage
evohome2mqtt 0.0.0-development
Usage: evohome2mqtt [options]
Options:
--user Your evohome username [required]
--password Your evohome password [required]
-l, --logging Logging level
[choices: "error", "warn", "info", "debug"] [default: "info"]
-m, --mqtt mqtt broker url. See
https://github.com/svrooij/evohome2mqtt#mqtt-url
[default: "mqtt://127.0.0.1"]
-n, --name instance name. used as mqtt client id and as topic
prefix [default: "evohome"]
-p, --polling-interval evohome polling interval in seconds [default: 30]
--app Specify a different application ID (EXPERT?)
[default: "91db1612-73fd-4500-91b2-e63b069b185c"]
-h, --help Show help [boolean]
--version Show version number [boolean]
Evohome credentials
We need your evohome credentials, so those are required. evohome2mqtt --user yourUsername --password yourSecretPassword
MQTT Url
Use the MQTT url to connect to your specific mqtt server. Check out mqtt.connect for the full description.
Connection without port (port 1883 gets used)
[protocol]://[address] (eg. mqtt://127.0.0.1)
Connection with port
[protocol]://[address]:[port] (eg. mqtt://127.0.0.1:1883)
Secure connection with username/password and port
[protocol]://[username]:[password]@[address]:[port] (eg. mqtts://myuser:secretpassword@127.0.0.1:8883)
Environment variables
You can also config this app with environment variables, they all start with EVOHOME2MQTT_
and then then full name of the argument. Like EVOHOME2MQTT_USER
, EVOHOME2MQTT_PASSWORD
or EVOHOME2MQTT_POLLING_INTERVAL
Topics
Every message starts with a prefix (see usage) that defaults to evohome
. So if you change this all the topics change.
Connect messages
This bridge uses the evohome/connected
topic to send retained connection messages. Use this topic to check your evohome bridge is still running.
-
0
or missing is not connected (set by will functionality). -
1
is connected to mqtt, but not to evohome. -
2
is connected to mqtt and evohome. (ultimate success!)
Status messages
The status of each thermostat will be published to evohome/status/thermostat/zone_name
as a JSON object containing the following fields.
-
val
current temperature. -
state
JSON object retrieved from evohome server. -
lc
last change.
We also publish the temperature as a single value to evohome/status/thermostat/zone_name/temp
.
Setting the temperature
You can control each zone by sending a json message to evohome/set/thermostat/zone_name
with the following fields:
-
temp
is the new temperature. -
minutes
is the number of minutes this new temp should be set (optional).
evohome/set/thermostat/livingroom
{
"temp":20,
"minutes":48
}
Will set the temperature to 20º for 48 minutes.
An empty message to evohome/set/thermostat/livingroom
will revert the livingroom
back to the schedule.
Run in Docker
You can run this app in docker. We provide an image for linux/amd64
linux/arm/v7
and linux/arm64
.
Everything is configurable with environment variables, docker compose sample:
version: "3.7"
services:
evohome:
image: svrooij/evohome2mqtt
restart: unless-stopped # This makes sure that on a crash it will automatically be restarted.
environment:
- EVOHOME2MQTT_USER=your_user_name # Replace with your username for the evohome system
- EVOHOME2MQTT_PASSWORD=complicated_password_I_hope # Replace with your password for the evohome system
- EVOHOME2MQTT_MQTT=mqtt://emqx:1883 # EMQX is a nice mqtt broker
depends_on:
- emqx
# Optional MQTT server (I like emqx over mosquitto)
emqx:
image: emqx/emqx
restart: unless-stopped
ports:
- "1883:1883"
- "18083:18083"
Off course you can also start it wil the following oneline.
# Start in current process CTRL+C quits the app
docker run -e "EVOHOME2MQTT_USER=your_user_name" -e "EVOHOME2MQTT_PASSWORD=complicated_password" -e "EVOHOME2MQTT_MQTT=mqtt://emqx:1883" -n evohome svrooij/evohome2mqtt
# Start in background
docker run -d -e "EVOHOME2MQTT_USER=your_user_name" -e "EVOHOME2MQTT_PASSWORD=complicated_password" -e "EVOHOME2MQTT_MQTT=mqtt://emqx:1883" -n evohome svrooij/evohome2mqtt
# Follow logs from running in background
docker logs -f evohome
Use PM2 to run in background (deprecated)
In the past running this app with PM2 was recommended, currently (Oct 2020) I would suggest to use docker.
If everything works as expected, you should make the app run in the background automatically. Personally I use PM2 for this. And they have a great guide for this.
Special thanks
The latest version of this bridge is inspired on hue2mqtt.js by Sabastian Raff. That was a great sample on how to create a globally installed, command-line, something2mqtt bridge.
Beer or Coffee
This bridge took me a lot of hours to build, so I invite everyone using it to at least have a look at my Sponsor page. Even though the sponsoring tiers are montly you can also cancel anytime