ATAG ONE binding v0.4.0-beta (pre-release, for testing)

0.4.0-beta — 2026-09-16

Changes since 0.3.0-beta: a critical fix for a schedule-write bug that silently wiped the whole
week to empty, whole-week schedule read/write, overlap protection on every schedule-write path,
and a channel audit that removed eight low-value channels.

What's changed

• Fixed: writing a schedule could silently wipe it to empty. The device's local API requires
  start/end as bare integers ([0,240,20.5]) — this binding was sending them as floats
  ([0.0,240.0,20.5]), which the device accepted, reported success for (acc_status:2), and then
  silently discarded, replacing the whole week with empty entries. No error, no controller-reset
  counter bump — the only way to catch it was an independent read-back that didn't trust the
  write's own reported success. If you've used any of the schedule-editing Actions on 0.3.0-beta,
  check your schedule after upgrading.
• New: heating#schedule / hotwater#schedule — read-only channels publishing the full
  polled week as JSON, for a rule or a UI to read before editing.
• New: setChSchedule / setDhwSchedule Thing Actions — replace a whole week in one device
  write instead of one write per period. A weekday the JSON omits is resent unchanged from the
  last poll, so a caller only needs to name the day(s) it actually edited.
• All four schedule-write Actions now reject an overlapping period — writing a period that
  overlaps another period already on the same weekday fails the call instead of silently accepting
  a write the device's behavior for is undefined.
• Channel audit — 8 channels removed, each either a constant reading with no ATAG-side
  settings surface, redundant with another channel, or an unverifiable inferred value:
  hotwater#water-pressure, heating#burner-target, device#memory-allocation,
  heating#regulation-state, control#vacation-duration-default,
  control#extend-duration-default, heating#min-modulation-level,
  heating#max-boiler-temperature.
• boilerDetectType Thing property removed — never confirmed to be a boiler type rather
  than a detection-method flag, and no mapping to a real model name was ever found.
• device#language is now writable, verified against the app.
• Hardening: schedule-write JSON input is capped in size and periods-per-day, and a deeply-nested
  payload now fails cleanly instead of risking a stack overflow.

Full current channel list

63 channels across five groups (down from 69 — see the removals above; two added back via the new
schedule channels).

Known limitations

• Same as 0.3.0-beta: device#time-zone write is only Berlin-verified; fireplace cancel always
  needs a physical button press.
• Scheduling a future vacation start is still not implemented.

Not yet implemented

• A structured schedule-editing UI — setChSchedule/setDhwSchedule give a rule or a UI the
  building blocks for one, but this binding doesn't ship a UI itself.

ATAG ONE binding v0.3.0-beta (pre-release, for testing)

0.3.0-beta — 2026-09-14

Changes since 0.2.0-beta: schedule read/write support (including per-entry editing), ~20 new
settings channels, a real bug fix in burner-status decoding, and a wide vocabulary/unit cleanup
pass. This is the largest update since the initial release.

What's changed

• Central heating and hot water schedules are now readable and writable, including per-entry
  editing via four new Thing Actions: setChSchedulePeriod, clearChSchedulePeriod,
  setDhwSchedulePeriod, clearDhwSchedulePeriod. Each schedule's fallback temperature
  (heating#schedule-base-temperature / hotwater#schedule-base-temperature) is also directly
  writable now.
• Fixed: boiler_status bitmask decoding had central heating and hot water swapped, and the
  flame bit was wrong. A real DHW heating cycle could be reported as heating#central-heating-active
  instead of hotwater#hot-water-active, and heating#flame never correctly went ON even while
  the burner was clearly firing. Corroborated against an independent protocol reference
  (kozmoz/atag-one-api) and a
  real-world misclassification report. If you're on 0.2.0-beta, this alone is worth upgrading for.
• ~20 new settings channels: frost protection (mode + thresholds), summer eco mode, legionella
  protection (day/time), display brightness, writable time zone, display language, and the
  weather-compensation tuning fields (insulation, building size, heating type, climate zone, room
  influence, max preheat).
• Three new temperature-correction channels: weather-dependent flow temperature shift, and
  independent outside/room sensor calibration offsets.
• Manual mode is writable again (preset-mode=manual), reversed after live verification found
  no basis for the original rejection.
• New read-only channels matching what the ATAG app/portal show that this binding didn't yet:
  delta temperature, independent central-heating/hot-water-active indicators, next-schedule
  preview (time + temperature), weather-service outside temperature, and regulation state.
• Thing properties: serial number, firmware version, installer ID, and boiler detection type,
  populated once paired.
• hotwater#schedule-base-temperature's and heating#schedule-base-temperature's setpoint
  bounds are now read from the device instead of hardcoded, since they vary by installation type.
• Display/unit fixes: several duration channels now show in sensible units instead of raw seconds,
  WiFi signal is now a 0–4 quality scale instead of a raw dBm reading that openHAB was silently
  misrendering as watts, legionella protection time now shows as HH:mm, and display language now
  shows as a name instead of a raw integer.
• Breaking — vocabulary aligned with the ATAG manual: heating#isolation →
  heating#insulation (channel ID rename); heating#control-mode's values room/weather →
  thermostat/weather-dependent; heating#frost-protection's values outdoor/indoor →
  outside/inside; heating#wdr-temperature-influence's values average/room-regulation →
  medium/room-control.
• Breaking — two redundant channels removed: heating#shown-set-temperature (always matched
  heating#target-temperature) and control#preset-mode-duration (duplicated
  control#extend-remaining/control#fireplace-remaining).
• Breaking — item type changed on device#wifi-signal (Number:Power → Number:Dimensionless),
  hotwater#legionella-protection-time (Number:Time → String), and device#language
  (Number → String).

Full current channel list

69 channels across five groups:

• Operating Mode (control#) — active preset, timed-mode durations and remaining-time
  countdowns, vacation setpoint/start/end/remaining, next-schedule preview.
• Central Heating (heating#) — room/target temperature, outside temperature (boiler estimate
  and weather-service), weather status, circuit water temperature/pressure/return/delta, control
  mode, flame, burner target, central-heating-active, modulation level, burning hours, schedule
  fallback temperature, frost protection, summer eco mode, and the weather-compensation settings
  (heating type, insulation, building size, climate zone, room influence, max preheat), plus
  advanced diagnostics (boiler flow/return temperature, PCB temperature, min modulation level,
  regulation state, time to target).
• Hot Water (hotwater#) — current temperature, target temperature, water pressure, flow
  rate, hot-water-active, schedule fallback temperature, legionella protection.
• Device (device#) — WiFi signal quality, supply voltage, controller resets, memory
  allocation, report timestamp, display brightness, time zone, display language.
• Alerts (alerts#) — device and boiler error codes.

Known limitations

• device#time-zone is writable, but only Berlin is verified against a real device — the other 9
  cities are inferred from the app/portal's dropdown order only. Write at your own risk.
• device#language stays read-only — changing the thermostat's display language from openHAB has
  near-zero automation value.
• Cancelling fireplace mode always needs a button press on the thermostat display — confirmed
  device behavior, no API payload avoids it.
• Upgrading from 0.2.0-beta requires deleting and re-adding the Thing, not just
  disabling/re-enabling it — an already-initialized Thing doesn't pick up a new channel-group
  structure, removed channels, or item-type changes from a jar swap alone. Re-link every item
  afterwards.

Not yet implemented

• Scheduling a future vacation start (today's holiday-mode activation is always immediate).
• A structured schedule-editing UI — the four new Actions let a rule build one up period by
  period, but there's no bulk/whole-week write yet.

ATAG ONE binding v0.2.0-beta (pre-release, for testing)

0.2.0-beta — 2026-08-31

Changes since 0.1.0-beta: a redesign of how modes are activated/cancelled, new Thing Actions, a
regrouped and renamed channel taxonomy, and several bugs found and fixed via live verification
against the device.

What's changed

• 42 channels, regrouped by subsystem instead of protocol block. control is now "Operating
  Mode" (preset/timed-mode only — target-temperature and dhw-target-temperature moved to their
  own subsystems). settings is gone; ch-control-mode moved into Central Heating. Several
  channels dropped redundant subsystem prefixes (dhw-temperature → hotwater#temperature,
  ch-water-temperature → heating#water-temperature, etc). All descriptions rewritten for end
  users. Breaking — see Known limitations below for the upgrade path.
• Trigger model: preset-mode is now the only channel that can activate or cancel a mode.
  Writing a duration channel only updates the stored value for next time — it never triggers
  activation on its own. Matches how the device itself treats a duration field written alone, and
  avoids a duration write accidentally flipping the active mode.
• New Thing Actions for single-write custom-duration control, since duration channels no
  longer trigger activation: activateVacation(seconds), activateExtend(seconds),
  activateFireplace(seconds), cancelMode().
• Timed-preset durations must now be whole units (hours for extend/fireplace, days for vacation) —
  enforced client-side, both on the channel and the action path. A non-conforming value doesn't
  fail safely on the device (it triggers the same physical-confirmation/reboot pathway as a
  cancel), so it's rejected before ever reaching the device.
• Fixed: cancelMode() against a pending (future-scheduled, not-yet-active) vacation used to
  report "nothing to cancel" and leave the schedule fully armed. Now correctly clears it.
• Fixed: hotwater#target-temperature writes were silently accepted but never took effect —
  the device field behind it turned out to be read-only/derived, not the actual control target.
  See Known limitations.
• Loosened the local API client's connection timeout, retry count, and rate-limit gap — the
  previous values were tuned defensively without a reference point and are the likely cause of the
  binding going OFFLINE more often than other integrations polling the same device.

Full current channel list

• Operating Mode (control#) — active preset (auto/holiday/extend/fireplace,
  manual read-only), timed-preset durations and remaining-time countdowns, vacation
  setpoint/start/end.
• Central Heating (heating#) — room/target temperature, outside temperature, weather
  status, circuit water temperature/pressure/return, control mode (room vs. weather-compensated),
  flame, burner target, modulation level, burning hours, and advanced diagnostics (boiler flow/
  return temperature, PCB temperature, min modulation level).
• Hot Water (hotwater#) — current temperature, flow rate. (See Known limitations below
  for the target-temperature channel.)
• Device (device#) — WiFi signal, supply voltage, controller resets, memory allocation,
  report timestamp.
• Alerts (alerts#) — device and boiler error codes.

Known limitations

• hotwater#target-temperature is read-only. The obvious device field for it
  (control.dhw_temp_setp) turned out to be read-only/derived — it tracks whichever hot-water
  schedule period is currently active, and writes to it are silently accepted but have no effect.
  The real user-settable field lives in the device's schedule data, which this binding doesn't
  read or write yet (see Not yet implemented). Exposed read-only in the meantime rather than
  shipped as a write that silently does nothing.
• Cancelling fireplace mode always needs a button press on the thermostat display. Confirmed
  device behavior, not a binding limitation — no API payload avoids it. The binding logs a
  warning when this happens, and cancelMode() reports it via its return value.
• Manual mode (ch_mode=1) is rejected on write, as a conservative safety choice — writing it
  is believed to destabilize the boiler API, though this hasn't been re-verified against current
  firmware. Set manually on the thermostat display instead.
• Upgrading from a previous build that used ungrouped or differently-grouped channels requires
  deleting and re-adding the Thing, not just disabling/re-enabling it — confirmed live that an
  already-initialized Thing doesn't pick up a new channel-group structure from a jar swap alone.

Not yet implemented

• Reading or writing the device's hot-water/heating schedules.
• Additional device settings as channels (frost protection, summer eco mode, legionella
  protection, heating curve/isolation/building-size, display brightness, time zone, language) —
  the device fields are documented in DEVELOPERS.md but not yet wired to channels.
• Thing properties for static device identity (boiler ID, installer ID, firmware version).

Full field-by-field API documentation, including what's verified vs. inferred, lives in
DEVELOPERS.md in this bundle.

ATAG ONE binding v0.1.0-beta (pre-release, for testing)

Pre-release build of the native ATAG ONE openHAB binding, for community testing ahead of the upstream PR to openhab/openhab-addons.

Drop the JAR into your openHAB addons/ folder to install. No cloud connection or MQTT broker required — talks directly to the thermostat's local LAN API.

Built from commit 177a01d on the atagone-binding-5.3.x branch (based on openHAB 5.3.0-SNAPSHOT).

See the binding's README for setup, pairing, and channel documentation.