DEV Community: Michael Bernhart

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

Control an AC·THOR 9s from Home Assistant When Modbus Writes Are Blocked: the my-PV Cloud API

Michael Bernhart — Fri, 19 Jun 2026 06:27:34 +0000

I wanted something that sounds trivial: to boost my AC·THOR 9s — the my-PV heating element that turns PV surplus into hot water — to a target temperature from Home Assistant whenever the evening didn't bring enough sun. Reading over Modbus TCP had worked for ages: boiler temperature, power, all sitting cleanly as sensors in HA. So I figured the write path was one line of YAML away.

It wasn't. Every Modbus write to the AC·THOR ended in a connection refused. No timeout, no silent failure — the device actively rejects write attempts. It's in no documentation, and it cost me an evening of debugging to understand: on the AC·THOR 9s, Modbus TCP is read-only. Full stop.

The real problem: Modbus reads yes, writes no

The split is hard and reproducible. Monitoring works permanently over Modbus, control doesn't at all. If you, like me, build the read sensors first and feel pleased with yourself, you hit a wall the moment the first set command lands. Here's the inventory I noted down after the debugging session:

BLOCKED:  Modbus-TCP write operations (device-side restriction, 'connection refused' on every write attempt)
WORKING:  Control via Cloud API PUT /setup
WORKING:  Temperature monitoring via Modbus-TCP still works (read-only)

Tested parameters (PUT /setup, JSON body):
  bstmode    Assurance/boost mode           0=Off, 1=On
  ww1boost   Target temperature             550 = 55.0°C   (tenths °C)
  ww1target  Max temperature, solar mode    650 = 65.0°C   (tenths °C)
  bstton1    Boost window 1 start           Hour 0-23
  bsttof1    Boost window 1 end             Hour 0-23

Gotchas:
  - Propagation delay: a change only takes effect after 4-6 s on the device.
  - The API replies immediately with 'ok' (no proof the value is set yet).
  - Wait before the GET /setup verification.

The rescue is the my-PV Cloud API. It's barely documented, but it accepts exactly the write commands that local Modbus refuses. So the path doesn't go over the LAN straight to the device — it takes the detour through the my-PV cloud, which the device then syncs from itself.

The solution: the my-PV Cloud API via PUT /setup

The API has a single control endpoint that matters: PUT /api/v1/device//setup. The JSON body carries exactly the fields you want to change — everything else stays untouched. You authenticate with an Authorization header carrying your cloud API token. That's the whole transport mechanism: a PUT with a few keys in the body.

An important framing: this post only covers the transport layer — that is, how the write command reaches the device at all. The actual surplus logic (when to boost, boost-stop at 55 °C) belongs in a separate automation and is the subject of the AC·THOR surplus post.

The shell_command.yaml — set boost and target temperature

Since there's no native HA integration for the my-PV cloud, I build the write commands as shell_command entries using curl. Each entry is a single PUT. Replace DEVICE_SERIAL with your my-PV serial and YOUR_MYPV_API_TOKEN with your cloud API token (ideally pulled from !secret — inline here for readability):

# AC·THOR 9s Cloud API commands (direct REST calls)
# Uses the my-PV Cloud API, since Modbus-TCP write is blocked device-side.
# Replace placeholders:
#   DEVICE_SERIAL = your my-PV device serial number
#   YOUR_MYPV_API_TOKEN = your my-PV Cloud API authorization token

acthor_enable_boost: 'curl -s -X PUT "https://api.my-pv.com/api/v1/device/DEVICE_SERIAL/setup" -H "Authorization: YOUR_MYPV_API_TOKEN" -H "Content-Type: application/json" -d "{\"bstmode\": 1}"'
acthor_disable_boost: 'curl -s -X PUT "https://api.my-pv.com/api/v1/device/DEVICE_SERIAL/setup" -H "Authorization: YOUR_MYPV_API_TOKEN" -H "Content-Type: application/json" -d "{\"bstmode\": 0}"'

# Target temperature (in tenths °C: 550=55°C, 600=60°C, 650=65°C)
acthor_set_target_temp_55: 'curl -s -X PUT "https://api.my-pv.com/api/v1/device/DEVICE_SERIAL/setup" -H "Authorization: YOUR_MYPV_API_TOKEN" -H "Content-Type: application/json" -d "{\"ww1boost\": 550}"'

# Max solar temperature
acthor_set_max_temp_65: 'curl -s -X PUT "https://api.my-pv.com/api/v1/device/DEVICE_SERIAL/setup" -H "Authorization: YOUR_MYPV_API_TOKEN" -H "Content-Type: application/json" -d "{\"ww1target\": 650}"'

# Boost window (start/end as hour 0-23)
acthor_enable_boost_with_time: 'curl -s -X PUT "https://api.my-pv.com/api/v1/device/DEVICE_SERIAL/setup" -H "Authorization: YOUR_MYPV_API_TOKEN" -H "Content-Type: application/json" -d "{\"bstmode\": 1, \"bstton1\": {{ start_hour }}, \"bsttof1\": {{ end_hour }}}"'

After a reload of the shell commands, shell_command.acthor_enable_boost and the others are available as services in HA and can be called from any automation or from the Developer Tools service tab. That restores the write path that Modbus refused.

The parameters that actually work

I tested the fields one by one, because the my-PV docs are silent here. These four (plus the two time-window fields) are enough for full boost control. bstmode is the switch: 1 starts the boost, 0 stops it. ww1boost is the boost's target temperature, ww1target the maximum temperature in normal solar operation — both in tenths of a degree, so 550 means 55.0 °C. bstton1 and bsttof1 define a boost window as a whole hour (0–23).

The most common beginner mistake is the unit: send 55 instead of 550 and you set the device to a 5.5 °C target — effectively off. The tenths-of-a-degree convention isn't documented cleanly anywhere, but it's consistent across all temperature fields.

The gotcha: the propagation delay

This is where I lost the most time. The API answers every PUT instantly with 'ok' — but that only means the cloud accepted the command, not that the device has applied the value yet. It takes 4 to 6 seconds before the change actually reaches the AC·THOR.

In practice that means: if you verify with GET /setup immediately after writing, you'll still read the old value and conclude the command failed. So build in a short wait after the PUT before triggering the verification or a follow-up action. In an HA automation I do this with a delay of a few seconds between the shell_command and the next step — that eliminated every phantom failure.

Monitoring stays on Modbus

A pleasant side effect: you don't have to give up the working Modbus read. On my setup HA keeps reading the boiler temperature and power locally over Modbus TCP — no cloud dependency, no rate limit. Only the write path goes through the cloud. This hybrid (read locally, write via cloud) is robust: if the internet drops you lose control, not the display. If you wire up the inverter behind it over Modbus too, the basics are in the Modbus cache post.

Frequently asked questions

Why doesn't the AC·THOR 9s allow Modbus writes?

It's a device-side restriction from my-PV: the Modbus TCP server on the AC·THOR is designed read-only, and every write attempt is rejected with 'connection refused'. Control is intended exclusively via the official app, the local web interface, or the cloud API. It's not a bug in your configuration — it's the manufacturer's intent.

Do I strictly need the cloud, or can I do it locally?

For API write access, the documented path goes through the my-PV cloud (api.my-pv.com). Some firmware versions additionally expose local HTTP endpoints, but that's version-dependent and not guaranteed. The cloud path shown here works reliably across devices — the cost is an internet dependency for control. Monitoring stays local and unaffected.

Why does my verification fail right after writing?

Almost certainly the propagation delay. The API acknowledges instantly with 'ok', but the device only applies the value after 4–6 seconds. If you query GET /setup immediately afterward, you still read the old state. Wait a few seconds between writing and reading and the result is correct.

How do I hide the serial number and token in the config?

Put both in secrets.yaml and reference them with !secret in the shell_command. That keeps neither the device serial nor the cloud API token in versioned YAML. Be especially careful that the token never appears in logs, screenshots, or a Git repo — it grants full write access to your device.

Detect a Failing PV String in Home Assistant: Shading, Dead Module or Loose MC4

Michael Bernhart — Wed, 17 Jun 2026 07:23:11 +0000

A PV string can quietly underperform for months, and you only notice on the annual statement. Partial shading from a tree that grew taller, a module with a failed bypass diode, an MC4 connector that worked itself loose over the years — each one costs yield without throwing a single error. My inverter happily shows green while half a string sits in shade.

The fix is surprisingly simple and needs no extra hardware: if your system has two MPPT trackers, the two strings should track each other closely throughout the day when they face the same direction. If they drift apart for any length of time, something is wrong. Here is how to watch for exactly that in Home Assistant, in three steps.

The idea: compare your two MPPT strings

On a system with two equally-oriented strings, the current per string is nearly identical across the day. Voltage tells you little (it stays fairly stable even under shade), but current drops the moment a module in one string gets less light or is electrically worse connected. So we continuously compute the percentage difference between the two string currents and raise an alert when it stays above a threshold — not on a passing cloud, but on a sustained deviation.

Step 1 — read each string's current over Modbus

The data comes from the inverter's Modbus holding registers. On my Huawei SUN2000, voltage and current per string sit right next to each other: 32016/32017 for string 1, 32018/32019 for string 2 (voltage scale 0.1, current scale 0.01). How to wire the inverter up over Modbus in the first place is covered in the Modbus basics post.

# inside a Modbus TCP hub (host/port = your own inverter/SDongle/proxy)
sensors:
  - name: "PV String 1 Voltage"
    slave: 1
    address: 32016
    input_type: holding
    data_type: int16
    scale: 0.1
    unit_of_measurement: "V"
    device_class: voltage
    scan_interval: 60
  - name: "PV String 1 Current"
    slave: 1
    address: 32017
    input_type: holding
    data_type: int16
    scale: 0.01
    precision: 2
    unit_of_measurement: "A"
    device_class: current
    scan_interval: 60
  - name: "PV String 2 Voltage"
    slave: 1
    address: 32018
    input_type: holding
    data_type: int16
    scale: 0.1
    unit_of_measurement: "V"
    device_class: voltage
    scan_interval: 60
  - name: "PV String 2 Current"
    slave: 1
    address: 32019
    input_type: holding
    data_type: int16
    scale: 0.01
    precision: 2
    unit_of_measurement: "A"
    device_class: current
    scan_interval: 60

Register addresses are vendor-specific. On a different inverter (Fronius, SMA, GoodWe) you'll find the string registers in the vendor's Modbus map — the logic after that is identical.

Step 2 — a template sensor for the percentage difference

This template sensor computes the deviation relative to the stronger of the two strings. The key detail is the 0.5 A floor: at dawn and dusk, when both strings deliver near zero, any tiny mismatch would blow up to a huge percentage — the floor masks that twilight window and cleanly returns 0.

- name: "PV String Difference"
  unique_id: pv_string_difference
  unit_of_measurement: "%"
  icon: "mdi:solar-panel"
  state: >
    {% set s1 = states('sensor.pv_string_1_current') | float(0) %}
    {% set s2 = states('sensor.pv_string_2_current') | float(0) %}
    {% set max_val = [s1, s2] | max %}
    {% if max_val > 0.5 %}
      {{ ((s1 - s2) | abs / max_val * 100) | round(1) }}
    {% else %}
      0
    {% endif %}

Step 3 — the alert automation with a false-alarm guard

Now it all comes together. The automation fires when the difference exceeds 30 % and holds for 30 minutes. The second guard is the condition "string 1 current above 1 A": it prevents false alarms at night and around sunrise/sunset, when the array barely produces anything anyway.

- id: pv_string_anomaly_warning
  alias: "PV String Anomaly Warning"
  description: "Warn when PV strings differ by >30% for >30 min"
  triggers:
  - trigger: numeric_state
    entity_id: sensor.pv_string_difference
    above: 30
    for:
      minutes: 30
  conditions:
  - condition: numeric_state
    entity_id: sensor.pv_string_1_current
    above: 1
  actions:
  - action: notify.mobile_app_your_phone
    data:
      title: "PV String Anomaly"
      message: >-
        String 1: {{ states('sensor.pv_string_1_voltage') }}V / {{ states('sensor.pv_string_1_current') }}A |
        String 2: {{ states('sensor.pv_string_2_voltage') }}V / {{ states('sensor.pv_string_2_current') }}A |
        Difference: {{ states('sensor.pv_string_difference') }}% |
        Check for shading, a dead module or a loose connector.
  mode: single

The push message names voltage and current of both strings plus the difference — you see right on the lock screen which string is weak, without opening the app. Replace notify.mobile_app_your_phone with your own mobile device.

What the warning actually catches

In practice it's three causes. Shading: a tree, a new rooftop structure, or in winter the chimney's afternoon shadow — the affected string drops reproducibly at the same time of day. A dead module: a blown bypass diode or microcracks pull one string down permanently. A loose MC4 connector: a connector that has corroded over the years or never quite clicked in raises resistance — dangerous, because in the worst case it gets hot. A 30 % difference that doesn't depend on the time of day is exactly the signal worth chasing.

Tuning the thresholds

30 % and 30 minutes are a good starting point for two nominally identical strings. For strings of different size or orientation (east/west) a constant baseline difference is normal — then raise the threshold, or compare specific yield per module instead. Want a more sensitive warning? Drop to 20 %. Want quiet? Stretch the for duration to 60 minutes.

Frequently asked questions

Why 30 % and not a smaller threshold?

Below about 20 % you're in the range of normal scatter from drifting clouds, slightly different module temperatures and measurement noise. 30 % over 30 minutes reliably separates real faults from weather. For very uniform systems you can carefully tighten it after a few weeks of observation.

Does this work with a single-string inverter?

The direct string comparison doesn't — it needs two MPPT trackers. On a single-string system you'd compare actual against expected power (from irradiance/time of day) instead, which is considerably more work. That's exactly why the two-string comparison is so attractive: it needs no reference, the strings are each other's reference.

Will it false-alarm on cloudy days?

No — clouds hit both strings at once, so the difference stays small. That's precisely why we compare the strings against each other rather than against a fixed value. The 30-minute condition additionally absorbs short, uneven shadow passes.

Which Modbus registers does my inverter use?

The 32016–32019 above are for Huawei SUN2000. Other vendors have their own maps; search your inverter's Modbus document for "PV1 Voltage/Current" and "PV2 Voltage/Current". The scale factors (0.1 for voltage, 0.01 for current) are vendor-dependent too — if values are off by a factor of 10, it's almost always the scale.

The Best HACS Integrations for Home Assistant (My Must-Haves)

Michael Bernhart — Tue, 16 Jun 2026 06:10:58 +0000

Once HACS is installed, the real question is what to put in it. (New to HACS? Start with What is HACS? and how to install HACS.) Here are the HACS integrations I actually run in my own Home Assistant setup – followed by the community must-haves worth knowing.

The HACS integrations I actually use

Huawei Solar

This is how I read my Huawei SUN2000 inverter over Modbus: power, daily yield, battery state and grid import/export all land as native Home Assistant sensors – no vendor cloud in the loop. If you run a Huawei inverter, it's the single most useful integration on this list. I wrote up the Modbus side in detail in caching a Huawei SUN2000 over Modbus.

Tapo: Cameras Control

Brings TP-Link Tapo cameras into Home Assistant as proper entities – stream, motion detection, privacy mode and more – without depending on the Tapo cloud. If you've got Tapo gear, this turns it into first-class HA devices.

ShellyForHass

The community Shelly integration. Worth being honest here: Home Assistant now ships a core Shelly integration too, so for a fresh setup you can often use that instead. I still run ShellyForHass, but check which one fits before adding it.

button-card

My go-to custom Lovelace card. button-card gives you fully templatable buttons and tiles – custom states, icons, colours and tap actions – which is what most "how did they build that dashboard?" screenshots are really made of.

Other popular HACS must-haves worth knowing

These are community favourites I'd recommend looking at, even where they aren't in my own stack:

Mushroom

A set of clean, minimal dashboard cards – the fastest way to a modern-looking Lovelace UI without hand-writing CSS.

Card Mod

Apply custom CSS to almost any card. The standard tool once you want your dashboard to look exactly your way.

mini-graph-card

Compact, good-looking history graphs for any sensor – ideal for energy, temperature and humidity at a glance.

auto-entities

Populate cards automatically by filter (area, domain, attribute) instead of maintaining entity lists by hand. A huge time-saver as your setup grows.

Frigate

Local AI object detection for cameras/NVR. If you outgrow basic camera control and want person/car detection that runs on your own hardware, this is the one.

Frequently asked questions

Are HACS integrations free?

Almost all are free and open source. The integration itself stays free even when the underlying device or service has a paid tier.

How many HACS integrations should I install?

Only the ones you'll actually use – each adds maintenance and update overhead. A handful of well-chosen integrations beats dozens of half-used ones.

Do HACS integrations update automatically?

No. HACS notifies you when an update is available; you apply it with a click and a restart. Updates aren't silent by default.

Next step

Not sure what HACS even is yet? Read What is HACS? – or if you haven't set it up, follow how to install HACS in Home Assistant.

An Open-Source SEO + GEO Audit Toolkit in Plain Node

Michael Bernhart — Sun, 14 Jun 2026 08:31:42 +0000

I run this blog on a self-hosted stack, and I like knowing exactly how healthy it is — broken links, metadata, rankings, the lot. The tools that answer those questions properly start at around $99 a month, and I mostly needed the answers once a week. So over the last few weeks I built my own: four small Node scripts, each answering one question, each producing a markdown report. Today I cleaned them up and put them on GitHub.

The result is seo-geo-audit — MIT-licensed, about 1,500 lines total, and zero npm dependencies (one exception, more on that below). Every tool is a single command, and every report is plain markdown you can read in the terminal, diff in git, or paste into an issue.

Why GEO? AI crawlers don't run your JavaScript

GEO — Generative Engine Optimization — asks whether AI answer engines like ChatGPT, Claude or Perplexity can actually read and cite your site. This stopped being theoretical for me when AI assistants started showing up as referrers in my own analytics. Those visitors are real, and they arrive because an AI read your page and linked it.

Here is the catch: most AI crawlers fetch your raw server HTML and do not execute JavaScript. Google renders your page; GPTBot, ClaudeBot and PerplexityBot mostly don't. So structured data your framework injects client-side is invisible to them, even though every SEO browser extension tells you it's fine. The same goes for metadata that streaming frameworks flush into the body instead of the initial head — Google relocates it, a JS-less crawler misses it. My own site had six pages doing exactly that, and I only know because the crawler flags it as its own issue category.

The four tools

seo-audit crawls your sitemap, then every internal link and image target, and analyzes the raw server HTML — deliberately the JS-less view. It covers the classic checks (titles, descriptions, canonicals, hreflang, Open Graph, broken links with redirect-chain resolution, sitemap hygiene) plus the GEO set: client-side-only JSON-LD, metadata streamed to the body, heading-outline gaps, thin content, llms.txt presence, and AI crawlers blocked in robots.txt.

seo-audit/run.sh https://your-site.com

perf-audit is the one tool with a dependency — it drives a real browser via Playwright. It measures lab Core Web Vitals (LCP, CLS, FCP, TTFB, TBT) against Google's thresholds, pulls real-user CrUX field data including INP through the free PageSpeed Insights API, tracks a performance budget per page, and — most usefully — captures the post-hydration DOM so you can diff what Google sees against what AI crawlers see.

gsc-fetch talks to the Search Console API and computes the two lists a solo operator actually acts on: striking-distance queries (position 5–20 with real impressions — one title tweak from page 1) and low-CTR winners (already top 5, earning fewer clicks than the position implies, with an estimate of the clicks left on the table). That second list is literally my editorial backlog now.

umami-fetch pulls a self-hosted Umami v3 instance: traffic channels, top pages, custom events, UTM campaigns — and a datacenter-adjusted totals row, because one datacenter country turned out to be a third of my “visits” before I started subtracting it. Umami's API only filters by equality, so the tool fetches the suspect countries separately and does the math.

What it found on my own site

Eating my own dog food was sobering: six pages with metadata invisible to JS-less crawlers, eighty meta descriptions over the length limit, a broken internal link target I had missed for weeks, bot traffic inflating my visitor numbers by half, and a brand query ranking #1 with a 0% click-through rate. None of this was visible in any single dashboard I had. An audit you can re-run in thirty seconds is much harder to ignore than a subscription you check monthly.

Philosophy

One command, one markdown report. No build step, no config file with eighty options, no platform. Plain Node scripts you can read in one sitting and edit to your needs — sharp little knives, not a Swiss army knife. If a check doesn't apply to your stack, delete it; it's your copy.

FAQ

Is it free?

Yes — MIT license, no paid tier. The only optional costs are third-party APIs: PageSpeed Insights is free with a Google API key, Search Console is free, and backlink data is the one thing that genuinely has no free source (the tool plugs into a paid provider if you have one, and says so honestly if you don't).

What exactly is GEO?

Generative Engine Optimization: making your content readable, parseable and citable for AI answer engines. In practice it overlaps heavily with technical SEO — the difference is the renderer. AI crawlers read raw HTML, so anything that only exists after JavaScript runs does not exist for them.

Do I need API keys?

The crawler needs nothing — clone and run against any site. PageSpeed field data needs a free Google API key, Search Console needs a one-time OAuth flow (the kit includes a dependency-free helper that mints the refresh token), and the analytics tool needs your own Umami login.

Get it

git clone https://github.com/lireking/seo-geo-audit
cd seo-geo-audit
seo-audit/run.sh https://your-site.com

That's all there is to it — the repo is at github.com/lireking/seo-geo-audit. If it flags something on your site that it shouldn't (or misses something it should catch), open an issue. PRs welcome — the scope stays small on purpose.

How to Install HACS in Home Assistant – Step by Step

Michael Bernhart — Thu, 11 Jun 2026 13:17:41 +0000

Want to use custom integrations, themes, or dashboard cards that aren't in Home Assistant's default catalog? Then you need HACS – the Home Assistant Community Store. (For what HACS actually is, see What is HACS?.) HACS is the first thing I set up on every fresh Home Assistant instance – most of my own setup, from KNX automations to PV monitoring, relies on integrations that only exist there. This guide walks you through installing HACS step by step – from download to GitHub authorization to your first integration.

Prerequisites

A running Home Assistant installation. You need to know which type you run (HAOS/Supervised vs. Container/Core) – the install method differs.

Container / Core: terminal access to the config directory. HAOS / Supervised: no terminal needed.

A free GitHub account – HACS loads its integrations through GitHub.

Install HACS step by step

1. Download HACS

HAOS / Supervised (the most common setup): go to Settings → Add-ons → Add-on Store → ⋮ (top right) → Repositories, and add https://github.com/hacs/addons. Then install the Get HACS add-on, start it, and follow the instructions in the add-on logs.

Container / Core: run the official installer inside your Home Assistant config directory:

wget -O - https://get.hacs.xyz | bash -

2. Restart Home Assistant

Go to Settings → System → Restart. Home Assistant only detects the new integration after a restart.

3. Add the HACS integration

Go to Settings → Devices & Services → Add Integration and search for HACS. Important: HACS only shows up after you clear your browser cache or do a hard refresh – this is the most common "HACS doesn't appear" cause. Then acknowledge the statements and submit.

4. Authorize with GitHub and finish

HACS uses a GitHub device OAuth flow: copy the device code it shows, open github.com/login/device, sign in, enter the code, and authorize HACS. Back in Home Assistant, assign HACS to an area and select Finish.

5. Install your first integration

HACS now appears in your sidebar. Open it, browse the available integrations, install one, and restart Home Assistant. That's it.

Common problems

HACS doesn't appear in the integration list: clear your browser cache or hard-refresh (officially the most common cause), and double-check you restarted Home Assistant.

HACS stays empty: the GitHub authorization (step 4) was skipped.

GitHub rate limit: wait a few minutes and run the authorization again.

Frequently asked questions

Is HACS free?

Yes – HACS is open source and completely free.

Do I need a GitHub account?

Yes – HACS loads its integrations through GitHub, so a free account is required.

Does HACS work with Home Assistant Container or Core?

Yes – the one-line installer works on all installation types. On HAOS, the Get HACS add-on is the easiest route.

How do I update HACS integrations?

HACS shows available updates directly in its panel; a single click plus a restart is enough.

Next step

HACS is up and running. Next, learn what HACS is and why it's a must-have for every Home Assistant user in What is HACS?.

Why the Home Assistant Community Store (HACS) is a Must-Have for Every HA User

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

For my first few months with Home Assistant I stuck to the built-in integrations and wondered why everyone online had dashboards and devices I just couldn't find. The answer was HACS — the Home Assistant Community Store. It's the one add-on that unlocks the huge ecosystem of community integrations, cards and themes that aren't in core, and it's the first thing I install on any fresh HA setup now. Here's what HACS is, why it matters, and how it changed the way I run my smart home.

Home automation is all about customization and flexibility. For those using Home Assistant, the open-source platform for managing your smart home, you likely already appreciate its powerful integrations and ability to grow alongside your needs. But even with its extensive core capabilities, there’s a way to unlock even more potential: the Home Assistant Community Store (HACS).In this story, we’ll explore HACS, why it’s a game-changer, and how to get started with it.

What Is HACS?

HACS — the Home Assistant Community Store — is a free, open-source add-on that lets you discover, install, and update community-built integrations, themes, dashboard cards, and automations inside Home Assistant, all from one place. It isn’t part of Home Assistant by default and isn’t an official add-on store; think of it as a community-run “app store” that fills the gap between Home Assistant’s built-in integrations and the thousands of custom ones the community maintains on GitHub.

Why Use HACS?

Here are a few compelling reasons to add HACS to your Home Assistant setup:

1. Expand Home Assistant’s Capabilities

Home Assistant already supports many devices and services, but HACS takes it further by introducing custom integrations. For instance:

Want to integrate niche smart devices or APIs not officially supported? HACS has got you covered.
Do you need a new feature, like advanced analytics or a custom card for your dashboard? HACS is where you’ll find it.

2. Stunning Custom Dashboards

Home Assistant’s Lovelace UI is flexible out of the box, but HACS brings a treasure trove of custom Lovelace cards and themes. With these, you can build sleek, visually appealing dashboards tailored to your preferences.

3. Community-Driven Innovation

The Home Assistant community is packed with talented developers, and HACS is the go-to platform for their creations. You’ll often find cutting-edge integrations or solutions to common challenges here before they’re available in the core platform.

4. Seamless Updates

HACS makes managing custom components simple. With its intuitive interface, you can:

Install new integrations in a few clicks.
Receive notifications when updates are available.
Update integrations directly within the Home Assistant UI.

5. Completely Open Source

True to Home Assistant’s ethos, HACS is 100% open source, ensuring transparency and fostering a collaborative ecosystem.

Popular HACS Integrations and Plugins

Some standout offerings available through HACS include:

Mini Graph Card : Create beautiful graphs for temperature, power usage, and more.
Lovelace Auto-Entities : Dynamically display entities on your dashboard based on filters.
Garbage Collection : Stay on top of your trash and recycling schedule.
Custom Animated Weather Cards : Add visually stunning weather widgets.
UI Themes : Transform the look and feel of your Home Assistant interface with themes like “Dark Mode” or “Google Material Design.”

How to Install and Use HACS

Installing HACS is straightforward, but it requires a few steps. Here’s a quick guide to get you started:

1. Prepare Home Assistant

Before you begin, ensure you’re running Home Assistant Core on a supported platform like Docker, a Raspberry Pi, or a virtual machine.We will continue with the docker installation, which was done in the first step.

How to install Homeassistant via Docker on an Azure Linux VM

2. Install HACS

HACS installation is best done via Home Assistant’s CLI:

Official Documentation: https://hacs.xyz/docs/use/configuration/basic/#to-set-up-the-hacs-integration

SSH into your Home Assistant setup.
Change to your config-volume, which in our case is mounted under /home/xxxUserDirxxx/homeassistant
Run the following command to install HACS:

curl -sfSL https://get.hacs.xyz | bash -

3. Integrate HACS with Home Assistant

Once installed, restart Home Assistant.

Navigate to Settings > Integrations in the Home Assistant UI.

Search for “HACS” and follow the on-screen instructions to complete setup.
Follow this detailed how-to for the final steps ->

4. Start Exploring

After setup, HACS will appear in your sidebar. Browse and install custom integrations, themes, and plugins with just a few clicks.

As you can see, I needed the integration “Fusion Solar” to connect my Huawei PV-Solution, and I installed the “Mobile App” as well. The next step will be installing the KNX/EIB solution so that I can interact with my home.

Frequently Asked Questions about HACS

What is HACS in Home Assistant?

HACS (Home Assistant Community Store) is a community-maintained store for installing and updating custom integrations, themes, and Lovelace cards that aren’t in Home Assistant’s official integration list.

Is HACS official or safe to use?

HACS isn’t an official Home Assistant project, but it’s widely used and open source. The integrations you install through it are community-made, so review a repository’s popularity and source before installing — just as you would with any third-party software.

Do I need HACS for Home Assistant?

No — Home Assistant works fully without it. You only need HACS once you want a custom integration, theme, or dashboard card that isn’t available in the built-in catalog.

How do I install HACS?

The quickest way is the official one-line installer run from your Home Assistant CLI, then adding HACS as an integration and authorizing it with a GitHub account. See the step-by-step section above.

What are the must-have HACS integrations?

Popular picks include custom Lovelace cards such as Mushroom and mini-graph-card, the Card Mod and Browser Mod tools, and device-specific integrations the core doesn’t ship — see the “Popular HACS Integrations” section above.

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

Caching a Huawei SUN2000 over Modbus for Home Assistant

Michael Bernhart — Mon, 08 Jun 2026 18:06:57 +0000

My Huawei SDongle accepts exactly one Modbus connection at a time — but Home Assistant, my AC·THOR and evcc all want to read the inverter at once. Polling it from three clients just gave me dropped connections and gaps in my data. So I wrote a small asyncio cache server (~300 lines) that does one quiet poll of the SUN2000 and serves every client from that cached snapshot. Here's how it works, and the full code.

The fault that finally pushed me into writing my own Modbus server wasn't dramatic. It was a hole. Every evening, right around the time the boiler heater kicked in, my energy dashboard in Home Assistant would flatline for a few minutes and then snap back. Not a crash — just a gap, the kind you stop noticing until you're squinting at a graph trying to work out where 0.4 kWh went.

One connection, and everyone wants it

I run a Huawei SUN2000-8KTL-M1 with a LUNA2000 battery. The inverter talks to the outside world through a little SDongle, and the SDongle speaks Modbus TCP on port 502. The catch — and it's one a lot of Huawei owners walk straight into — is that the SDongle accepts exactly one Modbus TCP connection at a time.

And I had four things that wanted it: Home Assistant's Huawei Solar integration for the dashboard, the AC·THOR 9s that dumps PV surplus into the hot-water boiler and needs a live meter reading to modulate, evcc for the wallbox, and the FusionSolar cloud. FusionSolar is the lucky one — it rides its own channel up to Huawei's servers and never touches Modbus. The other three were elbowing each other off the single slot. Whoever connected last won; the rest got connection resets, and the dashboard got that flatline.

First fix: a transparent proxy

The obvious answer is a proxy: one process holds the single connection to the SDongle, every client talks to the proxy instead. I started with the ha-modbusproxy add-on — point it at the SDongle, have it listen on 5502, repoint Home Assistant and the AC·THOR there.

It worked. For a while. But a transparent proxy still forwards every client's read straight through to the inverter, and that surfaced a subtler problem. Modbus TCP tags each request with a transaction id, and several clients sharing one upstream connection don't coordinate those ids. Under load you can get a client receiving a response meant for someone else's request, decoding it, and quietly believing the battery sits at 7% when it's really at 70%. Rare — but wrong in the worst possible way, because it's silent.

The fix that stuck: stop talking to the inverter

So I stopped letting the clients talk to the inverter at all. Instead of forwarding reads, I poll the SDongle myself, once, on a schedule, cache every register I care about, and serve all the clients out of that cache. It's about 300 lines of asyncio Python, it runs as a systemd service on port 5502, and the inverter only ever sees one polite reader.

The reader side is a list of register batches and a loop:

REGISTER_BATCHES = [
    (32106, 2), # cumulative energy yield (uint32)
    (32114, 2), # daily energy yield
    (37113, 2), # active grid power (int32)
    (37760, 1), # battery SOC
    (37765, 2), # battery power (int32)
    # ...thirteen batches in total
]

# one connection, walk every batch 50 ms apart, then sleep 10 s
for start, count in REGISTER_BATCHES:
    values = await read_batch(reader, writer, start, count)
    for i, v in enumerate(values):
        register_cache[start + i] = v

Each batch is a plain function-code-3 read. I keep 50 ms between them so I'm not rushing a device that's slower than a normal Modbus meter, and the whole sweep repeats every ten seconds. That's the only conversation the SDongle ever has.

Serving the clients from cache

The server side speaks just enough Modbus to be useful. A read never touches the inverter — it's answered straight from the dict, and crucially I build the response against the calling client's own header, so the transaction-id problem simply cannot happen:

if fc == 3: # read holding registers — served from cache, never the inverter
    reg_addr, reg_count = struct.unpack(">HH", pdu[1:5])
    values = [register_cache.get(reg_addr + i, 0) for i in range(reg_count)]
    resp_pdu = struct.pack(">BB", fc, reg_count * 2)
    resp_pdu += struct.pack(">" + "H" * reg_count, *values)
    # built against THIS client's own header → no transaction-id mix-ups
    resp_header = struct.pack(">HHHB", tx_id, 0, len(resp_pdu) + 1, unit_id)
    client_writer.write(resp_header + resp_pdu)

Writes are the exception. A write (function code 6) is usually battery control — telling the inverter to charge or discharge — and that has to reach real hardware, so I forward those straight to the SDongle and pass the result back. Reads are cached, writes are real. That one split is the whole design.

What it actually bought me

The part I didn't expect to enjoy this much is the decoupling. A client's poll rate is now completely independent of the inverter's. Home Assistant can ask every five seconds, the AC·THOR every second, evcc whenever it feels like it — and the SDongle still sees exactly one reader, once every ten. The flatline is gone, and the AC·THOR hasn't lost its meter value since.

It also gave me a clean place to hang the numbers I actually care about. On top of those cached registers I built a handful of template sensors: self-consumption sitting around 65.9% , autarky 76.9% , the battery turning in 97.2% round-trip efficiency. Those are exactly the figures the FusionSolar app never quite shows you in one place — and they're the subject of the next part.

The honest gotcha

A cache can go stale, and an energy dashboard that lies confidently is worse than one with an honest gap. If the SDongle drops — a firmware reboot, a flaky switch — the reader loop keeps failing and the cached values quietly age. So I log it: once the cache is older than 120 seconds a warning fires, and the retry backs off instead of hammering a device that isn't answering. Clients keep getting the last-known value, which for a power graph is the right failure mode — a held line beats a hole — but you do want to know when it's happening.

If you run Home Assistant on a VM like I do — I wrote earlier about getting it onto an Azure Linux box — dropping a 300-line Python service next to it costs almost nothing, and it's been the single most stable part of my solar setup ever since. Next part: turning those cached registers into the autarky and self-consumption numbers that actually tell you whether the battery was worth buying.