pyowershades 0.1.0__tar.gz

pyowershades-0.1.0/LICENSE

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

pyowershades-0.1.0/PKG-INFO

@@ -0,0 +1,19 @@
+Metadata-Version: 2.4
+Name: pyowershades
+Version: 0.1.0
+Summary: Asyncio library for PowerShades motorized blinds
+Project-URL: Homepage, https://github.com/vemboy200/Pyowershades
+Author-email: Vem Boynerian <vemboy20@gmail.com>
+License: 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
+Requires-Python: >=3.12
+Description-Content-Type: text/markdown
+
+# Pyowershades
+A phython library for controlling powershades

pyowershades-0.1.0/README.md

@@ -0,0 +1,2 @@
+# Pyowershades
+A phython library for controlling powershades

pyowershades-0.1.0/pyowershades/__init__.py

@@ -0,0 +1,83 @@
+"""Asyncio library for PowerShades motorized blinds."""
+
+from .connection import (
+    DiscoveredDevice,
+    PowerShadesConnection,
+    PowerShadesDeviceInfo,
+    PowerShadesTimeoutError,
+    async_discover_devices,
+    async_get_device_info,
+)
+from .const import (
+    DISCOVERY_TIMEOUT,
+    LIMIT_LOWER,
+    LIMIT_UPPER,
+    MODEL_NAMES,
+    OP_CLEAR_LIMITS,
+    OP_GET_DEVICE_NAME,
+    OP_GET_SERIAL,
+    OP_GET_SHADE_NAME,
+    OP_GET_STATUS,
+    OP_INDICATE,
+    OP_JOG_DOWN,
+    OP_JOG_STOP,
+    OP_JOG_UP,
+    OP_SET_LIMIT,
+    OP_SET_POSITION,
+    OP_STEP_DOWN,
+    OP_STEP_UP,
+    REQUEST_RETRIES,
+    REQUEST_TIMEOUT,
+    UDP_PORT,
+)
+from .protocol import (
+    GET_SHADE_NAME_PAYLOAD,
+    StatusReply,
+    build_packet,
+    build_set_limit_payload,
+    build_set_name_payload,
+    build_set_position_payload,
+    parse_device_name_reply,
+    parse_serial_reply,
+    parse_shade_name_reply,
+    parse_status_reply,
+)
+
+__all__ = [
+    "DiscoveredDevice",
+    "DISCOVERY_TIMEOUT",
+    "GET_SHADE_NAME_PAYLOAD",
+    "LIMIT_LOWER",
+    "LIMIT_UPPER",
+    "MODEL_NAMES",
+    "OP_CLEAR_LIMITS",
+    "OP_GET_DEVICE_NAME",
+    "OP_GET_SERIAL",
+    "OP_GET_SHADE_NAME",
+    "OP_GET_STATUS",
+    "OP_INDICATE",
+    "OP_JOG_DOWN",
+    "OP_JOG_STOP",
+    "OP_JOG_UP",
+    "OP_SET_LIMIT",
+    "OP_SET_POSITION",
+    "OP_STEP_DOWN",
+    "OP_STEP_UP",
+    "PowerShadesConnection",
+    "PowerShadesDeviceInfo",
+    "PowerShadesTimeoutError",
+    "REQUEST_RETRIES",
+    "REQUEST_TIMEOUT",
+    "StatusReply",
+    "UDP_PORT",
+    "async_discover_devices",
+    "async_get_device_info",
+    "build_packet",
+    "build_set_limit_payload",
+    "build_set_name_payload",
+    "build_set_position_payload",
+    "parse_device_name_reply",
+    "parse_serial_reply",
+    "parse_shade_name_reply",
+    "parse_status_reply",
+]

pyowershades-0.1.0/pyowershades/connection.py

@@ -0,0 +1,268 @@
+"""Asyncio UDP transport and discovery for PowerShades devices."""
+
+import asyncio
+from collections.abc import Callable
+import logging
+from typing import TypedDict
+
+from .const import (
+    BROADCAST_IP,
+    DISCOVERY_TIMEOUT,
+    OP_GET_DEVICE_NAME,
+    OP_GET_SERIAL,
+    OP_GET_SHADE_NAME,
+    OP_GET_STATUS,
+    REQUEST_RETRIES,
+    REQUEST_TIMEOUT,
+    UDP_PORT,
+)
+from .protocol import (
+    GET_SHADE_NAME_PAYLOAD,
+    StatusReply,
+    build_packet,
+    parse_device_name_reply,
+    parse_header,
+    parse_serial_reply,
+    parse_shade_name_reply,
+    parse_status_reply,
+    verify_packet,
+)
+
+_LOGGER = logging.getLogger(__name__)
+
+
+class DiscoveredDevice(TypedDict):
+    """A device found via UDP broadcast discovery."""
+
+    ip: str
+    serial: int
+    model: int
+
+
+class PowerShadesDeviceInfo(TypedDict):
+    """Information probed from a device during config flow validation."""
+
+    serial: int
+    name: str | None
+    model: int
+
+
+class PowerShadesTimeoutError(Exception):
+    """The device did not reply in time."""
+
+
+class _PowerShadesProtocol(asyncio.DatagramProtocol):
+    """Datagram protocol routing replies to pending requests and status pushes."""
+
+    def __init__(self, on_status: Callable[[StatusReply], None]) -> None:
+        self._on_status = on_status
+        # Keyed by op alone: real shades do not reliably echo the
+        # request's sequence (Get Status always replies sequence 1,
+        # whatever was sent). Requests on a connection are serialized,
+        # so at most one request per op is pending at a time.
+        self.pending: dict[int, asyncio.Future[bytes]] = {}
+
+    def datagram_received(self, data: bytes, addr: tuple[str, int]) -> None:
+        if not verify_packet(data):
+            _LOGGER.debug("Dropping invalid packet from %s: %s", addr[0], data.hex())
+            return
+        header = parse_header(data)
+        if header is None:
+            return
+        _LOGGER.debug(
+            "Received op=0x%02X seq=%d from %s: %s",
+            header.op,
+            header.sequence,
+            addr[0],
+            data.hex(),
+        )
+        fut = self.pending.pop(header.op, None)
+        if fut is not None and not fut.done():
+            fut.set_result(data)
+            return
+        if header.op == OP_GET_STATUS:
+            status = parse_status_reply(data)
+            if status is not None:
+                self._on_status(status)
+
+    def error_received(self, exc: Exception) -> None:
+        _LOGGER.debug("UDP error received: %s", exc)
+
+
+class PowerShadesConnection:
+    """A single UDP endpoint talking to one PowerShades device."""
+
+    def __init__(self, host: str) -> None:
+        self._host = host
+        self._transport: asyncio.DatagramTransport | None = None
+        self._protocol: _PowerShadesProtocol | None = None
+        self._lock = asyncio.Lock()
+        self._sequence = 0
+        self._status_callback: Callable[[StatusReply], None] | None = None
+
+    @property
+    def host(self) -> str:
+        return self._host
+
+    def set_status_callback(self, callback: Callable[[StatusReply], None]) -> None:
+        self._status_callback = callback
+
+    def _handle_status(self, status: StatusReply) -> None:
+        if self._status_callback is not None:
+            self._status_callback(status)
+
+    async def async_connect(self) -> None:
+        loop = asyncio.get_running_loop()
+        self._transport, self._protocol = await loop.create_datagram_endpoint(
+            lambda: _PowerShadesProtocol(self._handle_status),
+            local_addr=("0.0.0.0", 0),
+        )
+
+    def _send(self, op: int, sequence: int, payload: bytes = b"") -> None:
+        if self._transport is None:
+            raise PowerShadesTimeoutError("Connection is closed")
+        packet = build_packet(op, sequence, payload=payload)
+        self._transport.sendto(packet, (self._host, UDP_PORT))
+        _LOGGER.debug(
+            "Sent op=0x%02X seq=%d to %s:%d: %s",
+            op,
+            sequence,
+            self._host,
+            UDP_PORT,
+            packet.hex(),
+        )
+
+    def _next_sequence(self) -> int:
+        self._sequence = (self._sequence + 1) % 256
+        return self._sequence
+
+    async def async_request(
+        self,
+        op: int,
+        payload: bytes = b"",
+        timeout: float = REQUEST_TIMEOUT,
+        retries: int = REQUEST_RETRIES,
+    ) -> bytes:
+        if self._protocol is None or self._transport is None:
+            raise PowerShadesTimeoutError("Connection is closed")
+        async with self._lock:
+            # Each attempt sends a fresh sequence, but replies are matched
+            # by op only — the device does not echo the sequence on all ops.
+            for _attempt in range(retries + 1):
+                sequence = self._next_sequence()
+                fut: asyncio.Future[bytes] = asyncio.get_running_loop().create_future()
+                self._protocol.pending[op] = fut
+                self._send(op, sequence, payload)
+                try:
+                    return await asyncio.wait_for(fut, timeout)
+                except TimeoutError:
+                    pass
+                finally:
+                    if self._protocol is not None:
+                        self._protocol.pending.pop(op, None)
+            raise PowerShadesTimeoutError(
+                f"No reply to op 0x{op:02X} from {self._host}"
+            )
+
+    def close(self) -> None:
+        if self._transport is not None:
+            self._transport.close()
+            self._transport = None
+            self._protocol = None
+
+
+class _DiscoveryProtocol(asyncio.DatagramProtocol):
+    """Collects Get Serial replies during broadcast discovery."""
+
+    def __init__(self, results: dict[str, DiscoveredDevice]) -> None:
+        self._results = results
+
+    def datagram_received(self, data: bytes, addr: tuple[str, int]) -> None:
+        if not verify_packet(data):
+            _LOGGER.debug("Dropping invalid discovery reply from %s", addr[0])
+            return
+        parsed = parse_serial_reply(data)
+        # Key by the packet source address — it is authoritative, the
+        # IP embedded in the reply payload is not.
+        if parsed is not None and addr[0] not in self._results:
+            self._results[addr[0]] = {
+                "ip": addr[0],
+                "serial": parsed["serial"],
+                "model": parsed["model"],
+            }
+            _LOGGER.debug("Discovered device %s (serial %s)", addr[0], parsed["serial"])
+
+    def error_received(self, exc: Exception) -> None:
+        _LOGGER.debug("Discovery UDP error: %s", exc)
+
+
+async def async_discover_devices(
+    local_addresses: list[str],
+    timeout: float = DISCOVERY_TIMEOUT,
+) -> list[DiscoveredDevice]:
+    """Discover PowerShades devices via UDP broadcast on all provided local addresses."""
+    loop = asyncio.get_running_loop()
+    results: dict[str, DiscoveredDevice] = {}
+    transports: list[asyncio.DatagramTransport] = []
+    packet = build_packet(OP_GET_SERIAL, sequence=0x01)
+
+    for address in local_addresses:
+        try:
+            transport, _protocol = await loop.create_datagram_endpoint(
+                lambda: _DiscoveryProtocol(results),
+                local_addr=(address, 0),
+                allow_broadcast=True,
+            )
+        except OSError as err:
+            _LOGGER.debug("Could not bind discovery socket to %s: %s", address, err)
+            continue
+        transport.sendto(packet, (BROADCAST_IP, UDP_PORT))
+        transports.append(transport)
+
+    if not transports:
+        return []
+
+    try:
+        await asyncio.sleep(timeout)
+    finally:
+        for transport in transports:
+            transport.close()
+
+    _LOGGER.info("Discovery complete, found %d device(s)", len(results))
+    return list(results.values())
+
+
+async def async_get_device_info(ip_address: str) -> PowerShadesDeviceInfo:
+    """Probe a device for its serial number and name.
+
+    Raises PowerShadesTimeoutError if the device does not answer the
+    serial request.
+    """
+    connection = PowerShadesConnection(ip_address)
+    await connection.async_connect()
+    try:
+        reply = await connection.async_request(OP_GET_SERIAL, retries=1)
+        parsed = parse_serial_reply(reply)
+        if parsed is None:
+            raise PowerShadesTimeoutError(f"Malformed serial reply from {ip_address}")
+
+        name = None
+        for op, payload, parser in (
+            (OP_GET_SHADE_NAME, GET_SHADE_NAME_PAYLOAD, parse_shade_name_reply),
+            (OP_GET_DEVICE_NAME, b"", parse_device_name_reply),
+        ):
+            try:
+                name_reply = await connection.async_request(op, payload, retries=0)
+            except PowerShadesTimeoutError:
+                continue
+            name = parser(name_reply)
+            if name:
+                break
+
+        return {
+            "serial": parsed["serial"],
+            "name": name,
+            "model": parsed["model"],
+        }
+    finally:
+        connection.close()

pyowershades-0.1.0/pyowershades/const.py

@@ -0,0 +1,34 @@
+"""Constants for the PowerShades protocol."""
+
+UDP_PORT = 42
+BROADCAST_IP = "255.255.255.255"
+
+# Protocol opcodes
+OP_GET_SERIAL = 0x00
+OP_SET_LIMIT = 0x01
+OP_JOG_UP = 0x03
+OP_JOG_DOWN = 0x04
+OP_JOG_STOP = 0x05
+OP_INDICATE = 0x08
+OP_SET_POSITION = 0x1A
+OP_GET_STATUS = 0x1D
+OP_CLEAR_LIMITS = 0x1E
+OP_STEP_UP = 0x23
+OP_STEP_DOWN = 0x24
+OP_GET_SHADE_NAME = 0x34
+OP_GET_DEVICE_NAME = 0x3A
+
+# Limit types
+LIMIT_UPPER = 0x0000
+LIMIT_LOWER = 0x0001
+
+# Model byte in the Get Serial Number reply
+MODEL_NAMES = {
+    1: "PoE Shade",
+    100: "RF Gateway",
+}
+
+# Timing
+DISCOVERY_TIMEOUT = 3.0
+REQUEST_TIMEOUT = 2.0
+REQUEST_RETRIES = 2

pyowershades-0.1.0/pyowershades/protocol.py

@@ -0,0 +1,210 @@
+"""PowerShades UDP packet building and parsing.
+
+Packet layout (little-endian):
+    Length(2) + CRC16-XMODEM(2) + Op(1) + Sequence(1) + Channel(1) + Reserved(1) + Payload
+The CRC covers Op + Sequence + Channel + Reserved + Payload.
+"""
+
+from dataclasses import dataclass
+import struct
+from typing import TypedDict
+
+from .const import OP_GET_STATUS
+
+
+class SerialReply(TypedDict):
+    """Parsed Get Serial Number reply."""
+
+    model: int
+    direction: int
+    serial: int
+    dhcp_enabled: bool
+
+
+HEADER_SIZE = 8
+
+CrcTable = [
+    0x0000, 0x1021, 0x2042, 0x3063, 0x4084, 0x50A5, 0x60C6, 0x70E7,
+    0x8108, 0x9129, 0xA14A, 0xB16B, 0xC18C, 0xD1AD, 0xE1CE, 0xF1EF,
+    0x1231, 0x0210, 0x3273, 0x2252, 0x52B5, 0x4294, 0x72F7, 0x62D6,
+    0x9339, 0x8318, 0xB37B, 0xA35A, 0xD3BD, 0xC39C, 0xF3FF, 0xE3DE,
+    0x2462, 0x3443, 0x0420, 0x1401, 0x64E6, 0x74C7, 0x44A4, 0x5485,
+    0xA56A, 0xB54B, 0x8528, 0x9509, 0xE5EE, 0xF5CF, 0xC5AC, 0xD58D,
+    0x3653, 0x2672, 0x1611, 0x0630, 0x76D7, 0x66F6, 0x5695, 0x46B4,
+    0xB75B, 0xA77A, 0x9719, 0x8738, 0xF7DF, 0xE7FE, 0xD79D, 0xC7BC,
+    0x48C4, 0x58E5, 0x6886, 0x78A7, 0x0840, 0x1861, 0x2802, 0x3823,
+    0xC9CC, 0xD9ED, 0xE98E, 0xF9AF, 0x8948, 0x9969, 0xA90A, 0xB92B,
+    0x5AF5, 0x4AD4, 0x7AB7, 0x6A96, 0x1A71, 0x0A50, 0x3A33, 0x2A12,
+    0xDBFD, 0xCBDC, 0xFBBF, 0xEB9E, 0x9B79, 0x8B58, 0xBB3B, 0xAB1A,
+    0x6CA6, 0x7C87, 0x4CE4, 0x5CC5, 0x2C22, 0x3C03, 0x0C60, 0x1C41,
+    0xEDAE, 0xFD8F, 0xCDEC, 0xDDCD, 0xAD2A, 0xBD0B, 0x8D68, 0x9D49,
+    0x7E97, 0x6EB6, 0x5ED5, 0x4EF4, 0x3E13, 0x2E32, 0x1E51, 0x0E70,
+    0xFF9F, 0xEFBE, 0xDFDD, 0xCFFC, 0xBF1B, 0xAF3A, 0x9F59, 0x8F78,
+    0x9188, 0x81A9, 0xB1CA, 0xA1EB, 0xD10C, 0xC12D, 0xF14E, 0xE16F,
+    0x1080, 0x00A1, 0x30C2, 0x20E3, 0x5004, 0x4025, 0x7046, 0x6067,
+    0x83B9, 0x9398, 0xA3FB, 0xB3DA, 0xC33D, 0xD31C, 0xE37F, 0xF35E,
+    0x02B1, 0x1290, 0x22F3, 0x32D2, 0x4235, 0x5214, 0x6277, 0x7256,
+    0xB5EA, 0xA5CB, 0x95A8, 0x8589, 0xF56E, 0xE54F, 0xD52C, 0xC50D,
+    0x34E2, 0x24C3, 0x14A0, 0x0481, 0x7466, 0x6447, 0x5424, 0x4405,
+    0xA7DB, 0xB7FA, 0x8799, 0x97B8, 0xE75F, 0xF77E, 0xC71D, 0xD73C,
+    0x26D3, 0x36F2, 0x0691, 0x16B0, 0x6657, 0x7676, 0x4615, 0x5634,
+    0xD94C, 0xC96D, 0xF90E, 0xE92F, 0x99C8, 0x89E9, 0xB98A, 0xA9AB,
+    0x5844, 0x4865, 0x7806, 0x6827, 0x18C0, 0x08E1, 0x3882, 0x28A3,
+    0xCB7D, 0xDB5C, 0xEB3F, 0xFB1E, 0x8BF9, 0x9BD8, 0xABBB, 0xBB9A,
+    0x4A75, 0x5A54, 0x6A37, 0x7A16, 0x0AF1, 0x1AD0, 0x2AB3, 0x3A92,
+    0xFD2E, 0xED0F, 0xDD6C, 0xCD4D, 0xBDAA, 0xAD8B, 0x9DE8, 0x8DC9,
+    0x7C26, 0x6C07, 0x5C64, 0x4C45, 0x3CA2, 0x2C83, 0x1CE0, 0x0CC1,
+    0xEF1F, 0xFF3E, 0xCF5D, 0xDF7C, 0xAF9B, 0xBFBA, 0x8FD9, 0x9FF8,
+    0x6E17, 0x7E36, 0x4E55, 0x5E74, 0x2E93, 0x3EB2, 0x0ED1, 0x1EF0,
+]
+
+# Get/Set flag payload for the Get PoE Shade Name command (0 = Get)
+GET_SHADE_NAME_PAYLOAD = b"\x00"
+
+
+def crc16_xmodem(data: bytes) -> int:
+    crc = 0
+    for b in data:
+        crc = ((crc << 8) & 0xFFFF) ^ CrcTable[((crc >> 8) ^ b) & 0xFF]
+    return crc
+
+
+def build_packet(
+    op: int, sequence: int = 0, channel: int = 0, payload: bytes = b""
+) -> bytes:
+    reserved = 0
+    crc_data = struct.pack("<BBBB", op, sequence, channel, reserved) + payload
+    crc = crc16_xmodem(crc_data)
+    return (
+        struct.pack("<HHBBBB", len(payload), crc, op, sequence, channel, reserved)
+        + payload
+    )
+
+
+def build_set_position_payload(percent: int) -> bytes:
+    mask = 0x0001  # MASK_PERCENT
+    tilt = 0
+    channel_mask = 0
+    return struct.pack("<HhhI", mask, percent, tilt, channel_mask)
+
+
+def build_set_limit_payload(limit_type: int) -> bytes:
+    return struct.pack("<H", limit_type)
+
+
+def build_set_name_payload(name: str) -> bytes:
+    return b"\x01" + name.encode("ascii")[:50].ljust(50, b"\x00")
+
+
+@dataclass(frozen=True)
+class PacketHeader:
+    """Parsed packet header."""
+
+    length: int
+    crc: int
+    op: int
+    sequence: int
+    channel: int
+
+
+def parse_header(data: bytes) -> PacketHeader | None:
+    if len(data) < HEADER_SIZE:
+        return None
+    length, crc, op, sequence, channel, _reserved = struct.unpack(
+        "<HHBBBB", data[:HEADER_SIZE]
+    )
+    return PacketHeader(length, crc, op, sequence, channel)
+
+
+def verify_packet(data: bytes) -> bool:
+    """Validate a packet's length field and CRC.
+
+    The CRC covers Op + Sequence + Channel + Reserved + Payload for
+    replies as well as commands (verified against real device replies).
+    """
+    header = parse_header(data)
+    if header is None or len(data) < HEADER_SIZE + header.length:
+        return False
+    return crc16_xmodem(data[4 : HEADER_SIZE + header.length]) == header.crc
+
+
+def parse_serial_reply(data: bytes) -> SerialReply | None:
+    """Parse a Get Serial Number reply packet.
+
+    Payload layout (after the 8-byte header): Model(1) Pad1(1) Pad2(1)
+    Direction(1) SerialLow(4) SerialHigh(4) DhcpEnabled(1) IP(4)
+    Subnet(4) Gateway(4) Internal(50).
+    """
+    if len(data) < 24:
+        return None
+    model = data[8]
+    direction = data[11]
+    serial_low = struct.unpack("<I", data[12:16])[0]
+    serial_high = struct.unpack("<I", data[16:20])[0]
+    dhcp_enabled = bool(data[20])
+    return {
+        "model": model,
+        "direction": direction,
+        "serial": (serial_high << 32) | serial_low,
+        "dhcp_enabled": dhcp_enabled,
+    }
+
+
+def _decode_name(name_bytes: bytes) -> str | None:
+    name = name_bytes.split(b"\x00")[0].decode("ascii", errors="ignore").strip()
+    return name or None
+
+
+def parse_device_name_reply(data: bytes) -> str | None:
+    if len(data) < 58:  # 8-byte header + 50-byte name
+        return None
+    return _decode_name(data[8:58])
+
+
+def parse_shade_name_reply(data: bytes) -> str | None:
+    if len(data) < 59:  # 8-byte header + 1-byte get/set flag + 50-byte name
+        return None
+    return _decode_name(data[9:59])
+
+
+@dataclass(frozen=True)
+class StatusReply:
+    """Parsed status reply."""
+
+    position: int | None
+    battery_mv: int
+
+
+def parse_status_reply(data: bytes) -> StatusReply | None:
+    header = parse_header(data)
+    if header is None or header.op != OP_GET_STATUS:
+        return None
+    payload = data[HEADER_SIZE : HEADER_SIZE + header.length]
+    if len(payload) < 30:
+        return None
+    (
+        percent,
+        _tilt,
+        _memory,
+        battery_mv,
+        _time,
+        _cycles,
+        _stalls,
+        _temperature,
+        _raw_percent,
+        _raw_tilt,
+    ) = struct.unpack("<hhHHIIIhII", payload[:30])
+    position = percent if 0 <= percent <= 100 else None
+    return StatusReply(position=position, battery_mv=battery_mv)
+
+
+def battery_percentage(battery_mv: int | None) -> int | None:
+    """Convert battery voltage (mV) to a rough percentage (3.0V=0%, 4.2V=100%)."""
+    if battery_mv is None:
+        return None
+    voltage = battery_mv / 1000.0
+    if voltage <= 3.0:
+        return 0
+    if voltage >= 4.2:
+        return 100
+    return int((voltage - 3.0) / (4.2 - 3.0) * 100)

pyowershades-0.1.0/pyproject.toml

@@ -0,0 +1,26 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "pyowershades"
+version = "0.1.0"
+description = "Asyncio library for PowerShades motorized blinds"
+readme = "README.md"
+license = {text = "MIT"}
+requires-python = ">=3.12"
+authors = [
+    {name = "Vem Boynerian", email = "vemboy20@gmail.com"},
+]
+classifiers = [
+    "Development Status :: 3 - Alpha",
+    "Intended Audience :: Developers",
+    "License :: OSI Approved :: MIT License",
+    "Programming Language :: Python :: 3",
+    "Programming Language :: Python :: 3.12",
+    "Programming Language :: Python :: 3.13",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://github.com/vemboy200/Pyowershades"