bluetti-modbus 0.1.0__tar.gz

bluetti_modbus-0.1.0/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Patrick762
+
+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.

bluetti_modbus-0.1.0/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: bluetti-modbus
+Version: 0.1.0
+Summary: Unofficial library for basic communication to Bluetti Power Stations via Modbus
+Author: Patrick762, bluetti-community
+License: MIT
+Project-URL: Homepage, https://github.com/bluetti-community/bluetti-modbus-lib
+Keywords: modbus,bluetti,home-assistant
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: modbus-connection>=4.10.0
+Provides-Extra: cli
+Requires-Dist: modbus-connection[pymodbus]>=4.10.0; extra == "cli"
+Dynamic: license-file
+
+# bluetti-modbus-lib
+Unofficial library for basic communication to Bluetti Power Stations via Modbus.
+
+Based on official documentation https://github.com/bluetti-official/bluetti-modbus-tcp-slave
+
+You have to enable Modbus TCP in the webinterface of your device first.
+
+## Relationship to Patrick762's `bluetti-modbus-lib`
+
+This repository started as a fork of
+[Patrick762/bluetti-modbus-lib](https://github.com/Patrick762/bluetti-modbus-lib)
+and has since diverged significantly (packaging, testing, retry handling,
+device coverage). Patrick762 is still actively maintaining his own version
+independently and was asked directly whether he'd like to fold this work
+back into his project or join `bluetti-community` - he's not in a position
+to commit the time to that right now, which is completely fine.
+
+Since the PyPI name `bluetti-modbus-lib` is his and still actively used,
+this project is published on PyPI under a different name, **`bluetti-modbus`**,
+to avoid any ambiguity between the two. The GitHub repository itself keeps
+its original name.
+
+## Disclaimer
+This library is provided without any warranty or support by Bluetti. I do not take responsibility for any problems it may cause in all cases. Use it at your own risk.
+
+## Supported devices and data
+
+- Balco260
+- EP2000
+- SMeter (Bluetti's AC meter/CT device - untested against real hardware so far)
+
+Field names, units, and Modbus registers come from
+[bluetti-registers](https://github.com/bluetti-community/bluetti-registers) -
+`devices/balco260.py`, `devices/ep2000.py`, and `devices/smeter.py` in this
+repo are generated from it by `import.py`, not written by hand.
+
+## Architecture
+
+This library does not create or own a Modbus transport itself. It's built on
+[modbus-connection](https://pypi.org/project/modbus-connection/)'s
+device-modelling framework: `Balco260`, `EP2000`, and `SMeter`
+(`bluetti_modbus_lib.devices`) each take a `ModbusUnit` supplied by the
+caller, built from whichever backend and connection the caller already
+manages. That's the integration surface for embedding this library into
+another application (a Home Assistant integration, for example).
+
+`BluettiModbusClient` (`bluetti_modbus_lib.modbus.client`) is different: it
+owns and manages its own connection. It exists for the `bluetti-modread` CLI
+below and standalone/manual use, not as something another application should
+build on - doing so would open a second, competing connection to the device
+instead of sharing one.
+
+Field metadata is deliberately limited to what's true at the Modbus/protocol
+level - address, type, scale, unit, whether it's writable. It does not carry
+Home Assistant concepts like entity category, state class, or device class:
+those describe how a value should be presented in an HA UI, not anything
+about the register itself, and belong in whichever integration consumes this
+library, not in the library.
+
+## Installation
+
+```bash
+pip install bluetti-modbus
+```
+
+Installing `bluetti-modbus` alone only pulls in `modbus-connection`'s
+backend-neutral interface - enough to use the device classes directly against
+a `ModbusUnit` you already have. The `bluetti-modread` CLI needs a concrete
+backend, installed via the `cli` extra:
+
+```bash
+pip install "bluetti-modbus[cli]"
+```
+
+## Sponsoring
+
+If you want to support this project, you can sponsor [Patrick762 on GitHub](https://github.com/sponsors/Patrick762), the original author.
+
+## Commands for testing
+
+Commands included in this library should only be used for testing.
+
+### Read device data for supported devices
+
+```bash
+usage: bluetti-modread [-h] [-c HOST] [-p PORT] [-t TYPE]
+
+Read bluetti devices via modbus
+
+options:
+  -h, --help            show this help message and exit
+  -c HOST, --host HOST  IP-address of the device
+  -p PORT, --port PORT  Port of the device
+  -t TYPE, --type TYPE  Device type
+```
+
+Example:
+
+```bash
+bluetti-modread -c 10.2.1.60 -p 502 -t balco260
+```
+
+Example output, captured from a real Balco260 (truncated - `bluetti-modread` prints one line per field):
+
+```bash
+d_num_inverters: 1
+ac_o_p_total: 84 W
+pv_i_p_total: 0 W
+ac_o_e_total: 64.7 kWh
+d_inverter_status: InverterStatus.GridConnectedOperation
+g_i_f: 50.0 Hz
+b_v: 27.1 V
+b_soc: 100 %
+b_cycle_count: 8
+b_t_avg: 0 °C
+b_i_e: 23420 Wh
+```
+
+Note the two energy fields above: most cumulative energy fields (`ac_o_e_total`, etc.) are reported in kWh, but the battery charge/discharge ones (`b_i_e`, `b_o_e`) are in Wh - both correct as reported by the device, just worth knowing if you're comparing values across fields.
+
+Field names follow the naming convention documented in
+[bluetti-registers](https://github.com/bluetti-community/bluetti-registers#naming-convention-for-field-names).

bluetti_modbus-0.1.0/README.md

@@ -0,0 +1,122 @@
+# bluetti-modbus-lib
+Unofficial library for basic communication to Bluetti Power Stations via Modbus.
+
+Based on official documentation https://github.com/bluetti-official/bluetti-modbus-tcp-slave
+
+You have to enable Modbus TCP in the webinterface of your device first.
+
+## Relationship to Patrick762's `bluetti-modbus-lib`
+
+This repository started as a fork of
+[Patrick762/bluetti-modbus-lib](https://github.com/Patrick762/bluetti-modbus-lib)
+and has since diverged significantly (packaging, testing, retry handling,
+device coverage). Patrick762 is still actively maintaining his own version
+independently and was asked directly whether he'd like to fold this work
+back into his project or join `bluetti-community` - he's not in a position
+to commit the time to that right now, which is completely fine.
+
+Since the PyPI name `bluetti-modbus-lib` is his and still actively used,
+this project is published on PyPI under a different name, **`bluetti-modbus`**,
+to avoid any ambiguity between the two. The GitHub repository itself keeps
+its original name.
+
+## Disclaimer
+This library is provided without any warranty or support by Bluetti. I do not take responsibility for any problems it may cause in all cases. Use it at your own risk.
+
+## Supported devices and data
+
+- Balco260
+- EP2000
+- SMeter (Bluetti's AC meter/CT device - untested against real hardware so far)
+
+Field names, units, and Modbus registers come from
+[bluetti-registers](https://github.com/bluetti-community/bluetti-registers) -
+`devices/balco260.py`, `devices/ep2000.py`, and `devices/smeter.py` in this
+repo are generated from it by `import.py`, not written by hand.
+
+## Architecture
+
+This library does not create or own a Modbus transport itself. It's built on
+[modbus-connection](https://pypi.org/project/modbus-connection/)'s
+device-modelling framework: `Balco260`, `EP2000`, and `SMeter`
+(`bluetti_modbus_lib.devices`) each take a `ModbusUnit` supplied by the
+caller, built from whichever backend and connection the caller already
+manages. That's the integration surface for embedding this library into
+another application (a Home Assistant integration, for example).
+
+`BluettiModbusClient` (`bluetti_modbus_lib.modbus.client`) is different: it
+owns and manages its own connection. It exists for the `bluetti-modread` CLI
+below and standalone/manual use, not as something another application should
+build on - doing so would open a second, competing connection to the device
+instead of sharing one.
+
+Field metadata is deliberately limited to what's true at the Modbus/protocol
+level - address, type, scale, unit, whether it's writable. It does not carry
+Home Assistant concepts like entity category, state class, or device class:
+those describe how a value should be presented in an HA UI, not anything
+about the register itself, and belong in whichever integration consumes this
+library, not in the library.
+
+## Installation
+
+```bash
+pip install bluetti-modbus
+```
+
+Installing `bluetti-modbus` alone only pulls in `modbus-connection`'s
+backend-neutral interface - enough to use the device classes directly against
+a `ModbusUnit` you already have. The `bluetti-modread` CLI needs a concrete
+backend, installed via the `cli` extra:
+
+```bash
+pip install "bluetti-modbus[cli]"
+```
+
+## Sponsoring
+
+If you want to support this project, you can sponsor [Patrick762 on GitHub](https://github.com/sponsors/Patrick762), the original author.
+
+## Commands for testing
+
+Commands included in this library should only be used for testing.
+
+### Read device data for supported devices
+
+```bash
+usage: bluetti-modread [-h] [-c HOST] [-p PORT] [-t TYPE]
+
+Read bluetti devices via modbus
+
+options:
+  -h, --help            show this help message and exit
+  -c HOST, --host HOST  IP-address of the device
+  -p PORT, --port PORT  Port of the device
+  -t TYPE, --type TYPE  Device type
+```
+
+Example:
+
+```bash
+bluetti-modread -c 10.2.1.60 -p 502 -t balco260
+```
+
+Example output, captured from a real Balco260 (truncated - `bluetti-modread` prints one line per field):
+
+```bash
+d_num_inverters: 1
+ac_o_p_total: 84 W
+pv_i_p_total: 0 W
+ac_o_e_total: 64.7 kWh
+d_inverter_status: InverterStatus.GridConnectedOperation
+g_i_f: 50.0 Hz
+b_v: 27.1 V
+b_soc: 100 %
+b_cycle_count: 8
+b_t_avg: 0 °C
+b_i_e: 23420 Wh
+```
+
+Note the two energy fields above: most cumulative energy fields (`ac_o_e_total`, etc.) are reported in kWh, but the battery charge/discharge ones (`b_i_e`, `b_o_e`) are in Wh - both correct as reported by the device, just worth knowing if you're comparing values across fields.
+
+Field names follow the naming convention documented in
+[bluetti-registers](https://github.com/bluetti-community/bluetti-registers#naming-convention-for-field-names).

bluetti_modbus-0.1.0/pyproject.toml

@@ -0,0 +1,56 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "bluetti-modbus"
+version = "0.1.0"
+description = "Unofficial library for basic communication to Bluetti Power Stations via Modbus"
+readme = "README.md"
+requires-python = ">=3.13"
+license = { text = "MIT" }
+authors = [{ name = "Patrick762" }, { name = "bluetti-community" }]
+keywords = ["modbus", "bluetti", "home-assistant"]
+classifiers = [
+    "Development Status :: 4 - Beta",
+    "Intended Audience :: Developers",
+    "Programming Language :: Python :: 3",
+]
+# Protocol + the device-modelling framework (modbus_connection.model). The
+# caller injects a ModbusUnit built from whichever backend they choose - see
+# README.md. This package does not create or own a Modbus transport itself.
+dependencies = ["modbus-connection>=4.10.0"]
+
+[project.optional-dependencies]
+# Concrete backend for the bluetti-modread CLI (pip install bluetti-modbus[cli]).
+cli = ["modbus-connection[pymodbus]>=4.10.0"]
+
+[project.urls]
+Homepage = "https://github.com/bluetti-community/bluetti-modbus-lib"
+
+[project.scripts]
+bluetti-modread = "bluetti_modbus_lib.scripts.bluetti_modread:start"
+
+[dependency-groups]
+dev = ["pytest>=8", "pytest-asyncio>=0.24", "pytest-cov>=5"]
+
+[tool.setuptools.packages.find]
+where = ["src"]
+
+[tool.setuptools.package-data]
+bluetti_modbus_lib = ["py.typed"]
+
+[tool.ruff]
+target-version = "py313"
+src = ["src"]
+
+[tool.mypy]
+strict = true
+packages = ["bluetti_modbus_lib"]
+
+[tool.coverage.run]
+omit = [
+    # The bluetti-modread CLI - README.md: "Commands included in this
+    # library should only be used for testing." Not library logic.
+    "src/bluetti_modbus_lib/scripts/*",
+]

bluetti_modbus-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+

bluetti_modbus-0.1.0/src/bluetti_modbus.egg-info/PKG-INFO

@@ -0,0 +1,141 @@
+Metadata-Version: 2.4
+Name: bluetti-modbus
+Version: 0.1.0
+Summary: Unofficial library for basic communication to Bluetti Power Stations via Modbus
+Author: Patrick762, bluetti-community
+License: MIT
+Project-URL: Homepage, https://github.com/bluetti-community/bluetti-modbus-lib
+Keywords: modbus,bluetti,home-assistant
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Programming Language :: Python :: 3
+Requires-Python: >=3.13
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: modbus-connection>=4.10.0
+Provides-Extra: cli
+Requires-Dist: modbus-connection[pymodbus]>=4.10.0; extra == "cli"
+Dynamic: license-file
+
+# bluetti-modbus-lib
+Unofficial library for basic communication to Bluetti Power Stations via Modbus.
+
+Based on official documentation https://github.com/bluetti-official/bluetti-modbus-tcp-slave
+
+You have to enable Modbus TCP in the webinterface of your device first.
+
+## Relationship to Patrick762's `bluetti-modbus-lib`
+
+This repository started as a fork of
+[Patrick762/bluetti-modbus-lib](https://github.com/Patrick762/bluetti-modbus-lib)
+and has since diverged significantly (packaging, testing, retry handling,
+device coverage). Patrick762 is still actively maintaining his own version
+independently and was asked directly whether he'd like to fold this work
+back into his project or join `bluetti-community` - he's not in a position
+to commit the time to that right now, which is completely fine.
+
+Since the PyPI name `bluetti-modbus-lib` is his and still actively used,
+this project is published on PyPI under a different name, **`bluetti-modbus`**,
+to avoid any ambiguity between the two. The GitHub repository itself keeps
+its original name.
+
+## Disclaimer
+This library is provided without any warranty or support by Bluetti. I do not take responsibility for any problems it may cause in all cases. Use it at your own risk.
+
+## Supported devices and data
+
+- Balco260
+- EP2000
+- SMeter (Bluetti's AC meter/CT device - untested against real hardware so far)
+
+Field names, units, and Modbus registers come from
+[bluetti-registers](https://github.com/bluetti-community/bluetti-registers) -
+`devices/balco260.py`, `devices/ep2000.py`, and `devices/smeter.py` in this
+repo are generated from it by `import.py`, not written by hand.
+
+## Architecture
+
+This library does not create or own a Modbus transport itself. It's built on
+[modbus-connection](https://pypi.org/project/modbus-connection/)'s
+device-modelling framework: `Balco260`, `EP2000`, and `SMeter`
+(`bluetti_modbus_lib.devices`) each take a `ModbusUnit` supplied by the
+caller, built from whichever backend and connection the caller already
+manages. That's the integration surface for embedding this library into
+another application (a Home Assistant integration, for example).
+
+`BluettiModbusClient` (`bluetti_modbus_lib.modbus.client`) is different: it
+owns and manages its own connection. It exists for the `bluetti-modread` CLI
+below and standalone/manual use, not as something another application should
+build on - doing so would open a second, competing connection to the device
+instead of sharing one.
+
+Field metadata is deliberately limited to what's true at the Modbus/protocol
+level - address, type, scale, unit, whether it's writable. It does not carry
+Home Assistant concepts like entity category, state class, or device class:
+those describe how a value should be presented in an HA UI, not anything
+about the register itself, and belong in whichever integration consumes this
+library, not in the library.
+
+## Installation
+
+```bash
+pip install bluetti-modbus
+```
+
+Installing `bluetti-modbus` alone only pulls in `modbus-connection`'s
+backend-neutral interface - enough to use the device classes directly against
+a `ModbusUnit` you already have. The `bluetti-modread` CLI needs a concrete
+backend, installed via the `cli` extra:
+
+```bash
+pip install "bluetti-modbus[cli]"
+```
+
+## Sponsoring
+
+If you want to support this project, you can sponsor [Patrick762 on GitHub](https://github.com/sponsors/Patrick762), the original author.
+
+## Commands for testing
+
+Commands included in this library should only be used for testing.
+
+### Read device data for supported devices
+
+```bash
+usage: bluetti-modread [-h] [-c HOST] [-p PORT] [-t TYPE]
+
+Read bluetti devices via modbus
+
+options:
+  -h, --help            show this help message and exit
+  -c HOST, --host HOST  IP-address of the device
+  -p PORT, --port PORT  Port of the device
+  -t TYPE, --type TYPE  Device type
+```
+
+Example:
+
+```bash
+bluetti-modread -c 10.2.1.60 -p 502 -t balco260
+```
+
+Example output, captured from a real Balco260 (truncated - `bluetti-modread` prints one line per field):
+
+```bash
+d_num_inverters: 1
+ac_o_p_total: 84 W
+pv_i_p_total: 0 W
+ac_o_e_total: 64.7 kWh
+d_inverter_status: InverterStatus.GridConnectedOperation
+g_i_f: 50.0 Hz
+b_v: 27.1 V
+b_soc: 100 %
+b_cycle_count: 8
+b_t_avg: 0 °C
+b_i_e: 23420 Wh
+```
+
+Note the two energy fields above: most cumulative energy fields (`ac_o_e_total`, etc.) are reported in kWh, but the battery charge/discharge ones (`b_i_e`, `b_o_e`) are in Wh - both correct as reported by the device, just worth knowing if you're comparing values across fields.
+
+Field names follow the naming convention documented in
+[bluetti-registers](https://github.com/bluetti-community/bluetti-registers#naming-convention-for-field-names).

bluetti_modbus-0.1.0/src/bluetti_modbus.egg-info/SOURCES.txt

@@ -0,0 +1,32 @@
+LICENSE
+README.md
+pyproject.toml
+src/bluetti_modbus.egg-info/PKG-INFO
+src/bluetti_modbus.egg-info/SOURCES.txt
+src/bluetti_modbus.egg-info/dependency_links.txt
+src/bluetti_modbus.egg-info/entry_points.txt
+src/bluetti_modbus.egg-info/requires.txt
+src/bluetti_modbus.egg-info/top_level.txt
+src/bluetti_modbus_lib/__init__.py
+src/bluetti_modbus_lib/py.typed
+src/bluetti_modbus_lib/base_devices/__init__.py
+src/bluetti_modbus_lib/base_devices/bluetti_device.py
+src/bluetti_modbus_lib/devices/__init__.py
+src/bluetti_modbus_lib/devices/balco260.py
+src/bluetti_modbus_lib/devices/ep2000.py
+src/bluetti_modbus_lib/devices/getter.py
+src/bluetti_modbus_lib/devices/smeter.py
+src/bluetti_modbus_lib/enums/__init__.py
+src/bluetti_modbus_lib/enums/inverter_fault.py
+src/bluetti_modbus_lib/enums/inverter_status.py
+src/bluetti_modbus_lib/enums/inverter_warning.py
+src/bluetti_modbus_lib/fields/__init__.py
+src/bluetti_modbus_lib/fields/custom_fields.py
+src/bluetti_modbus_lib/modbus/__init__.py
+src/bluetti_modbus_lib/modbus/client.py
+src/bluetti_modbus_lib/scripts/__init__.py
+src/bluetti_modbus_lib/scripts/bluetti_modread.py
+tests/test_base_devices.py
+tests/test_client.py
+tests/test_custom_fields.py
+tests/test_getter.py

bluetti_modbus-0.1.0/src/bluetti_modbus.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

bluetti_modbus-0.1.0/src/bluetti_modbus.egg-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+bluetti-modread = bluetti_modbus_lib.scripts.bluetti_modread:start

bluetti_modbus-0.1.0/src/bluetti_modbus.egg-info/requires.txt

@@ -0,0 +1,4 @@
+modbus-connection>=4.10.0
+
+[cli]
+modbus-connection[pymodbus]>=4.10.0

bluetti_modbus-0.1.0/src/bluetti_modbus.egg-info/top_level.txt

@@ -0,0 +1 @@
+bluetti_modbus_lib

bluetti_modbus-0.1.0/src/bluetti_modbus_lib/__init__.py

@@ -0,0 +1,2 @@
+from .devices.getter import *
+from .modbus.client import *

bluetti_modbus-0.1.0/src/bluetti_modbus_lib/base_devices/__init__.py

@@ -0,0 +1 @@
+from .bluetti_device import *

bluetti_modbus-0.1.0/src/bluetti_modbus_lib/base_devices/bluetti_device.py

@@ -0,0 +1,18 @@
+from collections.abc import KeysView
+from typing import Any
+
+from modbus_connection.model import Component, RegisterField
+
+
+class BluettiDevice(Component):
+    max_gap = 5
+    max_span = 50
+
+    def field_names(self) -> KeysView[str]:
+        return self._register_fields.keys()
+
+    def get_field(self, field_name: str) -> RegisterField[Any] | None:
+        return self._register_fields.get(field_name)
+
+    def get_sensors(self) -> KeysView[str]:
+        return self.field_names()

bluetti_modbus-0.1.0/src/bluetti_modbus_lib/devices/__init__.py

@@ -0,0 +1,4 @@
+from .balco260 import Balco260 as Balco260
+from .ep2000 import EP2000 as EP2000
+from .getter import *
+from .smeter import SMeter as SMeter