Metadata-Version: 2.5
Name: python-intelbras-solar-local
Version: 0.1.1
Summary: Async Python client for Intelbras solar inverters (Sungrow WiNet-S) over Modbus TCP and the datalogger WebSocket
Project-URL: Homepage, https://github.com/hudsonbrendon/python-intelbras-solar-local
Project-URL: Documentation, https://hudsonbrendon.github.io/python-intelbras-solar-local/
Project-URL: Issues, https://github.com/hudsonbrendon/python-intelbras-solar-local/issues
Author-email: Hudson Brendon <contato.hudsonbrendon@gmail.com>
License: MIT
License-File: LICENSE
Keywords: aiohttp,async,home-assistant,intelbras,inverter,modbus,solar,sungrow,winet
Classifier: Development Status :: 4 - Beta
Classifier: Framework :: AsyncIO
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Topic :: Software Development :: Libraries
Requires-Python: >=3.11
Requires-Dist: aiohttp>=3.9
Provides-Extra: docs
Requires-Dist: mkdocs-material>=9.5; extra == 'docs'
Requires-Dist: mkdocstrings[python]>=0.25; extra == 'docs'
Provides-Extra: test
Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
Requires-Dist: pytest>=8; extra == 'test'
Requires-Dist: ruff; extra == 'test'
Description-Content-Type: text/markdown

<p align="center"><img src="docs/assets/logo.png" width="300" alt="Intelbras"></p>

# python-intelbras-solar-local

[![Tests](https://github.com/hudsonbrendon/python-intelbras-solar-local/actions/workflows/tests.yml/badge.svg)](https://github.com/hudsonbrendon/python-intelbras-solar-local/actions/workflows/tests.yml)
[![PyPI version](https://img.shields.io/pypi/v/python-intelbras-solar-local.svg)](https://pypi.org/project/python-intelbras-solar-local/)
[![Python](https://img.shields.io/pypi/pyversions/python-intelbras-solar-local.svg)](https://pypi.org/project/python-intelbras-solar-local/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)

This is an async Python client that reads and controls **Intelbras solar inverters** over the local network, with no cloud
and no account. It was built for the
[`ha-intelbras-solar-local`](https://github.com/hudsonbrendon/ha-intelbras-solar-local) Home Assistant integration.

Intelbras IONS inverters are rebranded **Sungrow** string inverters, and their Wi-Fi datalogger is a Sungrow **WiNet-S**.
The datalogger exposes two interfaces without a login, and this library uses both:

- **Modbus TCP** on port `502`, using the Sungrow SG-RS register map. This is the main data source.
- The **datalogger WebSocket** on port `8082`, which the built-in web UI uses. It provides Wi-Fi and cloud link state,
  active faults and alarms, and the commercial model.

## Features

- ⚡ Power readings: AC, DC, apparent and reactive power, plus power factor.
- 🔋 Energy counters for today, the month, the year and the lifetime total (0.1 kWh resolution).
- ☀️ Voltage, current and power for each MPPT input.
- 🔌 Grid voltage, current and frequency (0.01 Hz).
- 🩺 Health data: work state, internal temperature, bus voltage, insulation resistance and fault code.
- 📡 Datalogger data: Wi-Fi and cloud connectivity, active fault list and alarm count.
- 🛠️ Controls: start or stop the inverter, switch power limitation on or off, set the power limit (%), set the clock.
- No `pymodbus` dependency. The library ships a tiny asyncio Modbus TCP client, so it never clashes with the version
  that Home Assistant pins.
- Fully async (`aiohttp`) and typed (`py.typed`).

## Installation

```bash
pip install python-intelbras-solar-local
```

## Quickstart

```python
import asyncio
from intelbras_solar_local import IntelbrasSolarClient


async def main() -> None:
    async with IntelbrasSolarClient("192.168.31.17") as client:
        status = await client.async_get_status()
        print(status.model, status.serial, status.work_state)
        print(f"{status.power_ac} W now, {status.energy_today} kWh today")
        for n, mppt in enumerate(status.mppts, 1):
            print(f"MPPT{n}: {mppt.voltage} V x {mppt.current} A = {mppt.power} W")


asyncio.run(main())
```

## Supported hardware

| Inverter | Datalogger firmware | Sungrow type code |
|---|---|---|
| Intelbras IONS-5K M5 | `WIFI-SV300.001.03.P002` (WiNet-S) | `0x2614` |

Other Intelbras IONS models and Sungrow SG-RS inverters behind a WiNet-S should work as well.
If yours differs, open an issue with the output of `examples/status.py`.

## API overview

| Method | Description |
|--------|-------------|
| `async_get_status()` | Returns an `InverterStatus` from Modbus, with a `DataloggerStatus` when the WebSocket answers (best-effort) |
| `async_get_inverter_data()` | Modbus-only `InverterStatus` |
| `winet.async_get_status()` | Datalogger-only `DataloggerStatus` |
| `async_set_inverter_on(on)` | Starts or stops generation (holding register 5005) |
| `async_set_power_limit_enabled(enabled)` | Switches power limitation on or off (5006) |
| `async_set_power_limit(percent)` | Sets the power limit, 0–100 % (5007) |
| `async_set_clock(datetime)` | Sets the inverter clock (4999–5004) |

The register map and the WebSocket protocol are documented in the
[docs](https://hudsonbrendon.github.io/python-intelbras-solar-local/protocol/).

## Development

```bash
uv venv && uv pip install -e ".[test]"
pytest
ruff check .
```

## License

MIT © Hudson Brendon. This project is not affiliated with Intelbras or Sungrow.
