Metadata-Version: 2.4
Name: aiopowerwall
Version: 0.1.0
Summary: Async Tesla Powerwall 3 client over the TEDAPI v1r RSA-signed LAN protocol.
Project-URL: Homepage, https://github.com/Teslemetry/aiopowerwall
Project-URL: Repository, https://github.com/Teslemetry/aiopowerwall
Project-URL: Issues, https://github.com/Teslemetry/aiopowerwall/issues
Project-URL: Changelog, https://github.com/Teslemetry/aiopowerwall/releases
Author-email: Teslemetry <hello@teslemetry.com>
License-Expression: MIT
License-File: LICENSE
Keywords: aiohttp,asyncio,home-assistant,powerwall,tedapi,tesla
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: Intended Audience :: Developers
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3 :: Only
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Home Automation
Classifier: Typing :: Typed
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9
Requires-Dist: cryptography>=41
Requires-Dist: protobuf>=4.25
Provides-Extra: dev
Requires-Dist: mypy>=1.8; extra == 'dev'
Requires-Dist: pytest-asyncio>=0.23; extra == 'dev'
Requires-Dist: pytest>=8; extra == 'dev'
Requires-Dist: ruff>=0.5; extra == 'dev'
Requires-Dist: types-protobuf; extra == 'dev'
Description-Content-Type: text/markdown

# aiopowerwall

An async Tesla Powerwall 3 client built on `aiohttp`, written for Home
Assistant and any other asyncio code.

## Status

**Beta (0.x).** The wire protocol and the public Python API may change
between minor versions until 1.0. Pin a tight version range if you depend
on this library in production.

This library speaks the Powerwall's **TEDAPI v1r** protocol — RSA-signed
protobuf messages directly to your Powerwall. It is intentionally
scoped to:

- Powerwall 3, and updated Powerwall 2 (untested)
- Local LAN access only (no cloud telemetry)
- Read + control commands (status, config, firmware, components, max-backup)

The RSA key pair used for v1r authentication must be **registered with the
gateway out-of-band**, typically via the Tesla Fleet API. This library
consumes an already-paired private key — it does not implement registration.

## Install

```bash
pip install aiopowerwall
```

## Quick start

```python
import asyncio
from pathlib import Path
from aiopowerwall import PowerwallClient

async def main() -> None:
    pem = Path("tedapi_rsa_private.pem").read_bytes()
    async with PowerwallClient(
        host="192.168.91.1",
        gateway_password="<gateway-password>",
        rsa_private_key_pem=pem,
    ) as pw:
        await pw.connect()
        print("DIN:", pw.din)
        print("Battery SoC:", await pw.get_battery_soe(), "%")
        print("Grid:", await pw.get_grid_status())
        print("Power:", await pw.current_power())

asyncio.run(main())
```

## API surface

| Method | Returns |
| --- | --- |
| `connect()` | DIN string |
| `get_din()` | DIN string |
| `get_config()` | `config.json` (dict) |
| `get_status()` | DeviceController query (narrow) |
| `get_device_controller()` | DeviceController query (extended) |
| `get_components()` | Powerwall 3 component data |
| `get_firmware_version(details=...)` | Version string or details dict |
| `get_meters_aggregates()` | `/api/meters/aggregates` |
| `get_battery_soe()` | Battery SoC percentage |
| `get_grid_status()` | Grid status string |
| `battery_level()` | SoC computed from status payload |
| `current_power(location=...)` | Real power per meter aggregate |
| `backup_time_remaining()` | Hours of backup at current load |
| `write_config(updates)` | Patch `config.json` (dotted paths) |
| `schedule_max_backup(seconds)` | Schedule manual backup event |
| `cancel_max_backup()` | Cancel manual backup event |
| `get_backup_events()` | Active and scheduled backup events |

All read methods cache responses with a configurable TTL
(`cache_status_ttl`, `cache_config_ttl`); pass `force=True` to refresh.

## Exceptions

All errors are subclasses of `PowerwallError`:

- `PowerwallConnectionError` — transport failure / timeout
- `PowerwallAuthenticationError` — bad password or unregistered RSA key
- `PowerwallRateLimitError` — gateway returned 429/503
- `PowerwallFaultError` — signed-message fault (key inactive, expired, etc.)
- `PowerwallProtocolError` — malformed response

## Acknowledgements

This project builds on the protocol research and reference implementation in
[`pypowerwall`](https://github.com/jasonacox/pypowerwall) by
[Jason Cox](https://github.com/jasonacox), distributed under the
[MIT License](https://github.com/jasonacox/pypowerwall/blob/main/LICENSE).
Huge thanks to Jason and the pypowerwall contributors for reverse-engineering
and documenting the TEDAPI protocol.

## License

MIT (see `LICENSE`). Original pypowerwall copyright and license notice are
retained in `LICENSE`.
