SolixBLE 3.6.0__tar.gz → 3.7.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SolixBLE
-Version: 3.6.0
+Version: 3.7.0
 Summary: Python module for monitoring & controlling Bluetooth Anker Solix devices
 Author-email: Harvey Lelliott <harveylelliott@duck.com>
 License: MIT License

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

@@ -62,8 +62,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
@@ -347,11 +347,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 +493,7 @@ 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 +502,46 @@ 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
 
-        new_payload = self._telemetry_payload_large + self._telemetry_payload_small
+            self._fragment_buffers[cmd_key][fragment_index] = fragment_data
 
-        # If we are accepting the new payload we invalidate
-        # the partial payloads
-        self._telemetry_payload_large = None
-        self._telemetry_payload_small = None
+            # Wait until all fragments have arrived
+            if len(self._fragment_buffers[cmd_key]) < fragment_total:
+                _LOGGER.debug("Waiting for remaining fragments...")
+                return
 
-        _LOGGER.debug(f"Merged payload: {new_payload.hex()}")
-        decrypted_payload = self._decrypt_payload(new_payload)
+            # 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"
+            )
+
+        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 +585,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")
@@ -625,9 +626,9 @@ class SolixBLEDevice:
                 match cmd.hex():
 
                     # Telemetry messages
-                    case "c402" | "4300":
+                    case "c402" | "4300" | "c405":
                         _LOGGER.debug("Received telemetry message!")
-                        return await self._process_telemetry_packet(payload)
+                        return await self._process_telemetry_packet(payload, cmd)
 
                     # Unknown messages
                     case _:
@@ -1041,8 +1042,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.7.0}/SolixBLE/devices/solarbank2.py

@@ -4,8 +4,38 @@
 
 """
 
-from ..const import DEFAULT_METADATA_FLOAT, DEFAULT_METADATA_STRING
+from enum import Enum
+
+from ..const import (
+    DEFAULT_METADATA_BOOL,
+    DEFAULT_METADATA_FLOAT,
+    DEFAULT_METADATA_STRING,
+)
 from ..device import SolixBLEDevice
+from ..states import GridStatus, LightMode, SBPowerCutoff, SBUsageMode, TemperatureUnit
+
+
+class MaxLoadSB2(Enum):
+    """
+    Maximum output power of the Solarbank 2 in watts.
+    
+    Only specific values are allowed.
+    """
+
+    #: The maximum load is unknown.
+    UNKNOWN = -1
+
+    #: 350 watts.
+    W350 = 350
+
+    #: 600 watts.
+    W600 = 600
+
+    #: 800 watts.
+    W800 = 800
+
+    #: 1000 watts.
+    W1000 = 1000
 
 
 class Solarbank2(SolixBLEDevice):
@@ -15,10 +45,6 @@ class Solarbank2(SolixBLEDevice):
     Use this class to connect and monitor a Solarbank 2 power station.
     This model is also known as the A17C1.
 
-    .. 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
@@ -132,9 +158,9 @@ class Solarbank2(SolixBLEDevice):
 
     @property
     def pv_yield(self) -> float:
-        """Solar power generated.
+        """Solar energy generated in kWh.
 
-        :returns: Total solar power generated or default float value.
+        :returns: Total solar energy generated or default float value.
         """
         if self._data is None:
             return DEFAULT_METADATA_FLOAT
@@ -143,18 +169,20 @@ class Solarbank2(SolixBLEDevice):
 
     @property
     def charged_energy(self) -> float:
-        """Energy used to charge the battery?
+        """Total accumulated energy that passed through the battery in kWh
 
-        :returns: I don't know what this means or default float value.
+        :returns: The amount of energy or default float value.
         """
         if self._data is None:
             return DEFAULT_METADATA_FLOAT
 
-        return self._parse_int("b2", begin=1) / 10000.0
+        # The / 100 000 is correct despite all other divisors being 10 000.
+        # This is the "Storage" stats field in the Anker app
+        return self._parse_int("b2", begin=1) / 100000.0
 
     @property
     def output_energy(self) -> float:
-        """Output energy.
+        """Output energy in kWh.
 
         :returns: Total energy output or default float value.
         """
@@ -305,3 +333,115 @@ class Solarbank2(SolixBLEDevice):
             return DEFAULT_METADATA_FLOAT
 
         return self._parse_int("d3", begin=1) / 10.0
+
+    @property
+    def error_code(self) -> int:
+        """Device error code.
+
+        :returns: Error code or default int value.
+        """
+        return self._parse_int("a5", begin=1)
+
+    @property
+    def temperature_unit(self) -> TemperatureUnit:
+        """Temperature unit setting.
+
+        :returns: Temperature unit (Celsius or Fahrenheit).
+        """
+        return TemperatureUnit(self._parse_int("a9", begin=1))
+
+    @property
+    def output_cutoff_data(self) -> SBPowerCutoff:
+        """
+        Output cutoff threshold in %.
+
+        Minimum battery SOC to maintain.
+
+        :returns: Output cutoff battery SOC threshold.
+        """
+        return SBPowerCutoff(self._parse_int("b4", begin=1))
+
+    @property
+    def lowpower_input_data(self) -> int:
+        """Low power input data.
+
+        :returns: Low power input data or default int value.
+        """
+        return self._parse_int("b5", begin=1)
+
+    @property
+    def input_cutoff_data(self) -> SBPowerCutoff:
+        """Input cutoff threshold in %.
+
+        :returns: Input cutoff battery SOC threshold.
+        """
+        return SBPowerCutoff(self._parse_int("b6", begin=1))
+
+    @property
+    def max_load(self) -> MaxLoadSB2:
+        """
+        Maximum output power in watts.
+        
+        Maximum legal value depends on country of operation.
+
+        :returns: Maximum load as a MaxLoadSB2 enum value.
+        """
+        return MaxLoadSB2(self._parse_int("c2", begin=1))
+
+    @property
+    def usage_mode(self) -> SBUsageMode:
+        """Usage mode.
+
+        :returns: Usage mode as a SBUsageMode enum value.
+        """
+        return SBUsageMode(self._parse_int("c6", begin=1))
+
+    @property
+    def home_load_preset(self) -> int:
+        """Home load preset in watts.
+
+        :returns: Home load preset in watts or default int value.
+        """
+        return self._parse_int("c7", begin=1)
+
+    @property
+    def light_mode(self) -> LightMode:
+        """Light mode. Normal or Mood.
+
+        :returns: Light mode.
+        """
+        return LightMode(self._parse_int("d2", begin=1))
+
+    @property
+    def grid_status(self) -> GridStatus:
+        """Grid connection status.
+
+        :returns: Grid status.
+        """
+        return GridStatus(self._parse_int("e0", begin=1))
+
+    @property
+    def light_on(self) -> bool | None:
+        """Whether the light is switched on.
+        Original value is inverted because it is called "light_off_switch"
+
+        :returns: True if light is on, False if off.
+        """
+        return (
+            not bool(self._parse_int("e1", begin=1))
+            if self._data is not None
+            else DEFAULT_METADATA_BOOL
+        )
+
+    @property
+    def battery_heating(self) -> bool | None:
+        """Whether the battery is currently heating.
+
+        :returns: True if heating, False if not heating.
+        """
+        return (
+            bool(self._parse_int("e8", begin=1))
+            if self._data is not None
+            else DEFAULT_METADATA_BOOL
+        )
+

{solixble-3.6.0 → solixble-3.7.0}/SolixBLE/prime_device.py

@@ -487,7 +487,7 @@ class PrimeDevice(SolixBLEDevice):
     # Packet processing #
     #####################
 
-    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 an Anker Prime device.
 

{solixble-3.6.0 → solixble-3.7.0}/SolixBLE/states.py

@@ -90,6 +90,19 @@ class LightStatus(Enum):
     SOS = 4
 
 
+class LightMode(Enum):
+    """The light mode of the device."""
+
+    #: The light mode is unknown.
+    UNKNOWN = -1
+
+    #: Normal light mode.
+    NORMAL = 0
+
+    #: Mood light mode.
+    MOOD = 1
+
+
 class DisplayTimeout(Enum):
     """Display timeout on device in seconds. Only specific values are allowed."""
 
@@ -123,6 +136,68 @@ class TemperatureUnit(Enum):
     #: Display unit is Fahrenheit.
     FAHRENHEIT = 1
 
+class GridStatus(Enum):
+    """The grid connection status."""
+
+    #: The grid status is unknown.
+    UNKNOWN = -1
+
+    #: Grid is connected and OK.
+    OK = 1
+
+    #: Undocumented in API, but device operates as expected and
+    #: outputs power to grid. Maybe a pure "dispense" state because
+    #: SB2 can't draw power from the grid
+    OK_AS_WELL_I_GUESS = 2
+
+    #: Grid is connecting.
+    CONNECTING = 3
+
+    #: No grid connection.
+    NO_GRID = 6
+
+
+class SBUsageMode(Enum):
+    """Usage mode of a Solarbank device."""
+
+    #: The usage mode is unknown.
+    UNKNOWN = -1
+
+    #: Manual (schedule) mode.
+    MANUAL = 1
+
+    #: Smart meter mode.
+    SMARTMETER = 2
+
+    #: Smart plugs mode.
+    SMARTPLUGS = 3
+
+    #: Backup mode.
+    BACKUP = 4
+
+    #: Use time mode.
+    USE_TIME = 5
+
+    #: Smart mode.
+    SMART = 7
+
+    #: Time slot mode.
+    TIME_SLOT = 8
+
+
+class SBPowerCutoff(Enum):
+    """Power cutoff threshold of a Solarbank device in %."""
+
+    #: The cutoff threshold is unknown.
+    UNKNOWN = -1
+
+    #: 5 %.
+    P5 = 5
+
+    #: 10 %.
+    P10 = 10
+
+
 class PortOverload(Enum):
     """The overload status of a port."""
 

{solixble-3.6.0 → solixble-3.7.0}/SolixBLE.egg-info/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SolixBLE
-Version: 3.6.0
+Version: 3.7.0
 Summary: Python module for monitoring & controlling Bluetooth Anker Solix devices
 Author-email: Harvey Lelliott <harveylelliott@duck.com>
 License: MIT License

{solixble-3.6.0 → solixble-3.7.0}/pyproject.toml

@@ -1,6 +1,6 @@
 [project]
 name = "SolixBLE"
-version = "3.6.0"
+version = "3.7.0"
 dependencies = [
   "bleak>=0.19.0",
   "cryptography",

{solixble-3.6.0 → solixble-3.7.0}/tests/test_devices.py

@@ -22,9 +22,12 @@ from SolixBLE import (
     PortStatus,
     PrimeCharger160w,
     PrimeDevice,
+    Solarbank2,
     SolixBLEDevice,
     TemperatureUnit,
 )
+from SolixBLE.devices.solarbank2 import MaxLoadSB2
+from SolixBLE.states import GridStatus, LightMode, SBPowerCutoff, SBUsageMode
 from tests.const import (
     MOCK_BLE_DEVICE,
     NEGOTIATION_RESPONSES_PRIME,
@@ -614,6 +617,51 @@ from tests.helpers import MockDevice
             },
             id="c300_dc_mixed_values",
         ),
+        pytest.param(
+            Solarbank2,
+            "a10131a2110041504347513830453030303030303030a302013aa4020101a503020000a605030100060aa7050300000631a8050300030306a9020100aa020111ab050300000000ac0503f4010000ad02013aae020100af020100b0050300000000b10503e0bd0200b20503723c0a00b305038d840200b4020105b5020104b6020105b7050388130000b8020101b9020100ba050328000000bb020100bc050300000000bd050300000000be050300000000bf050300000000c0110000000000000000000000000000000000c1020100c203022003c40503f4010000c5020100c6020101c703023200c8050300000000c9050306000000ca050300000000cb050300000000cc050300000000cd050300000000d2020100d30503f4010000d4110000000000000000000000000000000000d503020000d6110000000000000000000000000000000000d703020000d8110000000000000000000000000000000000d903020000da110000000000000000000000000000000000db03020000dc110000000000000000000000000000000000dd03020000de110000000000000000000000000000000000df03020000e0020102e1020101e2020100e3020100e4020100e5020100e6020100e7020100e8020100e9020100ea020101fe05039a46d969fb050300000000fc1604010101010001010101010100000000000000000000",
+            {
+                "serial_number": "APCGQ80E00000000",
+                "battery_percentage": 58,
+                "battery_percentage_aggregate": 58,
+                "error_code": 0,
+                "software_version": "1.6.8.1.6.5.3.7.7",
+                "software_version_controller": "8.2.2.4.7.6.8.0.0",
+                "software_version_expansion": "1.0.0.8.6.0.6.7.2",
+                "temperature_unit": TemperatureUnit.CELSIUS,
+                "temperature": 17,
+                "solar_power_in": 0.0,
+                "solar_pv_1_power_in": 0.0,
+                "solar_pv_2_power_in": 0.0,
+                "solar_pv_3_power_in": 0.0,
+                "solar_pv_4_power_in": 0.0,
+                "ac_power_out": 50.0,
+                "ac_power_out_sockets": 0.0,
+                "battery_charge_power": 0.0,
+                "battery_discharge_power": 50.0,
+                "pv_yield": 17.968,
+                "charged_energy": 6.70834,
+                "output_energy": 16.5005,
+                "grid_to_home_power": 0.0,
+                "pv_to_grid_power": 0.0,
+                "grid_import_energy": 0.0,
+                "grid_export_energy": 0.0,
+                "house_demand": 50.0,
+                "consumed_energy": 0.0006,
+                "power_out": 50.0,
+                "max_load": MaxLoadSB2.W800,
+                "output_cutoff_data": SBPowerCutoff.P5,
+                "lowpower_input_data": 4,
+                "input_cutoff_data": SBPowerCutoff.P5,
+                "usage_mode": SBUsageMode.MANUAL,
+                "home_load_preset": 50,
+                "light_mode": LightMode.NORMAL,
+                "grid_status": GridStatus.OK_AS_WELL_I_GUESS,
+                "light_on": False,
+                "battery_heating": False,
+            },
+            id="solarbank2_telemetry",
+        ),
     ],
 )
 async def test_values(
@@ -692,6 +740,19 @@ async def test_values(
             "0c4d9db9ef376fcfe627b9b73089eda514315d4bf67fb7eb299f2894ef7a059c",
             id="c1000_2",
         ),
+        pytest.param(
+            Solarbank2,
+            [
+                "ff090e00030001080100a1010152",
+                "ff091b00030001080300a10102a202fd00a30144a40101a50102ff",
+                "ff093800030001082900a10103a2054553503332a307302e302e302e33a41041504347513830453030303030303030a50600000000000039",
+                "ff090b00030001080500f2",
+                "ff094d00030001082100a140f809d676751fba1346f21198c8a583b1ef9b9a617fb804455c388d07090e6dc2976c1bb1cf06aee1f30a3286af9dd80f8f0c594010f60755292addedfe41385972",
+                None,
+            ],
+            "6a2c89888de58cce1e15d98eb22669898ec29bcb1519ce19f950439aac9dbcb5",
+            id="solarbank2_1",
+        ),
     ],
 )
 async def test_negotiation(