evohome2mqtt

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 :wink: