Boiler Monitor, Display and Home Assistant Project

[richardsg307]

Background

For a couple of years now, I've had an ESP8266 on my boiler monitoring temperatures and whether it's burning or not and reporting to Home Assistant. Recently, I got a couple of Lilygo T-Display-S3 ESP32s to mess around with and thought it would be good to have the display as my boiler monitor. After giving it some thought and some successes with Tasmota, Berry, LVGL and HASPmota, I gave it a go. Those last three things were all new to me and I found little on the web to guide me (I like following examples rather than reading often cryptic manuals), but with the help of this forum and in particular sfromis and s-hadinger, I got there in the end. So here is my Project with all the code and stuff and I hope others find it helpful. I've got a few ideas to tweek it a bit but now it's in, I want to let it settle down and prove it's working properly over several days. I'll probably spend a few days writing this project so it will grow as I add more detail; I hope that's OK.

Overview

First off, some pictures of the display.



The device has sensors monitoring 3 temperatures and 2 opto-isolated mains detectors for incoming demand (HW/CH) and if the internal thermostat is also demanding. From the latter I can derive burn time and how much oil is being consumed and even get how much oil is left in my tank. It reports to Home Assistant and gets some data back , eg the kwh and cost for the day (I intend to add 'Oil in tank').
On the Tasmota side, there is some setting up to do, some Berry code to add and a HASPmota page file that defines how things get displayed on the screen.
In Home Assistant, it gets picked up as a Device and a couple of MQTT sensors need adding manually through the configuration.yaml file. There are also a few Automations and Template entities to add. I will describe all these in the sections below.

Hardware

Lilygo T-Display-S3 and Shell - Bangood
Mains detector (3 Channel) - AliExpress
Temperature Sensors DS18B20 - AliExpress

Tasmota

1. I flashed the device using the Web Installer selecting the Tasmota32-S3 (QIO Flash/OPI PSRAM) firmware variant and then set it up for my router's WiFi.
2. Next I used its web interface to Auto Configure with the Lilygo-S3-Display
3. I set GPIO43 to DS18x20 - These for the 3 (or however many you want) temperature sensors; they all use the One Wire, 3V and Ground and require a single 4k7 pull-up resistor.
4. GPIOs 10 and 16 were used for the mains detector inputs and set as Switch 2 & 1 respectively. SetOptions - SetOption114 1 and SetOption73 1 are required along with SwitchMode1 2 and SwitchMode2 2.
5. Note: the 2 onboard buttons are hard wired and configured into GPIO0 and GPIO14 as Button1 and Button2. Both are used in the code/Home Assistant.
6. In Configure Other I set both the Device Name and Friendly Name 1 to Boiler.
7. In Configure MQTT I set my Home Assistant IP in Host, entered my User and Password, and set the Topic to boilerdisplay.

Berry

This is where things got tricky for me with no knowledge of Berry. What I've done may be 'bad' code but it works. I'm happy to receive constructive criticism. The first thing to note is that Berry is only on the ESP32 Tasmota variants and my understanding is that it is an object language sitting alongside Tasmota and can communicate with it. When Tasmota starts up it looks for a file called autoexec.be and will execute it. In that file you can create functions, rules and timers (and more I expect but they are all I used). Here is my Berry code in the autoexec.be file:

import haspmota
import string
import mqtt
import persist
import json
import lv_boiler_graph
haspmota.start()

var cp = 1 # Current Page
var boileron = 0 # Millis when boiler gets turned on
var runtime = 0  # Total burntime today in seconds
var runtime_hours = 0.0 # Total burntime today in hours for reporting to HA
var burntime = 0 # Time of this burn in seconds
var burn_delay = 12000 # 12 second delay between startup and firing

# Create function that gets called by a Tasmota command 'BoilerStats'
tasmota.add_cmd('BoilerStats',
  def (cmd, idx, payload, raw)
    print(     # For debug
      cmd,     # command name
      idx,     # index glued on to command name, or 0
      payload, # payload as string
      raw)     # If payload was in JSON format, a map with the parsed data
    # Now update display
    global.p1b35.text = string.format("%5.2fHrs",raw["Hours"])
    global.p1b36.text = string.format("%5.2fL",raw["Oil"])
    global.p1b37.text = string.format("%5.2fKWh",raw["KWh"])
    global.p1b38.text = string.format("£%5.2f",raw["Cost"])
    # This preserves the day's runtime if device rebooted. Needs some code in HA too 
    var ha_max_runtime = raw["Maxruntime"] * 3600
    if ha_max_runtime > runtime 
      runtime = ha_max_runtime
    end
    tasmota.resp_cmnd_done() # Report success to Tasmota
  end)

def update_screen() # function to update the burn time on screen every second if running
                                # Called by a tasmota.set_timer()
  if boileron != 0 # Don't run if boiler (just) turned off
    burntime = (tasmota.millis() - (boileron+burn_delay))/1000 # Current burn time in seconds
    if burntime < 0 burntime = 0 end # If it stops before firing up
    global.p1b50.text = string.format("%ds",burntime) # Update seconds on display
    tasmota.set_timer(1000, update_screen) # Do this all again in a second
  end
end

def rule_b(value, trigger)    # Function gets called by rule when boiler thermostat turns on or off
  if value=="ON"              # when boiler turns on
    print("Boiler is On")
    boileron=tasmota.millis() # Boiler start time
    tasmota.set_timer(1000, update_screen) # Call update_screen in 1 second
  else                        # when boiler turns off
    burntime = (tasmota.millis()-(boileron+burn_delay))/1000 
    if burntime < 0 burntime = 0 end
             # Note many seconds delay before boiler fires up
    runtime = runtime + burntime
    runtime_hours = runtime/3600.0
    print("Runtime is now ", runtime, " seconds") # Debug
    global.p1b41.text = string.format("%5.2fHrs", runtime_hours)
    persist.totalhours += burntime/3600.0
    global.p1b43.text = string.format("%7.1fHrs", persist.totalhours)
    # Now update HA
    mqtt.publish("tele/boilerdisplay/RUNTIME", str(runtime_hours))
    mqtt.publish("tele/boilerdisplay/TOTHRS", str(persist.totalhours))
    boileron = 0
  end
end

# Add rule to Tasmota to call the function above
tasmota.add_rule("Burn#Action", rule_b)

def mn() # Gets called every midnight by the cron set up below
  persist.save() # Save to Flash totalhours daily at midnight
  runtime = 0 # Reset runtime for new day
  runtime_hours = 0.0
  global.p1b41.text = string.format("%ds", runtime)
  mqtt.publish("tele/boilerdisplay/RUNTIME", "0.0")
end

tasmota.add_cron("0 0 0 * * *", mn, "midnight") # To call the function above

global.p1b43.text = string.format("%7.1fHrs", persist.totalhours)

def rule_gpio0(value, trigger) # Change screen page if top (my orientation) onboard buttons gets pressed
  print("GPIO0 button pressed - ", value, trigger); # Debug. ; found necessary!
  if cp == 1 global.p2.show() cp = 2
  else 
    if cp == 2 global.p3.show() cp = 3
    else global.p1.show() cp = 1 end
  end
end

# Add rule to Tasmota to call the function above
tasmota.add_rule("Button1#Action", rule_gpio0)

There's lots of comments in the code so I won't try to explain it here but will try to answer any questions on it.

Another file called lv_boiler_graph.be is responsible for the graph page shown in one of the pictures above. I based it on the code I found in this GitHub Tasmota repository for the WiFi widget included on the Tasmota page. This is the code for my lv_boiler_graph widget:

# lv_boiler_graph class

class lv_boiler_graph : lv.chart
    var ws_h
    var ws_w
    var ser1 # For Outflow temperature
    var ser2 # Inflow
    var ser3 # Cabinet
    var wsl
    var delay
  
    def init(parent)
      super(self).init(parent)
      
      self.set_style_bg_color(lv.color(0x000000), lv.PART_MAIN | lv.STATE_DEFAULT)
      self.set_style_bg_opa(100, lv.PART_MAIN | lv.STATE_DEFAULT)
      self.set_style_border_color(lv.color(0x0099EE), lv.PART_MAIN | lv.STATE_DEFAULT)
      self.set_style_border_width(1, lv.PART_MAIN | lv.STATE_DEFAULT)
      #self.set_style_border_opa(200, lv.PART_MAIN | lv.STATE_DEFAULT)
      self.set_style_radius(0, lv.PART_MAIN | lv.STATE_DEFAULT)
      self.set_style_pad_all(2, lv.PART_MAIN | lv.STATE_DEFAULT)
  
      self.set_range(lv.CHART_AXIS_PRIMARY_Y, 0, 100)
      self.set_div_line_count(0,0)		# no lines
      self.set_type(lv.CHART_TYPE_LINE)
      self.set_div_line_count(6, 6)
      self.set_style_line_color(lv.color(0xb0b0a5), 0) # Sets the color of the division lines
#      self.set_style_opa(20, lv.PART_SERIES_BG | lv.STATE_DEFAULT)
      
      self.set_style_size(0, lv.PART_INDICATOR) # don't show dots
      self.set_style_line_rounded(true, lv.PART_ITEMS)
      self.set_style_line_width(2, lv.PART_ITEMS) # don't show dots
      self.set_update_mode(lv.CHART_UPDATE_MODE_SHIFT)
      
      self.set_point_count(1200) # 4 points per minute * 5 hours = 1200 points

      # My 3 lines I want displayed
      self.ser1 = self.add_series(lv.color(0xEE4444), lv.CHART_AXIS_PRIMARY_Y) # Outflow
      self.ser2 = self.add_series(lv.color(0xF5A320), lv.CHART_AXIS_PRIMARY_Y) # Inflow
      self.ser3 = self.add_series(lv.color(0x2FA3DE), lv.CHART_AXIS_PRIMARY_Y) # Cabinet
  
      self.wsl = lv.label(self)
      self.wsl.set_style_text_color(lv.color(0xFFFFFF), lv.PART_MAIN | lv.STATE_DEFAULT)
      self.wsl.set_text("Boiler Temperatures - Last 5 Hours")
      self.wsl.set_style_text_font(lv.font_montserrat(14), lv.PART_MAIN | lv.STATE_DEFAULT)
      self.wsl.set_align(lv.ALIGN_BOTTOM_MID)
  
      self.delay = 1 # ensures a point gets added at first call of func every_second()
  
      self.add_event_cb(/->self.before_del(), lv.EVENT_DELETE, 0)   # register `before_del` to be called when object is deleted
      tasmota.add_driver(self)
    end
  
    def add_boiler_point()
      var sensors = json.load(tasmota.read_sensors())  
      var out_t = int(sensors['DS18B20-1']['Temperature'])
      var in_t = int(sensors['DS18B20-3']['Temperature'])
      var cab_t = int(sensors['DS18B20-2']['Temperature'])
      self.set_next_value(self.ser1, out_t)
      self.set_next_value(self.ser2, in_t)
      self.set_next_value(self.ser3, cab_t)
    end
  
    def every_second() # This gets called every second - inbuilt
      self.delay -= 1
      if self.delay == 0
        self.add_boiler_point()
        self.delay = 15 # So the point is added every 15 seconds
      end
    end
  
    def before_del()
      tasmota.remove_driver(self)
    end
  end
  
  return lv_boiler_graph

I've added comments to my code and don't profess to understand much of the LVGL speak within it.
These two files above and a third file ( haspmota_widgets.tapp ) got from GitHub need adding to the device through the Manage File System console.

HASPmota

This is where you define the Pages you want displayed on the screen. It looks a bit daunting at first but you quickly get used to it once using it, I found. Each line of the pages.jsonl HASPmota file represents 1 object on screen. The line contains the attribute values you want for each and if omitted they take a default. Here's my file which also needs adding through the Manage File System console:

{"page":0,"comment":"---------- Upper stat line ----------"}

{"id":11,"obj":"label","x":0,"y":0,"w":320,"pad_right":90,"h":22,"bg_color":"#D00000","bg_opa":255,"text_color":"#ffffff","radius":0,"border_side":0,"text":"Boiler Stats","text_font":"montserrat-20"}

{"id":15,"obj":"lv_wifi_arcs","x":291,"y":0,"w":29,"h":22,"radius":0,"border_side":0,"bg_color":"#000000","line_color":"#FFFFFF"}
{"id":16,"obj":"lv_clock","x":232,"y":3,"w":55,"h":16,"radius":0,"border_side":0,"text_color":"#ffffff"}

{"page":1,"comment":"---------- Page 1 ----------"}
{"id":0,"bg_color":"#0000A0","bg_grad_color":"#000000","bg_grad_dir":1,"text_color":"#FFFFFF"}

{"id":19,"obj":"label","x":10,"y":30,"w":100,"text":"Local Readings","align":2}
{"id":20,"obj":"label","x":10,"y":50,"w":70,"text":"Outflow = ","align":2}
{"id":21,"obj":"label","x":10,"y":70,"w":70,"text":"Inflow = ","align":2}
{"id":22,"obj":"label","x":10,"y":90,"w":70,"text":"Cabinet = ","align":2}
{"id":23,"obj":"label","x":10,"y":110,"w":70,"text":"Demand = ","align":2}
{"id":24,"obj":"label","x":10,"y":130,"w":70,"text":"Burn = ","align":2}
{"id":40,"obj":"label","x":10,"y":150,"w":70,"text":"Runtime = ","align":2}

{"id":25,"obj":"label","x":80,"y":50,"w":60,"align":0,"text_rule":"DS18B20-1#Temperature","text_rule_format":"%4.1f°C"}
{"id":26,"obj":"label","x":80,"y":70,"w":60,"align":0,"text_rule":"DS18B20-3#Temperature","text_rule_format":"%4.1f°C"}
{"id":27,"obj":"label","x":80,"y":90,"w":60,"align":0,"text_rule":"DS18B20-2#Temperature","text_rule_format":"%4.1f°C"}
{"id":28,"obj":"label","x":80,"y":110,"w":60,"align":0,"text_rule":"Demand#Action","text_rule_format":"%s"}
{"id":29,"obj":"label","x":80,"y":130,"w":60,"align":0,"text_rule":"Burn#Action","text_rule_format":"%s"}
{"id":50,"obj":"label","x":110,"y":130,"w":60,"align":0,"text":"0s","text_rule":"burn_time","text_rule_format":"%ds"}
{"id":41,"obj":"label","x":80,"y":150,"w":60,"align":0,"text_rule":"runtime","text_rule_format":"%s"}

{"id":30,"obj":"label","x":150,"y":30,"w":100,"text":"HA Stats","align":2}
{"id":31,"obj":"label","x":150,"y":50,"w":80,"text":"Run Time = ","align":2}
{"id":32,"obj":"label","x":150,"y":70,"w":80,"text":"Oil = ","align":2}
{"id":33,"obj":"label","x":150,"y":90,"w":80,"text":"Energy = ","align":2}
{"id":34,"obj":"label","x":150,"y":110,"w":80,"text":"Cost = ","align":2}
{"id":42,"obj":"label","x":150,"y":150,"w":80,"text":"Hours = ","align":2}

{"id":35,"obj":"label","x":230,"y":50,"w":90,"align":0,"text":"Waiting"}
{"id":36,"obj":"label","x":230,"y":70,"w":90,"align":0,"text":"  for  "}
{"id":37,"obj":"label","x":230,"y":90,"w":90,"align":0,"text":"  next "}
{"id":38,"obj":"label","x":230,"y":110,"w":90,"align":0,"text":"report"}
{"id":43,"obj":"label","x":230,"y":150,"w":90,"align":0,"text_rule":"persist.totalhours"}

{"page":2,"comment":"---------- Page 2 Can be updated dynamically for experimentation ----------"}
{"id":0,"bg_color":"#0000A0","bg_grad_color":"#000000","bg_grad_dir":1,"text_color":"#FFFFFF"}

{"comment":"---------- Wifi status ----------"}
{"id":20,"obj":"lv_wifi_graph","x":257,"y":25,"w":60,"h":40,"radius":0}
{"id":21,"obj":"lv_tasmota_info","x":3,"y":25,"w":251,"h":40,"radius":0}
{"id":22,"obj":"lv_tasmota_log","x":3,"y":68,"w":314,"h":90,"radius":0,"text_font":12}

{"page":3,"comment":"---------- Page 3 Can be updated dynamically for experimentation ----------"}
{"id":0,"bg_color":"#0000A0","bg_grad_color":"#000000","bg_grad_dir":1,"text_color":"#FFFFFF"}

{"comment":"---------- Boiler status ----------"}
{"id":20,"obj":"lv_boiler_graph","x":3,"y":25,"w":314,"h":144,"radius":0}
{"id":21,"obj":"label","x":6,"y":25,"w":30,"text":"100","align":0}
{"id":22,"obj":"label","x":8,"y":45,"w":30,"text":"80","align":0}
{"id":23,"obj":"label","x":8,"y":73,"w":30,"text":"60","align":0}
{"id":24,"obj":"label","x":8,"y":101,"w":30,"text":"40","align":0}
{"id":25,"obj":"label","x":8,"y":129,"w":30,"text":"20","align":0}
{"id":26,"obj":"label","x":8,"y":149,"w":30,"text":"0","align":0}
{"id":27,"obj":"label","x":292,"y":25,"w":20,"text":"0","align":2}
{"id":28,"obj":"label","x":230,"y":25,"w":20,"text":"1","align":2}
{"id":29,"obj":"label","x":168,"y":25,"w":20,"text":"2","align":2}
{"id":30,"obj":"label","x":106,"y":25,"w":20,"text":"3","align":2}
{"id":31,"obj":"label","x":44,"y":25,"w":20,"text":"4","align":2}

Persist

I wanted my device to be the 'Source' of the lifetime usage in hours of the boiler so needed to ensure it retained it across reboots. That it where Persist comes in; it's a method to store something in Flash memory. I read that it wears out over so many writes but without knowing the numbers (I read anything between 10,000 and 100,000 write cycles) didn't want to push my luck so opted to save the number once per day at midnight using the mn() function and the cron in the autoexec.be file.
I can't remember the details but I think I created the original Persist entry using the Berry Console by typing something like:

import persist
persist.totalhours = 1900
persist.save()

You have to type 2 Returns together to get the above 3 lines to then run. After that you will see a new file called _persist.json in the Manage File System; mine now looks like:

{"totalhours":1916.01}

If people think I could get away with more frequent saving then let me know. Currently, I'm not planning on rebooting that often so the odd day's missed hours don't worry me.

Wiring

Here's the wiring diagram:

And a picture of my original loom. Originally I was going to have the plug/socket connector inside the case but I decided to make the wiring to the board longer and the connector outside the casing for ease of taking it back to the breadboard.

Home Assistant

If the Tasmota Integration is installed in HA the device should be discovered automatically and go by the name of the Device Name given in Configuration Other, in my case boiler. The mains detection Entities will have the names binary_sensor.boiler_switch1 and _switch2. The Temperature sensor Entities will have the names of the form sensor.boiler_ds18b20_1_temperature also a 2 and a 3. Now in my case the device appeared twice, with the Temperatures in one and the mains detectors in the other. It may have been because I'd been messing around on the workbench with 2 different Lilygos using the same MQTT Topic and HA just got in a muddle. Hopefully, anyone implementing this project does not get the same!
Two other Entities (runtime and life runtime) coming from the device have to be manually entered in the configuration.yaml file with the following code:

mqtt:
  sensor:
     - name: "Boiler Runtime Today"
          unique_id: [give your unique id; it helps]
          state_topic: "tele/boilerdisplay/RUNTIME"
          unit_of_measurement: 'Hrs'
          force_update: true
        - name: "Boiler Runtime Life"
          unique_id: [give your unique id; it helps]
          state_topic: "tele/boilerdisplay/TOTHRS"
          unit_of_measurement: 'Hrs'
          force_update: true

You should note that the Topics above match the Topics used in the Berry autoexec.be code file. The Entities will go by the names sensor.boiler_runtime_today and _life. If you already have mqtt sensors configured, miss out the first 2 lines and add the rest to your mqtt block.
That's all the sensors sorted and you now need to add an Automation to publish the HA stats. I chose to do this every 5 minutes, when there's a change in sensor.boiler_runtime_today and in response to the second onboard button being pressed. Here is the code for the automation:

alias: Boiler Publish Stats
description: ""
trigger:
  - platform: device
    domain: tasmota
    device_id: 7ed4ee2541a6044d0efb68e6f47e01aa
    type: button_short_press
    subtype: button_2
    discovery_id: 4827E2EA5880_button_2_SINGLE
  - platform: time_pattern
    minutes: /5
  - platform: state
    entity_id:
      - sensor.boiler_runtime_today
condition: []
action:
  - service: mqtt.publish
    data:
      qos: 0
      retain: false
      payload_template: |-
        {% set x =
               ['sensor.boiler_runtime_today',
                'sensor.oil_litres_today',
                'sensor.oil_kwh_today',
                'sensor.oil_cost_today',
                'input_number.boiler_max_runtime_today']
              | map('states') | map('float', 0) | list %}
            {{ '{"Hours": %5.2f, "Oil": %5.2f, "KWh": %5.2f, "Cost": %5.2f, "Maxruntime": %7.5f}'|
            format(*x)  }}
      topic: cmnd/boilerdisplay/BoilerStats
mode: single

Note: discovery_id: and device_id: will be different on another implementation. The mqtt publish topic issues the command BoilerStats to the Tasmota device and the boilerstats function defined in the autoexec.be file is what gets run as a result.
Also note that I was concerned about reboots of the device during the day losing the runtime so far, so I added some code to retain the value so far in HA, report it in the boiler stats such that the device can compare the 2 values and update its internal one if necessary. The code is in the autoexec.be above and the HA automation is here:

alias: Boiler log max daily temperature
description: >-
  Used to ensure the Lilygo display gets told current runtime if it reboots.
trigger:
  - platform: state
    entity_id:
      - sensor.boiler_runtime_today
condition: []
action:
    sequence:
      - if:
          - condition: template
            value_template: >-
              {{states('sensor.boiler_runtime_today')|float >
              states('input_number.boiler_max_runtime_today')|float}}
        then:
          - service: input_number.set_value
            entity_id: input_number.boiler_max_runtime_today
            data_template:
              value: "{{states('sensor.boiler_runtime_today')}}"
mode: single

That's all for now. I have some other stuff in HA to record the oil left in the tank as it gets used and to store values for 'Yesterday' so I can have dashboards that show Today's values with Yesterday's as a comparison. I also want to add some other features. Once I've tidied them up to my liking I will add them.
Happy to have comments about how I might have done stuff better and questions if I've not explained anything properly.

[sfromis]

Did you consider whether the recently added HASPmota chart object would be usable for you?
https://tasmota.github.io/docs/HASPmota/#attributes-specific-to-chart

[richardsg307]

Yes. I tried it out and it could have worked, but I wanted a third series; it only does 2. I may even add a fourth to indicate demand; especially after I do something to tell HA whether its CH or HW doing the demanding. I could show that on the graph (or a second very small, in the y, bar graph).

[Leonardodicorsio]

Great,
i have added 2 relays to my boiler and can control is via Domoticz.
it is set to heat the water depending on the sun (solarpanels) in 500W 1000W or 2000W. my means of R1 and R2 see attm