Real-time energy data from HomeWizard Energy devices over the local API v2.

Requirements

A HomeWizard device that speaks API v2: P1 Meter (HWE-P1), kWh Meter 1-phase (HWE-KWH1 / SDM230) or 3-phase (HWE-KWH3 / SDM630), Plug-In Battery (HWE-BAT).
Firmware with the local API v2 (see HomeWizard's compatibility list). Nothing has to be switched on in the HomeWizard app for it: the "Local API" switch there belongs to the old v1 API and should stay off.
Node.js >= 22, js-controller >= 7.2.2, Admin >= 8.0.11.

Energy Socket, Watermeter and Energy Display speak only the deprecated v1 API. They are out of scope and will not be added.

Adding a device

The adapter has no device table in its settings — devices live in the object tree and are added by pressing the button on the device itself.

With automatic discovery (normal case)

Open the Objects tab and set homewizard.0.startPairing to true.
Within 60 seconds, press the physical button on the HomeWizard device (kWh Meter: hold it for 1–3 seconds).
The device appears under the instance with its own folder.

The window stays open for the full 60 seconds, so several devices can be added in one go.

With a fixed IP address — for networks where mDNS does not get through (a separate VLAN, Docker without host networking):

Write the device's IP address into homewizard.0.pairingIp.
Then set homewizard.0.startPairing to true and press the button on the device.

What you get

Each device gets a folder named <product type>_<serial>. The folder shows the product name the device reports (e.g. "P1 Meter") — the HomeWizard API does not provide the name you give the device in the app. Log lines name the device as P1 Meter (hwe-p1_5c2fafaabbcc), so two devices of the same type can be told apart. The folder contains:

Folder	Contents
`info`	Product name and type, firmware, WiFi network and signal strength, uptime, connection state
`measurement`	Power, voltage, current, frequency, energy totals per tariff, timestamps
`measurement.quality`	Voltage sags and swells, power failure counters (P1 only)
`measurement.external`	Gas, water and heat meters that report through the P1 meter; a meter that has not been reported for a day (after a replacement, for example) is removed
`system`	Cloud connection, status LED brightness (not on the kWh Meter), legacy v1 API and reboot (not on the Plug-In Battery), identify (not on the kWh Meter)
`battery`	Charge mode, permissions, target power and counters — on the meter the battery is paired with

remove deletes a device including all of its data points.

Connection states

<device>.info.connected — true while the device answers the adapter. That includes the fallback polling, not just the real-time connection.
info.connection — true while at least one device answers.
info.devicesTotal / info.devicesOnline / info.devicesAllOnline — how many devices are set up and how many of them answer. devicesTotal keeps its value when the adapter is stopped.

Measurements normally arrive as a push about once per second. If that connection drops, the adapter polls over HTTPS instead (every 10 seconds, every 30 for a device with a weak signal) while it reconnects in the background, so the data keeps flowing.

Controlling a Plug-In Battery

The battery is paired as its own device, but the controls sit on the P1 or kWh meter it works with — that is where HomeWizard exposes them:

battery.mode — zero (keeps the home at net zero, charging or discharging to do so) or predictive. HomeWizard marks to_full and standby as legacy: use charge_to_full and permissions instead.
battery.power_w / battery.target_power_w — positive means charging, negative means discharging.
battery.charge_to_full — charge to 100 % once.
battery.permissions — a JSON array, written as text.

predictive and charge_to_full need a recent battery firmware (API 2.3.0). Older firmware rejects them and the value is not applied.

When something does not work

Pairing does not find the device. mDNS often does not cross VLANs or Docker bridges. Use the fixed-IP path above.

Pairing fails right after the button press. The adapter revokes the token it was issued and asks you to try again. On a kWh Meter, hold the button for 1–3 seconds; a short press is not enough.

A device shows as not connected. The adapter never gives up: it retries the real-time connection with growing intervals (up to 5 minutes), searches for a changed IP address via mDNS about once an hour, and switches to a faster rhythm for devices it recognises as having a weak signal. A meter in a cellar hallway can be gone for hours; nothing needs to be done for it to come back.

"token invalid — re-pair device to fix". The device no longer accepts the adapter's token, usually after a factory reset. Pair it again (startPairing and the button, with pairingIp if mDNS does not reach it) — the adapter accepts a device whose token no longer works, and the existing data points are kept.

Log lines about the bundled certificate expiring. The adapter carries the HomeWizard CA certificate to verify device certificates. Well before it expires, an adapter update will ship a fresh one.

Privacy and security

Device tokens are stored encrypted in the device object, never in the adapter configuration.
The adapter verifies each device's certificate against its known identity, so it will not talk to a different device that happens to hold a HomeWizard certificate.
Removing a device also revokes the adapter's token on the device itself.
Every ioBroker system and instance signs in on the device under its own name, so a test and a production system can share a meter.
Turning on system.api_v1_enabled re-enables the old v1 API on the device. That API has no encryption and no token — anyone on the network can then read and control the device. The adapter warns when you do it.

Changelog

0.20.0 (2026-09-24) — stable

Fixed: on Node.js 26 a device no longer stops updating for good after an oversized or interrupted reply from it — the adapter now gives up on that reply and carries on.
Changed: the device folder keeps the product name the device reports; the HomeWizard API does not provide the name you give the device in the app, so renaming it there does not reach ioBroker.
Fixed: writing the text "false" into cloud_enabled, api_v1_enabled or charge_to_full switched it on, and writing false to reboot restarted the device — values are now read strictly.
Fixed: the battery descriptions now say that positive power means charging and that the zero mode charges or discharges to keep your home at net zero.
Fixed: the setup notes no longer ask for the Local API switch in the app, which belongs to the old v1 API, and tell you to hold the button of a kWh Meter for 1–3 seconds.
Fixed: another program using the network search port no longer stops the adapter; it says so and points you to pairing the device by its IP address instead.
Fixed: a device that answers while the adapter restores its live connection no longer flips between online and offline with every attempt.
Fixed: a device showing "token invalid" can be paired again by pressing its button, and a second device that needs a new address during a running search is found as well.
Changed: a kWh Meter no longer shows an identify button or an LED brightness setting — the device has neither, and pressing them only ever failed.
Fixed: one device whose stored entry is damaged no longer stops the other devices from starting — they come up and update as usual.
New: every ioBroker system and instance pairs under its own name on the device, so a test and a production system can use the same meter side by side.
New: a gas, water or heat meter the P1 Meter has not reported for a day is removed together with its data points, instead of keeping its last reading forever.
Improved: when the pairing window closes, the adapter tells you how many devices were paired, or that none was found and what to try next.
Fixed: when a different device answers at a paired device's address, the adapter now tells you that the address has probably changed.
Fixed: the battery folder is removed completely when no battery is connected any more, including entries that had lost their folder.
Improved: the WiFi signal strength is marked as a signal strength value, so visualisations and other adapters recognise it correctly.

0.19.0 (2026-09-15) — stable

Fixed: a device that changed its IP address is found again — the reply to the adapter's own network search was discarded, leaving the device unreachable until it was paired anew.
Fixed: removing a device now really withdraws its access on the device itself — the request was cut off before it left, so the adapter's user stayed behind on every device removed so far.
Fixed: a device that is re-paired while the adapter is still working with the old connection keeps its new access token — that work could overwrite it and leave the device unusable.
Improved: pairing now says once per device why it is not getting anywhere — a wrong address or a device without the local API used to fail silently until the window closed.
Fixed: a device that does not manage batteries no longer keeps a battery folder — leftover entries from an earlier version are cleared the first time the device says it has none.
Fixed: data points the adapter removes during a start no longer reappear empty a moment later, which left nameless leftovers in the tree that nothing ever cleaned up again.
Improved: a setting the device refuses is corrected in the tree at once — it used to keep showing the requested value for up to a minute before the next check put it right.
Fixed: the name of a gas, water or heat meter folder now also reaches installations whose meter has been quiet since the update, instead of only the entries below it.
New: every device now shows a pictogram of its type in the object tree — a meter, a three-phase meter or a battery — drawn to read on the light and the dark theme alike.
Changed: a device now carries the name it has in the HomeWizard app; renaming it there reaches the object tree, and a rename made in the tree is put back at the next check.

0.18.2 (2026-09-06)

Fixed: a device the adapter could not read the stored token for can be removed again — its remove data point did nothing at all, and the device stayed in the tree for good.
Fixed: renaming a device in the HomeWizard app now updates its info.productName data point; until now the new name showed up nowhere until the adapter was restarted.
Fixed: the firmware version keeps up with a device that updates itself, instead of showing the version from the last adapter start.
Fixed: a button falls back to "not pressed" even when the device cannot be reached, so it stays clickable instead of staying stuck.
Changed: a device entry that is damaged or unreadable is now reported in the log instead of disappearing without a word.

0.18.1 (2026-09-04)

Fixed: corrected data point names now also reach devices that are currently offline — until now they waited for the device to answer again, which for a meter with a weak signal could mean never.
Changed: the object tree no longer holds the info.legacyMigrated data point, which never carried any information about your devices or their readings.

0.18.0 (2026-09-04)

Fixed: a device that keeps answering while its push connection is down is no longer shown as not connected — the status describes the device now, not one connection type.
Fixed: WiFi signal strength and uptime keep updating for such a device instead of freezing at the values from before the drop.
Fixed: corrected names and descriptions now reach installations that already exist — until now they only ever arrived on fresh ones.
Fixed: sending a message to the adapter works again — a leftover setting from an earlier version blocked every message silently, with nothing about it in the log.
Fixed: a device with no usable IP address is reported at start-up and searched for, instead of staying quietly dead until the next restart.
Fixed: the reboot and identify buttons reset themselves even when the command fails, so they no longer stay pressed in Admin.
Fixed: the battery data points are removed once the meter reports that no battery is connected any more, instead of showing its last values forever.
New: the data points under info explain what they mean in all eleven languages, and a user guide is now part of the documentation portal.
Changed: for security, an address announced over the network is only accepted when it belongs to a private range, so pairing can no longer be directed at a host outside your own network.

License

MIT License

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