ESP32-based control system for oil-fired central heating with schedule-based temperature management, safety monitoring, and Prometheus metrics export.

Features

Schedule Control: Day/night temperature targets per weekday
Summer Mode: Automatic heating disable based on outdoor temperature
Safety Monitoring: Sensor sanity checks with automatic safe-state fallback
Prometheus Metrics: HTTP endpoint at port 9100

System Overview

flowchart TB
    subgraph OUTSIDE[" "]
        OT[/"🌡️ Outdoor Temp<br/>DS18B20"/]
    end

    subgraph BURNER["OIL BURNER"]
        CT[/"🌡️ Chamber Temp<br/>DS18B20"/]
        BF[["⚠️ Burner Fault<br/>GPIO19 INPUT"]]
        BR(["🔥 Burner Relay<br/>GPIO14"])
        SC(["🔌 Safety Contact<br/>GPIO12"])
    end

    subgraph CIRCUIT["HEATING CIRCUIT"]
        IT[/"🌡️ Inlet Temp<br/>DS18B20"/]
        CP(["💧 Circulation Pump<br/>GPIO27"])
        RT[/"🌡️ Return Temp<br/>DS18B20"/]
    end

    RAD["🏠 Radiators"]

    BURNER -->|"hot water"| IT
    IT --> CP
    CP --> RAD
    RAD --> RT
    RT -->|"cold water"| BURNER

Prometheus Metrics

curl http://X.X.X.X:9100/metrics

Example

burner_fault_pending 1
circulation_pump_enabled 1
burner_enabled 0
safety_contact_enabled 1
chamber_temperature 37.312500
chamber_temperature_avg10 37.393749
chamber_temperature_avg60 37.689583
chamber_temperature_damped 38.058098
chamber_temperature_pred60 36.697266
inlet_flow_temperature 34.562500
inlet_flow_temperature_avg10 34.587502
inlet_flow_temperature_avg60 34.880207
inlet_flow_temperature_damped 35.255993
inlet_flow_temperature_pred60 33.910374
outdoor_temperature 1.812500
outdoor_temperature_avg10 1.825000
outdoor_temperature_avg60 1.821875
outdoor_temperature_damped 2.390663
outdoor_temperature_pred60 1.840263
return_flow_temperature 34.125000
return_flow_temperature_avg10 34.162498
return_flow_temperature_avg60 34.304165
return_flow_temperature_damped 31.430506
return_flow_temperature_pred60 33.858772
chamber_temperature_state 0
outdoor_temperature_state 0
inlet_flow_temperature_state 0
return_flow_temperature_state 0
safety_state 0
control_state 3
control_current_weekday 5
control_current_entry_time 24300
control_current_entry_chamber_temperature 80.000000
control_current_entry_return_flow_temperature 30.000000
sntp_state 0
system_unixtime 1768067412
uptime_seconds 344878
wifi_rssi -59

Status Encoding

Digital Themperatur Sensor DS10B20

chamber_temperature_state
outdoor_temperature_state
inlet_flow_temperature_state
return_flow_temperature_state

Enum eSensorErrorState in safety.h	Value	Description
SENSOR_NO_ERROR	0
SENSOR_TOO_HIGH	1	Sanity check failed
SENSOR_TOO_LOW	2	Sanity check failed
SENSOR_UNCHANGED	3	Sanity check failed
SENSOR_NOT_FOUND	4	No Communication

Safety Loop

safety_state

Enum eSafetyState in safety.h	Value	Description
SAFETY_NO_ERROR	0
SAFETY_SENSOR_ERROR	1	At least one sensor failed
SAFETY_INTERNAL_ERROR	2	Internal error

Control Loop

control_state

Enum eControlState in control.h	Value	Description
CONTROL_STARTING	0
CONTROL_HEATING	1	Burner running
CONTROL_OUTDOOR_TOO_WARM	2	Heating not needed
CONTROL_RETURN_FLOW_TOO_WARM	3	Heating not needed
CONTROL_FAULT_BURNER	4	Burner reported fault after threshold is reached
CONTROL_FAULT_SAFETY	5	Unable to control due safety fault
CONTROL_FAULT_SNTP	6	Unable to control due SNTP fault

SNTP Client

sntp_state

Enum eSntpState in sntp.h	Value	Description
SYNC_SUCCESSFUL	0
SYNC_NOT_STARTED	1
SYNC_FAILED	2

Hardware

Function	ESP32	PLC ES32C14
Output CirculationPump	IO27	Relay 1 NC1
Output Burner Fire Signal	IO14	Relay 2 NC2
Output Safety Contact (powers Burner)	IO12	Relay 3 NC2
Input Burner Fault	IO19	Digital Input IN1
Input Temperature DS10B20	IO04	1-Wire

Configuration

All parameters configurable via idf.py menuconfig:

WiFi credentials and static IP
GPIO pin assignments
1-Wire sensor addresses
Temperature thresholds and limits
Heating schedule (day/night per weekday)
Damping factors

Building

idf.py set-target esp32
idf.py menuconfig  # Configure settings
idf.py build flash monitor