SolixBLE 3.9.0__tar.gz → 4.0.0b2__tar.gz

{solixble-3.9.0 → solixble-4.0.0b2}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: SolixBLE
-Version: 3.9.0
+Version: 4.0.0b2
 Summary: Python module for monitoring & controlling Bluetooth Anker Solix devices
 Author-email: Harvey Lelliott <harveylelliott@duck.com>
 License: MIT License
@@ -45,6 +45,9 @@ Requires-Dist: bleak>=0.19.0
 Requires-Dist: cryptography
 Requires-Dist: pycryptodome
 Requires-Dist: bleak-retry-connector
+Requires-Dist: construct
+Requires-Dist: tzdata
+Requires-Dist: tzlocal
 Dynamic: license-file
 
 # SolixBLE

{solixble-3.9.0 → solixble-4.0.0b2}/SolixBLE/__init__.py

@@ -4,6 +4,7 @@
 
 """
 
+from .advertisement import capability_from_advertisement
 from .device import SolixBLEDevice
 from .devices import (
     C300,
@@ -22,6 +23,7 @@ from .devices import (
     Solarbank2,
     Solarbank3,
 )
+from .factory import device_class_from_advertisement
 from .prime_device import PrimeDevice
 from .states import (
     ChargingStatus,
@@ -60,4 +62,6 @@ __all__ = [
     "TemperatureUnit",
     "PortOverload",
     "discover_devices",
+    "capability_from_advertisement",
+    "device_class_from_advertisement",
 ]

solixble-4.0.0b2/SolixBLE/advertisement.py

@@ -0,0 +1,70 @@
+"""Anker manufacturer advertisement record.
+
+Anker devices publish a fixed-shape record under BLE company identifier
+``0xffff``: the device MAC, the model key (``product_type``), the sku, and on
+newer firmware a ``capability`` byte whose ``0x04`` bit means the device
+accepts the encrypted negotiation. All of it is readable before connecting.
+
+.. moduleauthor:: kb1ibt
+"""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+from construct import (  # type: ignore[import-untyped]  # construct ships no types
+    Bytes,
+    ConstructError,
+    Container,
+    Error,
+    Int8ub,
+    Optional,
+    PaddedString,
+    Struct,
+    Switch,
+    this,
+)
+
+if TYPE_CHECKING:
+    from bleak.backends.scanner import AdvertisementData
+
+#: BLE company identifier the record is published under.
+ANKER_COMPANY_ID = 0xFFFF
+
+#: Capability bit: the device accepts the encrypted ``4xxx`` negotiation.
+CAPABILITY_ENCRYPTED_ECDH = 0x04
+
+#: ``version_code | mac(6) | bind_type | product_type(2) | sku(3-4) | capability(0-1)``.
+ANKER_RECORD = Struct(
+    "version_code" / Int8ub,
+    "mac" / Bytes(6),
+    "bind_type" / Int8ub,
+    "product_type" / Bytes(2),
+    "sku"
+    / Switch(
+        this.version_code,
+        {1: PaddedString(3, "ascii"), 2: PaddedString(4, "ascii")},
+        default=Error,
+    ),
+    "capability" / Optional(Int8ub),
+)
+
+
+def parse_advertisement(data: bytes) -> Container | None:
+    """Decode an Anker ``0xffff`` manufacturer record, or None if malformed."""
+    try:
+        return ANKER_RECORD.parse(data)
+    except ConstructError:
+        return None
+
+
+def record_from_advertisement(advertisement: AdvertisementData) -> Container | None:
+    """Decode the Anker record of a scan result, if it carries one."""
+    data = advertisement.manufacturer_data.get(ANKER_COMPANY_ID)
+    return parse_advertisement(data) if data is not None else None
+
+
+def capability_from_advertisement(advertisement: AdvertisementData) -> int | None:
+    """Read the capability byte from a scan result, or None if absent."""
+    record = record_from_advertisement(advertisement)
+    return record.capability if record is not None else None

{solixble-3.9.0 → solixble-4.0.0b2}/SolixBLE/const.py

@@ -13,6 +13,27 @@ UUID_COMMAND = "8c850002-0302-41c5-b46e-cf057c562025"
 #: GATT Service UUID for identifying Solix/Prime devices (Tested on C300X, C1000, and Prime 160w Charger).
 UUID_IDENTIFIER = "0000ff09-0000-1000-8000-00805f9b34fb"
 
+#: GATT Service UUID of devices on the legacy transport (e.g the 767 / F2000).
+LEGACY_SERVICE = "00001780-0000-1000-8000-00805f9b34fb"
+
+#: GATT Characteristic UUID for legacy transport telemetry. Is subscribable.
+UUID_TELEMETRY_LEGACY = "00008888-0000-1000-8000-00805f9b34fb"
+
+#: GATT Characteristic UUID for sending legacy transport commands.
+UUID_COMMAND_LEGACY = "00007777-0000-1000-8000-00805f9b34fb"
+
+#: GATT Service UUID of devices on the 2215 transport (e.g the A1340 Prime power bank).
+SERVICE_2215 = "00002215-0000-1000-8000-00805f9b34fb"
+
+#: GATT Characteristic UUID for 2215 transport telemetry. Is subscribable.
+UUID_TELEMETRY_2215 = "22150003-4002-81c5-b46e-cf057c562025"
+
+#: GATT Characteristic UUID for sending 2215 transport commands / negotiating.
+UUID_COMMAND_2215 = "22150002-4002-81c5-b46e-cf057c562025"
+
+#: GATT Service UUIDs that identify an Anker device on any transport.
+UUID_IDENTIFIERS = (UUID_IDENTIFIER, LEGACY_SERVICE, SERVICE_2215)
+
 #: Time to wait before re-connecting on an unexpected disconnect.
 RECONNECT_DELAY = 3
 
@@ -44,6 +65,12 @@ DEFAULT_METADATA_FLOAT = -1.0
 #: Bool value for unknown boolean attributes.
 DEFAULT_METADATA_BOOL = None
 
+#: The pattern used in telemetry packers from some Anker devices
+TELEMETRY_PATTERN_A = "03010f"
+
+#: The pattern used in negotiation packets from Anker devices
+NEGOTIATION_PATTERN = "030001"
+
 #: Command used to initiate negotiations
 NEGOTIATION_COMMAND_0 = "ff0936000300010001a10442ad8c69a22462326463306231372d623735642d346162662d626136652d656337633939376332336537b9"
 
@@ -54,7 +81,7 @@ NEGOTIATION_COMMAND_1 = "ff093d000300010003a10442ad8c69a22462326463306231372d623
 NEGOTIATION_COMMAND_2 = "ff0936000300010029a10442ad8c69a22462326463306231372d623735642d346162662d626136652d65633763393937633233653791"
 
 #: Response to receiving 3rd negotiation message
-NEGOTIATION_COMMAND_3 = "ff0940000300010005a10443ad8c69a22462326463306231372d623735642d346162662d626136652d656337633939376332336537a30120a40200f0a50140fa"
+NEGOTIATION_COMMAND_3 = "ff0940000300010005a10442ad8c69a22462326463306231372d623735642d346162662d626136652d656337633939376332336537a30120a40200f0a50140fb"
 
 #: Response to receiving 4th negotiation message
 NEGOTIATION_COMMAND_4 = "ff094c000300010021a140060ea168f232aedb37fb2d120c49180329ac72ab5ec3eb8fd30a2f252dc5e151dabccd9b1dc1e288704ca760a0d8c918e5c94823a1f609a4bf07fb4c33ee219085"
@@ -62,12 +89,6 @@ NEGOTIATION_COMMAND_4 = "ff094c000300010021a140060ea168f232aedb37fb2d120c4918032
 #: Response to receiving 5th negotiation message
 NEGOTIATION_COMMAND_5 = "ff095a000300014022580bc0532a53c739adf3da7b994a7b5f221bcc16bab6392c215cb4faaf41d9d58e2c81c016e474c78eed5569147cb74a1f22ca2b3fad2e209dbbcfbdaca352034a6c479f055f68581b5f1e22348809f526"
 
-#: The unix timestamp that is agreed upon in the negotiations. This is used
-#: by Anker to protect against replay attacks as commands must contain the
-#: current encrypted time.
-BASE_TIMESTAMP = "42ad8c69"
-
-
 #: The private key this program uses to perform the ECDH negotiation to
 #: get a shared secret which is then used as an AES key for encrypting
 #: communications between the program and the power station. Yes I know it
@@ -76,3 +97,6 @@ BASE_TIMESTAMP = "42ad8c69"
 #: reason this has to be done at all is because Anker power stations no longer
 #: support sending telemetry in plain text after the latest firmware update.
 PRIVATE_KEY = "7dfbea61cd95cee49c458ad7419e817f1ade9a66136de3c7d5787af1458e39f4"
+
+# POSIX timezone to use if determining the system time zone fails
+FALLBACK_TZ = "GMT0BST,M3.5.0/1,M10.5.0"

solixble-4.0.0b2/SolixBLE/constructs.py

@@ -0,0 +1,445 @@
+"""Data structures of packets.
+
+This module contains the byte structures used for encoding and
+decoding the packet format used by Anker devices.
+
+.. moduleauthor:: Harvey Lelliott (flip-dots) <harveylelliott@duck.com>
+
+"""
+
+import json
+import operator
+from functools import reduce
+from typing import Any, Self
+
+from construct import (
+    BitsInteger,
+    BitStruct,
+    Bytes,
+    Checksum,
+    Const,
+    Container,
+    ExprAdapter,
+    ExprValidator,
+    Flag,
+    GreedyBytes,
+    GreedyRange,
+    Hex,
+    HexDump,
+    If,
+    Int8ub,
+    Int8ul,
+    Int16ul,
+    Nibble,
+    Optional,
+    RawCopy,
+    Rebuild,
+    Struct,
+    this,
+)
+
+from SolixBLE.utilities import _to_bytes
+
+
+def _get_val(obj: Any, key: str, default: Any=None) -> Any:
+    """
+    Return value from dictionary, container, objects, or None.
+
+    :param obj: Object to extract value from.
+    :param key: The key or property to extract from the object.
+    :param default: Default to return if not found.
+    :returns: Found value or default.
+    """
+    if obj is None:
+        return default
+    if isinstance(obj, dict):
+        return obj.get(key, default)
+    return getattr(obj, key, default)
+
+Packet = ExprAdapter(
+
+    # Structure of the packet
+    Struct(
+
+        # Bytes of packet excluding checksum
+        "content" / RawCopy(
+            Struct(
+
+                # Header of the packet
+                "header" / Hex(Const(bytes.fromhex("ff09"))),
+
+                # Length of the entire packet
+                "length" / Rebuild(Int16ul, lambda this: 10 + len(this.payload_bytes)),
+
+                # Pattern of the packet (e.g negotiation type, telemetry type etc)
+                "pattern" / Hex(Bytes(3)),
+
+                # Command of the packet (e.g turn on, off, etc)
+                "cmd" / Hex(Bytes(2)),
+
+                # Payload bytes of the packet (may be encrypted or fragmented)
+                "payload_bytes" / HexDump(Bytes(lambda this: this.length - 10)),
+            ),
+        ),
+
+        # XOR checksum of the packet
+        "checksum" / Hex(Checksum(
+            Int8ul,
+            lambda data: reduce(operator.xor, data, 0),
+            this.content.data,
+        )),
+    ),
+
+    # Encoders and decoders which allow for direct access
+    # (e.g packet.cmd rather than packet.content.cmd)
+    decoder=lambda p, _: p.content.value,
+    encoder=lambda p, _: {
+            "content": {
+                "value": {
+                    "header": _to_bytes(_get_val(p, "header", "ff09")),
+                    "pattern": _to_bytes(_get_val(p, "pattern")),
+                    "cmd": _to_bytes(_get_val(p, "cmd")),
+                    "payload_bytes": _to_bytes(_get_val(p, "payload_bytes", b"")),
+                },
+            },
+    },
+)
+"""
+Anker device packet.
+
+This class represents a packet of an Anker device. Packets are made up of a
+header, size, pattern, cmd, payload, and a checksum.
+
+Structure: <Header 2B> <Size 2B> <Pattern 3B> <CMD 2B> <Payload nB> <Checksum 1B>.
+
+Usage:
+    .. code-block:: python
+       :linenos:
+
+        packet = Packet.parse(packet_bytes)
+        print(f"p: {packet.pattern}, c: {packet.cmd}, b: {packet.payload_bytes}")
+
+        packet_bytes = Packet.build({
+            "pattern": "030001",
+            "cmd": "0000",
+            "payload_bytes": "a101a20200a303010000",
+        })
+
+"""
+
+#: Dispatch channel of negotiation requests, replies and the grant.
+CHANNEL_NEGOTIATION = 0x01
+
+#: Dispatch channel of session commands, replies and pushes.
+CHANNEL_SESSION = 0x0F
+
+#: Dispatch channel of app session pushes.
+CHANNEL_APP = 0x11
+
+#: Composer of a reply that echoes the request's pattern.
+COMPOSER_REPLY = 0x00
+
+#: Composer of a frame the device sends on its own.
+COMPOSER_SEND = 0x01
+
+PacketPattern = Struct(
+    "family" / Int8ub,
+    "composer" / Int8ub,
+    "channel" / Int8ub,
+)
+"""
+Pattern of an Anker packet: ``03 <composer> <channel>``.
+
+The channel is the module's dispatch key (``0x01`` negotiation, ``0x0f`` /
+``0x11`` session); the composer is ``01`` on frames the module sends on its
+own and ``00`` on replies that echo the request.
+
+Usage:
+    .. code-block:: python
+       :linenos:
+
+        pattern = PacketPattern.parse(packet.pattern)
+        print(f"composer: {pattern.composer}, channel: {pattern.channel}")
+
+"""
+
+PacketCommand = ExprAdapter(
+    BitStruct(
+        "fragmented" / Flag,
+        "encrypted" / Flag,
+        "reserved" / BitsInteger(2),
+        "msgtype" / BitsInteger(12),
+    ),
+    decoder=lambda obj, _: Container(
+        fragmented=obj.fragmented,
+        encrypted=obj.encrypted,
+        msgtype=obj.msgtype,
+        response=bool(obj.msgtype & 0x800),
+    ),
+    encoder=lambda obj, _: {"reserved": 0, **obj},
+)
+"""
+Command of an Anker packet: link flags in the high nibble, a 12-bit message type.
+
+``0x80`` marks a fragment (the payload's first byte is index << 4 | total) and
+``0x40`` an encrypted/authorized link; a response is the request's message
+type with ``0x800`` set.
+
+Usage:
+    .. code-block:: python
+       :linenos:
+
+        command = PacketCommand.parse(packet.cmd)
+        print(f"msgtype: {command.msgtype:03x}, encrypted: {command.encrypted}")
+
+        cmd_bytes = PacketCommand.build({
+            "fragmented": False,
+            "encrypted": True,
+            "msgtype": 0x005,
+        })
+
+"""
+
+FragmentedPayload = Struct(
+
+    # Fragment information
+    "frag" / BitStruct(
+        "index" / Nibble,
+        "total" / Nibble,
+    ),
+
+    # The content of the payload
+    "data" / GreedyBytes,
+)
+"""
+Payload section of an Anker packet that is fragmented.
+
+The "frag" section represents the fragmentation information of the payload.
+This information is not always present in non-fragmented packets.
+
+The "data" section represents the content of the fragment and may be encrypted.
+The fragments must be re-assembled before decryption can begin.
+
+This structure is used for re-assembling fragmented payloads only.
+
+Structure: <Index 4b> <Total 4b> <Data nB>.
+
+Usage:
+
+    .. code-block:: python
+       :linenos:
+
+        frag_payload = FragmentedPayload.parse(payload_bytes)
+        print(f"{frag_p.frag.index}/{frag_p.frag.total}: {frag_p.data}")
+
+"""
+
+
+class ParameterContainer(Container):
+    """Subclass to allow for direct action on the parameter type."""
+
+    @property
+    def value_legacy(self) -> bytes:
+        """Return the type byte prepended to the value bytes for non-typed values."""
+        type_byte = self.type.to_bytes(1) if self.get("type") is not None else b""
+        val_bytes = self.get("value") or b""
+        return type_byte + val_bytes
+
+    def to_dict(self, types: bool | None = None) -> dict[str, str]:  # noqa: FBT001
+        """Return possible representations of the parameter in dict form.
+
+        :param: Parameter to be interpreted.
+        :types: Display parameter with type information (T=y, F=n, N=both).
+        :returns: Dictionary of encodings to decoded values.
+        """
+        representation: dict[str, str] = {}
+
+        # Representation where no type info is encoded
+        p_bytes = self.value_legacy
+
+        # Representation where first byte encodes type information
+        p_bytes_t = bytes(self.value)
+
+        if types is not True:
+            representation.update({
+                "bytes": str(p_bytes),
+                "hex": p_bytes.hex(),
+                "int": int.from_bytes(p_bytes, byteorder="little", signed=True),
+                "uint": int.from_bytes(p_bytes, byteorder="little", signed=False),
+                "length": len(p_bytes),
+            })
+
+        if types is not False:
+            representation.update({
+                "type (t)": self.type,
+                "bytes (t)": str(p_bytes_t),
+                "hex (t)": p_bytes_t.hex(),
+                "int (t)": int.from_bytes(p_bytes_t, byteorder="little", signed=True),
+                "uint (t)": int.from_bytes(p_bytes_t, byteorder="little", signed=False),
+                "length (t)": len(p_bytes_t),
+             })
+
+        return representation
+
+
+Parameter = ExprAdapter(
+    Struct(
+
+        # The key of the parameter (e.g a1, a2, ...)
+        "key" / Hex(Bytes(1)),
+
+        # The length of the parameter excluding the key
+        "length" / Rebuild(
+            Int8ul,
+            lambda p: (1 if p.get("type") is not None else 0) + len(p.get("value") or b""),
+        ),
+
+        # Optional type of the parameter
+        "type" / If(
+            lambda p: p.get("type") is not None if p._building else p.length > 1,
+            Int8ul,
+        ),
+
+        # Optional content of the parameter
+        "value" / If(
+            lambda p: (p.length - (1 if p.type is not None else 0)) > 0,
+            HexDump(Bytes(lambda p: p.length - (1 if p.type is not None else 0))),
+        ),
+    ),
+    decoder=lambda obj, _: ParameterContainer(obj),
+    encoder=lambda obj, _: obj,
+)
+"""
+Individual parameter of a payload of an Anker packet.
+
+Paramaters contain a key (e.g a1, a2, ...), the length, optional
+type information, and an optional content.
+
+Structure: <Key 1B> <Length 1B> <Type 1B> <Content nB>.
+
+The length value is the length of the entire parameter excluding the key.
+
+This structure is only used as a part of the Parameters type for creating,
+modifying, encoding, and decoding payloads.
+"""
+
+
+class ParameterDict(dict):
+    """Subclass to allow for direct action on the paramaters type."""
+
+    def __init__(self, *args, prefix: bytes | None = None, **kwargs):
+        super().__init__(*args, **kwargs)
+        self.prefix = prefix
+
+    @property
+    def status(self) -> int | None:
+        """Status byte of a reply, or None for a push."""
+        return self.prefix[0] if self.prefix else None
+
+    def diff(self, old: Self, types: bool | None = None) -> str:  # noqa: FBT001
+        """
+        Return changes from previous parameters to this in string representation.
+
+        :param old: Previous entry to compare against.
+        :param types: Display parameter with type information (T=y, F=n, N=both).
+        """
+        differences: dict[str, str] = {}
+
+        changed = {k for k in old.keys() & self.keys() if old[k] != self[k]}
+        added = self.keys() - old.keys()
+        removed = old.keys() - self.keys()
+
+        for k in sorted(changed | added | removed):
+
+            # Parameter modified
+            if k in changed:
+                old_p = old[k].to_dict(types=types)
+                new_p = self[k].to_dict(types=types)
+
+                differences[k] = {
+                    "state": "~",
+                    **{f: f"{old_p[f]} -> {new_p[f]}" for f in old_p},
+                }
+
+            # Parameter added
+            elif k in added:
+                differences[k] = {
+                    "state": "+",
+                    **self[k].to_dict(types=types),
+                }
+
+            # Parameter removed
+            elif k in removed:
+                differences[k] = {
+                    "state": "-",
+                    **old[k].to_dict(types=types),
+                }
+
+        return json.dumps(differences, indent=4)
+
+    def to_str(self, verbose: bool = False, types: bool | None = None) -> str:
+        """
+        Return string representation of potential parameter encodings.
+
+        :param verbose: Return possible representations instead of plain bytes.
+        :param types: Display parameter with type information (T=y, F=n, N=both).
+        :returns: String representation of parameters.
+        """
+        if verbose:
+            return json.dumps({k: p.to_dict(types) for k, p in self.items()}, indent=4)
+        return str({k: v.value_legacy.hex() for k, v in self.items()})
+
+    def __str__(self) -> str:
+        """Return string representation of potential parameter encodings."""
+        return self.to_str()
+
+STATUS_LIMIT = 0xA1
+"""TLV tags start at ``0xa1``; a lower first byte is a reply's status."""
+
+Parameters = ExprAdapter(
+    Struct(
+
+        # Optional status byte (replies only)
+        "prefix" / If(
+            lambda this: this._parsing or this.prefix is not None,
+            Optional(ExprValidator(Bytes(1), lambda obj, _: obj[0] < STATUS_LIMIT)),
+        ),
+
+        # List of parameters
+        "parameters" / GreedyRange(Parameter),
+    ),
+    decoder=lambda obj, _: ParameterDict(
+        {p.key.hex(): p for p in obj.parameters},
+        prefix=obj.prefix,
+    ),
+    encoder=lambda ps, _: {
+        "prefix": getattr(ps, "prefix", None),
+        "parameters": list(ps.values()) if isinstance(ps, dict) else ps,
+    },
+)
+"""
+Decoded parameters of the payload of an Anker packet.
+
+The payload of Anker packets is made up of a list of
+parameters. The payload of a reply starts with a status byte;
+pushes have none.
+
+Structure: <Prefix 1B> <Parameter 1 nB> ... <Parameter n nB>.
+
+This structure is used to encode, decode, modify, and generate payloads.
+
+Usage:
+
+    .. code-block:: python
+       :linenos:
+
+        parameters = Parameters.parse(reassembled_payload)
+        parameters["a1"] = Parameter({
+            "key": "a1",
+            "type": 12,
+            "value": "00ff",
+        })
+
+        plaintext_payload = Parameters.build(parameters)
+
+"""