Metadata-Version: 2.4
Name: superwatt
Version: 0.1.2
Summary: Add your description here
Author-email: Sygmei <3835355+Sygmei@users.noreply.github.com>
License-File: LICENSE
Requires-Python: >=3.12
Requires-Dist: pydantic>=2.0
Requires-Dist: pyserial>=3.5
Description-Content-Type: text/markdown

# Superwatt Python Client

Python client and CLI for SuperWatt / Voltronic-compatible inverters over serial.

## Install

```powershell
uv sync
```

Set the serial port with `--port` or `SUPERWATT_PORT`.

Examples:

```powershell
$env:SUPERWATT_PORT = "COM3"
uv run superwatt query protocol-id
uv run superwatt --port COM3 query protocol-id
```

```bash
export SUPERWATT_PORT=/dev/ttyUSB0
uv run superwatt query protocol-id
uv run superwatt --port /dev/ttyUSB0 query protocol-id
```

## CLI

Read a typed query:

```powershell
uv run superwatt query protocol-id
uv run superwatt query general-status
uv run superwatt query device-flags
```

Send a raw protocol query:

```powershell
uv run superwatt rawquery QPI
uv run superwatt rawquery QPIGS
uv run superwatt rawquery QFOO --allow-unknown
```

Build a parameter command without sending it:

```powershell
uv run superwatt parameter disable buzzer
uv run superwatt parameter disable lcd-backlight
```

Execute a parameter command:

```powershell
uv run superwatt parameter disable buzzer --execute
uv run superwatt parameter enable lcd-backlight --execute
```

Supported parameters:

```text
buzzer
bypass-to-utility-on-overload
fault-code-recording
lcd-backlight
lcd-timeout-escape-to-default-page
over-temperature-restart
overload-restart
power-saving
primary-source-interrupt-alarm
```

## Python

```python
from superwatt import SuperWattClient

client = SuperWattClient(port="/dev/ttyUSB0")

protocol = client.get_protocol_id()
status = client.get_general_status()
flags = client.get_device_flags()

dry_run = client.build_set_parameter_command("buzzer", False)
result = client.set_parameter_value("buzzer", False)
```

## Errors

`NegativeAcknowledgementError` is raised when the inverter returns `NAK`.

`UnknownQuery` is raised when an unknown query sent with `allow_unknown=True` returns `NAK`.
