Modbus Schnittstellenbeschreibung eingefügt

.gitignore

@@ -0,0 +1,5 @@
+# Python virtual environment
+.venv/
+
+# Exclude build folder
+build/

Makefile

@@ -0,0 +1,20 @@
+# Minimal makefile for Sphinx documentation
+#
+
+# You can set these variables from the command line, and also
+# from the environment for the first two.
+SPHINXOPTS    ?=
+SPHINXBUILD   ?= sphinx-build
+SOURCEDIR     = source
+BUILDDIR      = build
+
+# Put it first so that "make" without argument is like "make help".
+help:
+	@$(SPHINXBUILD) -M help "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)
+
+.PHONY: help Makefile
+
+# Catch-all target: route all unknown targets to Sphinx using the new
+# "make mode" option.  $(O) is meant as a shortcut for $(SPHINXOPTS).
+%: Makefile
+	@$(SPHINXBUILD) -M $@ "$(SOURCEDIR)" "$(BUILDDIR)" $(SPHINXOPTS) $(O)

README.md

@@ -0,0 +1,2 @@
+# How to build
+    make.bat html

make.bat

@@ -0,0 +1,35 @@
+@ECHO OFF
+
+pushd %~dp0
+
+REM Command file for Sphinx documentation
+
+if "%SPHINXBUILD%" == "" (
+	set SPHINXBUILD=sphinx-build
+)
+set SOURCEDIR=source
+set BUILDDIR=build
+
+%SPHINXBUILD% >NUL 2>NUL
+if errorlevel 9009 (
+	echo.
+	echo.The 'sphinx-build' command was not found. Make sure you have Sphinx
+	echo.installed, then set the SPHINXBUILD environment variable to point
+	echo.to the full path of the 'sphinx-build' executable. Alternatively you
+	echo.may add the Sphinx directory to PATH.
+	echo.
+	echo.If you don't have Sphinx installed, grab it from
+	echo.https://www.sphinx-doc.org/
+	exit /b 1
+)
+
+if "%1" == "" goto help
+
+%SPHINXBUILD% -M %1 %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+goto end
+
+:help
+%SPHINXBUILD% -M help %SOURCEDIR% %BUILDDIR% %SPHINXOPTS% %O%
+
+:end
+popd

source/_static/theme_overrides.css

@@ -0,0 +1,8 @@
+.bd-main .bd-content .bd-article-container {
+  max-width: 100%;   /*default is 60em */
+}
+
+.bd-page-width {
+  max-width: 100%;   /*default is 88rem */
+
+}

source/conf.py

@@ -0,0 +1,44 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# For the full list of built-in configuration values, see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Project information -----------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#project-information
+
+project = 'Uniper'
+copyright = '2025, M.Heisig'
+author = 'M.Heisig'
+
+# -- General configuration ---------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#general-configuration
+
+extensions = []
+
+templates_path = ['_templates']
+exclude_patterns = []
+
+language = 'de'
+
+# -- Options for HTML output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output
+
+#html_theme = 'alabaster'
+#html_theme = "sphinx_rtd_theme"
+html_theme = "pydata_sphinx_theme"
+html_static_path = ['_static']
+html_css_files = [
+    'theme_overrides.css',
+]
+
+html_theme_options = {
+   # ...
+   #"navbar_align": "left"
+   # ...
+}
+
+# -- Options for latex output -------------------------------------------------
+# https://www.sphinx-doc.org/en/master/latex.html
+latex_elements = {
+    'papersize': 'a4paper',
+}

source/general_overview/changelog.rst

@@ -0,0 +1,13 @@
+.. include:: ./../macros.txt
+.. include:: ./../units.txt
+
+.. _changelog:
+
+#########
+Changelog
+#########
+
+Alle Versionsänderung bei den Schnittstellen und am BMS werden hier dokumentiert und aufgelistet.
+
+Die Version wird nach dem folgendem Muster aufgebaut. ``MAJOR.MINOR.PATCH``, wobei ``MAJOR``,
+``MINOR`` und ``PATCH`` aus Zahlen bestehen.

source/index.rst

@@ -0,0 +1,73 @@
+.. include:: ./macros.txt
+.. include:: ./units.txt
+
+.. Uniper Dokumentation documentation master file, created by
+   sphinx-quickstart on Tue May 13 11:42:50 2025.
+   You can adapt this file completely to your liking, but it should at least
+   contain the root `toctree` directive.
+
+Uniper Dokumentation
+====================
+
+Willkommen zur Dokumentation des Uniperprojektes.
+
+.. note::
+
+   Die aktuelle Version der Dokumentation wurde generiert am |timestamp|.
+
+.. warning::
+
+   Der aktuelle Stand der Schnittstellen zwischen BMS und EMS, sowie über diese übermittelten Fehlermdeldungen,
+   sind noch nicht final und können sich noch ändern.
+
+Die Dokumentation gliedert sich in folgende Teile:
+
+#. Generelle Übersicht
+#. Betriebsmodi
+#. OPC-UA Schnittstellenbeschreibung
+#. Modbus-TCP/IP Schnittstellenbeschreibung
+#. Fehlermeldungen
+#. Entwickler Handbuch
+
+Der erste Teil soll ein Bild über das gesamte System vermitteln:
+
+- Wie ist die Batterie aufgebaut
+- Welche Sicherheitsfunktionen sind vorhanden
+- Wie ist die Kommunikation zwischen den einzelnen Komponenten geregelt
+
+Der zweite Teil handelt von den möglichen Betriebsarten der Batterie:
+
+- Automatik Remote
+- Automatik Lokal
+- Manuell
+- Balancing
+- Safety Check
+
+Im drittel Teil wird die zur verfügung gestellte OPC-UA-Schnittstelle beschrieben:
+
+- Verbindung zum OPC-UA-Server aufbauen
+- Welche Werte können gelesen werden und was bedeuten sie
+
+Im vierten Teil wird die Kommunikationsschnittstelle zwischen BMS und EMS beschrieben
+
+- Allgemeine Verbindungsparameter
+- Registerbeschreibungen
+- Watchdog
+- Verhalten bei Verbindungsabbruch
+
+Der fünfte Teil handelt von den möglichen auftretenden Fehlern und wie sie zu beheben sind:
+
+- Fehlermeldungen vom BMS an das EMS
+- Fehlermeldungen per OPC-UA-Server
+
+Der letzte Teil ist für die CMBlu eigenen Entwickler gedacht und beschreibt die Coding- und 
+Dokumentations-Regeln
+
+Alle genannten Abschnitte sind hier zu finden:
+
+.. toctree::
+   :maxdepth: 2
+   :caption: Contents:
+
+   ./general_overview/changelog
+   ./modbus/EMS_Schnittstelle

source/macros.txt

@@ -0,0 +1,10 @@
+.. include:: <isonum.txt>
+
+.. |timestamp| date:: %Y-%m-%d %H:%M:%S
+
+.. |uniper_repository| replace:: https://gitea.heisig-gmbh.de/
+
+.. |DC+|  replace:: ``DC+``
+.. |DC-|  replace:: ``DC-``
+
+.. |git| replace:: Git

source/modbus/EMS_Schnittstelle.rst

@@ -0,0 +1,115 @@
+#################
+EMS-Schnittstelle
+#################
+Allgemeine Informationen zu der Schnittstelle zwischen BMS und EMS:
+
+* Das Interface wir düber Modbus-TCP/IP abgebildet
+* Das EMS wird vom Kunden zur Verfügung gestellt
+* Das BMS wird von der CMBlu Energy AG bereitgestellt
+* Alle Register können über die Modbus-Funktion 0x03 "Read Holding Register" gelesen und die Funktion 0x06 "Write Single Register" oder 0x10 "Write Multiple Registers" geschrieben werden.
+  Dabei ist auf die in den Tabellen angegebene Lese und Schreibberechtigung zu achten.
+* Alle Strings sind im ASCII-Format
+* Alle Register haben die byte order: Big Endian
+* Die Pollrate des EMS sollte nicht kleiner sein als 200 ms
+* Der Adressbereicht ist: 10.000...16.000
+
+
+**********
+Datentypen
+**********
+.. csv-table:: Datentypen
+    :file: tables/datatypes.csv
+    :header-rows: 1
+
+
+********************
+Interface Definition
+********************
+.. csv-table:: Modbus Register
+    :file: tables/interface.csv
+    :header-rows: 1
+
+
+********************
+Enum Werte
+********************
+
+.. list-table:: Battery status
+    :header-rows: 0
+
+    * - ERROR
+      - 1
+    * - OFF
+      - 2
+    * - READY
+      - 3
+    * - ACTIVE
+      - 4
+    * - MAINTENANCE
+      - 5
+    * - TESTING
+      - 6
+
+.. list-table:: Charge status
+    :header-rows: 0
+
+    * - UNDEFINED
+      - 1
+    * - EMPTY
+      - 2
+    * - CHARGING
+      - 3
+    * - DISCHARGING
+      - 4
+    * - FULL
+      - 5
+
+.. list-table:: Reactive Power Type
+    :header-rows: 0
+
+    * - INDUCTIVE
+      - 1
+    * - CAPACITIVE
+      - 2
+    * - NONE
+      - 3
+
+
+*********************************
+Fehlermeldungen Registerübersicht
+*********************************
+.. csv-table:: Übersicht Fehler und Warnungen BMS
+    :file: tables/FW_Uebersicht_BMS.csv
+    :header-rows: 1
+
+.. csv-table:: Übersicht Warnungen Units
+    :file: tables/Warnungen_Uebersicht_Units.csv
+    :header-rows: 1
+
+.. csv-table:: Übersicht Fehler Units
+    :file: tables/Fehler_Uebersicht_Units.csv
+    :header-rows: 1
+
+
+*********************************************
+Registerbeschreibung Fehler und Warnungen BMS
+*********************************************
+.. csv-table:: Aktive BMS Warnungen - Register 13.000
+  :file: tables/Reg_13000_detail.csv
+  :header-rows: 1
+
+.. csv-table:: Aktive BMS Fehler - Register 13.001
+  :file: tables/Reg_13001_detail.csv
+  :header-rows: 1
+
+
+***********************************************
+Registerbeschreibung Fehler und Warnungen Units
+***********************************************
+.. csv-table:: Aktive Unit Warnungen - Register 14.000 - 14.046
+  :file: tables/Reg_14000_detail.csv
+  :header-rows: 1
+
+.. csv-table:: Aktive Unit Fehler - Register 15.000 - 15.046
+  :file: tables/Reg_15000_detail.csv
+  :header-rows: 1

source/modbus/tables/FW_Uebersicht_BMS.csv

@@ -0,0 +1,6 @@
+"Startadresse", "Größe (WORD)", "Name", "Typ", "Beschreibung"
+13000,1,"BMSWarnings","WORD","Aktive BMS Warnungen"
+13001,1,"BMSErrors","WORD","Aktive BMS Fehler"
+13002,1,"StringWarnings","WORD","Liste der Strings mit aktiven Warnungen (Bit 0 -> String 1, Bit 1 -> String 2, etc.)"
+13003,1,"StringErrors","WORD","Liste der Strings mit aktiven Fehlern (Bit 0 -> String 1, Bit 1 -> String 2, etc.)"
+13004,1,"ConfirmAlarms","WORD","Durch schreiben einer 1 in diese Register werden die Alarme quittiert"

source/modbus/tables/Fehler_Uebersicht_Units.csv

@@ -0,0 +1,5 @@
+"Startadresse", "Größe (WORD)", "Name", "Typ", "Beschreibung"
+15000,2,"Unit 1 active errors","DWORD","Bitmap mit den aktiven fehlern der Unit 1"
+15002,2,"Unit 2 active errors","DWORD","Bitmap mit den aktiven fehlern der Unit 2"
+"...",,,,
+15046,2,"Unit 24 active errors","DWORD","Bitmap mit den aktiven fehlern der Unit 24"

source/modbus/tables/Reg_13000_detail.csv

@@ -0,0 +1,17 @@
+"Bit", "Beschreibung"
+0, "Nicht alle Komponeten im Automatikmodus"
+1, "Safetyinterlock String 1 aktiv"
+2, "Safetyinterlock String 2 aktiv"
+3, ""
+4, ""
+5, ""
+6, ""
+7, ""
+8, ""
+9, ""
+10, ""
+11, ""
+12, ""
+13, ""
+14, ""
+15, ""

source/modbus/tables/Reg_13001_detail.csv

@@ -0,0 +1,17 @@
+"Bit", "Beschreibung"
+0, "E-Stop nicht ok"
+1, "EtherCAT Kommunikationsfehler"
+2, "DC-Hauptschater String 1 nicht geschlossen"
+3, "DC-Hauptschater String 2 nicht geschlossen"
+4, "Allgemeiner Fehler"
+5, ""
+6, ""
+7, ""
+8, ""
+9, ""
+10, ""
+11, ""
+12, ""
+13, ""
+14, ""
+15, ""

source/modbus/tables/Reg_14000_detail.csv

@@ -0,0 +1,17 @@
+"Bit", "Beschreibung"
+0, "Temperatur Negolyt zu gering"
+1, "Temperatur Negolyt zu hoch"
+2, "Temperatur Posolyt zu gering"
+3, "Temperatur Posolyt zu hoch"
+4, "Druck Segmenteinlass Negolyt zu gering"
+5, "Druck Segmenteinlass Negolyt zu hoch"
+6, "Druck Segmenteinlass Posolyt zu gering"
+7, "Druck Segmenteinlass Posolyt zu hoch"
+8, "Druck Tanke Negolyt zu gering"
+9, "Druck Tank Negolyt zu hoch"
+10, "Druck Tank Posolyt zu gering"
+11, "Druck Tank Posolyt zu hoch"
+12, "Segmentspannung zu gering"
+13, "Segmentspannung zu hoch"
+14, ""
+15, ""

source/modbus/tables/Reg_15000_detail.csv

@@ -0,0 +1,33 @@
+"Bit", "Beschreibung"
+0, "Temperatur Negolyt zu gering"
+1, "Temperatur Negolyt zu hoch"
+2, "Fehler Temperatursensor Negolyt"
+3, "Temperatur Posolyt zu gering"
+4, "Temperatur Posolyt zu hoch"
+5, "Fehler Temperatursensor Posolyt"
+6, "Druck Segmenteinlass Negolyt zu gering"
+7, "Druck Segmenteinlass Negolyt zu hoch"
+8, "Fehler Drucksensor Segmenteinlass Negolyt"
+9, "Druck Segmenteinlass Posolyt zu gering"
+10, "Druck Segmenteinlass Posolyt zu hoch"
+11, "Fehler Drucksensor Segmenteinlass Posolyt"
+12, "Druck Tanke Negolyt zu gering"
+13, "Druck Tank Negolyt zu hoch"
+14, "Fehler Drucksensor Tank Negolyt"
+15, "Druck Tank Posolyt zu gering"
+16, "Druck Tank Posolyt zu hoch"
+17, "Fehler Drucksensor Tank Posolyt"
+18, "Segmentspannung zu gering"
+19, "Segmentspannung zu hoch"
+20, "Fehler Sensor Segmentspannung"
+21, "Fehler Ventil Negolyt"
+22, "Fehler Ventil Posolyt"
+23, "Fehler Pumpe Negolyt"
+24, "Fehler Pumpe Posolyt"
+25, "Leckage an Unit"
+26, "Software Safetyinterlocks aktiv"
+27, ""
+28, ""
+29, ""
+30, ""
+31, ""

source/modbus/tables/Warnungen_Uebersicht_Units.csv

@@ -0,0 +1,5 @@
+"Startadresse", "Größe (WORD)", "Name", "Typ", "Beschreibung"
+14000,2,"Unit 1 active warnings","DWORD","Bitmap mit den aktiven warnungen der Unit 1"
+14002,2,"Unit 2 active warnings","DWORD","Bitmap mit den aktiven warnungen der Unit 2"
+"...",,,,
+14046,2,"Unit 24 active warnings","DWORD","Bitmap mit den aktiven warnungen der Unit 24"

source/modbus/tables/datatypes.csv

@@ -0,0 +1,12 @@
+Name ,Größe (WORD),Beschreibung,Bereich
+INT16 ,1,16-bit signed integer,-32.768...+32.767
+UINT16 ,1,16-bit unsigned integer,0...65.535
+INT32 ,2,32-bit signed integer,-2.147.483.648...+2.147.483.647
+UINT32 ,2,32-bit unsigned integer,0...4.294.967.295
+INT64 ,4,64-bit signed integer,-9.223.372.036.854.775.808...9.223.372.036.854.775.807
+UINT64 ,4,64-bit unsigned integer,0 to 18.446.744.073.709.600.000
+FLOAT32 ,2,"32-bit; Single precision float mit Vorzeichen bit, 8 bits Exponent,
+23 bits Mantisse",-3.4028E+38...+3.4028E+38
+ENUM16 ,1,Unsigned Integer 16; Decimalwert entspricht einem enum Wert ,
+ASCII ,1...n ,"Eine Zeichenkette aus ASCII Zeichen, welche  aus 1..n Register belegt; Byte order ist Big Endian; 2 ASCII Zeichen passen in 1 Register;",
+BITMAP ,1...n ,"Ein zusammengesetztes bitfeld, welches 1..n Register Belegt, Gelesen von rechts nach links",

source/modbus/tables/interface.csv

@@ -0,0 +1,36 @@
+Start Adresse, Größe (WORD), Name, Typ, EMS Access, BMS Access, Einheit, Beschreibung, Kommentar
+10000,16, Manufacturer, ASCII, R, RW, ,Batterie Hersteller Name, ""
+10016,16, Modell Name, ASCII, R, RW, ,Batterie Modell, ""
+10032,16, Serial Number, ASCII, R, RW, ,Batterie Seriennummer, ""
+10048,32, BMS Version, ASCII, R, RW, , BMS Version, ""
+10080,1, Total Parallel Members, UINT16, R, RW, ,"Anzahl aller parallel verschalteten Strings", ""
+10081,1, Active Parallel Members, UINT16, R, RW, ,"Anzahl der aktuell aktiven parallel veschalteten Strings", ""
+11000,1, Battery Status, ENUM16, R, RW, ,Batterie Status (Siehe 'Enum & Bitmap Values'), ""
+11001,1, Charge Status, ENUM16, R, RW, , Lade Status (Possible values in the table 'Enum & Bitmap Values'), ""
+11002,1, Self discharge rate, UINT16, R, RW, %, Selbstentladerate in Prozent der gesamtkapazität (WHRtg) pro Tag, "Nicht implementiert"
+11003,1, Max allowed SoC, UINT16, R, RW, %, "Maximaler SoC in abhägigkeit der gerade verwendeten Ladeleistung", "Nicht implementiert"
+11004,1, Min allowed SoC, UINT16, R, RW, %, "Minimaler SoC in abhägigkeit der gerade verwendeten Entladeleistung", "Nicht implementiert"
+11005,1, Current SoC, UINT16, R, RW, %, "State of charge", "Nicht implementiert"
+11006,1, Current DoD, UINT16, R, RW, %, "Depth of discharge", "Nicht implementiert"
+11007,1, Current SoH, UINT16, R, RW, %, "Aktueller Gesundheitszustand der Batterie (100% = Neu)", "Nicht implementiert"
+11008,2, Charge Capacity, UINT32, R, RW, Ah,"Ladekapazität in Amperestunden in abhängigkeit der aktuellen Ladeleistung",Nicht implementiert
+11010,2, Energy Capacity, UINT32, R, RW, Wh,"Energiekapazität in Wattstunden in abhängigkeit der aktuellen Ladeleistung",Nicht implementiert
+11012,2, Max Charging Active Power, UINT32, R, RW, W,"Maximale zulässige Ladeleistung", ""
+11014,2, Max Discharging Active Power, UINT32, R, RW, W,"Maximal zulässige Entladeleistung", ""
+11016,2, Max Available Inductive Reactive Power, UINT32, R, RW, var,"Maximal zulässige induktive Blindleistung", ""
+11018,2, Max Available Capacitive Reactive Power, UINT32, R, RW, var,"Maximal zulässige kapazitive Blindleistung", ""
+11020,2, Charged energy, UINT32, R, RW, Wh, "Geladene Energie", ""
+11022,2, Available energy, UINT32, R, RW, Wh,"Maximal verfügbare Energie",Nicht implementiert
+11024,2, Total AC Current Phase 1, INT32, R, RW, A, "AC Summenstrom aller Umrichter für Phase 1", ""
+11026,2, Total AC Current Phase 2, INT32, R, RW, A, "AC Summenstrom aller Umrichter für Phase 2", ""
+11028,2, Total AC Current Phase 3, INT32, R, RW, A, "AC Summenstrom aller Umrichter für Phase 3", ""
+11030,2, Setpoint Active Power Mirror, INT32, R, RW, W, "Von 'Setpoint Active Power' empfangener, umkopierter Wert", ""
+11032,2, Setpoint CosPhi Mirror,FLOAT32, R, RW, , "Von 'Setpoint CosPhi' empfangener, umkopierter Wert", ""
+11034,2, Current Active Power, INT32, R, RW, W, "Aktuelle Wirkleistung der Gesamtbatterie. Ein positiver Wert bedeutet, dass die Batterie Entladen wird. Ein negativer, dass die Batterie geladen wird.", ""
+11036,2, Current Reactive Power, INT32, R, RW, var,"Aktuelle Blindleistung der Gesamtbatterie. Ein positiver Wert steht für induktive  und ein negativer für Kapazitive Blindleistung", ""
+11038,2, Life Message, UINT32, R, RW, , "Lebenszeichen vom BMS. Wird jeden aktiven Kommunikationszyklus über die Modbus-Schnittstelle inkrementiert. Kann zur Erkennung von Kommunikationsausfällen genutzt werden.", ""
+11040,4, Warning Bitmap, BITMAP, R, RW, ,"Bitmaske mit Warnung", "Obsolet"
+11044,4, Error Bitmap, BITMAP, R, RW, ,"Bitmaske mit Fehlern", "Obsolet"
+12000,2, Setpoint Active Power, INT32, RW, R, W, "Leistungsvorgabe des EMS an das BMS. Negative Leistungsvorgabe zum Laden der Batterie und positive zum Entladen", ""
+12002,2, Setpoint CosPhi, FLOAT32, RW, R, , "Blindleistungsvorgabe des EMS an das BMS per CosPhi","Nicht implementiert, da keine Blidleistung erlaubt ist"
+12004,1, Reactive Power Type, ENUM16, RW, R, ,"Gibt vor, welche Art von Blindleistung, 'Induktiv', 'Kapaziziv' oder 'Keine' vom BMS eingestellt werden soll","Nicht implementiert, da keine Blidleistung erlaubt ist"

source/units.txt

@@ -0,0 +1,9 @@
+.. newline    This define creates a non-breaking whitespace
+.. |_| unicode:: 0xA0
+   :trim:
+
+.. |W| replace:: W
+.. |V| replace:: V
+.. |kW| replace:: kW
+.. |Wh| replace:: Wh
+.. |kWh| replace:: kWh