Skip to content

fquinto/pywibeee

BranchesTags

Repository files navigation

pywibeee

Python library, CLI, and Home Assistant integration for WiBeee (old Mirubee) energy meters manufactured by Smilics / Circutor.

Table of Contents

Home Assistant Integration

Native custom component for Home Assistant. No HACS required.

Supports two update modes (user chooses during setup):

  • Local Push (default, recommended) — the WiBeee sends data to HA's HTTP server in real time. Lowest latency.
  • Polling — HA periodically fetches status.xml from the device (configurable interval, default 30 s).

Features

  • 📡 Local Push (recommended) — real-time updates via HTTP push (no polling overhead).
  • 🔄 Polling mode — periodic fetch of status.xml (configurable interval, default 30 s).
  • 🔍 DHCP auto-discovery — devices with MAC prefix 00:1E:C0 are detected automatically.
  • ⚙️ Config Flow UI:
    • Step 1: enter or confirm device IP.
    • Step 2: select update mode (Local Push or Polling).
  • 🔧 Options Flow:
    • Switch between push and polling.
    • Configure polling interval.
    • Re-run push auto-configuration.
  • ⚡ Auto-configuration (optional) — the integration can configure the WiBeee to push data to HA (IP + HTTP port).
  • 24 sensor types per phase: voltage, current, active/apparent/reactive power, frequency, power factor, active energy, reactive energy, angle, THD current & voltage with harmonics.
  • 🧩 Device Registry:
    • Main device with manufacturer, model, firmware version, and link to the device web UI.
    • Per-phase sub-devices (L1, L2, L3) linked via via_device.
  • 🌍 Translations: English, Spanish, Catalan.
  • 12 device models: WBM, WBT, WMX, WTD, WX2, WX3, WXX, WBB, WB3, W3P, WGD, WBP.
  • 🧪 Fully async, non-blocking implementation.

Installation

Copy the custom_components/wibeee/ folder into your Home Assistant config/custom_components/ directory:

# From the repository root
cp -r custom_components/wibeee /path/to/ha/config/custom_components/

Restart Home Assistant, then go to Settings → Devices & Services → Add Integration → Wibeee Energy Monitor.

The integration will ask for:

  1. The device IP address (or it will be pre-filled if discovered via DHCP).
  2. The update mode: Local Push (recommended) or Polling.

If you choose Local Push with auto-configure enabled, the integration sends the HA IP and port to the WiBeee device and restarts it. The device will start pushing data to HA immediately.

Requirements

  • Home Assistant 2024.1.0 or later.
  • WiBeee device accessible on the local network (static IP or DHCP reservation recommended).
  • For Local Push: the WiBeee must be able to reach HA's HTTP port (8123 by default).

Architecture

The integration follows modern Home Assistant patterns (2024+):

  • ``entry.runtime_data`` — typed runtime data (WibeeeRuntimeData dataclass) instead of hass.data[DOMAIN].
  • Single ``WibeeeCoordinator(DataUpdateCoordinator)`` — handles both polling (update_interval=30s) and push (update_interval=None) modes. Push data arrives via async_push_update().
  • Single ``WibeeeSensor(CoordinatorEntity, SensorEntity)`` — one entity class for all sensor types.
  • Deterministic entity creation — phases are discovered from the device (1-phase vs 3-phase), then ALL 24 sensor types are created per phase. Sensors without data report available=False.
  • ``ConfigEntryNotReady`` — raised on connection errors during setup so HA retries automatically.
  • Narrow exceptions — aiohttp.ClientError, asyncio.TimeoutError, ET.ParseError instead of bare except Exception.
  • Read-only data contract — WibeeeData = Mapping[str, Mapping[str, str]] ensures coordinator data is not mutated downstream.
  • XML parsing via stdlib — uses xml.etree.ElementTree (no xmltodict dependency in the HA component).

Discovery & Push

  • DHCP discovery — devices with MAC prefix 00:1E:C0 are auto-detected.
  • Push receiver — registers an HTTP endpoint at /Wibeee/receiverAvg on HA's built-in HTTP server. The WiBeee sends periodic GET requests with sensor values as query parameters. The receiver maps push parameter prefixes (v, a, e, ...) to XML sensor keys (vrms, p_activa, energia_activa, ...) and routes data to the coordinator.
  • Auto-configure — optionally sends HA's IP and port to the device so it starts pushing immediately.

Design Decisions

  • Component version (1.2.0) != library version (0.1.1) — the HA custom component and the CLI library are versioned independently.
  • ``Mapping`` type alias — WibeeeData uses Mapping (read-only) instead of dict to prevent accidental mutation of coordinator data by sensor entities.
  • One coordinator, two modes — instead of separate coordinator classes for polling and push, a single coordinator handles both. Push mode sets update_interval=None and exposes async_push_update() as the public API for incoming data.
  • All sensors per phase — even if a sensor type has no data yet, the entity is created and marked available=False. This avoids entity churn when sensors appear/disappear.

Quality & Testing

  • 119 automated tests covering coordinator, sensors, config flow, API, push receiver, buttons, and constants.
  • Ruff clean (no lint warnings).
  • Translations in English, Spanish, and Catalan.

Quality Scale

This integration aims to meet the Integration Quality Scale:

  • ✅ Config flow
  • ✅ Options flow
  • ✅ Device registry support
  • ✅ Async implementation
  • ✅ Error handling
  • ✅ Logging
  • ✅ Translations
  • ✅ Tests
  • ✅ Documentation

Notes for Reviewers

  • Push mode uses the HA HTTP component (no custom ports opened).
  • Coordinator is used as a passive data bus for push updates (update_interval=None).
  • Entities are deterministic per discovered phase (hardware-defined).
  • Auto-configuration of push mode is optional and user-controlled.

Tested With

  • Multiple WiBeee device models (single-phase and three-phase).
  • Both push and polling modes.
  • DHCP discovery and manual setup.

CLI Library

Command line interface for WiBeee (old Mirubee) meters.

Features

  • Autodiscover the host (IP) of the meter on the network.
  • Get version, model, device name, info, status, and sensor list.
  • Actions: reboot (via command or web), reset energy counters, configure push server.
  • Output formats: xml, json, plain text, file.
  • Uses httpx for both sync and async HTTP calls (no other HTTP dependencies).

Requirements

pip install xmltodict httpx

Installation

Install from PyPI:

pip install pywibeee --upgrade

Or install latest source:

pip install git+https://github.com/fquinto/pywibeee

Usage

pywibeee -h

usage: pywibeee [-h] [-version] (--host HOST | --auto) [-p PORT] [-t SETTIMEOUT]
                [-o {xml,json,plain,file}]
                (-a {reboot,rebootweb,resetenergy,configureserver} | -g {model,version,status,info,sensors,devicename})
                [--serverip SERVERIP] [--serverport SERVERPORT]

CLI for WiBeee (old Mirubee) meter

optional arguments:
  -h, --help            show this help message and exit
  -version, --version   show program's version number and exit
  --host HOST           The host (or the IP) of the meter.
  --auto                Autodiscover host function, look IP on net.
  -p PORT, --port PORT  set port (default 80)
  -t SETTIMEOUT, --settimeout SETTIMEOUT
                        set timeout in seconds (default 10.0)
  -o FORMAT, --output FORMAT
                        xml|json|plain|file
  -a ACTION, --action ACTION
                        reboot|rebootweb|resetenergy|configureserver
  -g GET, --get GET     model|version|status|info|sensors|devicename
  --serverip SERVERIP   Server IP for push config (use with -a configureserver)
  --serverport SERVERPORT
                        Server port for push config (default 8600)

Enjoy! :)

Examples

Get status

$ pywibeee --host 192.168.1.150 --get status
{"response": {"model": "WBB", "webversion": "3.4.614", "time": "1570484447",
"fase1_vrms": "228.70", "fase1_irms": "1.59", "fase1_p_activa": "264.34", ...}}

Get model

$ pywibeee --host 192.168.1.150 --get model
{"response": {"model": "WBB", "model_description": "Wibeee BOX"}}

Get info

$ pywibeee --host 192.168.1.150 -g info
{"response": {"model": "WBB", "model_description": "Wibeee BOX",
"webversion": "3.4.614", "host": "192.168.1.150", "devicename": "WIBEEE"}}

Get sensors with autodiscover

$ pywibeee --auto -g sensors
{"vrms": ["Vrms", "V", "mdi:sine-wave"], "irms": ["Irms", "A", "mdi:flash-auto"], ...}

Configure push server

Configure the WiBeee to push data to a server (e.g. Home Assistant on 192.168.1.50:8600):

$ pywibeee --host 192.168.1.150 -a configureserver --serverip 192.168.1.50 --serverport 8600
{"response": {"configureServer": "done (server=192.168.1.50:8600)"}}

The device will restart to apply the configuration. The port is sent in hexadecimal to the WiBeee firmware (8600 decimal = 2198 hex).

Reboot the device

$ pywibeee --host 192.168.1.150 -a rebootweb

Reset energy counters

$ pywibeee --host 192.168.1.150 -a resetenergy

Local Push Protocol

The WiBeee device can be configured to push data to a server via HTTP GET requests. The device sends periodic requests to the configured server with all sensor values as query parameters.

Endpoint

GET /Wibeee/receiverAvg?mac=001ec0112233&v1=230.5&a1=277&e1=222157&vt=230.5&...

The server must respond with <<<WBAVG to acknowledge receipt.

The server can also send <<<WREBOOT to remotely reboot the device.

Push parameter mapping

Push param prefix Sensor Unit
v Phase voltage (vrms) V
i Current (irms) A
p Apparent power VA
a Active power W
r Inductive reactive power var
q Frequency Hz
f Power factor —
e Active energy Wh
o Inductive reactive energy varh

Phase suffixes: 1 = L1, 2 = L2, 3 = L3, t = Total.

Example: v1 = voltage L1, at = active power total, e2 = active energy L2.

Configure push via HTTP

# Set the push server (port in hex: 8123 = 1fbb for HA default port)
curl "http://192.168.1.150/configura_server?ipServidor=192.168.1.50&URLServidor=192.168.1.50&portServidor=1fbb"

# Reset the device to apply changes
curl "http://192.168.1.150/config_value?reset=true"

Other useful HTTP endpoints

# Harmonics data
curl http://192.168.1.150/services/user/harmonics.xml

# Waveform data (per phase)
curl http://192.168.1.150/services/user/wafeformsF1.xml

# Read measurement refresh rate
curl "http://192.168.1.150/services/user/values.xml?var=WIBEEE.measuresRefresh"

# Read app refresh rate
curl "http://192.168.1.150/services/user/values.xml?var=WIBEEE.appRefresh"

# Trigger WiFi scan and get results
curl "http://192.168.1.150/scan.cgi?getAllBss"
curl http://192.168.1.150/scanallresults.xml

Device Notes

  • Default IP: 192.168.1.150
  • Default credentials:
    • Basic: user / user
    • Admin: admin / Sm1l1cs?
    • Admin (alt): admin / Wib333?
  • MAC OUI: 00:1E:C0 (Microchip Technology / Circutor)

Open ports

80/tcp  open http      Web interface, configuration, bootloader commands
502/tcp open modbus    Modbus TCP (input registers from 1009)
550/tcp open binary    OTA firmware transfer (do NOT use without full understanding)

OTA commands

  • 21001A 576246696E697368426F6F746C6F6164657250726F6363657373 0D0A (hex) = WbStartBootloaderProccess
  • 200119 576246696e697368426f6f746c6f6164657250726f6363657373 0D0A (hex) = WbFinishBootloaderProccess
  • 0D (hex) = Enter key = get version
  • 0F (hex) = read Backup Position
  • 01 (hex) = reset

Models

Code Description
WBM Wibeee 1Ph
WBT Wibeee 3Ph
WMX Wibeee MAX
WTD Wibeee 3Ph RN
WX2 Wibeee MAX 2S
WX3 Wibeee MAX 3S
WXX Wibeee MAX MS
WBB Wibeee BOX
WB3 Wibeee BOX S3P
W3P Wibeee 3Ph 3W
WGD Wibeee GND
WBP Wibeee SMART PLUG

Security

The WiBeee has no authentication on local HTTP endpoints and uses plain HTTP. Recommended precautions:

  • Isolate the device on a separate VLAN or IoT network.
  • Use firewall rules to restrict access to ports 80, 502, and 550.
  • Do not expose the device to the internet.

Tools

Changelog

See CHANGELOG.md

License

GNU General Public License version 2

Community

Join the Telegram community channel for support, questions, and discussion:

About

Command line interface (CLI) for WiBeee (old Mirubee) meter.

github.com/fquinto/pywibeee

Topics

python home-automation energy-monitor meter electricity consumption homeassistant power-meter voltage-monitor power-monitor current-meter wibeee mirubee circutor

Resources

Readme

License

GPL-2.0 license
Activity

Stars

16 stars

Watchers

3 watching

Forks

1 fork
Report repository

Releases 6

v0.1.1 — HA Integration Latest
Apr 16, 2026
+ 5 releases

Packages

 
 
 

Contributors

Languages