diff --git a/LICENSE b/LICENSE new file mode 100644 index 0000000..593d148 --- /dev/null +++ b/LICENSE @@ -0,0 +1,77 @@ +Pylontech Console Community License (Nicht-kommerzielle Nutzung) + +Copyright (c) 2026 Zoltán Hrabovszki + +1. Begriffe + +- "Software": das Projekt "Pylontech Console" samt zugehöriger Quell- und + Binärdateien, Dokumentation und ausgelieferter Container-Images. +- "Nicht-kommerzielle Nutzung": jede Nutzung zu privaten, akademischen oder + öffentlich zugänglichen, nicht-kommerziellen Zwecken ohne direkten oder + indirekten Umsatzbezug sowie die reine Evaluierung oder ein Proof of Concept. +- "Kommerzielle Nutzung": jede Nutzung in oder für ein Produkt, einen Service + oder einen Prozess, der direkt oder indirekt Einnahmen generiert oder einer + geschäftlichen Tätigkeit dient. Dazu gehören insbesondere bezahlte Projekte, + Installationen oder Supportleistungen, Firmenbetrieb für kommerzielle Zwecke, + SaaS, Resale sowie kommerziell verwendete Originale, Änderungen, Forks und + abgeleitete Werke. Für kommerzielle Nutzung ist eine gesonderte kommerzielle + Lizenz erforderlich. + +2. Lizenzgewährung (nicht-kommerziell) + +Der Rechteinhaber gewährt eine weltweite, nicht-exklusive, nicht übertragbare, +unentgeltliche Lizenz zur Nutzung, Vervielfältigung, Änderung und Weitergabe +der Software ausschließlich für nicht-kommerzielle Zwecke, vorausgesetzt, dass +(a) dieser Lizenztext in Kopien und abgeleiteten Werken enthalten bleibt und +(b) Urheber- und Hinweistexte nicht entfernt werden. + +3. Einschränkungen + +- Kommerzielle Nutzung ist ohne kommerzielle Lizenz untersagt. +- Marken- und Namensrechte werden nicht gewährt. +- Unterlizenzierung ist nur unter Beibehaltung dieser Bedingungen zulässig. +- Die Nutzung eines Forks, einer Änderung oder eines abgeleiteten Werks zu + kommerziellen Zwecken erfordert ebenfalls eine gesonderte kommerzielle + Lizenz des Rechteinhabers. + +4. Support + +Es besteht kein Anspruch auf Wartung, Support oder Updates. + +5. Gewährleistungsausschluss + +Die Software wird "wie besehen" ("AS IS") bereitgestellt, ohne ausdrückliche +oder stillschweigende Gewährleistung. Insbesondere wird keine Gewähr für +Marktgängigkeit, Eignung für einen bestimmten Zweck, Nichtverletzung von +Rechten Dritter, Fehlerfreiheit, Richtigkeit oder Verfügbarkeit übernommen. + +6. Haftungsbeschränkung + +Soweit gesetzlich zulässig, haften der Rechteinhaber und Mitwirkende in keinem +Fall für Schäden jedweder Art (einschließlich, aber nicht beschränkt auf +direkte, indirekte, zufällige, besondere, exemplarische oder Folgeschäden, +entgangenen Gewinn, Produktions- oder Betriebsunterbrechung, Datenverlust oder +Rechtsverfolgungskosten), die aus der Nutzung, Unmöglichkeit der Nutzung oder +Leistung der Software entstehen, selbst wenn auf die Möglichkeit solcher +Schäden hingewiesen wurde. + +Unberührt bleiben zwingende Haftungstatbestände (z. B. nach dem +Produkthaftungsgesetz) sowie die Haftung für Vorsatz, grobe Fahrlässigkeit oder +für Verletzungen von Leben, Körper oder Gesundheit nach geltendem Recht. + +7. Laufzeit und Beendigung + +Diese Lizenz gilt bis zu ihrer Beendigung. Bei Verstoß erlischt das +Nutzungsrecht automatisch; die Nutzung ist einzustellen. Rechte an bereits +rechtmäßig weitergegebenen Kopien bleiben unberührt. + +8. Sonstiges + +Es gilt materielles Recht des Sitzstaats des Rechteinhabers unter Ausschluss +des Kollisionsrechts. Sollte eine Bestimmung unwirksam sein, bleibt der Rest +wirksam (Salvatorische Klausel). + +Kommerzielle Lizenz + +Für eine kommerzielle Nutzung (siehe Abschnitt 1) wenden Sie sich bitte an den +Rechteinhaber, um Konditionen und Lizenzgebühren zu vereinbaren. diff --git a/README.md b/README.md index 62ae673..7933e79 100644 --- a/README.md +++ b/README.md @@ -1,6 +1,7 @@ # Pylontech Console -Open documentation and reference implementation for the undocumented Pylontech RS232 debug console. +Source-available, read-only monitoring for the undocumented Pylontech RS232 +debug console. ## Goal @@ -67,7 +68,24 @@ Development starts with: - Reverse engineering completed. - Core protocol documented. - Architecture defined. -- Implementation ready to start. +- Production service implemented with REST, Web UI and MQTT. +- Running on a five-module mixed Pylontech US2000/US2000C rack. +- Published `linux/amd64` Docker images available from Docker Hub. + +## Tested hardware + +The verified reference installation uses: + +- two Pylontech US2000 modules; +- three Pylontech US2000C modules; +- 15 cells per module and 75 cells in total; +- a Waveshare RS232/485/422 TO POE ETH (B) serial device server; +- Docker on a Proxmox-hosted `linux/amd64` server; +- optional MQTT publishing to ioBroker. + +Other Pylontech models, serial adapters and container architectures are not yet +verified. See [`docs/hardware.md`](docs/hardware.md) for the exact compatibility +statement and [`docs/wiring.md`](docs/wiring.md) for the tested cable. ## Safety @@ -118,3 +136,11 @@ The published container is configured with the same validated `PYLONTECH_WAVESHARE_*`, `PYLONTECH_HTTP_*`, `PYLONTECH_WEB_*` and `PYLONTECH_MQTT_*` environment variables used by Docker Compose. Images currently target `linux/amd64`. + +## License + +Pylontech Console is source-available software. Private, academic and other +non-commercial use is permitted under the +[Pylontech Console Community License](LICENSE). Commercial products, services, +installations, support, internal business use, forks and derived works require +a separate commercial license from the rights holder. diff --git a/docs/README.md b/docs/README.md index 15a2f76..548beff 100644 --- a/docs/README.md +++ b/docs/README.md @@ -2,10 +2,14 @@ This directory contains the technical documentation for connecting to and operating the Pylontech debug console. -Planned documents: +Available documents: -- `hardware.md` — supported modules, ports and reference hardware; +- `hardware.md` — verified modules, deployment platform and explicit + compatibility limits; - `wiring.md` — RJ45 console and DB9 pinout; + +Planned documents: + - `waveshare.md` — transparent RS232-over-TCP configuration; - `console-access.md` — terminal settings and connection test; - `architecture.md` — integration with ioBroker, MQTT and Modbus TCP; diff --git a/docs/hardware.md b/docs/hardware.md new file mode 100644 index 0000000..1e10106 --- /dev/null +++ b/docs/hardware.md @@ -0,0 +1,66 @@ +# Tested hardware and compatibility + +This document distinguishes hardware verified on a real battery rack from +hardware that may use a similar protocol but has not been tested. + +## Verified battery rack + +Pylontech Console has been verified with one operational five-module rack +containing both module generations: + +| Module | Quantity | Identification observed by the console | +|---|---:|---| +| Pylontech US2000 | 2 | `US2KBPL` | +| Pylontech US2000C | 3 | `US2000C` | + +The mixed rack has 15 cells per module and 75 cells in total. The application +successfully verifies: + +- automatic discovery of all five positions; +- stable module identity by barcode; +- rack, module-detail and all 15 per-cell measurements; +- mixed US2000 and US2000C operation in one discovered topology; +- read-only Web UI and cell-voltage heatmap; +- read-only REST API; +- publish-only MQTT integration with ioBroker. + +This compatibility statement describes the observed monitoring behavior. It +does not constitute approval to combine battery models in a rack. Battery +selection, interconnection and operation must follow the Pylontech +documentation and the requirements of the complete electrical installation. + +## Verified serial device server + +| Component | Verified value | +|---|---| +| Device | Waveshare RS232/485/422 TO POE ETH (B) | +| Battery-side interface | RS232 | +| Network transport | transparent TCP | +| TCP port | configurable; tested with `4196` | +| Serial settings | 115200 baud, 8 data bits, no parity, 1 stop bit, no flow control | + +The physical reference connection uses the console port of the rack's +US2000C master module. See [wiring.md](wiring.md) for the verified RJ45-to-DB9 +pinout and the warning that the battery console connector is not Ethernet. + +## Verified deployment platform + +- Docker Engine with Docker Compose; +- Proxmox-hosted dedicated Docker server; +- published container architecture: `linux/amd64`; +- optional MQTT broker provided by an ioBroker MQTT adapter. + +## Not yet verified + +No compatibility claim is currently made for: + +- Pylontech models other than US2000 and US2000C; +- racks with a cell count other than 15 cells per module; +- USB serial adapters or serial device servers other than the tested + Waveshare model; +- container architectures other than `linux/amd64`; +- direct CAN, RS485 battery protocol or inverter communication. + +Similar Pylontech products may expose related console commands, but they must +be treated as unsupported until real captures and a read-only hardware test +confirm parser and acquisition compatibility.