Skip to content

setup-mqm-ha.adoc

Latest commit

 

History

History
175 lines (156 loc) · 7.08 KB

setup-mqm-ha.adoc

File metadata and controls

175 lines (156 loc) · 7.08 KB

Setup Home Assistant & mqmgateway

This is a step-by-step guide illustrating how to integrate a Modbus device into Home Assistant via MQTT.

These components are involved and should be setup in order:

  1. MQTT Broker

  2. mqmgateway

  3. Home Assistant

MQTT Broker

mqmgateway

mqmgateway requires a connection to the Modbus device, either via a serial device for Modbus RTU (e.g. an USB dongle) or via a network connection for Modbus TCP. mqmgateway may run on the same host as Home Assistant or any other host in the network.

  1. Find out the version of the heat pump software.

    The related component is called WPM for Dimplex-based devices, and the version number has the format <LETTER><NUMBER>.<NUMBER>. The generator uses this version to omit registers that are not supported by the heat pump software.

    Examples: M3.13 or L23.1

  2. Create container configuration.

    The concrete steps depend on how containers are started in the target environment. This could be editing a compose.yml, or a UI driven configuration in your container management tool of choice.

    Example: Compose file

  3. Create basic application configuration config.basic.yaml with all options except MQTT objects, optionally containing Poll groups. The exprconv.so plugin is required in the list of converter_plugins to support type conversions.

    Example: Configuration

  4. Create MQTT objects configuration config.mqtt-objects.yaml using mqm-gojq-generator. The generator accepts configuration options via environment variables. Supply the software version of the heat pump as argument. Example:

    $ docker run --rm -v "/home/me/data/dimplex-tcp:/opt/mobugen/data:ro" -e MQTT_TOPIC_PREFIX=heatpump -e MQM_ADDRESS_OFFSET=1 ghcr.io/git-developer/mobugen mqm-gojq-generator M3.13 >config.mqtt-objects.yaml

  5. Merge basic configuration with MQTT objects into config.yaml and verify its content. Example:

    $ cat config.basic.yaml config.mqtt-objects.yaml >config.yaml

  6. Start mqmgateway and verify that Modbus values are published via MQTT. Example:

    $ docker compose up -d
$ docker compose logs
[INFO ] modmqttd is starting
[INFO ] Added converter plugin std
[INFO ] Connecting to 192.168.0.100:502
[INFO ] Response timeout set to 500ms
[INFO ] modbus: connecting
[INFO ] modbus: connected
[INFO ] Waiting for mqtt network to become online
[INFO ] Connecting to broker:1883
[INFO ] Connection established
[INFO ] Mqtt connected, sending subscriptions…
[INFO ] Mqtt ready to process messages

$ mosquitto_sub -v -L mqtt://broker/heatpump/#
heatpump/systemstatus/sensorfehler Kein Fehler
heatpump/betriebsdaten/tapwater/r3/temperatur-warmwasser/state 53.2
...

Poll groups

Poll groups allow reading data for multiple MQTT objects using a single Modbus read call. They are configured within the options of a modbus slave.

Poll group configuration is optional and depends on the Modbus device and on polling requirements. This section contains examples for Dimplex heat pump devices.

Dimplex RTU
poll_groups:
  - { register: 2,     count: 71,  register_type: coil }
  - { register: 125,   count: 52,  register_type: coil }
  - { register: 2,     count: 93,  register_type: holding }
  - { register: 103,   count: 125, register_type: holding }
  - { register: 241,   count: 70,  register_type: holding }
  - { register: 337,   count: 52,  register_type: holding }
Dimplex TCP
poll_groups:
  - { register: 2,     count: 71,  register_type: coil }
  - { register: 125,   count: 52,  register_type: coil }
  - { register: 2,     count: 93,  register_type: holding }
  - { register: 103,   count: 125, register_type: holding }
  - { register: 241,   count: 70,  register_type: holding }
  - { register: 5006,  count: 100, register_type: holding }
  - { register: 5127,  count: 60,  register_type: holding }

Home Assistant

  1. Enable loading configuration files from the packages directory. Example:

    configuration.yaml
    homeassistant:
  packages: !include_dir_named packages

  2. (optional) Create a configuration file packages/heatpump_devices.yaml with a container device for generated entities. This step is not strictly required but recommended, for the sake of clarity. Example for a heat pump using wlw286 as ID:

    packages/heatpump_devices.yaml
    mqtt:
  - sensor:
      state_topic: "heatpump/device/wlw286/state"
      value_template: ""
      default_entity_id: heatpump_device_wlw286
      unique_id: heatpump_device_wlw286
      device:
        identifiers:
          - wlw286
        name: Heat Pump

  3. Create the entity configuration file packages/heatpump_entities.yaml using ha-mqtt-gojq-generator. The generator accepts configuration options via environment variables. Supply the software version of the heat pump as argument. Example:

    $ docker run --rm -v "/home/me/data/dimplex-tcp:/opt/mobugen/data:ro" -e MQTT_TOPIC_PREFIX=heatpump -e HA_DEVICE_ID=wlw286 ghcr.io/git-developer/mobugen ha-mqtt-gojq-generator M3.13 >heatpump_entities.yaml

  4. (optional) Customize packages/heatpump_devices.yaml.

    Example for an aggregation of entities for Dimplex devices:

    packages/heatpump_devices.yaml
    template:
  - sensor:
      - name: Wärmemenge Heizen
        unique_id: heatpump_waermemengen_heating_waermemenge_heizen
        device_class: energy
        state_class: total_increasing
        unit_of_measurement: kWh
        state: >
          {% set prefix = 'sensor.heatpump_waermemengen_heating_waermemenge_heizen_' %}
          {% set states = (prefix + '1_4', prefix + '5_8', prefix + '9_12') | map('states') | list %}
          {{
             states | map('float') | sum
             if (states | length) == (states | select('is_number') | list | length)
             else none
          }}
      - name: Wärmemenge Warmwasser
        unique_id: heatpump_waermemengen_tapwater_waermemenge_warmwasser
        device_class: energy
        state_class: total_increasing
        unit_of_measurement: kWh
        state: >
          {% set prefix = 'sensor.heatpump_waermemengen_tapwater_waermemenge_warmwasser_' %}
          {% set states = (prefix + '1_4', prefix + '5_8', prefix + '9_12') | map('states') | list %}
           {{
             states | map('float') | sum
             if (states | length) == (states | select('is_number') | list | length)
             else none
          }}

  5. Start or restart Home Assistant to load the configurations. Verify that entities exist and are updated from Modbus data.

  6. Create dashboards at will.

    Example: Demo dashboard (for use with raw configuration editor)