bcontrolpy

---

bcontrolpy is an asynchronous Python client for the TQ-Systems EM300 energy meter, providing authentication, session management, and data retrieval via the MUM webservice.

Table of Contents

• Installation

• Quickstart

• Usage

  • Python API
  • Command Line Example

• Configuration

• License

Installation

Install the latest release from PyPI:

pip install bcontrolpy

Or install the development version directly from GitHub:

pip install git+https://github.com/ITTV-tools/bcontrolpy.git

Quickstart

import asyncio
from bcontrolpy import BControl, AuthenticationError

async def main():
    # Connect to EM300 meter on local network
    bc = BControl(ip="192.168.1.100", password="your_password")
    try:
        info = await bc.login()
        print("Login successful:", info)

        data = await bc.get_data()
        print("Meter readings:", data)
    except AuthenticationError:
        print("Authentication failed: check your credentials")
    finally:
        await bc.close()

asyncio.run(main())

Usage

Python API

Method	Returns	Raises
login() -> dict	{'serial', 'app_version', 'authentication'}	AuthenticationError, CookieRetrievalError, LoginValueError, CookieValueError
get_data() -> dict	Measurement values mapped to human-readable keys	NotAuthenticatedError, HTTP errors
close() -> None

Example:

bc = BControl(ip="192.168.1.100", password="your_password")
info = await bc.login()
values = await bc.get_data()
await bc.close()

Command Line Example

Run the provided example script:

python example/example.py --ip 192.168.1.100 --password "your_password"

This prints the login details and current meter readings.

Configuration

• Reuse aiohttp.ClientSession: Pass an existing session (e.g., from Home Assistant) to BControl to take advantage of connection pooling. An external session will not be closed by BControl.close().
• Handle Exceptions: Catch AuthenticationError to trigger re-authentication flows.
• Customize Mapping: The OBIS code mapping resides in key_mapping.py and can be extended for additional measurements.

License

bcontrolpy is distributed under the Apache 2.0 License. See LICENSE for details.