OpenEMS – Controller.IO.HeatingElement
The Controller.IO.HeatingElement controls a multi-stage heating element (1–3 phases) depending on PV surplus, time constraints, or energy targets.
Source: ControllerIoHeatingElementImpl.java
Operating Modes (mode)
| Mode | Description |
|---|---|
MANUAL_OFF |
Heating element permanently off |
MANUAL_ON |
Heating element permanently on using defaultLevel |
AUTOMATIC |
Automatic control |
Heating Levels (Level)
| Level | Active Phases |
|---|---|
LEVEL_0 |
all off |
LEVEL_1 |
L1 |
LEVEL_2 |
L1 + L2 |
LEVEL_3 |
L1 + L2 + L3 |
WorkModes (workMode)
NONE
Pure surplus-power control.
Behavior: - Heats only when PV surplus is available - No minimum runtime or energy target - Battery discharge is considered
Suitable for: - simple PV surplus utilization
TIME
Time-based minimum runtime control.
Goal:
- Reach at least minTime before endTime
Behavior:
- Uses PV surplus first
- Enables forced heating if required (ACTIVE_FORCED)
- Uses defaultLevel as minimum heating level
Suitable for: - ensuring daily hot water availability
ENERGY
Energy-target-based control.
Goal:
- Reach minEnergylimit before endTimeWithMeter
Behavior:
- Uses PV surplus first
- Continuously calculates delivered energy (SESSION_ENERGY)
- Enables forced heating if required
- Detects:
- DONE
- UNREACHABLE
Note:
- Best used with a dedicated heating-element meter (meter_id)
Suitable for: - guaranteeing a defined daily hot-water energy amount
Schedule
An optional schedule (JSCalendar format) can be configured.
Behavior: - no active task → heating element off - active task → operates only within scheduled time window
Important Configuration Parameters
| Parameter | Description |
|---|---|
mode |
Main operating mode |
workMode |
NONE / TIME / ENERGY |
defaultLevel |
Default heating level |
powerPerPhase |
Power per phase |
meter_id |
Heating element meter |
outputChannelPhaseL1..L3 |
Digital output channels |
minTime |
Minimum runtime |
endTime |
End time for TIME mode |
minEnergylimit |
Minimum energy target |
endTimeWithMeter |
End time for ENERGY mode |
minimumSwitchingTime |
Switching hysteresis |
schedule |
Time schedule |
Status Values (Status)
| Status | Description |
|---|---|
INACTIVE |
off |
ACTIVE |
active using surplus |
ACTIVE_FORCED |
forced by time logic |
ACTIVE_FORCED_LIMIT |
forced by energy logic |
DONE |
target reached |
UNREACHABLE |
target cannot be reached |
CALIBRATION |
initial calibration |
Typical Use Cases
PV Surplus Heating
mode=AUTOMATIC
workMode=NONE
Ensure Hot Water Until Evening
mode=AUTOMATIC
workMode=ENERGY
Minimum Daily Runtime
mode=AUTOMATIC
workMode=TIME