iobroker.bydhvs 1.4.2 → 1.5.2

package/CHANGELOG_OLD.md

@@ -1,4 +1,21 @@
 # Older changes
+## 1.4.0 (2022-10-31)
+* Update of referred modules (mainly around testing)
+* improvmenets contributed by Tapter (5 modules, readme and better readable code)
+* Better detection of battery type and inverter
+* SOC not only from normal data but from diagnosis-data, too. There we have one decimal place more
+* removed frequency limit for battery detail data
+* increased max count of temperature measurements for HVS to 64
+* support for up to 5 HVS modules
+
+## 1.3.0 (2021-11-06)
+* updated even more dependencies
+* official release with new state SOH
+
+## 1.2.4-0 (2021-11-02)
+* Added state: SOH
+* updated dependencies as suggested from bot
+
 ## 1.2.3 (2021-06-18)
 * changed ratio of logo
 

package/LICENSE

@@ -1,21 +1,21 @@
-MIT License
-
-Copyright (c) 2021 Christian <github@familie-herrmann.de>
-
-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.
+MIT License
+
+Copyright (c) 2025 Christian <github@familie-herrmann.de>
+
+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.

package/README-German.md

@@ -0,0 +1,21 @@
+
+
+## Ein wenig Erklärungen:
+
+Prinzipiell ist der Adapter durch Anaylse der Datenpakete zwischen der BYD-App und dem BYD-Akku-System entstanden. Es werden im Wesentlichen die Daten aus dem TAB System Info und aus dem TAB Diagnosis dargestellt. Offensichtlich sind die Daten für "System Info" sofort in der Batterie bereit zum abholen, für die Diagnose-Daten sieht es so aus als wäre ein Messvorgang erforderlich, zwischen der Abfrage und den Werten muss ein Zeitintervall von gut 3 Sekunden eingehalten werden. 
+
+Ich bin mir nicht sicher ob das BYD-System durch zu häufige Abfragen beschädigt wird, also: Es ist Dein Risiko was Du hier einträgst!
+
+## Zu den Einstellungen:
+Intervall: Zeitlicher Abstand zwischen den Abfragen des Adapters
+
+IP-Adresse: Eigentlich logisch, damit ist die IP-Adresse des Adapters gemeint. Dafür gibt es zwei Möglichkeiten: Entweder hält man sich an die Anleitung von Becker3 aus dem Photovoltaik-Forum, ist hier verlinkt: https://www.photovoltaikforum.com/thread/150898-byd-hvs-firmware-update/?postID=2215343#post2215343 . Das hat den Vorteil das auch die BYD-APP läuft und man mit dieser direkt an die Daten, auch zum Vergleich, herankommt. Oder man trägt "nur" die IP-Adresse die die BYD-Box per DHCP erhalten hat ein. Ausdrücklich waren möchte ich vor Änderungen an den IP-Einstellungen der BOX! Im Forum kann man Berichte von Leute lesen die sich die Erreichbarkeit der Box dauerhaft ruiniert haben. 
+
+Batterie-Details: Steuerung, ob die Details zu den Zellen gelesen werden sollen
+
+Lesezyklen zu Batterie-Details: Anzahl der "Normal-Lese-Zyklen" bis wieder einmal die Diagnose-Daten gelesen werden. Hier die Warnung dazu: Ich habe keine Idee ob man sich durch häufige Diagnose-Messungen Nachteile einhandelt, daher empfehle ich den Wert möglichst hoch zu setzen. Ich wüsste auch nicht was man mit den Diagnose-Daten im regelmäßigen Poll anfangen sollte. 
+
+Zu den Batterie-Größen: Der Adapter funktioniert für Zelltemperaturen und ZellSpannungen bei 2-5 Batterie-Modulen. 
+
+[Zurück zur automatisch übersetzten Readme](README.md)
+

package/README.md

@@ -4,11 +4,9 @@
 
 BYD HVS Battery poll data
 
-## English:
-
 ## Introduction
 
-This Adapter takes data from a byd PV battery ( https://www.bydbatterybox.com/ ) and puts them into datapoints in the adapter. Unfortunately there is no official API and no documentation, so I used wireshark and a byd-hvs-simulator to try to understand the communication. My adapter simulates the byd-app, sends similar packets to the device and analyses the responses. 
+This Adapter takes data from a byd PV battery ( https://www.bydbatterybox.com/ ) and puts them into datapoints in the adapter. Unfortunately there is no official API and no documentation, so I used wireshark and a byd-hvs-simulator to try to understand the communication. My adapter simulates the byd-app, sends similar packets to the device and analyses the responses.
 
 ## be careful
 
@@ -21,38 +19,35 @@ Up to 5 HVS Modules are now supported.
 ## settings
 
 Interval: That's easy: how often (s) shall the data be polled
-IP-Adress: Thats self explaining. Either you use the standard address ( 192.168.16.254 ) and change the routing at home, e.g.: https://www.photovoltaikforum.com/thread/150898-byd-hvs-firmware-update/?postID=2215343#post2215343 . The advantage is: The beConnect app works, too. Other possibility: You change the IP-Adress of the box. But: Be warned: the text on the webpage is confusing and if you are not absolutely shure about the things you do: PLEASE do not touch the settings. In the German forums I read from people who were locked out of their system and there is no way back, either byd sends you a replacement HVU or you have to buy a new one. 
+IP-Adress: Thats self explaining. Either you use the standard address ( 192.168.16.254 ) and change the routing at home, e.g.: https://www.photovoltaikforum.com/thread/150898-byd-hvs-firmware-update/?postID=2215343#post2215343 . The advantage is: The beConnect app works, too. Other possibility: You change the IP-Adress of the box. But: Be warned: the text on the webpage is confusing and if you are not absolutely shure about the things you do: PLEASE do not touch the settings. In the German forums I read from people who were locked out of their system and there is no way back, either byd sends you a replacement HVU or you have to buy a new one.
 Battery-details: As explained above: Do you need the details of the battery? If so: set the checkobx.
 Battery-details - every ... cycles :Also like above, should be clear
 Test Mode - show data in error log: If you check this box: the sent and recieved data are displayed in the error-log, so you can easily download the data and send it to me in case of errors.
+Copy and Paste does not work - the data is cut at the end. You will have to download it before you send it to me.
 
-
-## German:
-
-
-## Ein wenig Erklärungen:
-
-Prinzipiell ist der Adapter durch Anaylse der Datenpakete zwischen der BYD-App und dem BYD-Akku-System entstanden. Es werden im Wesentlichen die Daten aus dem TAB System Info und aus dem TAB Diagnosis dargestellt. Offensichtlich sind die Daten für "System Info" sofort in der Batterie bereit zum abholen, für die Diagnose-Daten sieht es so aus als wäre ein Messvorgang erforderlich, zwischen der Abfrage und den Werten muss ein Zeitintervall von gut 3 Sekunden eingehalten werden. 
-
-Ich bin mir nicht sicher ob das BYD-System durch zu häufige Abfragen beschädigt wird, also: Es ist Dein Risiko was Du hier einträgst!
-
-## Zu den Einstellungen:
-Intervall: Zeitlicher Abstand zwischen den Abfragen des Adapters
-
-IP-Adresse: Eigentlich logisch, damit ist die IP-Adresse des Adapters gemeint. Dafür gibt es zwei Möglichkeiten: Entweder hält man sich an die Anleitung von Becker3 aus dem Photovoltaik-Forum, ist hier verlinkt: https://www.photovoltaikforum.com/thread/150898-byd-hvs-firmware-update/?postID=2215343#post2215343 . Das hat den Vorteil das auch die BYD-APP läuft und man mit dieser direkt an die Daten, auch zum Vergleich, herankommt. Oder man trägt "nur" die IP-Adresse die die BYD-Box per DHCP erhalten hat ein. Ausdrücklich waren möchte ich vor Änderungen an den IP-Einstellungen der BOX! Im Forum kann man Berichte von Leute lesen die sich die Erreichbarkeit der Box dauerhaft ruiniert haben. 
-
-Batterie-Details: Steuerung, ob die Details zu den Zellen gelesen werden sollen
-
-Lesezyklen zu Batterie-Details: Anzahl der "Normal-Lese-Zyklen" bis wieder einmal die Diagnose-Daten gelesen werden. Hier die Warnung dazu: Ich habe keine Idee ob man sich durch häufige Diagnose-Messungen Nachteile einhandelt, daher empfehle ich den Wert möglichst hoch zu setzen. Ich wüsste auch nicht was man mit den Diagnose-Daten im regelmäßigen Poll anfangen sollte. 
-
-Zu den Batterie-Größen: Der Adapter funktioniert für Zelltemperaturen und ZellSpannungen bei 2-5 Batterie-Modulen. 
-
+[Link zur nativen deutschen Readme:](README-German.md)
 
 ## Changelog
 <!--
 	Placeholder for the next version (at the beginning of the line):
 	### __WORK IN PROGRESS__
 -->
+### 1.5.2 (2025-08-02)
+* (arteck) add socketConnection DP
+* (arteck) use jsconConfig
+* (arteck) refactoring to modern Code
+* (arteck) use direct socket connection without detour IPClient
+* first Version with two towers in NPM
+
+### 1.5.1 (2024-01-15)
+* Enable the possibility to get informations from a two tower setup
+* BREAKING CHANGE of Structure.
+
+### 1.5.0 (2023-11-04)
+* Breaking change: nodejs 16 minimum required
+* automated checks and release-script repaired (thanks to mcm1957, he did the work)
+* nothing else changed in code
+
 ### 1.4.2 (2023-09-28)
 * Typo in version number removed
 
@@ -61,29 +56,12 @@ Zu den Batterie-Größen: Der Adapter funktioniert für Zelltemperaturen und Zel
 * Removed some bugs in detecting inverter
 * Inverternumber ist logged, so I can easily add new inverters if neccerary, just send me the silly-log if inverter is unknown.
 
-### 1.4.0 (2022-10-31)
-* Update of referred modules (mainly around testing)
-* improvmenets contributed by Tapter (5 modules, readme and better readable code)
-* Better detection of battery type and inverter
-* SOC not only from normal data but from diagnosis-data, too. There we have one decimal place more
-* removed frequency limit for battery detail data
-* increased max count of temperature measurements for HVS to 64
-* support for up to 5 HVS modules
-
-### 1.3.0 (2021-11-06)
-* updated even more dependencies
-* official release with new state SOH
-
-### 1.2.4-0 (2021-11-02)
-* Added state: SOH
-* updated dependencies as suggested from bot
-
 ###
 
 ## License
 MIT License
 
-Copyright (c) 2021 Christian <github@familie-herrmann.de>
+Copyright (c) 2025 Christian <github@familie-herrmann.de>
 
 Permission is hereby granted, free of charge, to any person obtaining a copy
 of this software and associated documentation files (the "Software"), to deal

package/admin/jsonConfig.json

@@ -0,0 +1,108 @@
+{
+    "type": "panel",
+    "i18n": true,
+    "items": {
+        "Account settings": {
+            "type": "header",
+            "text": "Adapter settings for BYD Battery",
+            "size": 2,
+            "newLine": true
+        },
+
+        "ConfPollInterval": {
+            "type": "number",
+            "label": "Interval (s)",
+            "unit": "sec",
+            "hidden": "data.ConfOverridePollInterval === true",
+            "min": 30,
+            "max": 3600,
+            "xs": 12,
+            "sm": 12,
+            "md": 4,
+            "lg": 3,
+            "xl": 3
+        },
+
+        "ConfIPAdress": {
+            "type": "text",
+            "label": "IP Address",
+            "xs": 12,
+            "sm": 12,
+            "md": 4,
+            "lg": 3,
+            "xl": 3
+        },
+
+        "ConfOverridePollInterval": {
+            "type": "checkbox",
+            "label": "Use poll interval from state and not from here",
+            "newLine": true,
+            "xs": 12,
+            "sm": 12,
+            "md": 8,
+            "lg": 4,
+            "xl": 4
+        },
+
+        "ConfBatDetails": {
+            "type": "checkbox",
+            "label": "Diagnosis Data from Battery (only tested with two and four modules)",
+            "xs": 12,
+            "sm": 12,
+            "md": 8,
+            "lg": 4,
+            "xl": 4
+        },
+
+        "ConfTestMode": {
+            "type": "checkbox",
+            "label": "Test Mode - show data in error log",
+            "newLine": true,
+            "xs": 12,
+            "sm": 12,
+            "md": 8,
+            "lg": 4,
+            "xl": 4
+        },
+
+        "ConfDetailshowoften": {
+            "newLine": true,
+            "type": "number",
+            "label": "Battery-details - every ... cycles",
+            "xs": 12,
+            "sm": 12,
+            "md": 4,
+            "lg": 3,
+            "xl": 3
+        },
+        "ConfBydTowerCount": {
+            "newLine": true,
+            "type": "select",
+            "label": "Count of towers",
+            "xs": 12,
+            "sm": 12,
+            "md": 4,
+            "lg": 3,
+            "xl": 3,
+            "options": [
+                {
+                    "label": "1",
+                    "value": "1"
+                },
+                {
+                    "label": "2",
+                    "value": "2"
+                }
+            ]
+        },
+        "ConfStoreRawMessages": {
+            "type": "checkbox",
+            "label": "Enable to store the raw messages",
+            "xs": 12,
+            "sm": 12,
+            "md": 8,
+            "lg": 4,
+            "xl": 4
+        }
+    }
+}

package/docs/byd-hexstructure.md

@@ -0,0 +1,78 @@
+# Structure of BYD HVS Messages
+
+## Captureing of messages
+These messages and decrypted by capturing the communication between the software Be Connect and the hardware. The position and information of each information is interpreted by the community and may be incorrect. Please take only valid information from BYD or its sub-companies.
+
+
+## Messages
+
+After a TCP Connection is estalished the communication requires to send a command to receive data or execute a measurement. The project of smarthomeNG describe it as a similarity for ModBus that we read and write registers with the TCP connection.
+https://github.com/lgb-this/plugins/blob/develop/byd_bat/user_doc.rst
+All Messages have a Header in Byte 1 and 2.
+
+### Message 0 - Initiate connection and Basic data
+The send out message is ```010300000066c5e0```
+
+| Byte | Type | Description |
+|:-- |:--:|:--|
+| 3 to 21 | string | This is the serialnumber. On the 2. character you can identify the hardwaretype (HVS, HVM, ...) |
+| 27 + 28 | character | Version in format V(27).(28) for the first BMU |
+| 29 + 30 | character | Version in format V(29).(30) for the 2nd BMU |
+| 33 | integer | used tower BMU |
+| 36 | 2 seperate byte integer | 1 byte - towers; 2 byte - modules (23 => 2 towers & 3 modules) |
+| 38 | enum | 0: OffGrid; 1: OnGrid; 2: Backup |
+
+### Message 1 - System diagnosis
+The send out message is ```01030500001984cc```
+
+| Byte | Type | Descriptio |
+|:-- |:--:|:--|
+| 3 | int16 signed | SOC of the whole system |
+| 5 | int16 signed | System max volts |
+| 7 | int16 signed | System min volts |
+| 9 | int16 signed | System SOH |
+| 11 | int16 signed | System amperes |
+| 13 | int16 unsigned | Battery volts with SF 100  |
+| 15 | int16 signed | max Temperature |
+| 17 | int16 signed | min Temperature |
+| 19 | int16 signed | Battery Temperature |
+| 29 | int16 signed | Error Number |
+| 31 + 32 | characters | Param T |
+| 35 | int16 unsigned | Ouput voltage with SF 100 |
+| 37 | int16 unsigned | Total charge of the system |
+| 41 | int16 unsinged | Total discharge of the system |
+
+### Message 2 - System diagnosis
+the send command is ```010300100003040e```
+
+| Byte | Type | Descriptio |
+|:-- |:--:|:--|
+| 3 | enum | inverter type |
+| 5 | enum | Battery type: 0: HVL; 1: HVM; 2: HVS |
+
+### Message 5 - Tower basic information
+
+| Byte | Type | Descriptio |
+|:-- |:--:|:--|
+| 5 | int16 signed | Tower max Volt |
+| 7 | int16 singed | Tower min Volt |
+| 9 | int | max volt cell number |
+| 10 | int | min volt cell number |
+| 11 | int16 signed | max temperature |
+| 13 | int 16 signed | min temperature |
+| 15 | int | max temperature cell |
+| 16 | int | min temperature cell number |
+| 17 - 32 | MSB, LSB | Balancing Flags |
+| 33 | int32 Unsigned | tower charge total with SF 1000 |
+| 37 | int32 Unsigned | tower discharge total with SF 1000 |
+| 45 | int16 signed | tower battery voltage SF 10 |
+| 51 | int16 singed | tower volt out |
+| 53 | int16 signed | SOC Percentage |
+| 55 | int16 signed | SOH percentage |
+| 57 | int16 signed | Currentamperes |
+| 59 + 60 | hex | state |
+
+## Glossary
+| Short | Description |
+|:--:|:-- |
+| SF | Scale Factor (Value 1234 & SF 100 => Real Value: 12.34) |

package/eslint.config.mjs

@@ -0,0 +1,33 @@
+// ioBroker eslint template configuration file for js and ts files
+// Please note that esm or react based modules need additional modules loaded.
+import config from '@iobroker/eslint-config';
+
+export default [
+    ...config,
+
+    {
+        // specify files to exclude from linting here
+        ignores: [
+            '.dev-server/',
+            '.vscode/',
+            '*.test.js', 
+            'test/**/*.js', 
+            '*.config.mjs', 
+            'build', 
+            'admin/build', 
+            'admin/words.js',
+            'admin/admin.d.ts',
+            '**/adapter-config.d.ts'     
+        ] 
+    },
+
+    {
+        // you may disable some 'jsdoc' warnings - but using jsdoc is highly recommended
+        // as this improves maintainability. jsdoc warnings will not block buiuld process.
+        rules: {
+            // 'jsdoc/require-jsdoc': 'off',
+            
+        },
+    },
+    
+];