SolixBLE 3.6.0__tar.gz → 3.8.0__tar.gz

{solixble-3.6.0 → solixble-3.8.0}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SolixBLE
-Version: 3.6.0
+Version: 3.8.0
 Summary: Python module for monitoring & controlling Bluetooth Anker Solix devices
 Author-email: Harvey Lelliott <harveylelliott@duck.com>
 License: MIT License
@@ -138,3 +138,8 @@ pip install SolixBLE
 See the `Generic` class inside `SolixBLE/devices/generic.py` and the 
 [documentation](https://solixble.readthedocs.io/en/latest/new_devices.html)
 for guidance on how to add support for new devices.
+
+
+## Disclaimer
+
+SolixBLE is a software library designed to work with Anker Solix/Prime devices. ANKER is a registered trademark of Anker Innovations Limited. This project is not affiliated with, endorsed by, or sponsored by Anker Innovations Limited (Though I wouldn't mind being sponsored 😉). All other trademarks cited herein are the property of their respective owners.

{solixble-3.6.0 → solixble-3.8.0}/README.md

@@ -89,3 +89,8 @@ pip install SolixBLE
 See the `Generic` class inside `SolixBLE/devices/generic.py` and the 
 [documentation](https://solixble.readthedocs.io/en/latest/new_devices.html)
 for guidance on how to add support for new devices.
+
+
+## Disclaimer
+
+SolixBLE is a software library designed to work with Anker Solix/Prime devices. ANKER is a registered trademark of Anker Innovations Limited. This project is not affiliated with, endorsed by, or sponsored by Anker Innovations Limited (Though I wouldn't mind being sponsored 😉). All other trademarks cited herein are the property of their respective owners.

{solixble-3.6.0 → solixble-3.8.0}/SolixBLE/__init__.py

@@ -16,6 +16,7 @@ from .devices import (
     Generic,
     PrimeCharger160w,
     PrimeCharger250w,
+    PrimePowerBank20k,
     Solarbank2,
     Solarbank3,
 )
@@ -25,9 +26,9 @@ from .states import (
     ChargingStatusF3800,
     DisplayTimeout,
     LightStatus,
+    PortOverload,
     PortStatus,
     TemperatureUnit,
-    PortOverload,
 )
 from .utilities import discover_devices
 
@@ -45,6 +46,7 @@ __all__ = [
     "Solarbank3",
     "PrimeCharger160w",
     "PrimeCharger250w",
+    "PrimePowerBank20k",
     "Generic",
     "ChargingStatus",
     "ChargingStatusF3800",

{solixble-3.6.0 → solixble-3.8.0}/SolixBLE/device.py

@@ -52,6 +52,11 @@ _LOGGER = logging.getLogger(__name__)
 class SolixBLEDevice:
     """Solix BLE device object."""
 
+    #: Command codes (hex) that carry telemetry for this device. Subclasses can
+    #: override this if their model uses different telemetry command codes
+    #: (e.g the C1000 Gen 2 uses ``c421``/``c900`` instead of ``c402``/``c405``).
+    _TELEMETRY_COMMANDS: tuple[str, ...] = ("c402", "4300", "c405")
+
     def __init__(self, ble_device: BLEDevice) -> None:
         """Initialise device object. Does not connect automatically."""
 
@@ -62,8 +67,8 @@ class SolixBLEDevice:
 
         self._ble_device: BLEDevice = ble_device
         self._client: BleakClient | None = None
-        self._telemetry_payload_small: bytes | None = None
-        self._telemetry_payload_large: bytes | None = None
+        self._fragment_buffers: dict[bytes, dict[int, bytes]] = {}
+        self._fragment_totals: dict[bytes, int] = {}
         self._data: dict[str, bytes] | None = None
         self._last_data_timestamp: datetime | None = None
         self._last_packet_timestamp: datetime | None = None
@@ -195,6 +200,15 @@ class SolixBLEDevice:
         if self._disconnect_event.is_set():
             self._disconnect_event.clear()
 
+        # Run any device-specific post-connect setup (e.g sending a subscribe
+        # command to start telemetry). This runs on every (re)connection. Errors
+        # are logged but do not abort the connection; the automatic reconnect
+        # task will retry.
+        try:
+            await self._post_connect()
+        except Exception:
+            _LOGGER.exception(f"Error running post-connect setup for '{self.name}'!")
+
         # Start an automatic reconnect task if its not running already
         if self._auto_reconnect_task is None:
             self._auto_reconnect_task = asyncio.create_task(self._auto_reconnect())
@@ -205,6 +219,17 @@ class SolixBLEDevice:
 
         return True
 
+    async def _post_connect(self) -> None:
+        """Run device-specific setup after a negotiated connection is established.
+
+        Called by :meth:`connect` once the encrypted session has been negotiated
+        (so :meth:`_send_command` may be used) and on every automatic reconnect.
+        The default implementation does nothing; subclasses can override it to,
+        for example, send a subscribe command to start a telemetry stream (see
+        :class:`~SolixBLE.devices.c1000g2.C1000G2`).
+        """
+        pass
+
     async def disconnect(self) -> None:
         """Disconnect from device and reset internal state.
 
@@ -347,11 +372,6 @@ class SolixBLEDevice:
         # Extract command
         packet_cmd = bytes([packet_copy.pop(0), packet_copy.pop(0)])
 
-        # Telemetry packets have an extra field which must be popped
-        if packet_pattern.hex() == "03010f" and packet_cmd.hex() == "c402":
-            special_value = bytes([packet_copy.pop(0)])
-            _LOGGER.debug(f"Special value: {special_value.hex()}")
-
         # Extract payload
         packet_payload = bytes(packet_copy)
 
@@ -498,7 +518,9 @@ class SolixBLEDevice:
         )
         return cipher.encrypt(padded_data)
 
-    async def _process_telemetry_packet(self, payload: bytes) -> None:
+    async def _process_telemetry_packet(
+        self, payload: bytes, cmd: bytes = None
+    ) -> None:
         """Process a telemetry packet from the device.
 
         This performs the default processing of telemetry packets in which
@@ -507,40 +529,44 @@ class SolixBLEDevice:
         telemetry.
         """
 
-        # Anker devices seem to split data across multiple
-        # packets so we need to wait until we have both
-        # packets before we can decrypt all of the data
-        if len(payload) < 50:
-            self._telemetry_payload_small = payload
-
-        # If we receive a big packet it invalidates the
-        # last small one since the big one comes before
-        # the small one
-        elif len(payload) > 230:
-            self._telemetry_payload_large = payload
-            self._telemetry_payload_small = None
+        # First byte encodes fragment info (high nibble = index, low = total)
+        fragment_index = (payload[0] >> 4) & 0x0F
+        fragment_total = payload[0] & 0x0F
 
-        else:
-            _LOGGER.warning(
-                f"Telemetry payload has an unexpected length of {len(payload)}!"
+        # Multi-part message
+        if fragment_total > 1:
+            fragment_data = payload[1:]
+            cmd_key = bytes(cmd)
+            _LOGGER.debug(
+                f"Fragment {fragment_index}/{fragment_total} for cmd {cmd.hex()}, {len(fragment_data)} bytes"
             )
 
-        if (
-            self._telemetry_payload_small is None
-            or self._telemetry_payload_large is None
-        ):
-            _LOGGER.debug("Missing other payload!")
-            return
+            # Store fragment
+            if cmd_key not in self._fragment_buffers or fragment_index == 1:
+                self._fragment_buffers[cmd_key] = {}
+                self._fragment_totals[cmd_key] = fragment_total
+
+            self._fragment_buffers[cmd_key][fragment_index] = fragment_data
 
-        new_payload = self._telemetry_payload_large + self._telemetry_payload_small
+            # Wait until all fragments have arrived
+            if len(self._fragment_buffers[cmd_key]) < fragment_total:
+                _LOGGER.debug("Waiting for remaining fragments...")
+                return
 
-        # If we are accepting the new payload we invalidate
-        # the partial payloads
-        self._telemetry_payload_large = None
-        self._telemetry_payload_small = None
+            # Reassemble in order
+            payload = b"".join(
+                self._fragment_buffers[cmd_key][i]
+                for i in sorted(self._fragment_buffers[cmd_key])
+            )
+            del self._fragment_buffers[cmd_key]
+            del self._fragment_totals[cmd_key]
+            _LOGGER.debug(f"Reassembled payload: {len(payload)} bytes")
 
-        _LOGGER.debug(f"Merged payload: {new_payload.hex()}")
-        decrypted_payload = self._decrypt_payload(new_payload)
+        else:
+            # Strip fragment info
+            payload = payload[1:]
+
+        decrypted_payload = self._decrypt_payload(payload)
         _LOGGER.debug(f"Decrypted payload: {decrypted_payload.hex()}")
         parameters = self._parse_payload(decrypted_payload)
         return await self._process_telemetry(parameters)
@@ -584,7 +610,7 @@ class SolixBLEDevice:
     ) -> None:
         """Process a notification from the device."""
 
-        _LOGGER.debug(f"The client the notification is from is: {client}")
+        _LOGGER.debug(f"The client the notification is from: {client}")
 
         if self._client is not client:
             _LOGGER.debug("Ignoring notification from old client")
@@ -614,51 +640,55 @@ class SolixBLEDevice:
         # Match against common message types
         match pattern.hex():
 
-            # Encryption negotiation
+            # Negotiation messages
             case "030001":
-                _LOGGER.debug("Received encryption negotiation message!")
+                _LOGGER.debug("Received negotiation message!")
                 return await self._process_negotiation(cmd, payload)
 
-            # Encrypted messages
+            # Session messages
             case "03010f" | "030111":
 
-                match cmd.hex():
-
-                    # Telemetry messages
-                    case "c402" | "4300":
-                        _LOGGER.debug("Received telemetry message!")
-                        return await self._process_telemetry_packet(payload)
-
-                    # Unknown messages
-                    case _:
-                        _LOGGER.debug(f"Received unknown message of type: {cmd.hex()}")
-                        try:
-
-                            # If the payload is one byte too short and we are
-                            # using the default AES (CBC) then try putting the
-                            # last byte of the cmd in front of it
-                            if (
-                                len(payload) % 16 == 15
-                                and self._decrypt_payload
-                                is SolixBLEDevice._decrypt_payload
-                            ):
-                                _LOGGER.debug(
-                                    "Using special trick of embedded part of CMD in payload..."
-                                )
-                                payload = cmd[1].to_bytes() + payload
+                # Non-encrypted telemetry messages
+                if cmd.hex() == "0300":
+                    _LOGGER.debug("Received non-encrypted telemetry message!")
+                    parameters = self._parse_payload(payload)
+                    return await self._process_telemetry(parameters)
 
-                            decrypted_payload = self._decrypt_payload(payload)
-                            _LOGGER.debug(
-                                f"Decrypted payload: {decrypted_payload.hex()}"
-                            )
-                            parameters = self._parse_payload(decrypted_payload)
+                # Encrypted telemetry messages
+                elif cmd.hex() in self._TELEMETRY_COMMANDS:
+                    _LOGGER.debug("Received encrypted telemetry message!")
+                    return await self._process_telemetry_packet(payload, cmd)
+
+                # Unknown messages
+                else:
+                    _LOGGER.debug(f"Received unknown message of type: {cmd.hex()}")
+                    try:
+
+                        # If the payload is one byte too short and we are
+                        # using the default AES (CBC) then try putting the
+                        # last byte of the cmd in front of it
+                        if (
+                            len(payload) % 16 == 15
+                            and self._decrypt_payload
+                            is SolixBLEDevice._decrypt_payload
+                        ):
                             _LOGGER.debug(
-                                f"Parameters: {self._parameters_to_str(parameters, types=True)}"
-                            )
-                        except Exception:
-                            _LOGGER.exception(
-                                "Exception decrypting unknown message type"
+                                "Using special trick of embedded part of CMD in payload..."
                             )
+                            payload = cmd[1].to_bytes() + payload
+
+                        decrypted_payload = self._decrypt_payload(payload)
+                        _LOGGER.debug(
+                            f"Decrypted payload: {decrypted_payload.hex()}"
+                        )
+                        parameters = self._parse_payload(decrypted_payload)
+                        _LOGGER.debug(
+                            f"Parameters: {self._parameters_to_str(parameters, types=True)}"
+                        )
+                    except Exception:
+                        _LOGGER.exception(
+                            "Exception decrypting unknown message type"
+                        )
 
             case _:
                 _LOGGER.warning(
@@ -1041,8 +1071,8 @@ class SolixBLEDevice:
             self._data = None
             self._last_data_timestamp = None
 
-        self._telemetry_payload_small = None
-        self._telemetry_payload_large = None
+        self._fragment_buffers = {}
+        self._fragment_totals = {}
         self._shared_secret = None
         self._last_packet_timestamp = None
         self._negotiation_timestamp = None

{solixble-3.6.0 → solixble-3.8.0}/SolixBLE/devices/__init__.py

@@ -14,6 +14,7 @@ from .f3800 import F3800
 from .generic import Generic
 from .prime_charger_160w import PrimeCharger160w
 from .prime_charger_250w import PrimeCharger250w
+from .prime_power_bank_20k import PrimePowerBank20k
 from .solarbank2 import Solarbank2
 from .solarbank3 import Solarbank3
 
@@ -29,5 +30,6 @@ __all__ = [
     "Solarbank3",
     "PrimeCharger160w",
     "PrimeCharger250w",
+    "PrimePowerBank20k",
     "Generic",
 ]

{solixble-3.6.0 → solixble-3.8.0}/SolixBLE/devices/c1000g2.py

@@ -4,33 +4,96 @@
 
 """
 
-from ..const import DEFAULT_METADATA_BOOL
 from ..device import SolixBLEDevice
 from ..states import PortStatus
 
+#: Command sent after connecting to start the telemetry stream. Unlike the gen-1
+#: models, the Gen 2 streams nothing until it receives this subscribe command.
+CMD_SUBSCRIBE = "4100"
+SUBSCRIBE_PAYLOAD = "a10121"
+
+CMD_AC_OUTPUT = "4101"
+CMD_DC_OUTPUT = "4102"
+
+PAYLOAD_ON = "a10121a2020101"
+PAYLOAD_OFF = "a10121a2020100"
+
 
 class C1000G2(SolixBLEDevice):
     """
     C1000(X) Gen 2 Power Station.
 
-    Use this class to connect and monitor a Gen 2 C1000(X) power station.
-    This model is also known as the A1763.
-
-    .. note::
-        This model was added using data from anker-solix-api. It has not been
-        tested!
-
-    .. note::
-        It should be possible to add more sensors. I think devices with lots of
-        telemetry values split them up into multiple messages but I have not
-        played around with this yet. That and I am being a bit conservative with
-        these initial implementations, if you want more sensors and are willing
-        to help with testing feel free to raise a GitHub issue.
+    Use this class to connect, monitor and control a Gen 2 C1000(X) power
+    station. This model is also known as the A1763.
 
+    The Gen 2 uses the same encryption and telemetry framing as the gen-1
+    models but with different command codes: it must be sent a subscribe command
+    (``4100``) after connecting before it streams any telemetry, its telemetry
+    arrives on commands ``c421``/``c900``, its AC output is controlled with
+    command ``4101`` and its DC output with command ``4102``. Telemetry and
+    AC/DC on/off control have been confirmed on real hardware.
     """
 
     _EXPECTED_TELEMETRY_LENGTH: int = 253
 
+    #: The Gen 2 pushes telemetry on different command codes to the gen-1 models.
+    _TELEMETRY_COMMANDS: tuple[str, ...] = ("c421", "c900")
+
+    async def _post_connect(self) -> None:
+        """Subscribe to telemetry once connected.
+
+        The Gen 2 streams no telemetry until it receives this command, so we send
+        it after every (re)connection.
+        """
+        await self._send_command(
+            cmd=bytes.fromhex(CMD_SUBSCRIBE),
+            payload=bytes.fromhex(SUBSCRIBE_PAYLOAD),
+        )
+
+    async def turn_ac_on(self) -> None:
+        """Turn the AC output on.
+
+        :raises ConnectionError: If not connected to device.
+        :raises BleakError: If command transmission fails.
+        """
+        await self._send_command(
+            cmd=bytes.fromhex(CMD_AC_OUTPUT), payload=bytes.fromhex(PAYLOAD_ON)
+        )
+
+    async def turn_ac_off(self) -> None:
+        """Turn the AC output off.
+
+        :raises ConnectionError: If not connected to device.
+        :raises BleakError: If command transmission fails.
+        """
+        await self._send_command(
+            cmd=bytes.fromhex(CMD_AC_OUTPUT), payload=bytes.fromhex(PAYLOAD_OFF)
+        )
+
+    async def turn_dc_on(self) -> None:
+        """Turn the DC (12 V) output on.
+
+        Confirmed on real hardware: the 12 V port physically switched and the
+        ``b2`` status byte latched on. The Gen 2 reuses the AC on/off payload on
+        a different command code (``4102``).
+
+        :raises ConnectionError: If not connected to device.
+        :raises BleakError: If command transmission fails.
+        """
+        await self._send_command(
+            cmd=bytes.fromhex(CMD_DC_OUTPUT), payload=bytes.fromhex(PAYLOAD_ON)
+        )
+
+    async def turn_dc_off(self) -> None:
+        """Turn the DC (12 V) output off.
+
+        :raises ConnectionError: If not connected to device.
+        :raises BleakError: If command transmission fails.
+        """
+        await self._send_command(
+            cmd=bytes.fromhex(CMD_DC_OUTPUT), payload=bytes.fromhex(PAYLOAD_OFF)
+        )
+
     @property
     def serial_number(self) -> str:
         """Device serial number.
@@ -73,7 +136,7 @@ class C1000G2(SolixBLEDevice):
 
     @property
     def power_out(self) -> int:
-        """Total Power Out.
+        """Total Power Out (watts).
 
         :returns: Total power out or default int value.
         """
@@ -81,7 +144,7 @@ class C1000G2(SolixBLEDevice):
 
     @property
     def ac_power_in(self) -> int:
-        """AC Power In.
+        """AC Power In (watts).
 
         :returns: Total AC power in or default int value.
         """
@@ -94,13 +157,24 @@ class C1000G2(SolixBLEDevice):
         PortStatus.NOT_CONNECTED signifies off.
         PortStatus.OUTPUT signifies on.
 
+        .. note::
+           :collapsible: closed
+
+           The AC port status is the first byte of the ``a7`` parameter,
+           mirroring the ``04 <status> <watts LE>`` per-port shape used by the
+           DC port (``b2``) and the USB ports; ``ac_power_out`` reads the watts
+           from this same ``a7`` TLV. Confirmed on hardware: ``a7[1]`` latches
+           ``01`` (OUTPUT) when AC is on and ``00`` when off, tracking the relay.
+           (The ``a4`` parameter is constant at the previously-used offset and
+           does NOT reflect the AC state.)
+
         :returns: Status of the AC port.
         """
         return PortStatus(self._parse_int("a7", begin=1, end=2))
 
     @property
     def ac_power_out(self) -> int:
-        """AC Power Out.
+        """AC Power Out (watts).
 
         :returns: Total AC power out or default int value.
         """
@@ -116,7 +190,9 @@ class C1000G2(SolixBLEDevice):
 
     @property
     def solar_power_in(self) -> int:
-        """Solar/DC Power In.
+        """Solar/DC Power In (watts).
+
+        .. note:: Offset inferred, not yet confirmed on hardware (no solar/DC-in capture taken).
 
         :returns: Solar/DC power in or default int value.
         """
@@ -164,7 +240,7 @@ class C1000G2(SolixBLEDevice):
 
     @property
     def usb_c3_power(self) -> int:
-        """USB C3 Power.
+        """USB C3 Power (watts).
 
         :returns: USB port C3 power or default int value.
         """
@@ -190,13 +266,19 @@ class C1000G2(SolixBLEDevice):
     def dc_output(self) -> PortStatus:
         """DC Port Status.
 
+        Confirmed on hardware: ``b2[1]`` latched ``01`` (OUTPUT) when the 12 V
+        port was switched on and ``00`` (NOT_CONNECTED) when off.
+
         :returns: Status of the DC output port.
         """
         return PortStatus(self._parse_int("b2", begin=1, end=2))
 
     @property
     def dc_power_out(self) -> int:
-        """DC Power Out.
+        """DC Power Out (watts).
+
+        Confirmed on hardware: ``b2`` [2:4] read 6 W with a 12 V load on the DC
+        output, matching the ``04 <status> <watts LE>`` per-port shape.
 
         :returns: DC power out or default int value.
         """