pybluetti 0.1.0__py3-none-any.whl

pybluetti/__init__.py

@@ -0,0 +1,31 @@
+"""
+Async Python client for the BLUETTI cloud API.
+
+Extracted from
+https://github.com/bluetti-official/bluetti-home-assistant's
+custom_components/bluetti/api/, the same way
+https://github.com/pyenphase/pyenphase backs the enphase_envoy Home Assistant
+integration. Fully async, including the websocket push-update transport
+(`aiohttp`'s native websocket client, no dedicated threads). Wiring
+bluetti-home-assistant to depend on this package is a separate follow-up.
+"""
+
+from .client import Bluetti
+from .const import Method
+from .exceptions import ApplicationRuntimeException
+from .models import UserProduct
+from .product_client import ProductClient
+from .unify_response import UnifyResponse
+from .websocket import StompClient
+
+__version__ = "0.1.0"
+
+__all__ = [
+    "ApplicationRuntimeException",
+    "Bluetti",
+    "Method",
+    "ProductClient",
+    "StompClient",
+    "UnifyResponse",
+    "UserProduct",
+]

pybluetti/client.py

@@ -0,0 +1,105 @@
+"""Base BLUETTI cloud API client."""
+
+import logging
+from abc import abstractmethod
+from collections.abc import Callable
+from json import dumps
+from typing import Any, Generic, TypeVar
+
+import aiohttp
+from pydantic import TypeAdapter
+
+from .const import Method
+from .exceptions import ApplicationRuntimeException
+from .unify_response import UnifyResponse
+
+T = TypeVar("T")
+
+
+class Bluetti(Generic[T]):
+    """Base class describing interactions with the BLUETTI cloud service."""
+
+    _accessToken: str | None = None
+    _httpSession: aiohttp.ClientSession
+    _gateway_url: str
+    _on_auth_expired: Callable[[], None] | None
+
+    @property
+    @abstractmethod
+    def logger(self) -> logging.Logger:
+        """The subclass's logger."""
+
+    def __init__(
+        self,
+        httpSession: aiohttp.ClientSession,
+        gateway_url: str,
+        accessToken: str | None = None,
+        on_auth_expired: Callable[[], None] | None = None,
+    ) -> None:
+        """
+        Initialize the client.
+
+        - httpSession: the aiohttp session to issue requests on.
+        - gateway_url: the BLUETTI cloud gateway base URL (region-specific).
+        - accessToken: the OAuth2 access token to authenticate requests with.
+        - on_auth_expired: called when the cloud reports the access token as
+          expired (msgCode 805), so the caller can react (e.g. trigger a
+          refresh or re-authentication flow).
+        """
+        self._httpSession = httpSession
+        self._gateway_url = gateway_url
+        self._accessToken = accessToken
+        self._on_auth_expired = on_auth_expired
+
+    async def _request(
+        self,
+        responseType: Any,
+        method: Method,
+        path: str,
+        params: dict[str, Any] | None = None,
+        body: dict[str, Any] | None = None,
+    ) -> UnifyResponse[T] | str:
+        """
+        Send a request to the server.
+
+        - responseType: the type of response data, without the UnifyResponse wrapper.
+        - method: the HTTP method.
+        """
+        # when the method is 'GET', the request body must be null.
+        if method == Method.GET:
+            body = None
+
+        headers = {
+            "Authorization": f"{self._accessToken}",
+        }
+
+        # Remove None values from params and json
+        if params:
+            params = {k: v for k, v in params.items() if v is not None}
+            self.logger.debug("======> Client request parameters: %s", params)
+        if body:
+            body = {k: v for k, v in body.items() if v is not None}
+            self.logger.debug("======> Client request body: %s", dumps(body))
+            headers["Content-Type"] = "application/json"
+
+        async with self._httpSession.request(
+            method,
+            f"{self._gateway_url}{path}",
+            headers=headers,
+            json=body,
+            params=params,
+        ) as response:
+            self.logger.debug("<====== Server response status %s from %s", response.status, response.url)
+            self.logger.debug("<====== Server response type is: %s", response.content_type)
+
+            if not response.ok:
+                raise ApplicationRuntimeException(msgCode=response.status, data=await response.text())
+
+            if response.content_type.lower().startswith("application/json"):
+                data = await response.json()  # read response body to JSON
+                unify_response = TypeAdapter(UnifyResponse[responseType]).validate_python(data)
+                if data.get("msgCode") == 805 and self._on_auth_expired is not None:
+                    self._on_auth_expired()
+                    self.logger.info("token have expired")
+                return unify_response
+            return await response.text()

pybluetti/const.py

@@ -0,0 +1,18 @@
+"""Shared constants for pybluetti."""
+
+from enum import Enum
+
+
+class StringEnum(str, Enum):
+    """String Enum define."""
+
+    def __str__(self) -> str:
+        return self.value
+
+
+class Method(StringEnum):
+    """HTTP Methods define."""
+
+    GET = "GET"
+    POST = "POST"
+    DELETE = "DELETE"

pybluetti/exceptions.py

@@ -0,0 +1,18 @@
+"""Exceptions raised by the pybluetti client."""
+
+
+class ApplicationRuntimeException(Exception):
+    """Raised when a BLUETTI cloud API call fails."""
+
+    message: str = "An unknown error has occurred."
+    msgCode: int
+    data: dict | str | None = None
+
+    def __init__(self, msgCode: int, data: dict | str | None = None, errMessage: str | None = None) -> None:
+        self.msgCode = msgCode
+        self.data = data
+
+        if errMessage is not None:
+            self.message = errMessage
+
+        super().__init__(self.message)

pybluetti/models.py

@@ -0,0 +1,14 @@
+"""Response models for the BLUETTI cloud API."""
+
+from pydantic import BaseModel
+
+
+class UserProduct(BaseModel):
+    """A device/power station bound to a BLUETTI account."""
+
+    sn: str
+    stateList: list
+    online: str
+    model: str | None = None
+    name: str | None = None
+    isBindByCurUser: str | None = None

pybluetti/product_client.py

@@ -0,0 +1,57 @@
+"""Client for the BLUETTI product/device endpoints."""
+
+import logging
+
+from .client import Bluetti
+from .const import Method
+from .models import UserProduct
+from .unify_response import UnifyResponse
+
+
+class ProductClient(Bluetti):
+    """Class describing for the BLUETTI products."""
+
+    __LOGGER__ = None
+    """The api client logger."""
+
+    @property
+    def logger(self) -> logging.Logger:
+        """Get the api client logger."""
+        if self.__LOGGER__ is None:
+            self.__LOGGER__ = logging.getLogger(__name__ + "." + __class__.__name__)
+        return self.__LOGGER__
+
+    async def get_user_products(self) -> UnifyResponse[list[UserProduct]]:
+        """Get the devices/power stations bound to the account."""
+        return await self._request(
+            list[UserProduct],
+            Method.GET,
+            "/api/bluiotdata/ha/v1/devices",
+        )
+
+    async def get_device_status(self, sns: str | None = None) -> UnifyResponse[list[UserProduct]]:
+        """Poll device state."""
+        return await self._request(
+            list[UserProduct],
+            Method.GET,
+            "/api/bluiotdata/ha/v1/deviceStates",
+            params={"sns": sns},
+        )
+
+    async def control_device(self, payload: dict | None = None) -> UnifyResponse[dict] | str:
+        """Send a control command to a device."""
+        return await self._request(
+            dict,
+            method=Method.POST,
+            path="/api/bluiotdata/ha/v1/fulfillment",
+            body=payload,
+        )
+
+    async def bind_devices(self, payload: dict | None = None) -> UnifyResponse[dict] | str:
+        """Bind devices to the account."""
+        return await self._request(
+            dict,
+            method=Method.POST,
+            path="/api/bluiotdata/ha/v1/bindDevices",
+            body=payload,
+        )

pybluetti/unify_response.py

@@ -0,0 +1,23 @@
+"""The envelope every BLUETTI cloud API response is wrapped in."""
+
+from typing import Generic, TypeVar
+
+from pydantic import BaseModel
+
+T = TypeVar("T")
+
+
+class UnifyResponse(BaseModel, Generic[T]):
+    """The Unify Server Response class."""
+
+    msgId: str
+    msgCode: int
+    data: T | None = None
+
+    def is_ok(self) -> bool:
+        """Return true if the server response is success."""
+        return self.msgCode == 0
+
+    def has_data(self) -> bool:
+        """Return true if the server response is success and has response data."""
+        return self.is_ok() and self.data is not None

pybluetti/websocket.py

@@ -0,0 +1,212 @@
+"""STOMP-over-websocket client for BLUETTI's real-time device push updates."""
+
+import asyncio
+import json
+import logging
+import warnings
+from collections.abc import Callable
+
+import aiohttp
+
+# stomper's stompbuffer module has an invalid regex escape sequence that
+# raises a SyntaxWarning on import (fixed in no released version as of
+# 0.4.3); silence it here so it isn't misattributed to this package.
+with warnings.catch_warnings():
+    warnings.simplefilter("ignore", SyntaxWarning)
+    import stomper
+
+from .exceptions import ApplicationRuntimeException
+
+__LOGGER__ = logging.getLogger(__name__)
+
+
+class StompClient:
+    """A STOMP client connected to the BLUETTI cloud's push-update websocket."""
+
+    def __init__(
+        self,
+        session: aiohttp.ClientSession,
+        url: str,
+        access_token: str,
+        handler: Callable[[str], None] | None = None,
+        on_auth_expired: Callable[[], None] | None = None,
+    ) -> None:
+        """
+        Initialize the client.
+
+        - session: the aiohttp session to open the websocket connection on.
+        - url: the websocket base URL (region-specific).
+        - access_token: the OAuth2 access token to authenticate the connection with.
+        - handler: called with each MESSAGE frame's body.
+        - on_auth_expired: called when the cloud reports the access token as
+          expired (msgCode 805), so the caller can react.
+        """
+        self._session = session
+        self.__url = url + "/websocket"
+        self.__headers = {
+            "Host": self.__get_host(url),
+            "Authorization": access_token,
+        }
+        self.__handler = handler
+        self.on_auth_expired = on_auth_expired
+        self._ws: aiohttp.ClientWebSocketResponse | None = None
+        self.running = False
+
+        self._receive_task: asyncio.Task | None = None
+        self._heartbeat_task: asyncio.Task | None = None
+        self.heartbeat_interval = 10
+
+        self.reconnect_delay = 1  # initial reconnect delay (seconds)
+        self.max_reconnect_delay = 30  # max reconnect delay (seconds)
+
+    @staticmethod
+    def __get_host(connection_url: str) -> str:
+        host = connection_url.split("//")[1]
+        index = host.find("/")
+        host = host[0:index]
+
+        if host.find(":") > -1:
+            host = host.split(":")[0]
+        return host
+
+    async def connect(self) -> None:
+        """Connect to the ws server and start the background receive/heartbeat tasks."""
+        __LOGGER__.info("Start to connect the BLUETTI WebSocket Server.")
+        self.running = True
+
+        try:
+            self._ws = await self._session.ws_connect(self.__url, headers=self.__headers)
+
+            connect_frame = (
+                "CONNECT\n"
+                "accept-version:1.0,1.1,2.0\n"
+                "Host:" + self.__headers["Host"] + "\n"
+                "Authorization: " + self.__headers["Authorization"] + "\n"
+                "heart-beat:10000,10000\n"
+                "\n\x00\n"
+            )
+            await self._ws.send_str(connect_frame)
+        except Exception:
+            # Same resilience as a run-time disconnect: log and retry with
+            # backoff rather than letting a connection failure go silent.
+            __LOGGER__.exception("Failed to connect to the BLUETTI WebSocket Server")
+            await self.reconnect()
+            return
+
+        __LOGGER__.info("Connect the BLUETTI WebSocket Server successfully.")
+
+        self._receive_task = asyncio.ensure_future(self._run())
+        self._heartbeat_task = asyncio.ensure_future(self._heartbeat_loop())
+
+    async def disconnect(self) -> None:
+        """Stop reconnecting, cancel background tasks, and close the connection."""
+        self.running = False
+        tasks = [t for t in (self._receive_task, self._heartbeat_task) if t is not None]
+        for task in tasks:
+            task.cancel()
+        if tasks:
+            await asyncio.gather(*tasks, return_exceptions=True)
+        if self._ws is not None:
+            await self._ws.close()
+
+    async def reconnect(self) -> None:
+        """Reconnect with exponential backoff, if still running."""
+        __LOGGER__.info("Websocket reconnect")
+        if self.running:
+            await asyncio.sleep(self.reconnect_delay)
+            self.reconnect_delay = min(self.reconnect_delay * 2, self.max_reconnect_delay)
+            await self.connect()
+        else:
+            __LOGGER__.info("Websocket have stop do not reconnect")
+
+    async def _heartbeat_loop(self) -> None:
+        r"""Send a STOMP heartbeat ("\n") on the configured interval."""
+        while self.running:
+            await asyncio.sleep(self.heartbeat_interval)
+            if self._ws is None or self._ws.closed:
+                break
+            try:
+                await self._ws.send_str("\n")
+                __LOGGER__.debug("Sent STOMP heartbeat")
+            except Exception as e:
+                __LOGGER__.error("Failed to send heartbeat: %s", e)
+                break
+
+    async def _run(self) -> None:
+        """Receive and handle STOMP frames until the connection closes."""
+        try:
+            async for msg in self._ws:
+                if msg.type == aiohttp.WSMsgType.TEXT:
+                    await self._handle_frame(msg.data)
+                elif msg.type == aiohttp.WSMsgType.ERROR:
+                    __LOGGER__.error("The BLUETTI WebSocket raised an error: %s", self._ws.exception())
+                    break
+                elif msg.type in (aiohttp.WSMsgType.CLOSE, aiohttp.WSMsgType.CLOSED):
+                    __LOGGER__.debug("WebSocket connection closed: %s", msg)
+                    break
+        except Exception:
+            __LOGGER__.exception("BLUETTI WebSocket task crashed")
+
+        if self.running:
+            await self.reconnect()
+
+    async def _handle_frame(self, message: str) -> None:
+        """Parse and handle one incoming STOMP frame."""
+        __LOGGER__.debug("Received the BLUETTI websocket message:\n %s", message)
+
+        if not message or message == "\n":
+            __LOGGER__.debug("Received heartbeat from server")
+            return
+
+        frame = stomper.Frame()
+        frame.unpack(message)
+
+        if frame.cmd == "ERROR":
+            await self._handle_error_frame(frame)
+        elif frame.cmd == "CONNECTED":
+            await self._handle_connected_frame(frame)
+        elif frame.cmd == "MESSAGE":
+            self._invoke_handler(frame.body)
+
+    async def _handle_error_frame(self, frame: stomper.Frame) -> None:
+        error = frame.headers["message"].replace("\\c", ":")
+        error = json.loads(error)
+        if error["msgCode"] == 805:
+            # Stop everything without cancelling our own currently-running
+            # task (this runs inside _run()'s receive loop): flip the
+            # running flag and close the socket so the loop exits on its
+            # own next iteration, then stop the (separate) heartbeat task.
+            self.running = False
+            if self._heartbeat_task is not None:
+                self._heartbeat_task.cancel()
+            if self._ws is not None:
+                await self._ws.close()
+            if self.on_auth_expired is not None:
+                self.on_auth_expired()
+            __LOGGER__.info("token have expired stop ws connect")
+        else:
+            raise ApplicationRuntimeException(msgCode=error["msgCode"], errMessage=error["message"])
+
+    async def _handle_connected_frame(self, frame: stomper.Frame) -> None:
+        heartbeat = frame.headers.get("heart-beat", "0,0")
+        server_send, server_receive = map(int, heartbeat.split(","))
+        __LOGGER__.info(
+            "Server heartbeat configuration: send=%s, receive=%s",
+            server_send, server_receive,
+        )
+
+        user_name = frame.headers.get("user-name")
+        if not user_name:
+            __LOGGER__.error("CONNECTED frame missing 'user-name' header, cannot subscribe")
+            return
+        destination = f"/ws-subscribe/user/{user_name}/notify"
+        sub = stomper.subscribe(destination, "clientUniqueId", ack="auto")
+        await self._ws.send_str(sub)
+
+    def _invoke_handler(self, body: str) -> None:
+        if not self.__handler:
+            return
+        try:
+            self.__handler(body)
+        except Exception as e:
+            __LOGGER__.error("error from callback %s: %s", self.__handler, e)

pybluetti-0.1.0.dist-info/METADATA

@@ -0,0 +1,77 @@
+Metadata-Version: 2.5
+Name: pybluetti
+Version: 0.1.0
+Summary: Async Python client for the BLUETTI cloud API - device discovery, state, and control.
+Project-URL: Homepage, https://github.com/chpego/pybluetti
+Project-URL: Used by, https://github.com/bluetti-official/bluetti-home-assistant
+Project-URL: Issues, https://github.com/chpego/pybluetti/issues
+Author: chpego
+License-Expression: MIT
+License-File: LICENSE
+Classifier: Development Status :: 3 - Alpha
+Classifier: Intended Audience :: Developers
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Topic :: Home Automation
+Requires-Python: >=3.12
+Requires-Dist: aiohttp>=3.9
+Requires-Dist: pydantic>=2.0
+Requires-Dist: stomper>=0.4
+Provides-Extra: test
+Requires-Dist: aioresponses; extra == 'test'
+Requires-Dist: pytest; extra == 'test'
+Requires-Dist: pytest-asyncio; extra == 'test'
+Requires-Dist: pytest-cov; extra == 'test'
+Description-Content-Type: text/markdown
+
+# pybluetti
+
+Async Python client for the BLUETTI cloud API - device discovery, state, and control.
+
+## Status: fully async, not yet wired up or published
+
+This repository is the extraction target for the API client code that used to
+live in
+[`bluetti-home-assistant`](https://github.com/bluetti-official/bluetti-home-assistant)'s
+`custom_components/bluetti/api/`, following the same pattern
+[`pyenphase`](https://github.com/pyenphase/pyenphase) uses for the `enphase_envoy`
+Home Assistant integration: a standalone, independently testable and
+versionable library, decoupled from Home Assistant's own release cycle.
+
+The extraction is happening in three steps:
+
+1. **Done.** Move the client code here mechanically, decoupled from `hass`
+   (server URLs and an `on_auth_expired` callback are passed in as plain
+   constructor arguments instead - see `src/pybluetti/`).
+2. **Done.** Replace the blocking `websocket-client` transport (previously
+   run on a dedicated thread to keep it out of Home Assistant's event loop)
+   with `aiohttp`'s native async websocket client - `src/pybluetti/websocket.py`
+   has no threads left. STOMP protocol framing (`stomper`) is unchanged.
+3. *Not started.* Publish to PyPI, and switch `bluetti-home-assistant`'s
+   `manifest.json`/imports to depend on this package instead of its own
+   in-tree copy.
+
+## Why extract it
+
+- **Independent testing and versioning**, not tied to Home Assistant's release cadence.
+- **A step toward Home Assistant core inclusion** - core integrations are expected to depend on
+  an external library for the actual device/API communication, not embed raw HTTP/websocket
+  calls directly in the integration.
+- **Fixed a known gap along the way**: the embedded client used to run the blocking
+  `websocket-client` library on a dedicated thread to keep it out of Home Assistant's event
+  loop. `pybluetti` is fully async instead, matching `bluetti-home-assistant`'s own
+  `quality_scale.yaml` `async-dependency` goal once step 3 wires it up.
+
+## Development
+
+```bash
+scripts/setup   # install runtime + test dependencies
+scripts/test    # run the test suite (100% line coverage enforced)
+scripts/lint    # run ruff, auto-fixing what it safely can
+```
+
+## License
+
+MIT - see [LICENSE](LICENSE).

pybluetti-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+pybluetti/__init__.py,sha256=7PwyzoAgM4k75y1SmBsZP6hjOwRKBpOgQRCz5RyXI0U,909
+pybluetti/client.py,sha256=tseKGBpb9t1PsJW5XgBFDxb5DP6BzfepziamQvWv1lk,3721
+pybluetti/const.py,sha256=OubZ1kb16163EJAeDTDfBwkN19OcVpRtqGuar9xMLuY,295
+pybluetti/exceptions.py,sha256=Zs1ZxrxG3y2TknADE5tRDkjGxacPi3Q_2fihtdp_4Uc,536
+pybluetti/models.py,sha256=7B-bAQEsTBmwcXW83K7q-w8B8Gln9xcJvDJhsfAJHDM,319
+pybluetti/product_client.py,sha256=a9U-y2H_M_xM6ukz5ma9RLPgxPH_n96uMrLu6MKnPbw,1828
+pybluetti/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+pybluetti/unify_response.py,sha256=UnP1dKpYGyhH-caiMJdQDTrlzlc2xAzjwCp8mboPX6E,596
+pybluetti/websocket.py,sha256=FsFhY3p0uojFzplAiDEUW0WKMFoc68bdClKTP8U2PUg,8375
+pybluetti-0.1.0.dist-info/METADATA,sha256=e2vim-Jlz0jgLQ_li0fB5D6-PATNg-KuaKWYa83I1Vs,3335
+pybluetti-0.1.0.dist-info/WHEEL,sha256=zOwg4jB6zX2kU910N-cMawjivD6tO8NEWvE12je1bVk,87
+pybluetti-0.1.0.dist-info/licenses/LICENSE,sha256=G3jdL6SdKnZnpGDLU6xdas4Vaqn0dw1cNgCc5ZuzTro,1063
+pybluetti-0.1.0.dist-info/RECORD,,

pybluetti-0.1.0.dist-info/WHEEL

@@ -0,0 +1,4 @@
+Wheel-Version: 1.0
+Generator: hatchling 1.32.0
+Root-Is-Purelib: true
+Tag: py3-none-any

pybluetti-0.1.0.dist-info/licenses/LICENSE

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