DEV Community: Michael Bernhart

Decoupling a KNX Alarm from the JUNG Panel in Home Assistant

Michael Bernhart — Tue, 21 Jul 2026 08:38:33 +0000

The house came with a JUNG EAM4000 KNX alarm panel, and for years it owned the entire security story. It gated the motion detectors, it decided whether the place was armed, and it drove the sirens. When I started pulling the house into Home Assistant, the obvious move was to read the alarm out of that panel and call it done. I didn't do that, and this post is about why.

The naive way couples you to the panel

The tempting approach is to tap the panel's own outputs: wire its zone and sabotage objects into HA and read them as sensors. It works on day one. But then HA only ever knows what the panel decides to tell it. When the panel is disarmed, those zone outputs go quiet, so HA sees nothing either. Your automation logic now lives downstream of someone else's arming logic, and you've inherited a dependency you can't easily reason about or change.

I didn't want Home Assistant to be a slave to the JUNG panel. I wanted HA to be the thing that decides, and the panel to become, at most, a peer on the bus. So I inverted who owns the truth.

HA owns the state and exposes it back onto the bus

The core trick is almost embarrassingly simple once you see it. Instead of reading the alarm's status out of the panel, I made Home Assistant the owner of the alarm state and exposed it back onto the KNX bus. Two HA input_booleans — an 'armed/active' object and a 'ready to arm' object — get published to KNX group addresses as type binary via an expose: block in knx.yaml. The bus now reflects HA's truth, not the panel's.

# knx.yaml — HA OWNS the alarm state and pushes it back onto the bus
# (status + 'ready' are HA input_booleans exposed to KNX, not read from the panel)
expose:
  - type: "binary"
    entity_id: "input_boolean.knx_ha_alarm_status"
    address: "x/1/10"   # HA-owned 'armed' object on the bus (real GA masked)
  - type: "binary"
    entity_id: "input_boolean.knx_ha_alarm_bereit"
    address: "x/1/11"   # HA-computed 'ready to arm'

Note these exposed objects deliberately omit sync_state — HA is the writer here, it's allowed to push. The addresses use the normal 3-level KNX form; I've masked the leading group because this is a security topic and the real map stays private.

Read presence off the light address, not the alarm zone

Here's the detail I'm genuinely happy about. The motion detectors already fire a light telegram to switch corridor and stair lighting, and they send it regardless of whether the alarm is armed. So I read each detector into HA through its light group address, not through the panel's alarm zone — a plain binary_sensor with device_class: motion pointed at the light status object. The payoff: HA sees presence even when the alarm is fully disarmed — exactly the information the panel would have hidden from me. There are seven JUNG 3361-1 detectors across the property, and I split them into a five-detector cellar set for a 'night' mode and the full seven-detector set for 'away'.

Every one of those read-only sensors sets sync_state: false — window contacts, motion detectors, tamper. That stops HA from issuing GroupValueRead requests or writing back, so on those objects HA is a passive listener and can't disturb the alarm's own bus traffic. The exposed alarm objects above deliberately omit it, because there HA is the writer.

'Ready to arm' is computed in HA, and arming is gated on HA's flag

The readiness lamp ('Bereit') isn't the panel's calculation anymore — it's mine. Window and opening contacts are modelled as binary_sensor with device_class: window straight off their KNX status objects, and the garage gets its own device_class: garage_door sensor. Two automations watch floor-level window groups for the ground and upper floors, and only when every window on both floors reports closed do they flip the exposed 'ready' boolean on. That computed readiness is then pushed back to KNX so the lamp on the bus shows HA's answer.

Arming converges on one source of truth. Two 'sync' automations keep a physical KNX wall switch and input_boolean.knx_ha_alarm_status in lock-step in both directions, so arming from the wall and arming from the app land on the same flag. And every escalation is gated on that flag: a window or door open triggers the automation, but nothing escalates unless HA's own armed flag is set. The JUNG panel is no longer in that decision.

# Every escalation is gated on HA's own armed flag, not the JUNG panel:
conditions:
  - condition: state
    entity_id: input_boolean.knx_ha_alarm_status
    state: 'on'
triggers:
  - trigger: state
    from: 'off'
    to: 'on'
    for:
      seconds: 5   # debounce a bouncing reed contact

That for: seconds: 5 is intentional anti-bounce — a flickering reed contact has to hold open for five seconds before it counts. On a real trigger HA writes the offending opening plus a timestamp into an input_text helper, logs it to the logbook, raises a persistent notification, sends a critical-priority push to the household phones (sound critical, volume 1.0, so it punches through iOS focus mode), and turns on a local buzzer plus lighting in a set of areas. The buzzer auto-deactivates five seconds after the armed boolean goes off again. All of it is orchestrated in HA, independent of the panel.

The safety net, and the honest trade-off

Before any of the HA work, I did one thing in ETS: I stripped the siren, flash and transmission group addresses out of the JUNG central unit. The point was that even if the panel mis-fired during the rewire, nothing would physically sound. HA becomes the only thing that can raise an alarm. (Editing the central unit needs JUNG's vendor ETS plug-in on Windows with a KNX/IP gateway — you can't reconfigure it from generic ETS.)

One real gotcha along the way: some detectors were still brightness-gated in ETS ('helligkeitsabhängig'), so they only sent their movement telegram in the dark. Reading presence off the light address means you have to reprogram those to send brightness-independently, or they show up dead in HA. A few of mine did exactly that until I caught it.

The honest trade-off: I gave up the panel's certified, tamper-monitored signal path for flexibility. The tamper contacts still exist — they're mapped as device_class: tamper sensors — but I'm no longer routing security through the panel's coupling. If you need a monitored, insurance-grade alarm path, that certified panel still has a real job. For a house where I want HA to actually own the logic, inverting ownership and listening passively on the bus was the cleaner build. If you're following the series, this leans on the same KNX foundation as the earlier HACS and Docker posts.

KNX Thermostats Drop to 'Standby' After Every Home Assistant Restart - A Startup Automation Fix

Michael Bernhart — Wed, 15 Jul 2026 10:19:28 +0000

It's a quiet bug that only bites you when the flat is cold in the morning: after every Home Assistant restart ‚Äî an update, an add-on install, a container restart, a power cut ‚Äî all of my KNX thermostats sat on 'standby'. No heating, no error, the mode simply gone. By the time I noticed it was usually hours too late and the radiators stone cold.

The cause is both harmless and infuriating: on restart the KNX integration briefly loses its connection to the bus, and many KNX climate actuators fall back to a safe default state ‚Äî namely 'standby'. Home Assistant no longer knows the previous mode after the reboot and doesn't restore it on its own. The fix is a small but precisely timed startup automation. It cost me about 30 minutes ‚Äî and the waking-up-cold problem has been gone ever since.

The symptom: 'standby' instead of 'heat'

Concretely: before the restart a thermostat is on hvac_mode: heat with preset comfort. After the restart the same climate entity shows standby (or 'off' on some actuators). The setpoint drops out of the control loop and the radiator stays cold. In the history graph you see the kink exactly at the restart moment. Important to understand: this is not a fault in your automations ‚Äî it's an initialisation gap right after boot.

Why a simple 'set mode' call isn't enough

The obvious reflex ‚Äî just fire climate.set_hvac_mode at startup ‚Äî fails, because in the first seconds after boot the climate entities are often still unavailable. The KNX bus has to connect first, the actuators have to report their state. Send the command too early and it goes nowhere, leaving the thermostat on standby. That's exactly why the automation needs two ingredients: a trigger on HA start and a short wait until the bus is back.

The fix: a timed startup automation

The automation below triggers on the homeassistant start event, waits 30 seconds for the KNX bus to connect and all climate entities to become available, and then sets the right state depending on night mode: if night mode is on, every thermostat goes to preset economy; otherwise to heat plus preset comfort. A simple input_boolean helper ‚Äî which I share with the master heating switch ‚Äî drives the day/night branch.

- id: heating_startup_initialize
  alias: 'Heizung: Modus beim Start initialisieren'
  description: >-
    Setzt alle Thermostate beim HA-Start auf den korrekten Modus,
    basierend auf dem Nachtmodus-Status
  triggers:
  - trigger: homeassistant
    event: start
  conditions: []
  actions:
  # the KNX bus needs a few seconds after the restart until all
  # climate entities are connected/available again
  - delay:
      seconds: 30
  - choose:
    # night mode active -> economy
    - conditions:
      - condition: state
        entity_id: input_boolean.heizung_nachtmodus
        state: 'on'
      sequence:
      - action: climate.set_preset_mode
        data:
          preset_mode: economy
        target:
          entity_id:
          - climate.thermostat_wohnzimmer
          - climate.thermostat_buro
          - climate.thermostat_kuche
          - climate.thermostat_schlafzimmer
          - climate.thermostat_kinderzimmer_1
          - climate.thermostat_kinderzimmer_2
    # otherwise day mode -> heat + comfort
    default:
    - action: climate.set_hvac_mode
      data:
        hvac_mode: heat
      target:
        entity_id:
        - climate.thermostat_wohnzimmer
        - climate.thermostat_buro
        - climate.thermostat_kuche
        - climate.thermostat_schlafzimmer
        - climate.thermostat_kinderzimmer_1
        - climate.thermostat_kinderzimmer_2
    - action: climate.set_preset_mode
      data:
        preset_mode: comfort
      target:
        entity_id:
        - climate.thermostat_wohnzimmer
        - climate.thermostat_buro
        - climate.thermostat_kuche
        - climate.thermostat_schlafzimmer
        - climate.thermostat_kinderzimmer_1
        - climate.thermostat_kinderzimmer_2
  mode: single

The entity list here targets my six rooms ‚Äî replace it with your own climate. entities. The room names are generic placeholders; fill in office, living room, kitchen and so on exactly as they're named in your setup.

Why exactly 30 seconds of delay

The 30 seconds aren't arbitrary. On my system the KNX integration reproducibly took about 10 to 20 seconds after boot before all climate entities flipped from 'unavailable' to a real state. 30 seconds gives a safe buffer without noticeably delaying when the flat warms up. On slower hardware (a Raspberry Pi, lots of integrations) it can make sense to go to 45 or 60 seconds. Rule of thumb: better to wait a little too long than to send the command into the void.

If you want it more robust, you can replace the fixed delay with a wait_template that waits until a representative climate entity is no longer 'unavailable' ‚Äî but for a home setup the plain 30-second delay is proven and entirely sufficient.

The day/night branch via choose

The choose block makes sure that a restart at three in the morning doesn't ramp everything up to full comfort temperature. If input_boolean.heizung_nachtmodus is 'on', all thermostats get the economy preset (set back); in the default branch ‚Äî i.e. during the day ‚Äî heat is set as the HVAC mode first, then comfort as the preset. I share this night-mode helper with the central heating switch, so startup and manual control use the same source of truth.

I use the same building-protection/preset logic in my window-contact-triggered frost-protection automation too ‚Äî both act on the same thermostat pool, just on different occasions.

Testing without restarting Home Assistant

You don't have to fully reboot every time to check the automation. In Developer Tools you can trigger the automation manually via 'Run' ‚Äî the homeassistant-start trigger is skipped, but the actions (delay + choose) run exactly as they would. First set a thermostat to 'standby' as a test and watch in the more-info dialog how it snaps back to 'comfort'/heat after a good 30 seconds. For the real test, do a deliberate restart and check the last-changed timestamps of the climate entities.

Frequently asked questions

Why do the KNX thermostats drop to standby on restart at all?

On restart the KNX integration briefly loses the bus connection. Many KNX climate actuators fall into a safe default on connection loss ‚Äî often 'standby' or 'off'. Home Assistant does not reconstruct the previous mode after boot automatically, so the actuator stays in the default until something actively resets it. That's precisely the gap the startup automation fills.

Isn't a shorter delay than 30 seconds enough?

Possibly, but it's risky. If you send the command before the climate entities are available, it goes nowhere and the thermostat stays on standby ‚Äî the bug is back. 30 seconds is a conservative, proven value. On fast hardware you can go down to 15 seconds, but then verify across several restarts that it reliably takes effect.

What if I don't have a night-mode helper at all?

Then you don't need the choose block. Keep just the default branch: 30 seconds delay, then climate.set_hvac_mode heat and climate.set_preset_mode comfort for all thermostats. You only create input_boolean.heizung_nachtmodus if you actually want a nightly set-back.

Does this work for other climate integrations, not just KNX?

Yes. The pattern ‚Äî trigger on homeassistant start, wait briefly for the entities to become available, then force the desired mode ‚Äî is generic. Any climate integration that falls into an unwanted default after a restart can be initialised this way. You only adjust the entity IDs and, if needed, the delay duration.

Window Open, Heating Off: Auto-Switch Each KNX Thermostat to Frost Protection in Home Assistant

Michael Bernhart — Sat, 11 Jul 2026 19:12:46 +0000

In winter I heat against the open window. Every time I tilt a window for a quick airing, the KNX thermostat below dutifully ramps up and blasts heating energy straight outside ‚Äî for minutes, until someone notices the room going cold and closes it again. Across a heating season that adds up to real money going out the window, literally.

The fix is a simple, per-room duplicable automation: window contact opens ‚Üí that room's thermostat goes to frost protection; window closes ‚Üí back to comfort. The one trick almost every tutorial leaves out is a 5-second debounce against false triggers. Here's my setup, step by step.

Why building_protection and not just "off"

The obvious reflex is to switch the thermostat fully off while the window is open (hvac_mode off or preset standby). That's dangerous: with a thermostat you forget or a window contact that gets stuck, the room can then cool down indefinitely ‚Äî in the worst case below freezing on an exterior wall. So I switch to the building_protection preset (frost guard, typically ~7 ¬∞C). The radiator stays supervised and kicks in if it genuinely gets cold, but it never heats the open window. That's the whole difference between "saving energy" and "a burst pipe in January".

Step 1 ‚Äî the window contact as a KNX binary_sensor

Every window I want to watch gets a binary_sensor with device_class window. That matters because Home Assistant derives the correct "open/closed" state and the right icons from it. The state address is the KNX group address your window contact reports on ‚Äî shown here as X/X/X placeholders; fill in your own. sync_state: false avoids needless polling of the bus, since the contact sends its state on its own.

binary_sensor:
  - name: "Fenster Buero Status Sensor"
    state_address: "X/X/X"
    sync_state: false
    device_class: window

  - name: "Fenster Wohnzimmer Status Sensor"
    state_address: "X/X/X"
    sync_state: false
    device_class: window

  - name: "Fenster Kinderzimmer 1 Status Sensor"
    state_address: "X/X/X"
    sync_state: false
    device_class: window

  - name: "Fenster Kueche Status Sensor"
    state_address: "X/X/X"
    sync_state: false
    device_class: window

  - name: "Fenster Kinderzimmer 2 Status Sensor"
    state_address: "X/X/X"
    sync_state: false
    device_class: window

One entry per window. The names are just examples ‚Äî generic room names like "Buero" (office) or "Wohnzimmer" (living room) keep the automations readable later on.

Step 2 ‚Äî the per-room automation pair

For each room I need two automations: one disables the heating on open, one re-enables it on close. Both hang off the same window contact and control the same thermostat. Here's the pair for the office:

- alias: Heizung Buero Deaktivieren
  triggers:
  - trigger: state
    entity_id: [binary_sensor.fenster_buro_status_sensor]
    from: 'off'
    to: 'on'
    for: {seconds: 5}
  actions:
  - action: climate.set_preset_mode
    data: {preset_mode: building_protection}
    target: {entity_id: climate.thermostat_buro}
  mode: single

- alias: Heizung Buero Aktivieren
  triggers:
  - trigger: state
    entity_id: [binary_sensor.fenster_buro_status_sensor]
    from: 'on'
    to: 'off'
    for: {seconds: 5}
  actions:
  - action: climate.set_preset_mode
    data: {preset_mode: comfort}
    target: {entity_id: climate.thermostat_buro}
  mode: single

On open it sets building_protection; on close, back to comfort. Which preset modes your KNX thermostat actually supports, and how they map onto the bus, is covered in detail in my post on KNX thermostat preset modes.

Step 3 ‚Äî understanding the 5-second debounce

The for: {seconds: 5} is the real trick and the reason this automation doesn't drive you mad in daily use. Without it, every micro-movement of the contact fires immediately: a reed contact sometimes bounces on closing, the window rattles in its frame during airing, and the KNX bus occasionally delivers brief flutter telegrams. Each of those glitches would otherwise trigger a pointless mode switch.

With the 5-second filter, the automation only fires once the window has actually been open (or closed) for five seconds. Short rattling is ignored, real airing is detected. Five seconds is short enough that no noticeable heating energy is lost, and long enough to mask all the flutter junk.

The mapping scales per room

The nice thing about the pattern: it's bluntly duplicable. One window-contact binary_sensor plus one climate thermostat per room, and the automation pair gets copied once with its two entity_ids swapped out. Here's my mapping table:

# Raum            Fensterkontakt                              Thermostat
# Buero           binary_sensor.fenster_buro_status_sensor    climate.thermostat_buro
# Wohnzimmer      binary_sensor.fenster_wohnzimmer_...        climate.thermostat_wohnzimmer
# Kueche          binary_sensor.fenster_kueche_...            climate.thermostat_kueche
# Kinderzimmer 1  binary_sensor.fenster_kinderzimmer_1_...    climate.thermostat_kinderzimmer_1
# Kinderzimmer 2  binary_sensor.fenster_kinderzimmer_2_...    climate.thermostat_kinderzimmer_2

If you have several windows per room, you can list them all in the trigger's entity_id and express "at least one window open" via a group or a template condition ‚Äî the logic stays the same.

Verifying it works

After reloading I test each room once by hand: open the window, wait a moment, then check in the thermostat overview that the preset jumped to building_protection (the list with secondary_info "last-changed" shows the timestamp). Close the window, wait five seconds, back to comfort. If the switch happens but too early or too late, the for duration is almost always the knob to turn.

Frequently asked questions

Why not hvac_mode off instead of building_protection?

Because off disables all frost protection. If a window is accidentally left open overnight or the contact gets stuck, the room cools down without limit ‚Äî on an exterior wall a burst pipe is the worst-case outcome. building_protection holds a safety minimum (~7 ¬∞C) but doesn't heat against the open window. That's the entire point of the exercise.

What if my thermostat doesn't have a building_protection preset?

Then check the climate entity's more-info dialog for which preset_modes it reports. On some KNX actuators the frost guard is called "frost", or it's done via a low target temperature with climate.set_temperature instead of a preset. The trigger logic stays identical ‚Äî you only swap the action in the disable block.

Do I really need two automations per room?

Not strictly ‚Äî you can also solve it in a single automation with two triggers and a choose block. I deliberately use two separate ones because they're instantly readable in the automation UI ("Heizung Buero Deaktivieren/Aktivieren") and can each be disabled individually when I'm testing something in one room. For a maintainable setup the small redundancy is worth it.

Do I lose heating energy during airing because of the 5-second delay?

Practically none. In five seconds a radiator gives off barely measurable heat, and the inertia of a water-based system is far larger anyway. Those five seconds buy you the reliability that not every rattle and bus glitch triggers a mode switch ‚Äî an excellent trade.

A Robust Modbus Proxy: Reconnect, Stale-Cache Detection and Timeouts Done Right

Michael Bernhart — Fri, 10 Jul 2026 13:26:12 +0000

A self-built Modbus cache proxy runs for weeks without complaint in summer — until the first night the inverter shuts down, or the first firmware reboot of the SDongle. That's exactly when you find out whether you built a proxy or a time bomb. My first attempt was naive: poll, cache, serve. It worked perfectly during the day. At night, when the SUN2000 went to sleep, the poll loop hung in a read that never returned — and for hours the proxy silently served the last daytime values as if nothing was wrong.

That's the dangerous failure: not the crash (you notice that), but the proxy that keeps running and serves stale data while nobody is the wiser. This post is the reliability playbook that turned my proxy into something I trust. I build the proxy itself in the Modbus caching basics post — here it's purely about the robustness underneath.

The failure mode no beginner guide covers

Tutorials show the happy path: connect to the SDongle, read registers, done. What they leave out: the SDongle is slow, opinionated hardware. It drops the connection at night, it needs a minute after a firmware reboot before it answers again, and it can't handle reads fired back-to-back. A naive asyncio read without a timeout then blocks forever, and your cache freezes on its last value. HA dutifully keeps showing numbers — they're just no longer true.

The fix has three pillars. First, every single read gets a hard timeout and the spacing the SDongle needs. Second, the poll loop retries fast and then backs off, instead of hanging. Third — and this is the part almost nobody builds — the proxy makes its own staleness visible, so Home Assistant can alert on it.

Step 1 — per-batch timeout and the 50 ms spacing

The inverter is polled in register batches. Each batch gets its own timeout (in the read_batch helper, as an asyncio.wait_for), and there's a 50-millisecond pause between two reads — the SDongle is too slow to answer reads in quick succession and punishes haste with timeouts. The crucial bit is distinguishing the two exceptions: a single TimeoutError is survivable (one batch is missing this round), but any other exception means the connection is probably dead — then we leave the loop immediately via break instead of hammering a dead socket.

for start, count in REGISTER_BATCHES:
    try:
        values = await read_batch(reader, writer, start, count)
        if values:
            async with cache_lock:
                for i, val in enumerate(values):
                    register_cache[start + i] = val
        await asyncio.sleep(0.05)  # 50ms between reads — the SDongle is slow
    except asyncio.TimeoutError:
        fail_count += 1
    except Exception:
        fail_count += 1
        break  # connection probably dead, leave the loop

The break is the heart of it: a single timeout must not abort the batch pass — otherwise every passing glitch loses you half the register set. But a real ConnectionError or a torn-down stream has to end the pass, so the outer loop can build a fresh reconnect instead of reading blindly into the void.

Step 2 — fast-retry-then-backoff and the stale-cache warning

The outer reader loop decides how often to reconnect. The logic is deliberately asymmetric: after a successful poll we wait the normal POLL_INTERVAL (10 s). When a poll fails, we retry fast — capped at 10 s, so a brief hiccup is bridged in seconds without flooding the SDongle with reconnect attempts. And then the most important part: when the cache is older than 120 seconds, we write an explicit Cache stale warning to the log.

retry_delay = 5
while True:
    success = await read_sdongle()
    if success:
        last_update = time.time()
        retry_delay = POLL_INTERVAL
    else:
        retry_delay = min(retry_delay, 10)
        age = time.time() - last_update if last_update > 0 else -1
        if age > 120:
            logger.warning(f"Cache stale for {age:.0f}s")
    await asyncio.sleep(retry_delay)

That one log line is the difference between a proxy that lies and one that's honest. It makes staleness observable. In Home Assistant you can catch it on the consumer side: a sensor that hasn't updated for minutes flips to unavailable — and you can hang a push notification off that, just like any other anomaly (see the pattern in the PV string anomaly post).

Step 3 — client idle timeout against dead connections

The other side of the proxy is the clients (HA, evcc, a second dashboard). Without an idle timeout, dead client connections pile up — an HA restart, a crashed container, and the old socket sits open forever. Every Modbus request starts with a 7-byte MBAP header; we read it with a 60-second timeout. If nothing arrives, or fewer than 7 bytes, the client is gone and we close the connection cleanly.

header = await asyncio.wait_for(client_reader.read(7), timeout=60)
if len(header) < 7:
    break  # Client disconnected

60 seconds is generous — HA typically polls every 30–60 s, so a healthy connection easily outlives the timeout. A dead connection, on the other hand, never sends another header and gets reaped within a minute at most, instead of holding a slot and memory hostage.

Configuration — never real LAN IPs

All the values that change live at the top in a config block. Put in your own SDongle address — a DHCP-reserved LAN address is ideal so it doesn't drift. The port is 502 or 6607 depending on firmware. Never publish your real LAN IP in a gist or forum post; use placeholders, like here.

# Configuration (mit eigenen Werten ersetzen)
SDONGLE_HOST = "YOUR_SDONGLE_IP"   # z.B. eine DHCP-reservierte Adresse im LAN
SDONGLE_PORT = 502                 # oder 6607, je nach Firmware
DEVICE_ID = 1

SERVER_HOST = "0.0.0.0"
SERVER_PORT = 5502
POLL_INTERVAL = 10  # seconds

Numbers from long-term operation

These values were tuned over months of real operation with a Huawei SUN2000 SDongle. 50 ms spacing: below it timeouts piled up, above it the poll got sluggish. 10 s poll interval: fine enough for PV data and gentle on the SDongle. 120 s stale threshold: two missed polls plus headroom. 60 s client idle: covers any sane HA scan interval. Tune them to your hardware, but start here.

Frequently asked questions

Why not just use the ready-made ha-modbusproxy add-on?

You can — the add-on is good and takes the work off your hands. This post is for those who built their own proxy (or want to understand what happens underneath) and need to control the reliability layer themselves. The failure modes and thresholds here apply conceptually to any caching proxy, self-built or add-on alike.

My cache still freezes sometimes — why?

Almost always the missing break in the batch loop: if the connection dies but a read throws only a TimeoutError instead of a ConnectionError, the loop keeps running against the dead socket and the outer loop never rebuilds. Make sure a real connection failure leaves the batch pass. Second suspect: a read with no asyncio.wait_for at all — a single read without a timeout is enough to block the whole loop forever.

How do I alert on a stale cache in Home Assistant?

Easiest is via the sensor staleness itself: a Modbus sensor that stops getting fresh values goes unavailable after a few missed scans. Hang an automation off that with a state trigger to unavailable and a for duration of a few minutes to ride out brief dropouts. If you want it more explicit, build a template binary sensor that checks the age of the last update against a threshold.

Which SDongle port is correct — 502 or 6607?

Depends on the SDongle firmware. Older firmware often speaks the standard Modbus port 502; newer ones moved Modbus TCP to 6607 in places, or require you to enable it in the FusionSolar app first. Try 502 first; if the connect is refused outright, use 6607. If nothing happens at all, Modbus TCP on the dongle is probably still disabled.

Solar Surplus into Hot Water: the AC·THOR in Home Assistant

Michael Bernhart — Wed, 08 Jul 2026 17:54:28 +0000

On a sunny afternoon my roof makes more power than the house can swallow. The battery fills, the inverter would rather give the rest to the grid for almost nothing, and meanwhile there's a 200-litre tank of cold water sitting in the cellar. The obvious move is to dump that surplus into the immersion heater and bank it as hot water. The device that does it is a my-PV AC·THOR 9s — a resistive PV-surplus diverter that modulates power into the boiler element instead of letting it spill to the grid. This post is the story of getting it under Home Assistant control, and the wall I hit doing it.

It's Part 03 of how I'm self-hosting my house. Part 01 put Home Assistant on a Docker host, Part 02 added HACS, and the inverter side — a Huawei SUN2000-8KTL-M1 read over Modbus TCP through a Huawei SDongle, plus a battery whose charge and discharge I track — was already prior art. Surplus, for the AC·THOR, is simply what's left after house load and battery charging. So the hard part wasn't the energy logic. It was the control plane.

The plan that should have worked

The AC·THOR speaks Modbus TCP, and my whole energy stack already lives on Modbus, so the design wrote itself. Two registers do everything: register 5000 is heating enable/disable (0 or 1), and register 5006 is the power limit in watts. The device has two useful modes — an Eco setting at 1500 W for pure-solar heating, and Full Power at 3000 W, which is also its hardware maximum. You can switch between them live while it's heating.

In Home Assistant I modelled that as a small control surface: an input_select for the power mode, an input_boolean for the heating-active flag, and a dashboard card — AC·THOR Steuerung — with plain Start and Stop buttons. Behind the buttons, a couple of mbpoll-style writes: poke 5000 to enable, set 5006 to 1500 or 3000. I tested the reads first to make sure I had the right slave and port. Boiler temperature came back clean on holding register 1001 (int16, in °C), polled every 30 seconds. Everything looked ready.

The wall: writes refused, reads fine

Then I sent the first write, and the AC·THOR slammed the door. Connection refused — not a timeout, not a bad-value error, a flat refusal at the device level. I checked the slave id, the register, the byte order, the function code. None of it mattered. The thing simply does not accept Modbus write operations. What made it genuinely confusing is that the very same connection happily answers reads: register 1001 kept returning boiler temperature every 30 seconds without complaint, on the same host and port, while every write bounced.

I'll be honest, that stung. I'd built the whole control path on the assumption that a device exposing Modbus exposes it both ways. It doesn't here, and that's a deliberate choice on my-PV's side — the registers are real, they're just read-only over local Modbus. So the switch-based, all-local design I was proud of was dead for control. The boiler-temperature monitoring, though, survives untouched, because that was only ever a read.

# Modbus read still works — boiler temp stays local; only WRITES are refused
- name: ac_thor
  type: tcp
  host: <LOCAL_IP>        # redacted — never publish your LAN address
  port: 502
  delay: 1
  timeout: 5
  sensors:
    - name: "Boiler Temperature"
      slave: 1
      address: 1001
      input_type: holding
      data_type: int16
      unit_of_measurement: "°C"
      scan_interval: 30

The pivot: read local, write cloud

The path that actually worked is the my-PV Cloud API. Every AC·THOR phones home, and that cloud exposes the same configuration the local Modbus writes would have touched: a GET /data for live monitoring and a GET/PUT /setup to read and change config. So the split I shipped is read-local, write-cloud — boiler temperature stays on local Modbus (register 1001, every 30 s, no internet dependency), and all control goes out through the cloud.

I resent it a little. Depending on a vendor cloud to turn my own immersion heater on is exactly the kind of dependency I self-host to avoid, and if their API goes down my morning shower is at the mercy of someone else's uptime. But it's the split that actually works today, and it unlocks something the local-only design never could: proper time-aware behaviour.

There's one gotcha worth a sentence. A PUT to /setup returns ok instantly, but the device doesn't apply it for another 4 to 6 seconds. If you immediately GET /setup back to confirm, you'll read the old values and think your write was ignored. It wasn't — you just have to wait, then poll.

What the cloud control actually buys: free heat by day, a warm tank by morning

The interesting part isn't on/off — it's two temperature targets and a time window. The AC·THOR carries a max solar target (ww1target) and a lower boost target (ww1boost). By day I let surplus push the tank all the way to a high solar cap — 65 °C — because that heat is free; every degree the sun banks is a degree I don't buy at night. Temperatures are encoded in tenths of a degree, so 650 means 65.0 °C and 400 means 40.0 °C, which trips you up exactly once.

The morning is handled by the cloud's assurance mode — Sicherstellungsmodus, parameter bstmode. I set a boost window from 01:00 to 08:00 (bstton1=1, bsttof1=8) with a modest 40 °C needed-target, so the tank is guaranteed warm by the time anyone showers, regardless of whether the night was sunny. A second optional window exists if you want it. Daytime stays solar-only up to the high cap; the night just guarantees a floor.

# Local Modbus writes are refused — drive config via the my-PV Cloud API instead.
# Set a 40°C morning-boost window 01:00–08:00 (values are tenths of a degree: 400 = 40.0°C)
curl -X PUT "https://api.my-pv.com/api/v1/device/<SERIAL>/setup" \
  -H "Authorization: <REDACTED_TOKEN>" \
  -H "Content-Type: application/json" \
  -d '{"bstmode": 1, "ww1boost": 400, "bstton1": 1, "bsttof1": 8}'
# API replies "ok" instantly; the device applies it ~4–6 s later, so poll GET /setup to confirm.

Seeing the split that justifies the whole thing

The reason any of this is worth the trouble shows up in two sensors: solar heating power and grid heating power, reported separately. The whole point of surplus diversion is that the first number is large and the second is zero — heat from sun I'd otherwise have exported, not from the meter. Alongside those I watch the current power limit and the boiler temperature, and the inverter's own Modbus reads give PV yield, grid export and import, and the battery's daily charge and discharge. With all of that in one place I can actually watch surplus turn into hot water in real time.

And one quiet safety note that made me trust the setup: whatever power or target I command, the AC·THOR enforces its own internal thermal and safety limits anyway. Software requests, hardware protects. That separation is exactly what you want for a 3 kW element in a water tank — my automation can be wrong without being dangerous.

Where this fits

The hot-water diverter is one slice of a whole-home energy setup, not a toy. The same Home Assistant install runs per-room radiator thermostats that drop to a setback preset when a window contact opens, and a scheduled house-wide Nachtmodus at 21:00 with Tagmodus back at 05:00 across a dozen-ish zones. The hot water just happens to be the one corner where the obvious local path was a dead end and I had to swallow a cloud dependency to ship.

If I had to compress the lesson: a device speaking a protocol doesn't promise it speaks every verb of it. Read worked, write didn't, and the fix wasn't to fight the device — it was to keep the cheap, local, no-internet read where it belonged and move only the writes to the one transport the vendor actually allows. Not the architecture I wanted. The one that put hot water in the tank by morning.

The automation behind it

Once the boiler hits 55 °C I switch the AC·THOR boost back off automatically — with a push confirmation to my phone. This is the exact automation I run:

# Stop the boost as soon as the boiler hits the 55 °C target
alias: "AC THOR: stop boost at 55 °C"
triggers:
  - trigger: numeric_state
    entity_id: sensor.boiler_temperature      # your own sensor name
    above: 55
    for:
      minutes: 5
conditions: []
actions:
  - action: shell_command.acthor_disable_boost
  - action: notify.mobile_app                 # generic — no device/person name
    data:
      title: "✅ AC·THOR target reached"
      message: "Boost off at {{ states('sensor.boiler_temperature') }} °C"
mode: single

My PV / boiler dashboard in Home Assistant — live PV power, battery SOC and boiler temperature at a glance.

Modbus Writes Through the Cache Proxy in Home Assistant

Michael Bernhart — Fri, 03 Jul 2026 13:13:41 +0000

My Huawei SDongle allows exactly one Modbus connection at a time. That's why I run a small caching proxy in front of it that holds the connection exclusively and answers all reads from cache — I described it in detail in the caching proxy post. It works beautifully as long as you only read. Then Tibber came into the picture, I wanted to force-charge the battery on negative electricity prices and set the export limit dynamically — and suddenly I needed writes.

Here's the non-obvious catch: a cache only solves reads. A write has no business sitting in a cache — it has to actually reach the inverter, otherwise nothing changes physically. So the proxy needs a special case: read from cache, pass writes straight through, and do it all without breaking the single-connection invariant. That write-through path is exactly what I'll show here.

Why a write must not go into the cache

The caching proxy gets all its mileage from the fact that read registers change slowly — battery level, string currents, daily yield. Those you can happily cache for a few seconds and serve to several clients at once. A write command is the exact opposite: it's a side effect, not a value. "Set register 47075 to forced-charge mode" has to land on the device, or the command was a no-op.

Modbus distinguishes this cleanly via the function code. Reads are FC3 (Read Holding Registers) or FC4 — those go into the cache. The classic for writing a single register is FC6 (Write Single Register), and that's exactly what the proxy intercepts and handles differently: pass through instead of cache.

Detecting and forwarding FC6

In the proxy's request handler I check the function code from the PDU. If it's a 6 and the PDU is long enough, I unpack the register address and value and forward the write straight to the SDongle. If it succeeds, I echo the standard write response (FC6 replies with the address and value mirrored back). If it fails, I return a proper Modbus exception instead of leaving the client hanging:

elif fc == 6 and len(pdu) >= 5:
    reg_addr, reg_value = struct.unpack(">HH", pdu[1:5])
    write_ok = await forward_write(tx_id, unit_id, reg_addr, reg_value)
    if write_ok:
        resp_pdu = struct.pack(">BHH", fc, reg_addr, reg_value)  # echo
    else:
        resp_pdu = struct.pack(">BB", fc + 0x80, 4)  # 0x80|fc, code 4 = device failure
    resp_header = struct.pack(">HHHB", tx_id, 0, len(resp_pdu) + 1, unit_id)
    client_writer.write(resp_header + resp_pdu)

Two details that matter. The transaction ID (tx_id) from the MBAP header I return unchanged — the client matches responses by it, and a wrong value leads to timeouts. And the error response follows the Modbus convention: function code with the top bit set (fc + 0x80) plus an exception code; the 4 means "Slave Device Failure". That way Home Assistant knows the write attempt failed instead of blindly waiting for a reply.

Forwarding the write on a short-lived connection

Now the core that preserves the single-connection invariant. The proxy keeps its one persistent connection for the polling loop. For a write I open a separate, short-lived connection to the SDongle, send exactly one FC6 frame, read the reply and close again immediately. Because the write is so brief, it practically never collides with the poll cycle — and if it does, this is the spot where a mutex around SDongle access belongs (more on that in a later post).

# SDONGLE_HOST / SDONGLE_PORT come from your config, e.g.
# SDONGLE_HOST = "10.0.0.x"   # your inverter's SDongle
# SDONGLE_PORT = 502

async def forward_write(tx_id, unit_id, reg_addr, reg_value):
    reader, writer = await asyncio.wait_for(
        asyncio.open_connection(SDONGLE_HOST, SDONGLE_PORT), timeout=10)
    req = struct.pack(">HHHBBHH", 0, 0, 6, unit_id, 6, reg_addr, reg_value)
    writer.write(req)
    await writer.drain()
    resp = await asyncio.wait_for(reader.read(12), timeout=10)
    writer.close()
    return len(resp) >= 12

The struct.pack(">HHHBBHH", ...) builds a complete Modbus TCP frame: MBAP header (transaction ID 0, protocol ID 0, length 6), then unit ID, function code 6, register address and value. The 10-second timeouts are generous — an SDongle normally answers a write in milliseconds. A valid FC6 response is 12 bytes; if I get fewer, the write counts as failed and the caller above sends the exception.

Rejecting unknown function codes cleanly

There are more function codes than FC3, FC4 and FC6 — FC16 (Write Multiple Registers), FC1, FC2 and so on. When a client sends a code the proxy doesn't implement, the worst reaction is to not reply at all. Then the client blocks until timeout and the whole poll loop stalls. The right answer is the Modbus exception "Illegal Function" (code 1) — the client knows immediately and moves on:

else:
    resp_pdu = struct.pack(">BB", fc + 0x80, 1)  # 0x80|fc, code 1 = illegal function
    resp_header = struct.pack(">HHHB", tx_id, 0, len(resp_pdu) + 1, unit_id)
    client_writer.write(resp_header + resp_pdu)

It's the same exception mechanic as the device-failure case, just with code 1 instead of 4. A well-behaved Modbus proxy never leaves a request unanswered — either the real result comes back or a defined error, but never silence.

What this actually lets you control

With the write-through path I control the battery directly from Home Assistant automations. The most interesting use is the dynamic tariff: when the Tibber price drops below a threshold I write the forced-charge mode, and when it rises again I switch back to self-consumption. To see whether the command actually took, I watch sensors like sensor.my_pv_batteriestand plus sensor.batterie_gesamt_ladung and sensor.batterie_gesamt_entladung. How to measure self-consumption and autarky cleanly is covered in the self-consumption post.

Important: write registers and their allowed values are strictly vendor-specific and partly dangerous (you can put a system into a nonsensical state). Take the concepts here, but look up the exact registers and permitted values in your own inverter's Modbus document — and test with harmless registers before flipping charge modes.

Frequently asked questions

Why not just cache writes too?

Because a write isn't a value, it's a command with a physical side effect. "Writing into the cache" would mean the command never reaches the device — the battery doesn't charge, the power limit doesn't change. Reads can be cached because they're idempotent; writes always have to be passed through.

Why a separate connection for the write — don't I already have one open?

The persistent connection is occupied by the polling loop. A short-lived extra connection just for the write keeps the logic simple and the write frame out of the read-cache path. Because the write is done in milliseconds, the SDongle's "one connection at a time" rule stays practically intact. For real parallel access, a mutex belongs at this spot.

What do exception codes 1 and 4 mean?

They are standard Modbus exception codes. Code 1 is "Illegal Function" — the function code isn't supported. Code 4 is "Slave Device Failure" — the command was valid but the device couldn't execute it. Both are signalled with the top bit set in the function code (fc + 0x80), so the client recognizes the response as an error immediately.

Does this work with FC16 for multiple registers?

The framework shown only handles FC6 (single register), because that's enough for charge mode and power limit. FC16 (Write Multiple Registers) can be added on the same pattern: unpack the PDU differently, build the frame with the matching byte count, forward, echo. Until then an FC16 request lands in the else branch and gets a clean "Illegal Function" back instead of blocking the client.

Pull a Cloud API into Home Assistant via REST Sensor

Michael Bernhart — Thu, 02 Jul 2026 13:44:49 +0000

Sooner or later almost every Home Assistant setup has a device with no native integration. A wallbox, an inverter, in my case a my-PV hot-water heating element — the vendor app shows every value nicely, but nothing of it appears in HA. What there almost always is, though, is a cloud or local JSON API: an HTTP endpoint that, on a GET request, returns a JSON object with all the readings. That is exactly where the built-in REST sensor comes in.

The trick the official docs cover only briefly: from a single JSON endpoint you can build a whole dozen clean HA sensors — one per field, each with its own name, unit and device_class. In this post I show the pattern on my real my-PV cloud API (which has no native HA integration), but every single line transfers to any REST/JSON API you like.

What the REST sensor does

The platform: rest sensor polls a URL on a fixed interval, gets JSON back, and turns one field of that JSON into a sensor state. You give it four things: the resource (the URL), authentication via headers if needed, a value_template that pulls the field you want out of the JSON, and a scan_interval that sets how often it polls. At its core, that's all it takes.

One thing to understand: each REST sensor makes its own HTTP request. That matters as soon as you want several fields from the same endpoint — more on that below.

The first sensor: one field from the API

Let's start with the simplest case: a single value from the my-PV cloud API. The API answers the /data endpoint with a JSON object that contains, among others, surplus (surplus power). The sensor pulls exactly that field out.

- platform: rest
  name: My-PV Surplus Power
  resource: "https://api.my-pv.com/api/v1/device/<device-id>/data"
  method: GET
  headers:
    Authorization: "!secret my_pv_api_token"
  value_template: "{{ value_json.surplus }}"
  unit_of_measurement: "W"
  scan_interval: 60

Three things happen here. value_json is the parsed JSON response — with value_json.surplus you access the field, just like in any other HA template. You never store the token in clear text; you keep it as !secret my_pv_api_token in your secrets.yaml and HA sets it as the Authorization header. And scan_interval: 60 polls once a minute — deliberately conservative, so you don't run into the cloud's rate limit.

One endpoint, many sensors

Now the actual pattern: the same /data response carries more than just surplus — a whole bundle of fields, including boiler temperature, battery state of charge, house consumption. For each you define another REST sensor with the same resource but a different value_template. That's how one endpoint becomes a whole dashboard.

value_template: "{{ value_json.temp1 | float / 10 }}"   # boiler temp in °C
# ...
value_template: "{{ value_json.m2soc }}"                 # battery state of charge %
# ...
value_template: "{{ value_json.m0sum }}"                 # house consumption W

Note the first entry: temp1 | float / 10. This is the single most common gotcha with vendor APIs — many return temperatures as tenths of a degree in integer form (550 instead of 55.0). With | float / 10 you scale that to the correct value right in the template. You know the counterpart from the Modbus world, where the scale factor does the same job — with register sensors HA scales for you, with REST you do it yourself in the value_template.

Making states readable: 0/1 to On/Off

Some fields aren't measurements but status flags. The my-PV API has a second endpoint, /setup, that returns the configuration — including bstmode, the boost status, as 0 or 1. With a small if in the value_template you turn that into a plain-text sensor that shows "On" or "Off" instead of a bare number.

- platform: rest
  name: My-PV AC THOR Boost Status
  resource: "https://api.my-pv.com/api/v1/device/<device-id>/setup"
  method: GET
  headers:
    Authorization: "!secret my_pv_api_token"
  value_template: "{{ 'On' if value_json.setup.bstmode == 1 else 'Off' }}"
  scan_interval: 30

Two things are new here. First, value_json.setup.bstmode — the response is nested, the value you want sits under a setup object, so you just extend the path with a dot. Second: if you query both /data and /setup, those are two different URLs and therefore two separate REST sensors, each with its own scan_interval.

Polling interval and rate limits

The scan_interval is the most important dial for being polite to the cloud. Each sensor polls independently — five sensors on the same endpoint at scan_interval 30 is ten requests per minute. Few vendors publish their rate limits; when in doubt, start at 60 seconds and only go lower if you genuinely need the value more often. For values that barely change (daily yield, configuration), even 300 seconds is perfectly fine.

If you need several fields from exactly the same endpoint and want to cut request load, look at the rest: platform (rather than platform: rest): there you define the endpoint once and hang several sensor blocks with their own value_template beneath it — one request, many sensors. The single-sensor pattern shown here is the better starting point, because each sensor is completely self-contained.

From reading to writing

The REST sensor is read-only. As soon as you want to actually control something over the same cloud API — in my setup, turning the AC·THOR heating element on and off, because its Modbus write access is blocked at the device — you need the writing counterpart: a shell_command with curl and PUT instead of GET. How I solved that for the my-PV control I cover in a separate post. The REST sensor provides the feedback for it: write with PUT, then verify with the /setup sensor that the value actually landed.

Frequently asked questions

What exactly is value_json?

value_json is the already-parsed JSON response of the endpoint, which HA hands you inside the value_template. You navigate it with dot notation: value_json.surplus for a top-level field, value_json.setup.bstmode for a nested one. If the API returns an array, you index with value_json[0]. If you don't know what the response looks like, hit the endpoint once with curl and inspect the JSON.

My sensor shows "unknown" — what's wrong?

Almost always one of three things: the value_template path doesn't match the real JSON structure (often a forgotten nested object), authentication fails (token wrong, or expected as Bearer instead of a bare value), or the API doesn't return JSON for that call at all. As a test, set value_template to {{ value }} instead of {{ value_json.field }} — you then see the raw response in the state and immediately know whether it's an auth or a path problem.

How do I scale raw values correctly?

In the value_template, with the normal Jinja filters. Divide tenths of a degree by 10 ({{ value_json.temp1 | float / 10 }}), milliwatts by 1000, and so on. The important bit is the | float (or | int): it cleanly casts the value to a number before you do math, otherwise some APIs give you string concatenation instead of a division. Set device_class and unit_of_measurement to match, so the value is sorted correctly in the dashboard and in statistics.

Does this work for a local API without a cloud?

Yes, identically. resource then simply points at the device's local address (e.g. http:///status) instead of a cloud host. For local devices without authentication you drop the headers block; everything else is the same. That's exactly what makes the REST sensor so universal — vendor cloud or a small HTTP server on your LAN, the pattern stays the same.

Self-Consumption & Autarky: PV Metrics in Home Assistant

Michael Bernhart — Tue, 30 Jun 2026 07:27:27 +0000

The number I actually care about with a PV system isn't how much the panels produced. It's how much of it I kept. The inverter's cloud portal shows me a self-consumption percentage and an autarky percentage on a nice dashboard, and for a long time I treated those two figures as the scoreboard for the whole house. The problem: they live in someone else's cloud, I can't chart their history the way I want, and I can't alert on them. So I rebuilt them in Home Assistant. The catch I didn't expect is that Home Assistant doesn't hand you any of these numbers either.

This is Part 02 of the series. Part 01 covered getting Home Assistant running via Docker and pulling the inverter in over Modbus. Now that the raw counters are flowing, this post is about turning them into the four metrics I wanted: self-consumption, autarky, battery round-trip efficiency, and a string-imbalance watchdog.

Home Assistant gives you counters, not KPIs

Here's the honest part. Home Assistant has an Energy Dashboard, and it's genuinely good at showing you a picture: production, grid import, grid export, battery flow. What it does not expose are the derived percentages. There is no sensor.self_consumption entity. There is no sensor.autarky entity. The Energy Dashboard computes that picture internally and draws it, but it never hands you the numbers back as entities you can chart over a year or trip an automation on.

My inverter is a Huawei SUN2000, and even its own integration only surfaces the raw lifetime and daily counters — total yield, grid feed-in, grid import, battery charge, battery discharge. Everything else I want is arithmetic on top of those. So I built the metrics myself as Home Assistant template sensors , defined in a templates.yaml file. That distinction matters to me: these aren't values the integration gave me, they're values I derived, which means I get to decide exactly how they're calculated.

Self-consumption and the reconstruction problem

Self-consumption is the easy one. It's the share of what you produced that you actually used yourself instead of exporting: total yield minus grid export, over total yield. My Eigenverbrauchsquote sensor does exactly that and lands around 65.9% — and it matches the number the cloud portal shows, which was a satisfying moment, because it meant I'd correctly reverse-engineered what the cloud was doing. Same logic, just running locally instead of in someone's data centre.

Autarky is where it gets interesting, and where the honest engineering beat lives. Autarky is the share of your consumption covered by your own production — one minus (grid import over consumption). But Home Assistant never measures household consumption directly. Nobody does, unless you've wired a meter on the main feed. So you reconstruct it from three counters: consumption equals yield, minus what you exported, plus what you pulled from the grid. That reconstructed consumption is what goes in the denominator. My Autarkiegrad sensor sits around 76.9%.

I want to be clear that this is a reconstruction, not a reading. If your counters drift, your autarky drifts with them. But for a household figure, three counters and a bit of algebra get you a number that's plenty accurate to act on — and it's a number that's now mine , living in my own history, not the inverter vendor's.

# Autarky as a Home Assistant template sensor
- name: "Autarkiegrad"
  unit_of_measurement: "%"
  icon: "mdi:leaf"
  state: >
    {% set ertrag = states('sensor.pv_gesamt_ertrag') | float(0) %}
    {% set einspeisung = states('sensor.netzeinspeisung_gesamt') | float(0) %}
    {% set netzbezug = states('sensor.netzbezug_gesamt') | float(0) %}
    {% set verbrauch = ertrag - einspeisung + netzbezug %}
    {% if verbrauch > 0 %}
      {{ ((1 - netzbezug / verbrauch) * 100) | round(1) }}
    {% else %}
      0
    {% endif %}

The entity names are German because they're mine — Autarkiegrad , Eigenverbrauchsquote — and I gave each a fitting icon, mdi:leaf for autarky and mdi:home-lightning-bolt for self-consumption. Small thing, but a leaf next to your autarky number in the dashboard is quietly motivating.

Battery health, in two cheap sensors

The battery deserves its own KPIs, and the nice thing is they fall out of counters you already have. Round-trip efficiency is just energy out over energy in: discharge over charge. My Batterie Effizienz sensor reports 97.2%, which is genuinely healthy for a home battery, and because it's a sensor with history I can watch that number slowly degrade over the years instead of finding out the hard way.

The second one is a full-cycle estimate. I don't have a true cycle counter, so I approximate: total charged kWh divided by 10, on the assumption of roughly 10 kWh usable capacity. It's a proxy, not a precise odometer, but as an equivalent-full-cycles figure it's a perfectly reasonable way to track wear. Cheap to compute, useful to chart.

There's also a tiny detail I enjoy. My boiler temperature comes off a Modbus register that reports tenths of a degree as a raw integer, so a Temperatur Boiler Präzise sensor just divides the raw value by 10. Nothing clever, but it's the kind of thing you only learn by reading the register table — the hardware speaks in tenths, and you have to scale it back yourself.

The watchdog: catching a sick string before the cloud would

My favourite sensor in the whole file is the string-imbalance detector. A PV array usually has two strings, and in healthy conditions their currents track each other closely. When one drifts well below the other, something is wrong — shading, a dead module, or a loose connector. The cloud portal hides this kind of diagnosis behind its own logic; I wanted it local and visible.

The sensor, PV String Differenz , computes the percentage difference between the two string currents. The gotcha — and this is the part worth showing — is night-time. At night both string currents fall to near zero, and a naive difference divided by a near-zero max blows up into meaningless noise. So the template only computes when the larger current is above 0.5 A; below that it just reports 0.

# String-imbalance detector — note the >0.5 A guard so it isn't noise at night
- name: "PV String Differenz"
  unit_of_measurement: "%"
  state: >
    {% set s1 = states('sensor.pv_string_1_strom') | float(0) %}
    {% set s2 = states('sensor.pv_string_2_strom') | float(0) %}
    {% set max_val = [s1, s2] | max %}
    {% if max_val > 0.5 %}
      {{ ((s1 - s2) | abs / max_val * 100) | round(1) }}
    {% else %}
      0
    {% endif %}

On its own that's just a number. The payoff is the automation behind it. PV String Anomalie Warnung fires when the difference stays above 30% for a sustained 30 minutes — the debounce matters, because a passing cloud will briefly imbalance the strings and you don't want a false alarm every time. It's also guarded to only fire in daylight, when string 1 is actually carrying current above 1 A. And the message it sends me literally spells out the likely causes: shading, a defective module, or a loose connector. That's the same diagnostic the inverter cloud keeps to itself, except now it's a push to my phone and I own the logic.

One line a day, and why it's worth it

The other automation is less dramatic but I read it every single evening. PV Tagesbericht fires once a day at 20:00 and crams the whole scoreboard into one push: the day's yield, battery charge and discharge, self-consumption percentage, autarky percentage, and lifetime yield in MWh. The lifetime figure comes off the raw watt-hour counter divided by 1000 and rounded to two decimals — another small scaling detail, like the boiler.

I also keep daily mirrors — Eigenverbrauch Heute and Verbrauch Heute — that recompute today's self-consumption and consumption from the daily yield, daily feed-in, and daily grid-import counters, so the daily figures use the same arithmetic as the lifetime ones. Percentages round to one decimal, daily kWh to two, cycles to zero. Tidy enough that the evening push reads like a clean report rather than a dump of floats.

That's the whole thread of this series, really: own your data, self-host the dashboard. The inverter cloud can show me a self-consumption gauge, but it can't let me alert on a sick string, chart my battery's efficiency over five years, or hand me a single evening line with everything in it. Home Assistant doesn't give you those metrics for free — but once you've reconstructed them from the raw counters, they're sensors like any other: chartable, alertable, and yours. Next in the series, I'll wire these numbers into actually doing something with the surplus.

What AI Crawlers Actually Do to a Small Blog: 9 Days of Logs

Michael Bernhart — Sun, 28 Jun 2026 14:03:43 +0000

I run a small Home Assistant / self-hosting blog. On a normal day a few dozen humans show up. So when I finally grepped my nginx logs for AI crawlers, the number made me stop: in nine days, AI bots hit the site 18,209 times. On a blog this size, the machines reading me now outnumber the people.

Here's the full breakdown, the things that surprised me, and a few points most "should I block AI bots?" threads get wrong.

The raw numbers (9 days, one small blog)

Of 348,667 total requests, 18,209 (5.2%) came from AI/LLM user-agents:

Bot	Requests	What it actually is
ChatGPT-User	6,687	OpenAI — live fetch when someone asks ChatGPT about a page
Bytespider	3,369	ByteDance / TikTok crawler
meta-externalagent	3,274	Meta AI
Amazonbot	1,923	Amazon
OAI-SearchBot	1,211	OpenAI search index
ClaudeBot	850	Anthropic — training / index crawler
PerplexityBot	319	Perplexity
DuckAssistBot	225	DuckDuckGo AI
GPTBot	172	OpenAI training crawler
CCBot	86	Common Crawl (feeds many models)
YouBot	68	You.com

Surprise #1: the #1 "AI bot" isn't a crawler

The biggest source by far — ChatGPT-User, 6,687 requests — isn't crawling to train a model. It's a live fetch: someone asked ChatGPT a question, ChatGPT decided my page was relevant, and pulled it in real time to answer them. Same story with Perplexity-User and the other assistant-side fetchers.

That flips the "should I block it?" math. ChatGPT-User isn't scraping you — it's a real person, through their assistant, reading your page right now. Block it and you don't stop any training; you just stop showing up in answers and lose the visit. (I can see the other end of it in my analytics: real sessions arriving from claude.ai and gemini.google.com.)

So the mental model "AI bot = scraper to block" is wrong for a big chunk of the traffic. There are training crawlers (GPTBot, ClaudeBot, CCBot) and there are live answer-engine fetchers (ChatGPT-User, Perplexity-User, DuckAssistBot). Treating them the same is the mistake.

Surprise #2: robots.txt behaviour is all over the place

I checked who actually requests /robots.txt:

ClaudeBot: 233 — diligent, checks constantly.
PerplexityBot: 56 — checks in.
Bytespider: 77 — does fetch it (whether it honours the contents is its own reputation).
GPTBot: 0 — didn't pull it once in this window (low volume, granted).
ChatGPT-User: 0 — never. And that's correct: it's user-initiated, like a browser. Browsers don't read robots.txt, and a live fetch on a human's behalf shouldn't either.

The practical upshot: a blanket Disallow is obeyed by the well-behaved training crawlers and ignored by the user-fetchers — because robots.txt was never meant for them. If your goal is "don't feed training, but keep appearing in answers," the default already does roughly the right thing — but only for the bots that honour it.

The gap nobody mentions: these crawlers don't run JavaScript

This is the one that actually cost me, and the reason I ended up building a little tool around it.

Almost every AI crawler fetches your raw server HTML and does not execute JavaScript. So if your framework injects JSON-LD structured data on the client, or your streaming-SSR setup flushes meta tags into the <body> instead of the initial <head>, those signals are invisible to the crawler — even though Google renders them and every SEO browser extension tells you you're fine.

I only found six pages on my own site doing exactly that, because I built a crawler that deliberately parses the JS-less view and diffs it against the hydrated DOM. Googlebot renders; GPTBot and ClaudeBot mostly don't. If you care about being represented correctly in AI answers, your structured data and metadata have to live in the server HTML, not get painted on after hydration.

What I'd actually do with this

Don't reflexively block "AI bots." Separate training crawlers (GPTBot, ClaudeBot, CCBot — robots.txt works) from live answer-fetchers (ChatGPT-User, Perplexity-User — blocking them costs real referrals).
Verify by ASN / reverse DNS, not the user-agent. The UA string is trivially spoofed; a "GPTBot" from a random consumer IP is not GPTBot.
Put structured data + metadata in the server-rendered HTML. If it only appears after JS, the AI crawlers never see it.
Watch Bytespider if load is a concern — it's the most aggressive of the genuine crawlers.

For a blog with a few dozen human readers a day, AI crawlers are now the single largest non-search audience hitting the server. They aren't going away — so it's worth knowing which ones are reading you, and making sure they can actually see what you publish.

The JS-less-view crawler I used is open-source (seo-geo-audit) — it flags exactly this gap, plus the usual SEO checks, in plain Node with no paid dependencies.

Read the Huawei SUN2000 in Home Assistant Without a Custom Integration: Native Modbus YAML

Michael Bernhart — Fri, 26 Jun 2026 12:29:36 +0000

Almost every Huawei SUN2000 guide opens with the same line: "install the huawei-solar custom integration." And it works — right up until the next Home Assistant upgrade introduces a breaking change, the integration won't load, and suddenly half your Energy Dashboard is blank. That happened to me twice before I switched to the dependency-free route.

The SUN2000 speaks Modbus-TCP natively, and Home Assistant ships a built-in modbus: platform. You don't need a custom component — you declare each sensor yourself by its register address. That's a bit more YAML, but nothing breaks on upgrade and you understand exactly where every value comes from. This post gives you the complete register-to-YAML map for PV yield, battery and grid — ready for the Energy Dashboard.

Why native modbus YAML instead of a custom integration

The custom integration is convenient, but it's an extra dependency between you and your data. Every HA update risks it becoming incompatible, and you can end up two days without energy data until a maintainer catches up. The built-in modbus: platform is a core part of Home Assistant — it's maintained with the core and can't "go orphaned." The price is transparency instead of magic: you write a handful of lines per value with register address, data_type and scale. Those exact lines are what I hand you here.

The Modbus hub: point at the proxy, not directly at the SDongle

The SUN2000's SDongle allows only one concurrent Modbus connection. If HA, evcc and an AC·THOR all hit it directly, they block each other. That's why my Modbus hub doesn't point at the SDongle IP but at 127.0.0.1:5502 — the local caching proxy that polls the SDongle once and serves the result to any number of clients. Why and how that's needed is covered in the Modbus caching basics post. If you have only a single client, you can point host/port straight at the SDongle instead — the sensors underneath stay identical.

- name: huawei_inverter
  type: tcp
  host: 127.0.0.1
  port: 5502
  delay: 2
  timeout: 10
  sensors:
    - name: "PV Cumulative Yield"
      unique_id: huawei_pv_cumulative_yield
      slave: 1
      address: 32106
      input_type: holding
      data_type: uint32
      scale: 0.01
      precision: 2
      unit_of_measurement: "kWh"
      device_class: energy
      state_class: total_increasing
      scan_interval: 60

The two fields that matter for the Energy Dashboard are device_class: energy and state_class: total_increasing. Without them the sensor won't even show up as a selectable source in the energy configuration. The delay: 2 on the hub gives the (slow) SDongle two seconds after connecting before the first read — without it you'll see sporadic timeouts at startup.

Battery: total charge and discharge as uint32

The battery energy registers are cumulative counters — they only go up, which fits total_increasing perfectly. The key here is the data_type uint32: the values quickly exceed the 16-bit range and therefore occupy two consecutive registers (37780 and the following one). HA reads both together when you set data_type uint32 — no second address needed.

    - name: "Battery Total Charge"
      unique_id: huawei_battery_total_charge
      slave: 1
      address: 37780
      input_type: holding
      data_type: uint32
      scale: 0.01
      precision: 2
      unit_of_measurement: "kWh"
      device_class: energy
      state_class: total_increasing
      scan_interval: 60
    - name: "Battery Total Discharge"
      unique_id: huawei_battery_total_discharge
      slave: 1
      address: 37782
      input_type: holding
      data_type: uint32
      scale: 0.01
      precision: 2
      unit_of_measurement: "kWh"
      device_class: energy
      state_class: total_increasing
      scan_interval: 60

You enter these two sensors in the Energy Dashboard as "home battery storage" — charge as "energy into the battery," discharge as "energy out of the battery." That lets HA track the battery round-trip balance correctly.

Grid: import and export as signed int32

With the grid registers the classic mistake is the data_type. Grid values can come as signed int32 depending on firmware — if you accidentally read them as uint32, a value just above or below zero flips into a huge number (two's complement). So read them as int32 and the sign and magnitude line up.

    - name: "Grid Total Exported"
      unique_id: huawei_grid_exported_energy
      slave: 1
      address: 37119
      input_type: holding
      data_type: int32
      scale: 0.01
      precision: 2
      unit_of_measurement: "kWh"
      device_class: energy
      state_class: total_increasing
      scan_interval: 60
    - name: "Grid Total Imported"
      unique_id: huawei_grid_imported_energy
      slave: 1
      address: 37121
      input_type: holding
      data_type: int32
      scale: 0.01
      precision: 2
      unit_of_measurement: "kWh"
      device_class: energy
      state_class: total_increasing
      scan_interval: 60

Grid export and import are the last two sources the Energy Dashboard needs for the full balance: export under "return to grid," import under "grid consumption." Once PV yield, battery and grid are entered, you have the complete Sankey diagram without a single custom line.

scale, precision and data_type — the three pitfalls

Three fields decide whether the values are right. scale: Huawei delivers energy in tenth- or hundredth-units — 0.01 turns the raw register into kWh. If your value is off by a factor of 10 or 100, it's almost always the scale. data_type: energy counters are 32-bit (uint32/int32); an accidental uint16 clips at ~655 kWh and wraps back to zero. precision: cosmetic only (decimal places), but two digits keep the history clean. If something stays "unavailable" after a restart, check slave (device ID, usually 1) and input_type (holding) first.

Enabling and verifying

The sensor blocks go under the modbus: hub in your configuration.yaml (or a file pulled in via !include). After "reload YAML configuration" → "Modbus" (or a restart) the entities appear. Go to Developer Tools → States and filter for sensor.pv_cumulative_yield and the battery/grid sensors: if you see plausible kWh values, you have a complete, upgrade-proof data source — with no custom integration at all. If you want to build derived metrics like self-sufficiency on top of these raw registers, that's covered in the self-consumption sensors post.

Frequently asked questions

Why 127.0.0.1:5502 instead of the real SDongle IP?

Because the SUN2000 SDongle allows only one concurrent Modbus connection. As soon as HA and a second client (evcc, AC·THOR, a script) connect directly, they choke each other. 127.0.0.1:5502 is a local caching proxy that polls the SDongle once and serves any number of clients. With a single client you can point host/port straight at the SDongle IP.

Why uint32 / int32 and not just uint16?

Energy counters in kWh quickly exceed the 16-bit range (max ~655 with scale 0.01) and therefore live across two consecutive registers. data_type uint32 (or int32 for signed grid values) reads both together. With uint16 you clip the high part and the counter appears to jump backwards.

Will this break on a Home Assistant upgrade?

No — that's exactly the point. The modbus platform is part of the HA core and maintained with it. There's no third-party integration that could become incompatible. In the worst case the spelling of a config key changes, which the release notes announce — but your data source never "goes orphaned."

Do these register addresses apply to every SUN2000?

The addresses given here (32106 yield, 37780/37782 battery, 37119/37121 grid) apply to the common residential SUN2000 inverters with LUNA storage. For different firmware or other models, check the official Huawei Modbus interface document — layout and scale can differ slightly between generations, but the YAML structure stays the same.

Build Your Own Modbus-TCP Cache Proxy in Python: One Inverter, Many Home Assistant Clients

Michael Bernhart — Wed, 24 Jun 2026 14:59:06 +0000

The Huawei SUN2000 SDongle has an annoying trait you only trip over once you want to connect more than one device: it accepts exactly one concurrent Modbus-TCP connection. The moment Home Assistant polls it, the AC·THOR stops getting answers; let evcc squeeze in and one of the two gets dropped. In my setup three clients wanted to read the same registers at once — and the dongle let exactly one through.

The usual advice is: use the ha-modbusproxy add-on. It works. But I wanted to understand what happens underneath, and I didn't want a black-box container for something that, at its core, is surprisingly small. So I wrote the proxy myself: roughly 300 lines of asyncio Python that poll the SDongle once every 10 seconds into an in-memory register cache and serve FC3 reads to any number of parallel clients. This post is the developer deep-dive to my concept post on caching Modbus proxies — that one is about the why, this one is about the how, down to the byte level.

The problem: one upstream, many clients

Modbus-TCP is a simple request-response protocol, but the SDongle is designed as a slave with exactly one master. Multiple masters at once aren't part of the standard, and Huawei enforces that hard. The solution is a proxy that behaves toward the dongle like the one permitted master, and toward every other device like a Modbus slave itself. The second half is the key: it answers client reads not by forwarding to the dongle, but from a cache. That way the dongle only ever sees one calm, periodic poller, no matter how many clients hang off the back.

The configuration: the only thing you change

I parameterize the whole proxy through a handful of constants at the top of the file. In the normal case you only change your SDongle's IP and maybe the listen port. Everything else fits a standard Huawei installation.

# === Configuration ===
SDONGLE_HOST = "192.0.2.10"   # <- deine Huawei SDongle IP (RFC 5737 Beispiel)
SDONGLE_PORT = 502
DEVICE_ID = 1

SERVER_HOST = "0.0.0.0"        # auf allen Interfaces lauschen
SERVER_PORT = 5502
POLL_INTERVAL = 10            # Sekunden

The proxy listens on port 5502 instead of 502 so it can run alongside the actual dongle and needs no root for a privileged port. In Home Assistant, AC·THOR and evcc you then simply enter the proxy host's IP and port 5502 — none of the clients notice they aren't talking to the dongle directly.

Register batching: fewer roundtrips to the dongle

The SDongle is slow, and every single read costs a full TCP roundtrip. Instead of querying each register individually, I read contiguous blocks in one go. Modbus allows up to 125 registers per FC3 read; I group the registers I need into a few batches along the natural gaps in the Huawei map.

REGISTER_BATCHES = [
    (32016, 4),   # PV string 1/2 voltage + current
    (32064, 2),   # Input power (int32)
    (32080, 2),   # Active power (int32)
    (32106, 2),   # Cumulative energy yield (uint32)
    (32114, 2),   # Daily energy yield (uint32)
    (37760, 1),   # Battery SOC
    (37765, 2),   # Battery power (int32)
    (37780, 8),   # Battery total charge/discharge + daily
]

Each entry is a (start_address, count) tuple. These eight batches cover everything my clients need — PV string values, power, yield and the full battery block. Per poll cycle that's eight small reads instead of dozens of individual queries, and the entire cycle finishes in well under a second.

Reading one FC3 batch: packing and unpacking the MBAP frame

This is where it gets interesting. A Modbus-TCP frame is the 7-byte MBAP header (transaction ID, protocol ID, length, unit ID) plus the PDU (function code + payload). With struct.pack I build the request frame, write it to the dongle, and unpack the response again. The format string ">HHHBBHH" encodes exactly that structure: three big-endian uint16 for the MBAP head, then unit, function code and the two uint16 for start address and count.

async def read_batch(reader, writer, start, count):
    req = struct.pack(">HHHBBHH", 0, 0, 6, DEVICE_ID, 3, start, count)
    writer.write(req)
    await writer.drain()
    resp = await asyncio.wait_for(reader.read(9 + count * 2), timeout=3)
    resp_tx, resp_proto, resp_len, resp_unit, resp_fc, byte_count = struct.unpack(
        ">HHHBBB", resp[:9])
    if resp_fc >= 0x80:  # Exception
        return None
    data = resp[9:]
    if len(data) >= count * 2:
        return struct.unpack(">" + "H" * count, data[:count * 2])

Two details matter. The asyncio.wait_for(..., timeout=3) stops a hung dongle from blocking the whole poller — if the answer never comes, the read times out and the cycle drops into backoff. And the resp_fc >= 0x80 check catches Modbus exceptions: if the dongle sets the top bit of the function code, it's not a data response but an error, so I return None instead of unpacking garbage. The int32/uint32 values from the batches get reassembled later by the caller from two consecutive uint16 registers each.

Serving the cache to every client

The second half of the proxy is the server side. When a client connects and sends an FC3 read, I answer it not from the dongle but from the in-memory cache. I read the requested start address and count from the client PDU, pull the values out of the cache dictionary under an asyncio.Lock, and build a valid Modbus response with a correct MBAP header back.

if fc == 3 and len(pdu) >= 5:
    reg_addr, reg_count = struct.unpack(">HH", pdu[1:5])
    values = []
    async with cache_lock:
        for i in range(reg_count):
            values.append(register_cache.get(reg_addr + i, 0))
    byte_count = reg_count * 2
    resp_pdu = struct.pack(">BB", fc, byte_count)
    resp_pdu += struct.pack(">" + "H" * reg_count, *values)
    resp_header = struct.pack(">HHHB", tx_id, 0, len(resp_pdu) + 1, unit_id)
    client_writer.write(resp_header + resp_pdu)

The cache_lock is not optional: the reader loop writes the cache while several client handlers read it at the same time — without the lock you could serve a half-updated register row. It's also important that I mirror the client's tx_id (transaction ID) in the response; a correct Modbus master matches responses precisely on that field, and a wrong value makes some clients discard the answer. Missing registers I answer with 0 rather than an error — that keeps picky clients happy.

The reader loop: poll, backoff, stale warning

Holding it all together is a single long-running task that polls the dongle in a loop. As long as everything is fine it runs at the normal 10-second cadence. If a poll fails, it goes into a shorter retry, and if the cache gets too old, it writes a warning to the log.

async def reader_loop():
    retry_delay = 5
    while True:
        success = await read_sdongle()
        if success:
            last_update = time.time()
            retry_delay = POLL_INTERVAL
        else:
            retry_delay = min(retry_delay, 10)
            age = time.time() - last_update if last_update > 0 else -1
            if age > 120:
                logger.warning(f"Cache stale for {age:.0f}s")
        await asyncio.sleep(retry_delay)

The stale warning after 120 seconds is my early-warning system: when it shows up in the log I know the dongle has stopped answering before the clients even start showing weird values. I deliberately kept the cache holding the last valid values on failure rather than dropping to zero — otherwise every dongle hiccup would push a PV power of 0 W to all clients and trigger false alarms and broken statistics in Home Assistant.

Wiring it into Home Assistant and checking it

On the HA side almost nothing changes versus a direct connection — you just point the Modbus hub at the proxy instead of the dongle. I now run three clients against the same upstream, and on the PV dashboard I see sensor.my_pv_pv_leistung, sensor.my_pv_batteriestand and sensor.pv_gesamt_ertrag updating live — all sourced through the proxy at the same time, without the clients stealing the connection from each other. How I turn these raw values into self-consumption and autarky is in the post on self-consumption and autarky sensors.

Frequently asked questions

Why not just use the ha-modbusproxy add-on?

You can, and for most people it's the right call. But I wanted to understand what happens under the hood and have full control over batching, cache behaviour and logging. If you're happy for an add-on to stay a black box, use the add-on; if you want to understand or extend the mechanism (e.g. your own computed registers, different poll intervals per batch), the home-built proxy is exactly right.

Doesn't the cache serve stale values?

At most as old as your poll interval — 10 seconds here. For PV power, battery SOC and yield that's perfectly fine; these values don't change meaningfully second by second. If you need it faster, lower POLL_INTERVAL, but keep in mind the SDongle gets cranky under overly aggressive polling. Ten seconds is the stable sweet spot for me.

Does the proxy support writes (FC6/FC16)?

Not this version — it's deliberately read-only and only handles FC3. That covers the sensor connection this post is about. Writes (say, a battery charge-mode control) you'd have to add, and then the 1-connection limit bites even harder: writes must not overlap. For pure data sharing across multiple clients, read-only is the safe and sufficient path.

What happens if the SDongle drops out briefly?

The reader loop goes into retry backoff and the cache holds the last valid values instead of falling to zero — so clients see no crash, just frozen values. After 120 seconds without an update the proxy writes a stale warning to the log. When the dongle comes back, the next successful poll refills the cache and the normal 10-second cadence resumes automatically.

Home Assistant — How to Install via Docker on an Azure Linux VM

Michael Bernhart — Tue, 23 Jun 2026 14:27:54 +0000

Home Assistant is a powerful, open-source home automation platform that puts local control and privacy first. If you want to host it on the cloud, using a Linux VM in Azure and Docker is a robust and scalable option. Here’s a step-by-step guide to setting it up.

1. Setting Up the Azure Linux VM

Step 1.1: Create the Linux VM

Log in to the Azure Portal.
Navigate to Virtual Machines > Create > Virtual Machine.
Configure the VM:

Subscription : Select your Azure subscription.
Resource Group: Create a new resource group or use an existing one.
Virtual Machine Name : Choose a descriptive name, e.g., HomeAssistantVM.
Region : Select the region closest to you.
Image : Choose Ubuntu Server 20.04 LTS (or later).
Size : Select an appropriate size, e.g., Standard B1ms (sufficient for Home Assistant).
Authentication Type : Use SSH Public Key (recommended for security).
Upload your SSH public key or generate one using ssh-keygen.
Enable Public Inbound Ports
Select Allow Selected Ports
Choose SSH (22).

Click Next through the Networking, Management, and other tabs.
Review and create the VM.

Step 1.2: Connect to the VM

Once the VM is created:

Find the public IP address of the VM in the Azure Portal.
SSH into the VM using:

 ssh -i /path/to/private-key username@<VM_PUBLIC_IP>

2. Prepare the Linux VM for Docker Installation

Step 2.1: Update the System

Run the following commands to ensure the system is updated:

 sudo apt update && sudo apt upgrade -y

3. Install & Setup Docker

Install dependencies for Docker:

sudo apt install -y docker.io
sudo systemctl start docker
sudo systemctl enable docker

4. Install Home Assistant in Docker

We change the directory to our home dir, and then we create a new directory for “Homeassistant”.

 mkdir /home/yourUser/homeassistant

Now we can start with the preconfigured container from “home-assistant”.

 sudo docker run -d --name homeassistant --restart unless-stopped \
  -v /home/userdir/homeassistant:/config \
  --network=host \
  ghcr.io/home-assistant/home-assistant:stable

Here is a detailed explanation of what the command does:

sudo :

Ensures the command runs with superuser privileges (necessary for Docker commands if not in the docker group).

docker run :

This is the base command to create and start a new Docker container.

-d :

Runs the container in detached mode (in the background). The terminal will not be attached to the container’s output.

--name homeassistant :

Assigns a name (homeassistant) to the container. This makes it easier to reference the container later using commands like docker start homeassistant

--restart unless-stopped :

Configures the container to automatically restart if it stops unexpectedly (e.g., due to a system reboot). It will remain stopped only if you manually stop it with a docker stop command.

-v /home/userdir/homeassistant:/config :

Mounts a volume between the host and the container:
/home/userdir/homeassistant -> is a directory on the host machine.
/config -> is the corresponding directory inside the container where Home Assistant stores its configuration files.
This ensures that your configurations persist across container restarts or updates.

--network=host :

Configures the container to use the host’s networking stack directly.
This eliminates network isolation between the container and the host, allowing Home Assistant to directly access the host’s network interfaces (important for Home Assistant to detect devices on the same network).

ghcr.io/home-assistant/home-assistant:stable :

Specifies the Docker image to use:
ghcr.io/home-assistant/home-assistant -> is the image's location in GitHub Container Registry.
:stable -> is the tag specifying the stable version of the Home Assistant image. If omitted, Docker will default to the latest tag.

5. Access Home Assistant

Open a browser and navigate to:

 http://<VM_PUBLIC_IP>:8123

Complete the initial setup by following the on-screen instructions.

Firewall Settings Azure VM

Don’t forget to open the TCP port 8123 on your Azure VM.

Now you have Home Assistant up and running. In the next posts, I will show you how to setup “HACS” Home Assistant Community Store and further configuration steps. Home Automation is not so tricky ;-)

Cloudapp-dev, and before you leave us

Thank you for reading until the end. Before you go:

Please consider clapping and following the writer! 👏 on our Medium Account

Or follow us on twitter -> Cloudapp.dev