blossom-ic Heating for Home Assistant

Unofficial integration for blossom-ic heating systems (GT-100 gateway + Avalon/Avalon+ thermostats and friends). Built by reverse engineering the Android app — blossom-ic has no official API.

Status: early development. The cloud API is implemented end to end but only exercised against live servers with a test account so far. See docs/protocol.md for the full protocol write-up.

How it talks to your heating

• Cloud (implemented): the same HTTPS/PHP API the official app uses ({2,3}.blossomic.net). Sessions use the app's rolling aes_id token scheme, reimplemented in custom_components/blossomic/api/crypto.py.
• Local (research): the GT-100 is a serial↔UDP device server bridging the RF protocol to the cloud over UDP/11320. A transparent MITM proxy (tools/udp_proxy.py) already captures and decodes the native framing; a future version of this integration aims to talk that protocol directly on the LAN. See docs/protocol.md.

Installation (HACS)

1. Add this repository as a custom repository in HACS (type: Integration).
2. Install blossom-ic Heating, restart Home Assistant.
3. Settings → Devices & Services → Add Integration → blossom-ic Heating.
4. Sign in with the credentials from the Blossomic app. If your account has several gateways, you can pick which one to bind.

What you get

• One climate entity per zone (ervid): current temperature, target temperature, heating action (Fire/Snow/None), weekly-program flag.
• One "All zones" climate entity per gateway: writes fan out to every zone — one card sets the whole home to sleep / comfort / a temperature. State shows the consensus (mode/preset/temp only when all zones agree; current temperature is the mean).
• HVAC modes: auto = blossom schedule ("Auto"), heat = manual hold, off = blossom "off" mode (real power-down of the stat — it may only rejoin on its wake interval, or need a physical button press).
• Presets: comfort / eco / sleep (the blossom timed programs; setting a preset also applies that program's configured temperature).
• Binary sensors: zone connectivity, per-device low battery.
• Schedules: blossom weekly programs keep running inside the system; native HA automations (climate.set_temperature / presets) layer on top. Direct editing of blossom weekly-program data via service calls is planned.

Rooms & group control

Zones are individual stats, not rooms — several stats can share one physical room (e.g. two radiators). For room-level control assign the climate entities to Areas (Settings → Areas, labels & zones) and target the area in automations/scripts — all standard climate services (climate.set_preset_mode, set_hvac_mode, set_temperature) accept area_id.

Example "Nachtmodus" scene/script (configuration.yaml or the UI editors):

script:
  nachtmodus_bad:
    alias: "Bad Nachtmodus"
    sequence:
      - action: climate.set_preset_mode
        target:
          area_id: badezimmer
        data:
          preset_mode: sleep

A ready-made script blueprint lives in blueprints/script/blossomic/apply_preset.yaml — in HA go to Settings → Automations & Scenes → Blueprints → Import blueprint and paste the raw file URL from your git server, then create a script from it (target = an area, a device, or the "All zones" entity).

Notes & caveats

• Writes use the app's read-modify-write semantics (the set API expects the full zone object) — a change takes two API calls plus a poll refresh.
• Polling defaults to 60 s (configurable in the integration options). The session token chain is shared with the official app: running HA and the app concurrently is expected to work but keep the interval modest.
• All RF-side magic (automatic hydronic balancing etc.) stays inside the blossom-ic system — the integration only moves setpoints and modes.
• Local gateway web UI exists (admin:admin on this unit — change it) but only exposes device-server network settings, no thermostat data.

Development

python3 -m venv tools/venv               # Windows: py -m venv tools\venv
tools/venv/bin/pip install -e ".[dev]"   # Windows: tools\venv\Scripts\pip install -e ".[dev]"

tools/venv/bin/python -m pytest tests/   # unit + mocked client tests
tools/probe.py                           # live API probe (needs tools/.env)
tools/udp_proxy.py                       # local-protocol MITM capture
tools/decode.py                          # frame decoder for capture logs

tools/.env (gitignored): BLOSSOMIC_USER=…, BLOSSOMIC_PASS=…

Not affiliated with blossom-ic. Trademarks belong to their owners.