elli-2-modbus 0.1.0__tar.gz

elli_2_modbus-0.1.0/.github/workflows/ci.yml

@@ -0,0 +1,15 @@
+name: CI
+on: [push, pull_request]
+jobs:
+  test:
+    runs-on: ubuntu-latest
+    strategy:
+      matrix:
+        python: ["3.10", "3.11", "3.12", "3.13"]
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: ${{ matrix.python }}
+      - run: pip install -e ".[test]"
+      - run: pytest

elli_2_modbus-0.1.0/.github/workflows/publish.yml

@@ -0,0 +1,19 @@
+# Publishes to PyPI when a GitHub release is published.
+# One-time setup on pypi.org: add a "trusted publisher" for this repo and workflow.
+name: Publish
+on:
+  release:
+    types: [published]
+jobs:
+  pypi:
+    runs-on: ubuntu-latest
+    environment: pypi
+    permissions:
+      id-token: write
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.13"
+      - run: pip install build && python -m build
+      - uses: pypa/gh-action-pypi-publish@release/v1

elli_2_modbus-0.1.0/.gitignore

@@ -0,0 +1,8 @@
+__pycache__/
+*.pyc
+.venv/
+.pytest_cache/
+.ruff_cache/
+.DS_Store
+dist/
+*.egg-info/

elli_2_modbus-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Frane Bandov
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

elli_2_modbus-0.1.0/PKG-INFO

@@ -0,0 +1,108 @@
+Metadata-Version: 2.5
+Name: elli-2-modbus
+Version: 0.1.0
+Summary: Local Modbus TCP control of Elli Charger 2 wallboxes (VW ID. Charger 2, Škoda, CUPRA)
+Project-URL: Homepage, https://github.com/frane/elli-2-modbus
+Project-URL: Issues, https://github.com/frane/elli-2-modbus/issues
+Author: Frane Bandov
+License-Expression: MIT
+License-File: LICENSE
+Keywords: elli,ev-charger,home-assistant,modbus,volkswagen,wallbox
+Classifier: Development Status :: 3 - Alpha
+Classifier: Framework :: AsyncIO
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Home Automation
+Classifier: Typing :: Typed
+Requires-Python: >=3.10
+Provides-Extra: test
+Requires-Dist: pytest-asyncio>=0.23; extra == 'test'
+Requires-Dist: pytest>=8; extra == 'test'
+Description-Content-Type: text/markdown
+
+# elli-2-modbus
+
+**English** | [Deutsch](README.de.md)
+
+Python library and CLI for local control of **Elli Charger 2** wallboxes over **Modbus TCP**. No cloud, no EEBUS, and no dependencies.
+
+The Home Assistant integration built on it is [ha-elli-2-modbus](https://github.com/frane/ha-elli-2-modbus).
+
+## Supported wallboxes
+
+Second-generation Elli wallboxes with firmware **R03.004.045.121-elli or newer** (the version that added the Modbus server):
+
+- Elli Charger Connect 2, Pro 2, Pro 2 Eichrecht
+- Volkswagen ID. Charger Connect 2 / Pro 2
+- Škoda Charger Connect 2 / Pro 2
+- CUPRA Charger 2 / Pro 2
+
+Modbus runs alongside the Elli backend, so the Elli app, OCPP and firmware updates keep working.
+
+## Enable Modbus on the wallbox
+
+Short version (detailed guide: [docs/enable-modbus.md](docs/enable-modbus.md)):
+
+1. Open the charger configuration in a browser at `https://<IP or hostname>`. Alternatively, connect to the wallbox hotspot and open `https://10.0.2.1`. Accept the certificate warning (**Advanced** → continue).
+2. Log in as **Service User** with the service user password from the access data card.
+3. **Software update**: the firmware must be **R03.004.045.121 or newer**.
+4. **Connections → Modbus server**: switch it **on**. Port 502, unit ID 1.
+5. Give the wallbox a fixed IP address (a DHCP reservation in your router).
+6. If something else controls the current, set **Charging management → Charging settings → PV surplus charging** to **off**.
+7. Test: `elli-2-modbus status <ip>`
+
+The interface is also available in German, with the same steps: *Verbindungen → Modbus-Server*, *Ladeverwaltung → Ladeeinstellungen*.
+
+## CLI
+
+```bash
+pip install elli-2-modbus
+
+elli-2-modbus status 192.168.1.50          # read everything
+elli-2-modbus status 192.168.1.50 --json
+elli-2-modbus set-current 192.168.1.50 10  # allow charging with up to 10 A
+elli-2-modbus stop 192.168.1.50            # block charging
+elli-2-modbus set-failsafe 192.168.1.50 0  # what happens when Modbus traffic stops
+elli-2-modbus set-watchdog 192.168.1.50 30
+elli-2-modbus simulate --port 5020         # simulated wallbox for testing
+```
+
+Without installing, from the repo: `PYTHONPATH=src python3 -m elli2modbus status <ip>`
+
+## Library
+
+```python
+from elli2modbus import ElliCharger
+
+async with ElliCharger("192.168.1.50") as charger:
+    info = await charger.read_info()      # layout version, min/max current
+    status = await charger.read_status()  # state, currents, voltages, power, energy, limits
+    if status.vehicle_connected:
+        await charger.set_current(10)     # 0.1 A resolution
+    await charger.stop()
+```
+
+The library raises three errors: `ModbusConnectionError` when the wallbox cannot be reached, `ModbusExceptionResponse` when it rejects the request, and `ValueError` when a value is out of range.
+
+## Things to know
+
+- **Watchdog:** if the wallbox sees no Modbus traffic for the watchdog time (default 15 s), it falls back to the failsafe current. Poll faster than that, and set the failsafe current deliberately: 0 stops charging, 6 A or more keeps charging.
+- **Maximum 16 A** over Modbus for now, including the 22 kW variants. Elli has announced 32 A for a future firmware.
+- **No phase switching** over Modbus.
+- Register 261 can report **less than you wrote**, because the wallbox's internal limits take priority. `status.current_limit` shows the limit that is actually in effect.
+- Power is reported as apparent power (VA).
+
+Register reference: [docs/registers.md](docs/registers.md).
+
+## Development
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e ".[test]"
+pytest
+```
+
+The simulator only implements registers from Elli's register list. Undocumented ones (for example Heidelberg's 13, 258, 259) return Modbus exception 2, like the real device.
+
+*Not affiliated with Elli or Volkswagen Group Charging GmbH.*

elli_2_modbus-0.1.0/README.de.md

@@ -0,0 +1,85 @@
+# elli-2-modbus
+
+[English](README.md) | **Deutsch**
+
+Python-Bibliothek und Kommandozeilen-Tool, um **Elli Charger 2** Wallboxen lokal über **Modbus TCP** zu steuern. Ohne Cloud, ohne EEBUS und ohne Abhängigkeiten.
+
+Die Home-Assistant-Integration dazu ist [ha-elli-2-modbus](https://github.com/frane/ha-elli-2-modbus).
+
+## Unterstützte Wallboxen
+
+Elli-Wallboxen der zweiten Generation mit Firmware **R03.004.045.121-elli oder neuer** (seitdem gibt es den Modbus-Server):
+
+- Elli Charger Connect 2, Pro 2, Pro 2 Eichrecht
+- Volkswagen ID. Charger Connect 2 / Pro 2
+- Škoda Charger Connect 2 / Pro 2
+- CUPRA Charger 2 / Pro 2
+
+Modbus läuft parallel zum Elli-Backend. Elli-App, OCPP und Firmware-Updates funktionieren also weiter.
+
+## Modbus an der Wallbox aktivieren
+
+Kurzfassung (ausführlich: [docs/enable-modbus.de.md](docs/enable-modbus.de.md)):
+
+1. Wallbox-Konfiguration im Browser öffnen: `https://<IP oder Hostname>`, oder mit dem Hotspot der Wallbox verbinden und `https://10.0.2.1` öffnen. Die Zertifikatswarnung bestätigen (**Erweitert** → fortfahren).
+2. Als **Service User** mit dem Service-User-Passwort von der Zugangsdatenkarte anmelden.
+3. **Software-Update**: Die Firmware muss **R03.004.045.121 oder neuer** sein.
+4. **Verbindungen → Modbus-Server**: **einschalten**. Port 502, Modbus-ID 1.
+5. Der Wallbox eine feste IP geben (DHCP-Reservierung im Router).
+6. Wenn ein anderes System den Strom regelt: **Ladeverwaltung → Ladeeinstellungen → PV-Überschuss-Laden** auf **PV-Laden aus** stellen.
+7. Testen: `elli-2-modbus status <ip>`
+
+Auf Englisch heißen die Menüs *Connections → Modbus server* und *Charging management → Charging settings*.
+
+## Kommandozeile
+
+```bash
+pip install elli-2-modbus
+
+elli-2-modbus status 192.168.1.50          # alles auslesen
+elli-2-modbus status 192.168.1.50 --json
+elli-2-modbus set-current 192.168.1.50 10  # Laden mit bis zu 10 A freigeben
+elli-2-modbus stop 192.168.1.50            # Laden sperren
+elli-2-modbus set-failsafe 192.168.1.50 0  # Verhalten, wenn der Modbus-Verkehr ausbleibt
+elli-2-modbus set-watchdog 192.168.1.50 30
+elli-2-modbus simulate --port 5020         # simulierte Wallbox zum Testen
+```
+
+Ohne Installation, direkt aus dem Repo: `PYTHONPATH=src python3 -m elli2modbus status <ip>`
+
+## Bibliothek
+
+```python
+from elli2modbus import ElliCharger
+
+async with ElliCharger("192.168.1.50") as charger:
+    info = await charger.read_info()      # Layout-Version, min./max. Strom
+    status = await charger.read_status()  # Status, Ströme, Spannungen, Leistung, Energie, Grenzen
+    if status.vehicle_connected:
+        await charger.set_current(10)     # Auflösung 0,1 A
+    await charger.stop()
+```
+
+Die Bibliothek wirft drei Fehler: `ModbusConnectionError`, wenn die Wallbox nicht erreichbar ist, `ModbusExceptionResponse`, wenn sie die Anfrage ablehnt, und `ValueError`, wenn ein Wert außerhalb des Bereichs liegt.
+
+## Gut zu wissen
+
+- **Watchdog:** Sieht die Wallbox länger als die Watchdog-Zeit (Standard 15 s) keinen Modbus-Verkehr, fällt sie auf den Failsafe-Strom zurück. Deshalb häufiger abfragen und den Failsafe-Strom bewusst setzen: 0 stoppt das Laden, ab 6 A lädt sie weiter.
+- **Maximal 16 A** per Modbus, auch bei den 22-kW-Varianten. Elli hat 32 A für eine künftige Firmware angekündigt.
+- **Keine Phasenumschaltung** per Modbus.
+- Register 261 kann **weniger zurückmelden als geschrieben**, weil die internen Grenzen der Wallbox Vorrang haben. `status.current_limit` zeigt die Grenze, die tatsächlich gilt.
+- Die Leistung wird als Scheinleistung (VA) gemeldet.
+
+Register-Referenz: [docs/registers.md](docs/registers.md).
+
+## Entwicklung
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e ".[test]"
+pytest
+```
+
+Der Simulator kennt nur die Register aus Ellis Registerliste. Nicht dokumentierte Register (z. B. 13, 258 und 259 von Heidelberg) beantwortet er wie das echte Gerät mit Modbus-Exception 2.
+
+*Kein offizielles Projekt von Elli oder der Volkswagen Group Charging GmbH.*

elli_2_modbus-0.1.0/README.md

@@ -0,0 +1,85 @@
+# elli-2-modbus
+
+**English** | [Deutsch](README.de.md)
+
+Python library and CLI for local control of **Elli Charger 2** wallboxes over **Modbus TCP**. No cloud, no EEBUS, and no dependencies.
+
+The Home Assistant integration built on it is [ha-elli-2-modbus](https://github.com/frane/ha-elli-2-modbus).
+
+## Supported wallboxes
+
+Second-generation Elli wallboxes with firmware **R03.004.045.121-elli or newer** (the version that added the Modbus server):
+
+- Elli Charger Connect 2, Pro 2, Pro 2 Eichrecht
+- Volkswagen ID. Charger Connect 2 / Pro 2
+- Škoda Charger Connect 2 / Pro 2
+- CUPRA Charger 2 / Pro 2
+
+Modbus runs alongside the Elli backend, so the Elli app, OCPP and firmware updates keep working.
+
+## Enable Modbus on the wallbox
+
+Short version (detailed guide: [docs/enable-modbus.md](docs/enable-modbus.md)):
+
+1. Open the charger configuration in a browser at `https://<IP or hostname>`. Alternatively, connect to the wallbox hotspot and open `https://10.0.2.1`. Accept the certificate warning (**Advanced** → continue).
+2. Log in as **Service User** with the service user password from the access data card.
+3. **Software update**: the firmware must be **R03.004.045.121 or newer**.
+4. **Connections → Modbus server**: switch it **on**. Port 502, unit ID 1.
+5. Give the wallbox a fixed IP address (a DHCP reservation in your router).
+6. If something else controls the current, set **Charging management → Charging settings → PV surplus charging** to **off**.
+7. Test: `elli-2-modbus status <ip>`
+
+The interface is also available in German, with the same steps: *Verbindungen → Modbus-Server*, *Ladeverwaltung → Ladeeinstellungen*.
+
+## CLI
+
+```bash
+pip install elli-2-modbus
+
+elli-2-modbus status 192.168.1.50          # read everything
+elli-2-modbus status 192.168.1.50 --json
+elli-2-modbus set-current 192.168.1.50 10  # allow charging with up to 10 A
+elli-2-modbus stop 192.168.1.50            # block charging
+elli-2-modbus set-failsafe 192.168.1.50 0  # what happens when Modbus traffic stops
+elli-2-modbus set-watchdog 192.168.1.50 30
+elli-2-modbus simulate --port 5020         # simulated wallbox for testing
+```
+
+Without installing, from the repo: `PYTHONPATH=src python3 -m elli2modbus status <ip>`
+
+## Library
+
+```python
+from elli2modbus import ElliCharger
+
+async with ElliCharger("192.168.1.50") as charger:
+    info = await charger.read_info()      # layout version, min/max current
+    status = await charger.read_status()  # state, currents, voltages, power, energy, limits
+    if status.vehicle_connected:
+        await charger.set_current(10)     # 0.1 A resolution
+    await charger.stop()
+```
+
+The library raises three errors: `ModbusConnectionError` when the wallbox cannot be reached, `ModbusExceptionResponse` when it rejects the request, and `ValueError` when a value is out of range.
+
+## Things to know
+
+- **Watchdog:** if the wallbox sees no Modbus traffic for the watchdog time (default 15 s), it falls back to the failsafe current. Poll faster than that, and set the failsafe current deliberately: 0 stops charging, 6 A or more keeps charging.
+- **Maximum 16 A** over Modbus for now, including the 22 kW variants. Elli has announced 32 A for a future firmware.
+- **No phase switching** over Modbus.
+- Register 261 can report **less than you wrote**, because the wallbox's internal limits take priority. `status.current_limit` shows the limit that is actually in effect.
+- Power is reported as apparent power (VA).
+
+Register reference: [docs/registers.md](docs/registers.md).
+
+## Development
+
+```bash
+python3 -m venv .venv && . .venv/bin/activate
+pip install -e ".[test]"
+pytest
+```
+
+The simulator only implements registers from Elli's register list. Undocumented ones (for example Heidelberg's 13, 258, 259) return Modbus exception 2, like the real device.
+
+*Not affiliated with Elli or Volkswagen Group Charging GmbH.*

elli_2_modbus-0.1.0/docs/enable-modbus.de.md

@@ -0,0 +1,62 @@
+# Modbus TCP an der Elli Charger 2 aktivieren
+
+[English](enable-modbus.md) | **Deutsch**
+
+Gilt für Elli Charger Connect 2 / Pro 2 / Pro 2 Eichrecht, VW ID. Charger 2, Škoda Charger 2 und CUPRA Charger 2. Die Weboberfläche der Wallbox gibt es auf Deutsch und Englisch (sie richtet sich nach der Browsersprache). Menünamen stehen unten auf Deutsch, die englische Bezeichnung in Klammern.
+
+Du brauchst die **Zugangsdatenkarte**, die bei der Wallbox lag. Darauf stehen WLAN-Name und -Passwort, der Hostname und das **Passwort für den Service User**.
+
+## 1. Wallbox-Konfiguration öffnen
+
+**Variante A: über das Heimnetz** (Wallbox per LAN oder WLAN verbunden)
+
+- Im Browser im selben Netz `https://<Hostname>` (von der Karte) oder `https://<IP der Wallbox>` öffnen. Die IP findest du in der Geräteliste deines Routers.
+
+**Variante B: über den Hotspot der Wallbox**
+
+- Mit dem WLAN der Wallbox verbinden (SSID und Passwort von der Karte) oder den QR-Code auf der Karte scannen.
+- `https://10.0.2.1` öffnen.
+
+Der Browser warnt vor einer unsicheren Verbindung, weil die Wallbox ein selbst signiertes Zertifikat nutzt. Auf **Erweitert** (*Advanced*) klicken und fortfahren.
+
+## 2. Als Service User anmelden
+
+Rolle **Service User** wählen und das Service-User-Passwort von der Karte eingeben. Der Standard User darf keine Systemeinstellungen ändern.
+
+## 3. Firmware prüfen
+
+Unter **Software-Update** (*Software update*) steht die installierte Version. Modbus braucht **R03.004.045.121-elli oder neuer**. Ist sie älter, zuerst aktualisieren (Elli-App oder *Software-Update*).
+
+## 4. Modbus-Server einschalten
+
+**Verbindungen → Modbus-Server** (*Connections → Modbus server*) → **Modbus-Server** einschalten.
+
+| Einstellung | Wert |
+|---|---|
+| Port | 502 |
+| Modbus-ID (Unit ID) | 1 |
+
+## 5. Feste IP-Adresse vergeben
+
+Die IP der Wallbox im Router reservieren (DHCP-Reservierung) oder unter **Verbindungen → Ethernet** (*Connections → Ethernet*) eine statische Adresse eintragen und DHCP ausschalten. Der Client muss im selben lokalen Netz sein; über LTE funktioniert es nicht.
+
+## 6. Eigenes PV-Überschussladen der Wallbox ausschalten
+
+Wenn ein anderes System den Strom regelt, soll die Wallbox nicht gleichzeitig selbst regeln:
+
+**Ladeverwaltung → Ladeeinstellungen → PV-Überschuss-Laden → PV-Laden aus** (*Charging management → Charging settings → PV surplus charging → off*).
+
+## 7. Testen
+
+```bash
+pip install elli-2-modbus
+elli-2-modbus status <IP der Wallbox>
+```
+
+Du solltest Ladestatus, Spannungen und Stromgrenze sehen. Bei `cannot connect`: Ist der Modbus-Server an, die IP richtig, und sind beide Geräte im selben Netz?
+
+## Gut zu wissen
+
+- Modbus läuft **zusätzlich** zum Elli-Backend. Elli-App, OCPP und Firmware-Updates funktionieren weiter.
+- **Watchdog:** Sobald einmal Modbus-Verkehr stattgefunden hat, erwartet die Wallbox regelmäßigen Verkehr (Standard alle 15 s). Bleibt er aus, schaltet sie auf den **Failsafe-Strom**. Den bewusst setzen: `elli-2-modbus set-failsafe <ip> 0` stoppt das Laden, `6` lädt langsam weiter.
+- **Autorisierung:** Modbus setzt die Stromgrenze. Ob ein Ladevorgang zusätzlich RFID oder App-Freigabe braucht, hängt von den Wallbox-Einstellungen ab. Für vollautomatisches Laden in der Elli-App *Sofortladen* (Laden ohne Authentifizierung) aktivieren.

elli_2_modbus-0.1.0/docs/enable-modbus.md

@@ -0,0 +1,62 @@
+# Enabling Modbus TCP on an Elli Charger 2
+
+**English** | [Deutsch](enable-modbus.de.md)
+
+Applies to Elli Charger Connect 2 / Pro 2 / Pro 2 Eichrecht, VW ID. Charger 2, Škoda Charger 2 and CUPRA Charger 2. The wallbox web interface is available in English and German (it follows the browser language). Menu names below are English, with the German label in brackets.
+
+You need the **card with the access data** that came with the wallbox: Wi-Fi SSID and password, hostname, and the **service user password**.
+
+## 1. Open the charger configuration
+
+**Option A: through your home network** (the wallbox is connected by LAN or Wi-Fi)
+
+- In a browser on the same network, open `https://<hostname>` (hostname from the card) or `https://<IP of the wallbox>` (from your router's device list).
+
+**Option B: through the wallbox hotspot**
+
+- Connect to the wallbox Wi-Fi (SSID and password from the card), or scan the QR code on the card.
+- Open `https://10.0.2.1`.
+
+The browser warns about an insecure connection, because the wallbox uses a self-signed certificate. Click **Advanced** (*Erweitert*) and continue.
+
+## 2. Log in as Service User
+
+Choose the role **Service User** and enter the service user password from the card. The Standard User cannot change system settings.
+
+## 3. Check the firmware
+
+**Software update** (*Software-Update*) shows the installed version. Modbus needs **R03.004.045.121-elli or newer**. If the version is older, update first (Elli app or *Software update*).
+
+## 4. Turn on the Modbus server
+
+**Connections → Modbus server** (*Verbindungen → Modbus-Server*) → switch **Modbus server** on.
+
+| Setting | Value |
+|---|---|
+| Port | 502 |
+| Unit ID (Modbus ID) | 1 |
+
+## 5. Give the wallbox a fixed IP address
+
+Reserve the wallbox's IP in your router (DHCP reservation), or set a static address under **Connections → Ethernet** (*Verbindungen → Ethernet*) with DHCP turned off. The client must be on the same local network; this does not work over LTE.
+
+## 6. Turn off the wallbox's own PV surplus charging
+
+When something else controls the current, the wallbox should not regulate on its own at the same time:
+
+**Charging management → Charging settings → PV surplus charging → off** (*Ladeverwaltung → Ladeeinstellungen → PV-Überschuss-Laden → PV-Laden aus*).
+
+## 7. Test
+
+```bash
+pip install elli-2-modbus
+elli-2-modbus status <IP of the wallbox>
+```
+
+You should see the charging state, voltages and the current limit. If you get `cannot connect`, check that the Modbus server is on, the IP is correct and both devices are on the same network.
+
+## Good to know
+
+- Modbus runs **in addition** to the Elli backend. The Elli app, OCPP and firmware updates keep working.
+- **Watchdog:** once Modbus traffic has started, the wallbox expects regular traffic (default every 15 s). If traffic stops, it switches to the **failsafe current**. Set it deliberately: `elli-2-modbus set-failsafe <ip> 0` stops charging, `6` keeps charging slowly.
+- **Authorization:** Modbus sets the current limit. Whether a session also needs RFID or app authorization depends on the wallbox settings. For fully automatic charging, enable instant charging (charging without authentication) in the Elli app.

elli_2_modbus-0.1.0/docs/registers.md

@@ -0,0 +1,41 @@
+# Elli Charger 2 Modbus registers
+
+Source: Elli "Modbus Register" list v1.0 (15 Oct 2025), valid from firmware R03.004.045.121-elli. Download: <https://www.elli.eco/de/downloads-charger2> → *Modbus Registerliste [EN]*.
+
+Elli states that the layout follows the "Ghost" platform implementation from eSystems, which is the Heidelberg/Amperfied layout. In Elli's PDF, footnote numbers are printed directly after the addresses (e.g. `2613` = register 261, footnote 3).
+
+Modbus TCP, port 502, unit ID 1. Big-endian, 16-bit registers.
+
+## Input registers (FC 0x04)
+
+| Reg | Content | Unit / encoding |
+|---|---|---|
+| 4 | Register layout version | 0x0100 = 1.0.0 |
+| 5 | Charging state | 2=A1, 3=A2, 4=B1, 5=B2, 6=C1, 7=C2, 8=derating, 9=E, 10=F, 11=ERR |
+| 6, 7, 8 | Current L1, L2, L3 rms | 0.1 A |
+| 9 | PCB temperature | int16, 0.1 °C |
+| 10, 11, 12 | Voltage L1, L2, L3 rms | V |
+| 14 | Power L1+L2+L3 | VA |
+| 15 / 16 | Energy since power-on, high / low word | VAh (high × 65536 + low) |
+| 17 / 18 | Energy since installation, high / low word | VAh |
+| 100 | Hardware max current | A (currently 0..16)¹ |
+| 101 | Hardware min current | A¹ |
+
+Register 13 (Heidelberg: external lock) is **not** documented by Elli and is never read.
+
+## Holding registers (FC 0x03 read / 0x06 write)
+
+| Reg | Content | Unit / range | Default |
+|---|---|---|---|
+| 257 | Modbus master watchdog timeout² | ms, 0 = off | 15000 |
+| 261 | Maximal current command³ | 0.1 A: 0 or 60..160 | |
+| 262 | Failsafe current (on loss of Modbus communication)⁴ | 0.1 A: 0 or 60..160 | |
+
+Heidelberg registers 258 (standby) and 259 (remote lock) are **not** documented by Elli.
+
+## Footnotes (Elli)
+
+1. To correctly support the 22 kW variants, the value ranges will be extended to [0..32] in a future release.
+2. The timer only starts after an initial interaction between client and server (read or write).
+3. Unlike the Amperfied reference implementation, the "MaximalCurrentCommand" value can be further reduced by additional internal limit functions. Writing register 261 sets an active limit; internal automatic limits or other external EMS controls can reduce it further. A read of register 261 always shows the currently valid limit. The maximum will be raised to 32 A for the 22 kW variant.
+4. The value 0 for the error state is not supported. Later, maximum values of 32 A (= 320) will be supported here as well, for the 22 kW variant.

elli_2_modbus-0.1.0/pyproject.toml

@@ -0,0 +1,45 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "elli-2-modbus"
+version = "0.1.0"
+description = "Local Modbus TCP control of Elli Charger 2 wallboxes (VW ID. Charger 2, Škoda, CUPRA)"
+readme = "README.md"
+license = "MIT"
+license-files = ["LICENSE"]
+authors = [{ name = "Frane Bandov" }]
+requires-python = ">=3.10"
+dependencies = []
+keywords = ["elli", "wallbox", "ev-charger", "modbus", "home-assistant", "volkswagen"]
+classifiers = [
+  "Development Status :: 3 - Alpha",
+  "Framework :: AsyncIO",
+  "Intended Audience :: Developers",
+  "Operating System :: OS Independent",
+  "Programming Language :: Python :: 3",
+  "Topic :: Home Automation",
+  "Typing :: Typed",
+]
+
+[project.urls]
+Homepage = "https://github.com/frane/elli-2-modbus"
+Issues = "https://github.com/frane/elli-2-modbus/issues"
+
+[project.scripts]
+elli-2-modbus = "elli2modbus.cli:main"
+
+[project.optional-dependencies]
+test = ["pytest>=8", "pytest-asyncio>=0.23"]
+
+[tool.hatch.build.targets.wheel]
+packages = ["src/elli2modbus"]
+
+[tool.pytest.ini_options]
+asyncio_mode = "auto"
+asyncio_default_fixture_loop_scope = "function"
+testpaths = ["tests"]
+
+[tool.ruff]
+line-length = 100

elli_2_modbus-0.1.0/src/elli2modbus/__init__.py

@@ -0,0 +1,24 @@
+"""Local Modbus TCP control of Elli Charger 2 wallboxes."""
+
+from .charger import ChargerInfo, ChargerStatus, ElliCharger
+from .client import (
+    ModbusConnectionError,
+    ModbusError,
+    ModbusExceptionResponse,
+    ModbusTcpClient,
+)
+from .registers import ChargingState
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ChargerInfo",
+    "ChargerStatus",
+    "ChargingState",
+    "ElliCharger",
+    "ModbusConnectionError",
+    "ModbusError",
+    "ModbusExceptionResponse",
+    "ModbusTcpClient",
+    "__version__",
+]

elli_2_modbus-0.1.0/src/elli2modbus/__main__.py

@@ -0,0 +1,3 @@
+from .cli import main
+
+raise SystemExit(main())