iobroker.homewizard
v0.9.3
Published
ioBroker adapter for HomeWizard Energy devices with API v2
Readme
ioBroker.homewizard
Real-time energy monitoring for HomeWizard Energy devices with API v2.
Features
- HomeWizard API v2 — HTTPS + WebSocket, bearer-token authentication
- mDNS pairing —
_homewizard._tcpdiscovery, press the device button to pair - WebSocket push — measurements arrive ~1/s; REST polling takes over while the WebSocket reconnects
- Plug-In Battery control — charge/discharge mode and grid-feed permissions through the paired P1/kWh meter
- Adaptive reconnect — devices with weak WiFi switch to a faster reconnect interval and keep REST polling running so data keeps flowing
- Encrypted device tokens — stored per device object, no adapter restart on pairing or removal
Requirements
- Node.js >= 22
- ioBroker js-controller >= 7.0.7
- ioBroker Admin >= 7.8.23
- HomeWizard device with API v2 support (firmware 4.x+ with local API enabled)
Supported Devices
| Device | Product Type | | ----------------- | ------------------------------ | | P1 Meter | HWE-P1 | | kWh Meter 1-Phase | HWE-KWH1 (also sold as SDM230) | | kWh Meter 3-Phase | HWE-KWH3 (also sold as SDM630) | | Plug-In Battery | HWE-BAT |
The Plug-In Battery is paired separately and shows up as its own device. To control charge/discharge mode and grid-feed permissions, you write to the battery.* data points of the P1 or kWh meter — that's where HomeWizard exposes the battery commands.
Configuration
Prerequisites
The local API must be enabled on your HomeWizard device:
- Open the HomeWizard app on your phone
- Go to Settings > Meters > select your device > Local API > Enable
Adding a device (automatic via mDNS)
- Go to the Objects tab in ioBroker Admin
- Set
homewizard.0.startPairingtotrue - Press the physical button on your HomeWizard device within 60 seconds
- The device is discovered automatically and appears under
homewizard.0
Adding a device (manual IP)
If mDNS is not available (e.g. different VLAN, Docker, or firewall blocking multicast):
- Set
homewizard.0.pairingIpto the IP address of your device - Set
homewizard.0.startPairingtotrue - Press the physical button on the device within 60 seconds
Managing devices
All paired devices are listed in the Objects tab under homewizard.0. Each device has its own folder (e.g. hwe-p1_5c2fafaabbcc) with measurement data, system settings, and device info.
- Remove a device: Set its
removedata point totrue— the device and all data points are deleted immediately - IP changes: Detected automatically — after 3 failed reconnects, mDNS searches for the new IP. If not found, the device is marked offline
State Tree
homewizard.0.
├── info.connection — Overall connection status (bool)
├── startPairing — Activate pairing mode (button)
├── pairingIp — Device IP for manual pairing (string)
└── {productType}_{serial}/ — e.g. hwe-p1_5c2fafaabbcc
├── info/
│ ├── productName — Device name (string)
│ ├── productType — Product type (string)
│ ├── firmware — Firmware version (string)
│ ├── connected — WebSocket connection status (bool)
│ ├── wifi_rssi_db — WiFi signal strength (number, dBm)
│ └── uptime_s — Device uptime (number, s)
├── measurement/ — Measurement data
│ ├── power_w — Total power (number, W)
│ ├── power_l1_w .. l3_w — Power per phase (number, W)
│ ├── voltage_v — Voltage single-phase (number, V)
│ ├── voltage_l1_v .. l3_v — Voltage per phase (number, V)
│ ├── current_a — Current single-phase (number, A)
│ ├── current_l1_a .. l3_a — Current per phase (number, A)
│ ├── frequency_hz — Grid frequency (number, Hz)
│ ├── energy_import_kwh — Total import (number, kWh)
│ ├── energy_import_t1..t4_kwh — Import per tariff (number, kWh)
│ ├── energy_export_kwh — Total export (number, kWh)
│ ├── energy_export_t1..t4_kwh — Export per tariff (number, kWh)
│ ├── tariff — Active tariff (number)
│ ├── state_of_charge_pct — Battery charge level (number, %)
│ ├── cycles — Battery charge cycles (number)
│ ├── average_power_15m_w — 15-min average power (number, W, Belgium)
│ ├── monthly_power_peak_w — Monthly power peak (number, W, Belgium)
│ ├── monthly_power_peak_timestamp — Monthly peak timestamp (string)
│ ├── meter_model — Meter model identifier (string)
│ ├── timestamp — Measurement timestamp (string)
│ ├── quality/ — Power quality counters
│ │ ├── voltage_sag_l1..l3_count
│ │ ├── voltage_swell_l1..l3_count
│ │ ├── power_fail_count
│ │ └── long_power_fail_count
│ └── external/ — External meters (gas, water, heat)
│ └── {type}_{id}/
│ ├── value — Meter reading (number)
│ ├── unit — Unit (string)
│ └── timestamp — Last update (string)
├── battery/ — Battery control (if batteries connected)
│ ├── mode — zero / to_full / standby (string, R/W)
│ ├── permissions — JSON array (string, R/W)
│ ├── battery_count — Connected batteries (number)
│ ├── power_w — Battery power (number, W)
│ ├── target_power_w — Target power (number, W)
│ ├── max_consumption_w — Max consumption (number, W)
│ └── max_production_w — Max production (number, W)
├── remove — Remove device (button)
└── system/ — System settings
├── cloud_enabled — Cloud communication (bool, R/W)
├── status_led_brightness_pct — LED brightness 0-100 (number, R/W)
├── api_v1_enabled — Toggle the device's deprecated v1 API (bool, R/W — leave off)
├── reboot — Reboot device (button)
└── identify — Blink LED (button)States are created dynamically based on what the device reports. Not all devices have all states. kWh meters additionally provide apparent/reactive current, apparent/reactive power, and power factor states.
Troubleshooting
Device not found during pairing
- Make sure the device is on the same network/VLAN as the ioBroker server
- Verify that local API is enabled in the HomeWizard app (Settings > Meters > your device > Local API)
- Check that multicast/mDNS traffic is not blocked by your router/firewall
WebSocket keeps disconnecting
- Check
info.wifi_rssi_db— above -75 dBm is comfortable, weaker than -85 dBm explains frequent drops - For devices with weak WiFi the adapter switches to a faster reconnect interval (60 s instead of 5 min) and keeps REST polling in the background so you don't lose data
- A WebSocket-layer ping/pong heartbeat (~30 s ping, 10 s pong window) catches half-dead links where the TCP stream is buffered but the device has stopped responding. Such links are torn down and reconnected automatically — you no longer end up with a stale "connected" status while measurement values stop updating.
- IP changes are picked up via mDNS — no manual reconfiguration needed
Token invalid after factory reset
- Set the device's
removedata point totrue, then pair again
Changelog
0.9.3 (2026-05-23)
- User-modified device names are no longer overwritten on adapter restart or IP recovery.
- Improved timer management for ioBroker compact mode.
0.9.2 (2026-05-23)
- Changelog rewritten in user-centric style across all versions.
0.9.1 (2026-05-23)
- Internal cleanup. No user-facing changes.
0.9.0 (2026-05-22)
- User-modified state names are no longer overwritten on adapter restart
0.8.3 (2026-05-21)
- Improved error handling and stability.
Older entries are in CHANGELOG_OLD.md.
Support Development
This adapter is free and open source. If you find it useful, consider buying me a coffee:
License
MIT License
Copyright (c) 2026 krobi [email protected]
Permission is hereby granted, free of charge, to any person obtaining a copy of this software and associated documentation files (the "Software"), to deal in the Software without restriction, including without limitation the rights to use, copy, modify, merge, publish, distribute, sublicense, and/or sell copies of the Software, and to permit persons to whom the Software is furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
Developed with assistance from Claude.ai