ee-smarthub 0.3.0

Async Python client for querying connected devices on EE SmartHub routers via USP over MQTT WebSocket

EE SmartHub Client

Python async client library for interacting with EE SmartHub routers using the USP protocol over MQTT WebSocket.

Why This Library?

The EE SmartHub web interface is React-based and dynamically loads data via JavaScript, making traditional web scraping impractical. This library uses the router's native USP (User Services Platform) protocol providing:

• Reliable data access — won't break with UI changes
• Efficient communication — direct protocol access, not HTML parsing
• Structured data — clean, typed Python objects

Installation

pip install ee-smarthub

Usage

The client requires an aiohttp.ClientSession, allowing callers to manage session lifecycle.

import asyncio
import aiohttp
from ee_smarthub import SmartHubClient

async def main():
    async with aiohttp.ClientSession() as session:
        client = SmartHubClient("192.168.1.1", "your-password", session)
        hosts = await client.get_hosts()
        for host in hosts:
            print(f"{host.name:30s} {host.ip_address:15s} {host.mac_address}")

asyncio.run(main())

Validating Credentials

To check that the router is reachable and the password is correct without fetching device data:

async with aiohttp.ClientSession() as session:
    client = SmartHubClient("192.168.1.1", "your-password", session)
    await client.validate_connection()  # raises on failure

This performs an HTTP fetch and MQTT connect/disconnect.

Host Fields

Each Host object contains:

Field	Type	Description
mac_address	str	Physical (MAC) address
ip_address	str	IP address
hostname	str	DHCP hostname
user_friendly_name	str	User-assigned name (BT vendor extension)
name	str (property)	Best available name (user-friendly > hostname > MAC)
active	bool	Currently connected
interface_type	str	Connection type (e.g. "Wi-Fi", "Ethernet")
frequency_band	str | None	Wi-Fi band (e.g. "2.4GHz", "5GHz")
bytes_sent	int	Total bytes sent
bytes_received	int	Total bytes received

How It Works

The library implements the User Services Platform (USP) protocol defined by the Broadband Forum:

1. Fetch serial number - HTTPS GET to {ROUTER_URL}/config.json
2. Connect to MQTT - WebSocket connection to router on port 443
3. Authenticate with router password
4. Send USP request - Protobuf-encoded Get request for Device.Hosts.Host.*
5. Parse response - Extract device parameters from protobuf response
6. Disconnect - Close connection (short-lived connection model)

The connection is short-lived by design - simple, reliable, and efficient for typical polling intervals.

Development

Regenerating Protobuf Code

If the USP protocol specification is updated, regenerate the Python protobuf code:

./scripts/generate_proto.sh

This downloads the latest .proto files from the Broadband Forum repository and generates Python code using betterproto into src/ee_smarthub/proto/.

Security Considerations

The EE SmartHub uses a self-signed SSL certificate. This library disables certificate verification for HTTPS and WebSocket connections to communicate with the router, which means TLS connections are not fully verified.

Since the router is on your local network, exposure is limited. Ensure your local network is secure.

Compatibility

• Python: 3.11+
• Router: EE SmartHub
• Protocol: USP

License

This project is licensed under the MIT License - see the LICENSE file for details.

Resources

• USP Technology
• CWMP Data Models
• Broadband Forum USP

---

Note: This is an unofficial client library and is not affiliated with or endorsed by EE Limited.