SolixBLE 3.7.0__tar.gz → 3.9.0__tar.gz

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

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SolixBLE
-Version: 3.7.0
+Version: 3.9.0
 Summary: Python module for monitoring & controlling Bluetooth Anker Solix devices
 Author-email: Harvey Lelliott <harveylelliott@duck.com>
 License: MIT License
@@ -97,11 +97,13 @@ See the [support table](https://solixble.readthedocs.io/en/latest) in the docume
 - C1000(X)
 - C1000 Gen 2
 - F2000 (767 PowerHouse)
+- F2600
 - F3800
 - Solarbank 2
 - Solarbank 3
 - Prime Charger 160w
 - Prime Charger 250w
+- Prime MagGo 3in1 (A25X7)
 - Potentially more!
 
 
@@ -138,3 +140,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.7.0 → solixble-3.9.0}/README.md

@@ -48,11 +48,13 @@ See the [support table](https://solixble.readthedocs.io/en/latest) in the docume
 - C1000(X)
 - C1000 Gen 2
 - F2000 (767 PowerHouse)
+- F2600
 - F3800
 - Solarbank 2
 - Solarbank 3
 - Prime Charger 160w
 - Prime Charger 250w
+- Prime MagGo 3in1 (A25X7)
 - Potentially more!
 
 
@@ -89,3 +91,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.7.0 → solixble-3.9.0}/SolixBLE/__init__.py

@@ -12,10 +12,13 @@ from .devices import (
     C1000,
     C1000G2,
     F2000,
+    F2600,
     F3800,
     Generic,
+    MagGo3in1,
     PrimeCharger160w,
     PrimeCharger250w,
+    PrimePowerBank20k,
     Solarbank2,
     Solarbank3,
 )
@@ -25,9 +28,9 @@ from .states import (
     ChargingStatusF3800,
     DisplayTimeout,
     LightStatus,
+    PortOverload,
     PortStatus,
     TemperatureUnit,
-    PortOverload,
 )
 from .utilities import discover_devices
 
@@ -40,11 +43,14 @@ __all__ = [
     "C1000",
     "C1000G2",
     "F2000",
+    "F2600",
     "F3800",
     "Solarbank2",
     "Solarbank3",
     "PrimeCharger160w",
     "PrimeCharger250w",
+    "PrimePowerBank20k",
+    "MagGo3in1",
     "Generic",
     "ChargingStatus",
     "ChargingStatusF3800",

{solixble-3.7.0 → solixble-3.9.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."""
 
@@ -71,6 +76,7 @@ class SolixBLEDevice:
         self._state_changed_callbacks: list[Callable[[], None]] = []
         self._packet_futures: dict[bytes, list[asyncio.Future]] = {}
         self._auto_reconnect_task: asyncio.Task | None = None
+        self._keep_alive_task: asyncio.Task | None = None
         self._disconnect_event: asyncio.Event = asyncio.Event()
         self._connection_attempts: int = 0
         self._shared_secret: bytes | None = None
@@ -195,16 +201,60 @@ 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())
 
+        # Start a keep-alive task if its not running already
+        if self._keep_alive_task is None:
+            self._keep_alive_task = asyncio.create_task(self._keep_alive_fn())
+
         # Execute callbacks if enabled
         if run_callbacks:
             self._run_state_changed_callbacks()
 
         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 _keep_alive(self) -> int | None:
+        """Execute designated keep-alive command periodically after good negotiation.
+
+        Use this to execute code periodically that is needed to keep the
+        connection. For example some devices need a special keep alive command
+        to keep receiving telemetry updates that must be sent every ~10 seconds.
+
+        This is automatically executed in a task created by :meth:`connect` once
+        the encrypted session has been negotiated (so :meth:`_send_command`
+        may be used) and on every automatic reconnect, with it not being
+        executed when not connected or negotiated.
+
+        The default implementation does nothing; subclasses can override it to,
+        for example, send a subscribe command to keep a telemetry stream (see
+        :class:`~SolixBLE.devices.prime_charger_250w.PrimeCharger250w`).
+
+        :returns: Seconds to wait before calling again or None for not implemented.
+        """
+        return None
+
     async def disconnect(self) -> None:
         """Disconnect from device and reset internal state.
 
@@ -217,6 +267,10 @@ class SolixBLEDevice:
         if self._auto_reconnect_task is not None:
             self._auto_reconnect_task.cancel()
 
+        # Cancel the keep-alive task
+        if self._keep_alive_task is not None:
+            self._keep_alive_task.cancel()
+
         # If there is a client disconnect and throw it away
         if self._client is not None:
             await self._dispose_of_client()
@@ -493,7 +547,9 @@ class SolixBLEDevice:
         )
         return cipher.encrypt(padded_data)
 
-    async def _process_telemetry_packet(self, payload: bytes, cmd: bytes = None) -> 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
@@ -533,14 +589,12 @@ class SolixBLEDevice:
             )
             del self._fragment_buffers[cmd_key]
             del self._fragment_totals[cmd_key]
-            _LOGGER.debug(
-                f"Reassembled payload: {len(payload)} bytes"
-            )
+            _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)
@@ -615,51 +669,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" | "c405":
-                        _LOGGER.debug("Received telemetry message!")
-                        return await self._process_telemetry_packet(payload, cmd)
-
-                    # 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(
@@ -996,6 +1054,39 @@ class SolixBLEDevice:
         except Exception:
             _LOGGER.exception("Unexpected exception in automatic reconnect task!")
 
+
+    async def _keep_alive_fn(self) -> None:
+        """Task designed to be run in background to execute keep-alive.
+
+        This task is executed automatically when a successful connection
+        is made and will periodically execute the keep alive function if
+        one exists.
+
+        This background task is cancelled when the connection is lost.
+        """
+        try:
+            while self.negotiated:
+
+                try:
+                    _LOGGER.debug("Executing keep-alive...")
+                    result = await self._keep_alive()
+
+                    if result is None:
+                        _LOGGER.debug("No keep-alive task registered, stopping task...")
+                        return
+
+                    _LOGGER.debug(f"Executing keep-alive in {result}s")
+                    await asyncio.sleep(result)
+
+                except Exception:
+                    _LOGGER.exception("Exception raised executing keep-alive function!")
+
+        except asyncio.CancelledError:
+            _LOGGER.debug("Keep-alive task has been canceled/stopped")
+
+        except Exception:
+            _LOGGER.exception("Unexpected exception in keep-alive task!")
+
     def _disconnect_callback(self, client: BaseBleakClient) -> None:
         """Callback executed by bleak when the connection is lost.
 

{solixble-3.7.0 → solixble-3.9.0}/SolixBLE/devices/__init__.py

@@ -10,10 +10,13 @@ from .c800 import C800
 from .c1000 import C1000
 from .c1000g2 import C1000G2
 from .f2000 import F2000
+from .f2600 import F2600
 from .f3800 import F3800
 from .generic import Generic
+from .maggo_3in1 import MagGo3in1
 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
 
@@ -24,10 +27,13 @@ __all__ = [
     "C1000",
     "C1000G2",
     "F2000",
+    "F2600",
     "F3800",
     "Solarbank2",
     "Solarbank3",
     "PrimeCharger160w",
     "PrimeCharger250w",
+    "PrimePowerBank20k",
+    "MagGo3in1",
     "Generic",
 ]

{solixble-3.7.0 → solixble-3.9.0}/SolixBLE/devices/c1000.py

@@ -186,6 +186,25 @@ class C1000(SolixBLEDevice):
         """
         return self._parse_int("b0", begin=1)
 
+    @property
+    def dc_output(self) -> PortStatus:
+        """DC Port Status.
+
+        PortStatus.NOT_CONNECTED signifies off.
+        PortStatus.OUTPUT signifies on.
+
+        :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.
+
+        :returns: DC power out or default int value.
+        """
+        return self._parse_int("b2", begin=2)
+
     @property
     def software_version(self) -> str:
         """Main software version.

{solixble-3.7.0 → solixble-3.9.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.
         """