{"id":36893281,"url":"https://github.com/f18m/floor-heating-controller","last_synced_at":"2026-01-12T15:39:56.867Z","repository":{"id":321684577,"uuid":"1086789724","full_name":"f18m/floor-heating-controller","owner":"f18m","description":"ESPHome project to expose up to 8x relays and temperature sensors to HomeAssistant","archived":false,"fork":false,"pushed_at":"2025-11-26T23:32:59.000Z","size":16338,"stargazers_count":1,"open_issues_count":2,"forks_count":0,"subscribers_count":0,"default_branch":"main","last_synced_at":"2025-11-29T03:57:42.177Z","etag":null,"topics":["esphome","floor-heating","home-assistant","homeassistant"],"latest_commit_sha":null,"homepage":"","language":null,"has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/f18m.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null}},"created_at":"2025-10-30T22:58:45.000Z","updated_at":"2025-11-26T23:32:39.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/f18m/floor-heating-controller","commit_stats":null,"previous_names":["f18m/floor-heating-controller"],"tags_count":2,"template":false,"template_full_name":null,"purl":"pkg:github/f18m/floor-heating-controller","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f18m%2Ffloor-heating-controller","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f18m%2Ffloor-heating-controller/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f18m%2Ffloor-heating-controller/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f18m%2Ffloor-heating-controller/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/f18m","download_url":"https://codeload.github.com/f18m/floor-heating-controller/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/f18m%2Ffloor-heating-controller/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28341195,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-12T12:22:26.515Z","status":"ssl_error","status_checked_at":"2026-01-12T12:22:10.856Z","response_time":98,"last_error":"SSL_connect returned=1 errno=0 peeraddr=140.82.121.6:443 state=error: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["esphome","floor-heating","home-assistant","homeassistant"],"created_at":"2026-01-12T15:39:56.154Z","updated_at":"2026-01-12T15:39:56.861Z","avatar_url":"https://github.com/f18m.png","language":null,"funding_links":[],"categories":[],"sub_categories":[],"readme":"# floor-heating-controller\n\nThis is an [ESPHome](https://esphome.io/) project to present to [HomeAssistant](https://www.home-assistant.io/) a floor heating controller, i.e. a board that can turn on or off the flow of warm water in under-floor heating pipes.\n\nIn particular this project provides an [ESPHome package](https://esphome.io/components/packages/) that is easy to reference\nfrom an ESPHome configuration. Keep reading for more details.\n\n\u003cimg title=\"ESPHome\" alt=\"ESPHome\" src=\"images/esphome.png\"\u003e\n\n\n## Highlights\n\n* Plain simple actuator board, all the hardware is Commercial Off-The-Shelf (COTS), \ntypically available on Aliexpress, and very cheap; easy to replace in future if it fails;\n* Connects to your [Home Assistant](https://www.home-assistant.io/) instance via Wi-fi;\n* Designed to be capable of running in a dumb, non-smart mode if Wi-fi connection drops\nor your HomeAssistant instance has troubles;\n* Presents _N_ basic switches plus 2 temperature sensors to Home Assistant; each switch represents an heating under-floor circuit; temperatures are sampled for both the incoming warm water and for room temperature\n\n\n## Architecture Overview\n\n\u003cimg title=\"Overview\" alt=\"Overview\" src=\"images/overview.drawio.png\"\u003e\n\nThis project allows to easily setup in HomeAssistant a [Generic Thermostat](https://www.home-assistant.io/integrations/generic_thermostat/) entity that allows to control the floor heating system:\n\n\n```yaml\nclimate:\n  - platform: generic_thermostat\n    name: Floor Heating\n    heater: switch.floorheatingactuatorcontroller_relay1\n    target_sensor: sensor.floorheatingactuatorcontroller_ambient_temperature\n    min_temp: 15\n    max_temp: 25\n    ac_mode: false\n    target_temp: 17\n    cold_tolerance: 0.3\n    hot_tolerance: 0\n    min_cycle_duration:\n      minutes: 1\n    initial_hvac_mode: \"off\"\n    precision: 0.1\n    # preset mode temps\n    away_temp: 20\n    home_temp: 22\n    sleep_temp: 21\n```\n\nOne climate entity is connected to 1 temperature sensor and to 1 switch for the \"heater\" exposed by this ESPHome project.\nSo if you have e.g. 5 rooms on your floor and you want to control heating independently you should:\n\n* install a temperature sensor in each room\n* cable the thermal actuator of each room to each relay available on this ESPHome project (see below ESP32 board details)\n* define a Generic Thermostat for each room\n\nPlease note that instead of writing YAML code in your HomeAssistant `configuration.yaml` file you probably\nwant to use the HomeAssistant UI: look for Helpers and choose `Generic Thermostat` from the list.\n\n\n## Bill Of Material\n\n* ESP32 relay board [bought on Aliexpress](https://it.aliexpress.com/item/1005007027676026.html?spm=a2g0o.order_list.order_list_main.31.42f53696cth4st\u0026gatewayAdapt=glo2ita) (17.5€ in Oct 2025).\nIts main characteristics are:\n\n  * Sports an [ESP32-WROOM-32E module](./datasheets/esp32-wroom-32e_esp32-wroom-32ue_datasheet_en.pdf) with 240MHz clock, 320kB RAM, 4MB Flash\n  * 5V DC power supply terminal\n  * 8 relay channels, both NC and NO contacts available\n\n\u003cimg title=\"Relay board\" alt=\"Relay board\" src=\"images/esp-relay-board-bare.jpg\"\u003e\n\n\n* 220V to 5V power adapter (5W), [bought on Aliexpress](https://it.aliexpress.com/item/1005006981553550.html?spm=a2g0o.order_list.order_list_main.47.45de36964bR8Kp\u0026gatewayAdapt=glo2ita) (4€ in Oct 2025)\n\n* Temperature sensors, bought on Aliexpress (few € in Oct 2025)\n\n  * `MAX6675` and a K-type thermocouple for reading pipe temperature,\n    see https://esphome.io/components/sensor/max6675/\n  * `DHT11`: Digital Temperature Humidity Sensor,\n    see https://esphome.io/components/sensor/dht/\n\nAlternative sensors I also tested in an instance of this ESPHome Package are:\n\n  * `MAX31855` and a K-type thermocouple for reading pipe temperature,\n    see https://esphome.io/components/sensor/max31855/\n  * `DHT22`: Digital Temperature Humidity Sensor,\n    see https://esphome.io/components/sensor/dht/\n\n\n## ESP32 Relay Board Pinout\n\nThe ESP32 relay board currently being used has the following pinout:\n\n* GPIO23: led D20\n* GPIO13: relay 1\n* GPIO12: relay 2\n* GPIO14: relay 3\n* GPIO27: relay 4\n* GPIO26: relay 5\n* GPIO25: relay 6\n* GPIO33: relay 7\n* GPIO32: relay 8\n\nPlease note that GPIO12 is a strapping PIN and should only be used for I/O with care.\nAttaching external pullup/down resistors to strapping pins can cause unexpected failures.\nSee https://esphome.io/guides/faq.html#why-am-i-getting-a-warning-about-strapping-pins\n\nIn addition to these, the following GPIOs are used for the temperature sensors:\n\n* GPIO5: `DHT11` sensor\n* GPIO16 (MISO), GPIO17 (CLK) and GPIO15 (CS): for the SPI bus to read the `MAX6675` sensor\n\nGraph of the ESP-to-sensor connections:\n\n\u003cimg title=\"Sensors\" alt=\"Sensors\" src=\"images/ESP-to-sensors-connections.drawio.png\"\u003e\n\nAnd a picture to help with physical connection setup:\n\n\u003cimg title=\"Relay board\" alt=\"Relay board\" src=\"images/esp-relay-board.png\"\u003e\n\n\n## Full ESPHome configuration\n\nSee the [main.yaml](./main.yaml) file for the ESPHome package provided by this project.\nPlease note that this is an [ESPHome package](https://esphome.io/components/packages/) and thus it uses [substitutions](https://esphome.io/components/substitutions/) to make the YAML config file as reusable as possible.\n\nAn actual ESPHome YAML config using this package could be:\n\n```yaml\npackages:\n  remote_package_files:\n    url: https://github.com/f18m/floor-heating-controller/\n    files: \n      - path: main.yaml\n        vars:\n          encryption_key: !secret encryption_key\n          wifi_ssid: !secret wifi_ssid\n          wifi_password: !secret wifi_password\n          wifi_ap_password: !secret wifi_ap_password\n          ota_password: !secret ota_password\n    ref: main  # optional\n    refresh: 1d  # optional\n\nesphome:\n  name: \"floorheating-p0\"\n  friendly_name: FloorHeatingActuatorController-P0\n```\n\nwhich is basically assigning the secrets defined in the ESPHome global \"secrets.yaml\" to the variables of this package.\nThen it's overriding just the name \u0026 friendly name from the package.\nSee e.g. [example-instance.yaml](./example-instance.yaml)\nand [example-instance-with-different-sensors.yaml](./example-instance-with-different-sensors.yaml).\n\n\n## First ESPHome install\n\nWhen you receive your ESP32 relay board, you will need to carry out the first ESPHome installation\nby \"wire\". Afterwards, you'll be able to install any ESPHome profile over the wireless connection using\nthe so-called On-The-Air update (OTA update).\n\nMake sure you read carefully the [ESPHome guide](https://esphome.io/guides/physical_device_connection/)\non how to Physically Connecting to your Device.\n\nYou will need a USB-to-serial module.\nI bought [one on Aliexpress](https://it.aliexpress.com/item/1005004742270942.html?spm=a2g0o.order_list.order_list_main.107.33a03696c66vOs\u0026gatewayAdapt=glo2ita) for 2€.\nA couple of pictures zooming on the programmer itself and then its connections to the ESP32 relay board:\n\n\u003cimg title=\"Programmer\" alt=\"Programmer\" src=\"images/programmer.jpg\"\u003e\n\u003cimg title=\"Programmer\" alt=\"Programmer\" src=\"images/programmer_connection.jpg\"\u003e\n\nOnce physical connection is ready, you will be able to install ESPHome initial firmware:\n\n1. Log on your HomeAssistant and go to the ESPHome web interface\n2. Create a new device, copy-pasting the [example-instance.yaml](./example-instance.yaml)\n3. Launch \"Validate\" from the 3-dots menu for your new ESPHome device\n4. Launch \"Install\" from the 3-dots menu for your new ESPHome device and choose \"Plug into this computer\" option:\n\n\n\u003cimg title=\"Programmer\" alt=\"Programmer\" src=\"images/programmer_esphome.png\"\u003e\n\nAfter successful flashing you should be able to see logs coming from your board and, if the Wifi credentials\nare OK, your board should appear in the list of DHCP clients of your DHCP server.\n\n\n## Labelling of the board\n\nSince most likely your floor heating controller will be installed in some hidden box\nand will stay around for a lot of time (many years hopefully), I suggest to provide \nsome documentation reference for that.\nA simple approach is to print a QR code pointing at this page.\n\nHere you can find a QR code I produced with the optimal [miniQR code generator](https://mini-qr-code-generator.vercel.app/):\n\n\u003cimg title=\"Programmer\" alt=\"Programmer\" src=\"images/qr-code.png\"\u003e\n\n\n## TODO\n\n* Write the [external component](https://esphome.io/components/external_components/) that will make it possible to control relays using the local temp sensor when connection to HA fails.\n\n* Signal wifi connectivity through the LED\n\n\n\n## Similar projects\n\n* [Smart Underfloor Heating Controller](https://hackaday.io/project/190828-smart-underfloor-heating-controller)\n* [Nicolas Liaudat's Floor Heating Controller](https://github.com/nliaudat/floor-heating-controller)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff18m%2Ffloor-heating-controller","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ff18m%2Ffloor-heating-controller","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ff18m%2Ffloor-heating-controller/lists"}