Reliability overhaul: HA 2026.7 + firmware >= 5.1.10 compatibility, event-loop-safe I/O

.github/workflows/quality.yml

@@ -0,0 +1,27 @@
+name: Quality
+
+on:
+  push:
+  pull_request:
+  workflow_dispatch:
+
+jobs:
+  python:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.12"
+      - name: Install test tools
+        run: python -m pip install ruff
+      - name: Ruff
+        run: |
+          ruff check .
+          ruff format --check .
+      - name: Tests
+        run: |
+          python -m unittest discover -s tests
+          python -m compileall -q custom_components tests
+      - name: Frontend syntax
+        run: node --check custom_components/bituopmd/www/bituo_panel.js

.github/workflows/validate.yml

@@ -11,7 +11,7 @@ jobs:
   validate-hacs:
     runs-on: "ubuntu-latest"
     steps:
-      - uses: "actions/checkout@v3"
+      - uses: "actions/checkout@v4"
       - name: HACS validation
         uses: "hacs/action@main"
         with:

.gitignore

@@ -1,2 +1,10 @@
 # Ignore macOS .DS_Store files
 .DS_Store
+
+# Python and test artifacts
+__pycache__/
+*.py[cod]
+.pytest_cache/
+.ruff_cache/
+.coverage
+.venv/

README.md

@@ -1,98 +1,121 @@
-# Bituo Device for Home Assistant
+# BituoPMD for Home Assistant
 
-## Installation
+An optimized fork of
+[`script0803/BituoPMD`](https://github.com/script0803/BituoPMD) for Bituo
+SPM/SDM power monitoring devices.
 
-### Install with HACS 
+This fork keeps the original `bituopmd` integration domain, config-entry data,
+device identifiers, and entity unique IDs. It can replace V1.0.4 without
+re-adding devices or changing existing entity IDs.
 
-[![Open BituoPMD inside your Home Assistant Community Store (HACS).](https://my.home-assistant.io/badges/hacs_repository.svg)](https://my.home-assistant.io/redirect/hacs_repository/?owner=Script0803&repository=bituopmd&category=integration) 👈Click this button to install.(Recommended)
+## What is improved
+
+- One shared coordinator per device instead of separate sensor and switch
+  polling loops.
+- Fully asynchronous HTTP through Home Assistant's shared client.
+- A five-second timeout on every device request so an offline meter cannot
+  stall startup or reload.
+- Clean unload behavior with no orphaned background tasks.
+- Polling interval stored in the Home Assistant config entry instead of a JSON
+  file inside `custom_components`.
+- Native options and reconfigure flows for polling interval and IP changes.
+- Missing data returns `unavailable`, never a fabricated zero.
+- Correct HA units and classes, including RSSI in dBm and current-unbalance as
+  a percentage rather than a power factor.
+- Reliable three-phase totals derived when current firmware omits them:
+  current, average current, average line-to-neutral voltage, active/reactive/
+  apparent power, forward energy, and reverse energy.
+- Secured compatibility panel: administrator-only configuration actions,
+  configured devices only, explicit action allowlists, and bounded requests.
+- HACS, hassfest, Ruff, syntax, and unit-test workflows.
 
-1. Open HACS (Home Assistant Community Store).
-2. Navigate to Integrations.
-3. Click on the "![](/images/symbol-1.png)" button to add a new repository.
-4. Click "Custom repositories".
-5. Enter the URL of this GitHub repository.
-6. Select the "Integration" category and click "Add".
+## Supported devices
 
-### Install manually
+The upstream integration documents support for:
 
-1. Install this platform by creating a `custom_components` folder in the same folder as your configuration.yaml, if it doesn't already exist.
-2. Create another folder `bituopmd` in the `custom_components` folder. Copy all files from custom_components into the `bituopmd` folder. Do not copy files from master branch, download latest release (.zip).
+- SPM01-xxEW
+- SPM02-xxEW
+- SDM01-EWx
+- SDM02-EW
 
-## Configuration
+The optimized code is designed around the same local HTTP API and preserves
+relay support for models that advertise it.
 
-After connecting your ESP device to the network following the manual guide, We have three ways to add your ESP devices to HomeAssistant.
+## Install with HACS
 
-### Discoverd
+1. Open HACS.
+2. Open the menu and choose **Custom repositories**.
+3. Add `https://github.com/kkangg1/BituoPMD` as category
+   **Integration**.
+4. Download `BituoPMD`.
+5. Restart Home Assistant.
 
-When you add your ESP device to the same network as Home Assistant, the device will be automatically scanned and appear in the discovered list.
+To add a new device, go to **Settings → Devices & services → Add
+integration**, search for `BituoPMD`, and enter its fixed IP address. Home
+Assistant native Zeroconf discovery is also supported.
 
-![](/images/discoverd.png)
+## Replace upstream V1.0.4
 
-After clicking 'Configure,' the following dialog box will pop up. Then, click 'Submit' to add the device.
+Create a Home Assistant backup first. Then install this repository through
+HACS over the existing `custom_components/bituopmd` directory and restart Home
+Assistant. Existing entries and entity IDs are retained.
 
-![](/images/discoverd-config.png)
+After restart, verify:
 
-### Zeroconf scan
+- every BituoPMD config entry is `Loaded`;
+- metering entities update;
+- existing dashboards and automations resolve their old entity IDs;
+- the system log contains no `bituopmd` errors.
 
-1. Select 'Use Zeroconf to scan device', and click 'Submit'. The integration will start scanning for devices on the current network.
+The previous V1.0.4 component should be kept as a rollback archive until the
+new version has run successfully.
 
-![](/images/zeroconf-1.png)
+## Polling interval
 
-2. The integration will list the devices it has scanned. Select the device you want to add and proceed with the addition.
+Open the integration entry and choose **Configure**. The supported range is
+5–3600 seconds. The default remains 5 seconds for compatibility. With several
+meters, 10–30 seconds usually reduces LAN and recorder load without affecting
+normal energy dashboards.
 
-![](/images/zeroconf-2.png)
+The legacy service remains available for panel compatibility:
 
-### Manual configure
+```yaml
+action: bituopmd.set_frequency
+data:
+  device_id: 192.0.2.10
+  frequency: 15
+```
 
-1. Select 'Use IP to pair devices', and click 'Submit'.
+`192.0.2.10` is a documentation-only TEST-NET address, not a real device.
 
-![](/images/manual-1.png)
+## Privacy and security
 
-2. Enter the device's IP address into the input field. Click the submit button.
+The integration communicates directly with configured devices on the local
+network. The repository and tests contain no installation-specific IP
+addresses, serial numbers, config-entry IDs, device-registry IDs, or real
+meter readings.
 
-![](/images/manual-2.png)
+The sidebar panel can change device Wi-Fi, MQTT, Modbus, and firmware settings.
+It is therefore visible only to Home Assistant administrators. The proxy
+rejects unknown hosts and actions.
 
-## Devices supported
-- SPM01-xxEW [[More details]](https://shop.bituo-technik.com/products/esp32-wifi-energy-meter-spm01-1p-n-63a)
-- SPM02-xxEW [[More details]](https://shop.bituo-technik.com/products/esp32-wifi-energy-meter-spm02-3p-n-63a-copy)
-- SDM01-EWx  [[More details]](https://shop.bituo-technik.com/products/sdm01-ew0-energy-meter-3p-n-up-to-200a-esp32-wi-fi-ble)
-- SDM02-EW   [[More details]](https://shop.bituo-technik.com/collections/all)
+## Development
 
-## Detail information
+Run the local checks:
 
-Click on the device name to enter the details page, where you can view all the parameters measured by the device.
+```bash
+python -m compileall -q custom_components tests
+python -m unittest discover -s tests
+node --check custom_components/bituopmd/www/bituo_panel.js
+ruff check .
+ruff format --check .
+```
+
+GitHub Actions additionally run HACS and hassfest validation.
 
-![](/images/interface-1.png)
+## Attribution and licensing
 
-Clicking 'View' will redirect you to the device's embedded webpage.
-
-![](/images/interface-2.jpg)
-
-All entities can have their units adjusted according to Home Assistant's rules.
-
-![](/images/interface-3.jpg)
-
-## Device settings
-
-Once the integration is activated, you can see the entry to the settings page in Home Assistant's sidebar.
-
-![](/images/UI-1.jpg)
-
-On this page, you can adjust all the settings of the device, as well as access other functions like Zero Energy, Restart, Erase Factory, and OTA.
-
-![](/images/UI-2.jpg)
-
-Click the dropdown menu at the top to select the device you want to configure.
-
-![](/images/UI-3.png)
-
-## Device OTA
-The device's parameter page will display the OTA status. When 'OTA available' is shown, please proceed to the embedded web page or the integration's settings page to perform the OTA.
-
-![](/images/OTA-2.jpg)
-
-![](/images/OTA-3.jpg)
-
-If 'Up to date' is displayed, it means the device is already on the latest version and no OTA is required.
-
-![](/images/OTA-1.png)
+This repository is a fork of the work by
+[`@Script0803`](https://github.com/script0803). The upstream repository does
+not currently include a license file. No new license is asserted by this
+fork; upstream authorship and applicable rights remain unchanged.