# Smart Oil Heating Control System

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
```mermaid
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](main/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](main/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](main/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](main/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

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