evohome2mqtt
v1.1.2
Published
Send the status of your evohome system to mqtt. Inspired on https://github.com/mqtt-smarthome
Downloads
27
Maintainers
Readme
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:[email protected]: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 :wink: