evohome2mqtt

    1.1.2 • Public • Published

    Evohome2mqtt

    npm Run tests and publish github issues Support me on Github mqtt-smarthome semantic-release

    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 😉

    Install

    npm i evohome2mqtt

    DownloadsWeekly Downloads

    6

    Version

    1.1.2

    License

    MIT

    Unpacked Size

    19.8 kB

    Total Files

    10

    Last publish

    Collaborators

    • avatar