utec-client 0.5.0__py3-none-any.whl

utec_client/api.py

@@ -0,0 +1,146 @@
+"""Api class for Uhome/Utec API."""
+
+import json
+import logging
+from enum import Enum
+from typing import Any, TypedDict
+from uuid import uuid4
+
+from attr import dataclass
+
+from .auth import AbstractAuth
+from .const import API_BASE_URL
+from .exceptions import ApiError
+
+logger = logging.getLogger(__name__)
+
+
+class ApiNamespace(str, Enum):
+    DEVICE = "Uhome.Device"
+    USER = "Uhome.User"
+    CONFIGURE = "Uhome.Configure"
+
+
+class ApiOperation(str, Enum):
+    DISCOVERY = "Discovery"
+    QUERY = "Query"
+    COMMAND = "Command"
+    SET = "Set"
+
+
+@dataclass
+class ApiHeader(TypedDict):
+    namespace: str
+    name: str
+    messageId: str
+    payloadVersion: str
+
+
+@dataclass
+class ApiRequest(TypedDict):
+    header: ApiHeader
+    payload: dict | None
+
+
+class UHomeApi:
+    """U-Home API client implementation."""
+
+    def __init__(self, Auth: AbstractAuth) -> None:
+        """Initialise the API."""
+        self.auth = Auth
+
+    async def async_create_request(
+        self, namespace: ApiNamespace, operation: ApiOperation, parameters: dict | None
+    ) -> ApiRequest:
+        """Create a standardised API request."""
+        header: ApiHeader = {
+            "namespace": namespace,
+            "name": operation,
+            "messageId": str(uuid4()),
+            "payloadVersion": "1",
+        }
+        return {"header": header, "payload": parameters}
+
+    async def _async_make_request(self, **kwargs):
+        """Make an authenticated API request."""
+        response = await self.auth.async_make_auth_request("POST", API_BASE_URL, **kwargs)
+        try:
+            if response.status == 204:
+                return {}
+            elif response.status in (200, 201, 202):
+                return await response.json()
+            else:
+                error_text = await response.text()
+                logger.error(f"API error: {response.status} - {error_text}")
+                raise ApiError(response.status, error_text)
+        finally:
+            await response.release()
+
+    async def validate_auth(self) -> bool:
+        """Validate authentication by making a test request."""
+        try:
+            await self.discover_devices()
+            return True
+        except ApiError:
+            return False
+
+    async def discover_devices(self) -> dict[str, Any]:
+        """Discover available devices."""
+        logger.debug("Discovering devices")
+        payload = await self.async_create_request(ApiNamespace.DEVICE, ApiOperation.DISCOVERY, {})
+        return await self._async_make_request(json=payload)
+
+    async def get_device_state(self, device_ids: list, custom_data: dict | None) -> dict[str, Any]:
+        """Get device status - supports multiple devices at once and custom data."""
+        devices = []
+        for device_id in device_ids:
+            device = {"id": device_id}
+            if custom_data:
+                device["custom_data"] = custom_data
+            devices.append(device)
+        params = {"devices": devices}
+        payload = await self.async_create_request(ApiNamespace.DEVICE, ApiOperation.QUERY, params)
+        return await self._async_make_request(json=payload)
+
+    async def query_device(self, device_id: str):
+        """Query single device."""
+        device = [{"id": device_id}]
+        params = {"devices": device}
+        payload = await self.async_create_request(ApiNamespace.DEVICE, ApiOperation.QUERY, params)
+        logger.debug(
+            "Querying device with device ID %s and payload %s",
+            device_id,
+            json.dumps(payload, default=str),
+        )
+        return await self._async_make_request(json=payload)
+
+    async def send_command(
+        self, device_id: str, capability: str, command: str, arguments: dict | None
+    ) -> dict[str, Any]:
+        """Send command to device."""
+        command_data: dict[str, Any] = {"capability": capability, "name": command}
+        if arguments:
+            command_data["arguments"] = arguments
+
+        params = {"devices": [{"id": device_id, "command": command_data}]}
+
+        payload = await self.async_create_request(ApiNamespace.DEVICE, ApiOperation.COMMAND, params)
+        logger.debug(
+            "Sending Command %s to device %s, with payload %s",
+            command,
+            device_id,
+            json.dumps(payload, default=str),
+        )
+        return await self._async_make_request(json=payload)
+
+    async def set_push_status(self, uri: str, access_token: str):
+        """Register URI for push device updates.
+
+        Args:
+            uri: URL to receive push updates - must be HTTP/HTTPS with valid CA cert
+            access_token: OAuth2 access token sent by U-Tec with each push notification
+        """
+        params = {"configure": {"notification": {"access_token": access_token, "url": uri}}}
+        payload = await self.async_create_request(ApiNamespace.CONFIGURE, ApiOperation.SET, params)
+        logger.debug("Setting push update url. URL: %s", uri)
+        return await self._async_make_request(json=payload)

utec_client/auth.py

@@ -0,0 +1,45 @@
+"""Abstract Auth class for Uhome/Utec API."""
+
+# auth.py - OAuth2 implementation
+
+from abc import ABC, abstractmethod
+
+from aiohttp import ClientResponse, ClientSession
+
+
+class AbstractAuth(ABC):
+    """Abstract Auth base for extension in integrations.
+
+    Takes an aiohttp clientsession for extending token management.
+
+    """
+
+    def __init__(self, websession: ClientSession) -> None:
+        """Initialise auth class."""
+        self.websession = websession
+
+    @abstractmethod
+    async def async_get_access_token(self) -> str:
+        """Return a valid access token (refresh if needed)."""
+
+    async def async_make_auth_request(self, method, host: str, **kwargs) -> ClientResponse:
+        """Performs authenticated request using the clientsession passed to the class init."""
+        if headers := kwargs.pop("headers", {}):
+            headers = dict(headers)
+
+        headers.update(
+            {
+                "Content-Type": "application/json",
+                "Accept": "application/json",
+            }
+        )
+
+        access_token = await self.async_get_access_token()
+        headers["authorization"] = f"Bearer {access_token}"
+
+        return await self.websession.request(
+            method,
+            host,
+            **kwargs,
+            headers=headers,
+        )

utec_client/const.py

@@ -0,0 +1,38 @@
+"""U-Home API constants."""
+
+from enum import Enum
+from typing import Any, TypedDict
+
+AUTH_BASE_URL = "https://oauth.u-tec.com/authorize?"
+TOKEN_BASE_URL = "https://oauth.u-tec.com/token?"
+API_BASE_URL = "https://api.u-tec.com/action"
+
+ATTR_HANDLE_TYPE = "handleType"
+ATTR_DEVICE_ID = "id"
+ATTR_NAME = "name"
+ATTR_CATEGORY = "category"
+ATTR_DEVICE_INFO = "deviceInfo"
+ATTR_ATTRIBUTES = "attributes"
+
+
+class ApiNamespace(str, Enum):
+    DEVICE = "Uhome.Device"
+    USER = "Uhome.User"
+
+
+class ApiOperation(str, Enum):
+    DISCOVERY = "Discovery"
+    QUERY = "Query"
+    COMMAND = "Command"
+
+
+class ApiHeader(TypedDict):
+    namespace: ApiNamespace
+    name: ApiOperation
+    messageID: str
+    payloadVersion: str
+
+
+class ApiRequest(TypedDict):
+    header: ApiHeader
+    payload: dict[str, Any] | None

utec_client/devices/device.py

@@ -0,0 +1,274 @@
+"""Base device implementation for U-Home API devices."""
+
+import logging
+from dataclasses import dataclass
+from datetime import datetime
+from typing import Any
+
+from ..api import UHomeApi
+from ..exceptions import DeviceError
+from .device_const import HANDLE_TYPE_CAPABILITIES, DeviceCategory, DeviceCommand
+
+logger = logging.getLogger(__name__)
+
+
+@dataclass
+class DeviceInfo:
+    """Class that represents device information in the U-Home API."""
+
+    manufacturer: str
+    model: str
+    hw_version: str
+    serial_number: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "DeviceInfo":
+        """Create DeviceInfo instance from API response dictionary."""
+        return cls(
+            manufacturer=data.get("manufacturer", ""),
+            model=data.get("model", ""),
+            hw_version=data.get("hwVersion", ""),
+            serial_number=data.get("serialNumber"),
+        )
+
+
+class BaseDevice:
+    """Base class for all U-Home devices."""
+
+    def __init__(self, discovery_data: dict, api: UHomeApi) -> None:
+        """Initialize the device with discovery data.
+
+        Args:
+            discovery_data: Dictionary containing device discovery information
+            api: UHomeApi instance for device communication
+
+        Raises:
+            DeviceError: If required device information is missing
+
+        """
+        self._api = api
+        self._discovery_data = discovery_data
+        self._state_data: dict | None = None
+        self._last_update: datetime | None = None
+
+        # Extract required fields
+        try:
+            self._id = discovery_data["id"]
+            self._name = discovery_data["name"]
+            self._handle_type = discovery_data["handleType"]
+            self._category = discovery_data.get("category", "unknown")
+
+            # Parse device info
+            device_info_data = discovery_data.get("deviceInfo", {})
+            self._device_info = DeviceInfo.from_dict(device_info_data)
+
+            # Get attributes and capabilities
+            self._attributes = discovery_data.get("attributes", {})
+            self._supported_capabilities = HANDLE_TYPE_CAPABILITIES.get(self._handle_type, set())
+
+            self._validate_capabilities()
+
+        except KeyError as err:
+            raise DeviceError(f"Missing required field in discovery data: {err}") from err
+
+    @property
+    def device_id(self) -> str:
+        """Get the unique device ID."""
+        return self._id
+
+    @property
+    def name(self) -> str:
+        """Get the device name."""
+        return self._name
+
+    @property
+    def handle_type(self) -> str:
+        """Get the device handle type."""
+        return self._handle_type
+
+    @property
+    def category(self) -> DeviceCategory:
+        """Get the device category."""
+        return DeviceCategory(self._category)
+
+    @property
+    def manufacturer(self) -> str:
+        """Get the device manufacturer."""
+        return self._device_info.manufacturer
+
+    @property
+    def model(self) -> str:
+        """Get the device model."""
+        return self._device_info.model
+
+    @property
+    def hw_version(self) -> str:
+        """Get the device hardware version."""
+        return self._device_info.hw_version
+
+    @property
+    def serial_number(self) -> str | None:
+        """Get the device serial number."""
+        return self._device_info.serial_number
+
+    @property
+    def supported_capabilities(self) -> set[str]:
+        """Get the set of supported capabilities."""
+        return self._supported_capabilities
+
+    @property
+    def available(self) -> bool:
+        """Indicate if the device is available."""
+        if not self._state_data:
+            return False
+        return self._get_state_value("st.healthCheck", "status") == "Online"
+
+    @property
+    def attributes(self) -> dict[str, Any]:
+        """Get device attributes."""
+        return self._attributes
+
+    def has_capability(self, capability: str) -> bool:
+        """Check if the device supports a specific capability."""
+        return capability in self._supported_capabilities
+
+    def _state_has_capability(self, *capabilities: str) -> bool:
+        """Return whether current state data contains one of the capabilities."""
+        if not self._state_data:
+            return False
+        return any(
+            state.get("capability") in capabilities for state in self._state_data.get("states", [])
+        )
+
+    def _validate_capabilities(self) -> None:
+        """Validate that the device has all required capabilities.
+
+        Raises:
+            DeviceError: If device is missing required capabilities
+
+        """
+        required_capabilities = HANDLE_TYPE_CAPABILITIES.get(self._handle_type, set())
+        if not required_capabilities.issubset(self._supported_capabilities):
+            missing = required_capabilities - self._supported_capabilities
+            raise DeviceError(f"Device {self._id} missing required capabilities: {missing}")
+
+    def _get_state_value(self, capability: str, attribute: str) -> Any:
+        """Get a specific state value from device state data.
+
+        Args:
+            capability: The capability namespace
+            attribute: The attribute name
+
+        Returns:
+            The state value if found, None otherwise
+
+        """
+        if not self._state_data:
+            logger.debug("No state data available for device %s", self.device_id)
+            return None
+
+        states = self._state_data.get("states", [])
+
+        if not states:
+            logger.debug("Empty states array for device %s", self.device_id)
+            return None
+
+        for state in states:
+            if state.get("capability") == capability and state.get("name") == attribute:
+                logger.debug("Found %s.%s = %s", capability, attribute, state.get("value"))
+                return state.get("value")
+        logger.debug("State %s.%s not found for device %s", capability, attribute, self.device_id)
+        return None
+
+    def get_state_data(self) -> dict:
+        """Get the current device states in a standardized format."""
+        states = {}
+        if self._state_data and "states" in self._state_data:
+            for state in self._state_data["states"]:
+                capability = state.get("capability")
+                name = state.get("name")
+                value = state.get("value")
+                if capability and name:
+                    if capability not in states:
+                        states[capability] = {}
+                    states[capability][name] = value
+        return states
+
+    async def send_command(self, command: DeviceCommand) -> None:
+        """Send a command to the device.
+
+        Args:
+            command: DeviceCommand instance containing command details
+
+        Raises:
+            DeviceError: If command sending fails
+
+        """
+        logger.debug("Sending command %s for device ID %s", command.name, self.device_id)
+        try:
+            await self._api.send_command(
+                self.device_id, command.capability, command.name, command.arguments
+            )
+
+            self._last_update = datetime.now()
+
+        except Exception as err:
+            raise DeviceError(f"Failed to send command to device: {err}") from err
+
+    async def update(self) -> None:
+        """Update device state data.
+
+        Raises:
+            DeviceError: If update fails
+
+        """
+        logger.debug("updating device %s", self.device_id)
+        try:
+            response = await self._api.query_device(self.device_id)
+            if response and "payload" in response:
+                devices = response["payload"].get("devices", [])
+                if devices:
+                    self._state_data = devices[0]
+                    logger.debug(
+                        "Updated device %s with data: %s",
+                        self.device_id,
+                        self._state_data,
+                    )
+                    self._last_update = datetime.now()
+
+        except Exception as err:
+            raise DeviceError(f"Failed to update device state: {err}") from err
+
+    async def update_state_data(self, push_data: dict) -> dict[str, Any] | None:
+        """Update device data from push data"""
+        if "states" in push_data:
+            self._state_data = push_data
+            logger.debug("Updated device %s with push data: %s", self.device_id, push_data)
+            self._last_update = datetime.now()
+        else:
+            logger.warning("Invalid push data format for device %s: %s", self.device_id, push_data)
+
+    @property
+    def device_info(self) -> dict[str, Any]:
+        """Get device information for Home Assistant."""
+        return {
+            "identifiers": {("uhome", self.device_id)},
+            "name": self.name,
+            "manufacturer": self.manufacturer,
+            "model": self.model,
+            "hw_version": self.hw_version,
+        }
+
+    def __str__(self) -> str:
+        """Return string representation of the device."""
+        return f"{self.__class__.__name__}(id={self.device_id}, name={self.name})"
+
+    def __repr__(self) -> str:
+        """Return detailed string representation of the device."""
+        return (
+            f"{self.__class__.__name__}("
+            f"id={self.device_id}, "
+            f"name={self.name}, "
+            f"type={self.handle_type}, "
+            f"category={self.category})"
+        )

utec_client/devices/device_const.py

@@ -0,0 +1,222 @@
+"""Device types and constants for U-Home API devices."""
+
+from dataclasses import dataclass
+from enum import Enum, IntEnum
+from typing import Any
+
+
+class HandleType(str, Enum):
+    """Device handle types supported by the API."""
+
+    UTEC_LOCK = "utec-lock"
+    UTEC_LOCK_SENSOR = "utec-lock-sensor"
+    UTEC_DIMMER = "utec-dimmer"
+    UTEC_LIGHT_RGBAW = "utec-light-rgbaw-br"
+    UTEC_SWITCH = "utec-switch"
+
+
+class DeviceCapability(str, Enum):
+    """Device capabilities supported by the API."""
+
+    SWITCH = "st.switch"
+    LOCK = "st.lock"
+    BATTERY_LEVEL = "st.batteryLevel"
+    LOCK_USER = "st.lockUser"
+    DOOR_SENSOR = "st.DoorSensor"
+    BRIGHTNESS = "st.brightness"
+    SWITCH_LEVEL = "st.switchLevel"
+    COLOR = "st.color"
+    COLOR_TEMPERATURE = "st.colorTemperature"
+    HEALTH_CHECK = "st.healthCheck"
+
+
+class DeviceCategory(str, Enum):
+    """Device categories as returned by the API."""
+
+    LOCK = "SmartLock"
+    PLUG = "SmartPlug"
+    SWITCH = "SmartSwitch"
+    LIGHT = "LIGHT"
+    UNKNOWN = "Unknown"
+
+
+class LockState(str, Enum):
+    """Lock state values from API."""
+
+    LOCKED = "Locked"
+    UNLOCKED = "Unlocked"
+    JAMMED = "Jammed"
+    UNKNOWN = "Unknown"
+
+
+class LockMode(IntEnum):
+    """Lock mode values from API (st.lock / lockMode attribute).
+
+    Per API spec: 0 = Normal, 1 = Passage, 2 = Locked.
+    """
+
+    NORMAL = 0
+    PASSAGE = 1
+    LOCKED = 2
+
+
+class DoorState(str, Enum):
+    """Door state values from API (st.doorSensor / sensorState attribute)."""
+
+    CLOSED = "Closed"
+    OPEN = "Open"
+    UNKNOWN = "Unknown"
+
+
+# SwitchState is kept for reading state values returned by the API.
+# Commands use the command name directly ("on"/"off") with no arguments,
+# per the st.switch capability spec.
+class SwitchState(str, Enum):
+    """Switch state values returned by the API."""
+
+    ON = "on"
+    OFF = "off"
+    UNKNOWN = "Unknown"
+
+
+@dataclass
+class DeviceCommand:
+    """Represents a command to be sent to a U-Home device."""
+
+    capability: str
+    name: str
+    arguments: dict[str, Any] | None = None
+
+    def to_dict(self) -> dict[str, Any]:
+        """Convert command to API-compatible dictionary format."""
+        command_dict: dict[str, Any] = {
+            "capability": self.capability,
+            "name": self.name,
+        }
+        if self.arguments:
+            command_dict["arguments"] = self.arguments
+        return command_dict
+
+
+@dataclass
+class ColorState:
+    """Represents color state of a light."""
+
+    r: int  # 0-255
+    g: int  # 0-255
+    b: int  # 0-255
+
+    @classmethod
+    def from_dict(cls, data: dict[str, int]) -> "ColorState":
+        """Create ColorState instance from dictionary."""
+        return cls(r=data.get("r", 0), g=data.get("g", 0), b=data.get("b", 0))
+
+    def to_dict(self) -> dict[str, int]:
+        """Convert color state to dictionary format."""
+        return {"r": self.r, "g": self.g, "b": self.b}
+
+
+@dataclass
+class ColorTemperatureRange(int):
+    """Represents color temperature range for lights."""
+
+    min: int  # Minimum temperature in Kelvin
+    max: int  # Maximum temperature in Kelvin
+    step: int = 1  # Step size for temperature adjustment
+
+
+class BrightnessRange(int):
+    """Constants for brightness range."""
+
+    MIN = 0
+    MAX = 100
+    STEP = 1
+
+
+class ColorTempRange(int):
+    """Constants for color temperature range in Kelvin."""
+
+    MIN = 2000
+    MAX = 9000
+    STEP = 1
+
+
+# Mapping of handle types to their required capabilities
+HANDLE_TYPE_CAPABILITIES: dict[str, set[str]] = {
+    HandleType.UTEC_LOCK: {
+        DeviceCapability.LOCK,
+        DeviceCapability.BATTERY_LEVEL,
+        DeviceCapability.LOCK_USER,
+        DeviceCapability.HEALTH_CHECK,
+    },
+    HandleType.UTEC_LOCK_SENSOR: {
+        DeviceCapability.LOCK,
+        DeviceCapability.BATTERY_LEVEL,
+        DeviceCapability.DOOR_SENSOR,
+        DeviceCapability.HEALTH_CHECK,
+    },
+    HandleType.UTEC_DIMMER: {
+        DeviceCapability.SWITCH,
+        DeviceCapability.BRIGHTNESS,
+        DeviceCapability.HEALTH_CHECK,
+    },
+    HandleType.UTEC_LIGHT_RGBAW: {
+        DeviceCapability.SWITCH,
+        DeviceCapability.BRIGHTNESS,
+        DeviceCapability.COLOR,
+        DeviceCapability.COLOR_TEMPERATURE,
+        DeviceCapability.HEALTH_CHECK,
+    },
+    HandleType.UTEC_SWITCH: {DeviceCapability.SWITCH, DeviceCapability.HEALTH_CHECK},
+}
+
+
+@dataclass
+class DeviceState:
+    """Represents a device state in the API."""
+
+    capability: str
+    name: str
+    value: Any
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "DeviceState":
+        """Create DeviceState instance from API response dictionary."""
+        return cls(capability=data["capability"], name=data["name"], value=data["value"])
+
+
+@dataclass
+class DeviceAttributes:
+    """Device attributes from discovery data."""
+
+    color_model: str | None = None
+    color_temp_range: ColorTemperatureRange | None = None
+    switch_type: str | None = None
+
+    @classmethod
+    def from_dict(cls, data: dict[str, Any]) -> "DeviceAttributes":
+        """Create DeviceAttributes instance from discovery data dictionary."""
+        temp_range = None
+        if "colorTemperatureRange" in data:
+            temp_range = ColorTemperatureRange(
+                min=data["colorTemperatureRange"]["min"],
+                max=data["colorTemperatureRange"]["max"],
+                step=data["colorTemperatureRange"].get("step", 1),
+            )
+
+        return cls(
+            color_model=data.get("colorModel"),
+            color_temp_range=temp_range,
+            switch_type=data.get("switchType"),
+        )
+
+
+# State value mapping for Home Assistant integration
+STATE_MAP = {
+    DoorState.CLOSED: "closed",
+    DoorState.OPEN: "open",
+    DoorState.UNKNOWN: "unknown",
+    SwitchState.ON: "on",
+    SwitchState.OFF: "off",
+    SwitchState.UNKNOWN: "unknown",
+}

utec_client/devices/light.py

@@ -0,0 +1,128 @@
+"""Abstraction layer for device interaction - Light."""
+# src/utec-client/devices/light.py
+
+from .device import BaseDevice
+from .device_const import (
+    BrightnessRange,
+    ColorState,
+    ColorTempRange,
+    DeviceCapability,
+    DeviceCommand,
+    SwitchState,
+)
+
+
+class Light(BaseDevice):
+    """Represents a Light device in the U-Home API.
+
+    Maps to Home Assistant's light platform.
+    """
+
+    @property
+    def is_on(self) -> bool:
+        """Get light state."""
+        state = self._get_state_value(DeviceCapability.SWITCH, "switch")
+        return state == SwitchState.ON if state is not None else False
+
+    @property
+    def brightness(self) -> int | None:
+        """Get brightness level (0-100).
+
+        The API reports brightness under st.switchLevel / level, not st.brightness.
+        """
+        return self._get_state_value(DeviceCapability.SWITCH_LEVEL, "level")
+
+    @property
+    def color_temp(self) -> int | None:
+        """Get color temperature in Kelvin."""
+        return self._get_state_value(DeviceCapability.COLOR_TEMPERATURE, "temperature")
+
+    @property
+    def rgb_color(self) -> tuple[int, int, int] | None:
+        """Get RGB color."""
+        color_data = self._get_state_value(DeviceCapability.COLOR, "color")
+        if color_data:
+            color = ColorState.from_dict(color_data)
+            return (color.r, color.g, color.b)
+        return None
+
+    @property
+    def supported_features(self) -> set:
+        """Get supported features for Home Assistant."""
+        features = set()
+        if self.has_capability(DeviceCapability.BRIGHTNESS):
+            features.add("brightness")
+        if self.has_capability(DeviceCapability.COLOR):
+            features.add("color")
+        if self.has_capability(DeviceCapability.COLOR_TEMPERATURE):
+            features.add("color_temp")
+        return features
+
+    async def turn_on(self, **kwargs) -> None:
+        """Turn on the light with optional attributes.
+
+        If an attribute command (brightness, color_temp, rgb_color) is provided,
+        the device turns on implicitly — no separate "on" command is needed.
+        Only send the explicit "on" command when no attributes are specified.
+        """
+        if "brightness" in kwargs:
+            await self.set_brightness(kwargs["brightness"])
+        elif "color_temp" in kwargs:
+            await self.set_color_temp(kwargs["color_temp"])
+        elif "rgb_color" in kwargs:
+            await self.set_rgb_color(*kwargs["rgb_color"])
+        else:
+            command = DeviceCommand(
+                capability=DeviceCapability.SWITCH,
+                name="on",
+            )
+            await self.send_command(command)
+
+    async def turn_off(self) -> None:
+        """Turn off the light.
+
+        Per st.switch capability spec, the command name is "off" with no arguments.
+        """
+        command = DeviceCommand(
+            capability=DeviceCapability.SWITCH,
+            name="off",
+        )
+        await self.send_command(command)
+
+    async def set_brightness(self, brightness: int) -> None:
+        """Set brightness level (1-100).
+
+        Per st.switchLevel capability spec, command is setLevel with a
+        "level" argument (integer 0-100). We clamp to 1 as the minimum
+        since 0 means off per the spec — use turn_off() for that.
+        """
+        brightness = max(1, min(BrightnessRange.MAX, brightness))
+        command = DeviceCommand(
+            capability=DeviceCapability.SWITCH_LEVEL,
+            name="setLevel",
+            arguments={"level": brightness},
+        )
+        await self.send_command(command)
+
+    async def set_color_temp(self, temp: int) -> None:
+        """Set color temperature in Kelvin."""
+        if not ColorTempRange.MIN <= temp <= ColorTempRange.MAX:
+            raise ValueError(
+                f"Color temperature must be between {ColorTempRange.MIN}K and {ColorTempRange.MAX}K"
+            )
+        command = DeviceCommand(
+            capability=DeviceCapability.COLOR_TEMPERATURE,
+            name="temperature",
+            arguments={"value": temp},
+        )
+        await self.send_command(command)
+
+    async def set_rgb_color(self, red: int, green: int, blue: int) -> None:
+        """Set RGB color."""
+        color = ColorState(r=red, g=green, b=blue)
+        command = DeviceCommand(
+            capability=DeviceCapability.COLOR,
+            name="color",
+            arguments={"value": color.to_dict()},
+        )
+        await self.send_command(command)

utec_client/devices/lock.py

@@ -0,0 +1,108 @@
+"""Abstraction layer for device interaction - Lock."""
+
+from .device import BaseDevice
+from .device_const import (
+    DeviceCapability,
+    DeviceCategory,
+    DeviceCommand,
+    DoorState,
+    LockMode,
+    LockState,
+)
+
+
+class Lock(BaseDevice):
+    """Represents a Lock device in the U-Home API.
+
+    Maps to Home Assistant's lock platform.
+    """
+
+    @property
+    def category(self) -> DeviceCategory:
+        """Get the device category."""
+        return DeviceCategory.LOCK
+
+    @property
+    def lock_state(self) -> str:
+        """Get the current lock state."""
+        state = self._get_state_value(DeviceCapability.LOCK, "lockState")
+        return state if state else "Unknown"
+
+    @property
+    def has_door_sensor(self) -> bool:
+        """Check if the lock has a door sensor capability."""
+        return (
+            self.has_capability(DeviceCapability.DOOR_SENSOR)
+            or self.has_capability("st.doorSensor")
+            or self._state_has_capability(DeviceCapability.DOOR_SENSOR, "st.doorSensor")
+        )
+
+    @property
+    def door_state(self) -> str | None:
+        """Get the door state if door sensor is present."""
+        if not self.has_door_sensor:
+            return None
+        door_state = self._get_state_value(DeviceCapability.DOOR_SENSOR, "sensorState")
+        return door_state or self._get_state_value("st.doorSensor", "sensorState")
+
+    @property
+    def lock_mode(self) -> str | None:
+        """Get the current lock mode."""
+        state = self._get_state_value(DeviceCapability.LOCK, "lockMode")
+        lock_mode_map = {
+            LockMode.NORMAL: "Normal",
+            LockMode.PASSAGE: "Passage",
+            LockMode.LOCKED: "Locked",
+        }
+        return lock_mode_map.get(state)
+
+    @property
+    def is_locked(self) -> bool:
+        """Check if the lock is in locked state."""
+        state = self._get_state_value(DeviceCapability.LOCK, "lockState")
+        return state == LockState.LOCKED if state is not None else False
+
+    @property
+    def is_jammed(self) -> bool:
+        """Check if the lock is jammed."""
+        state = self._get_state_value(DeviceCapability.LOCK, "lockState")
+        return state == LockState.JAMMED if state is not None else False
+
+    @property
+    def is_door_open(self) -> bool | None:
+        """Check if the door is open."""
+        if not self.has_door_sensor:
+            return None
+        return self.door_state == DoorState.OPEN
+
+    @property
+    def battery_status(self) -> str | None:
+        """Get the current battery level as a string."""
+        batt_level = self._get_state_value(DeviceCapability.BATTERY_LEVEL, "level")
+        battery_states = {
+            1: "Critically Low",
+            2: "Low",
+            3: "Medium",
+            4: "High",
+            5: "Full",
+        }
+        return battery_states.get(batt_level)
+
+    @property
+    def battery_level(self) -> int | None:
+        """Get the current battery level as a percentage."""
+        level = self._get_state_value(DeviceCapability.BATTERY_LEVEL, "level")
+        if level is None:
+            return None
+        batt_map = {1: 10, 2: 30, 3: 50, 4: 70, 5: 100}
+        return batt_map.get(level, 0)
+
+    async def lock(self) -> None:
+        """Lock the device."""
+        command = DeviceCommand(capability=DeviceCapability.LOCK, name="lock")
+        await self.send_command(command)
+
+    async def unlock(self) -> None:
+        """Unlock the device."""
+        command = DeviceCommand(capability=DeviceCapability.LOCK, name="unlock")
+        await self.send_command(command)

utec_client/devices/sensor.py

@@ -0,0 +1,10 @@
+"""Abstraction layer for sensor entities"""
+
+from .device import BaseDevice
+
+
+class Sensor(BaseDevice):
+    """Represents a Sensor device in the U-Home API.
+
+    Maps to Home Assistant's Sensor platform.
+    """

utec_client/devices/switch.py

@@ -0,0 +1,46 @@
+"""Abstraction layer for device interaction - Switch."""
+
+# src/utec-client/devices/switch.py
+
+from .device import BaseDevice
+from .device_const import DeviceCapability, DeviceCommand, SwitchState
+
+
+class Switch(BaseDevice):
+    """Represents a Switch device in the U-Home API.
+
+    Maps to Home Assistant's switch platform.
+    """
+
+    @property
+    def is_on(self) -> bool:
+        """Get switch state."""
+        state = self._get_state_value(DeviceCapability.SWITCH, "switch")
+        return state == SwitchState.ON if state is not None else False
+
+    @property
+    def available(self) -> bool:
+        """Device availability for Home Assistant."""
+        return self._state_data is not None
+
+    async def turn_on(self) -> None:
+        """Turn on the switch.
+
+        Per st.switch capability spec, the command name is "on" with no arguments.
+        """
+        command = DeviceCommand(
+            capability=DeviceCapability.SWITCH,
+            name="on",
+        )
+        await self.send_command(command)
+
+    async def turn_off(self) -> None:
+        """Turn off the switch.
+
+        Per st.switch capability spec, the command name is "off" with no arguments.
+        """
+        command = DeviceCommand(
+            capability=DeviceCapability.SWITCH,
+            name="off",
+        )
+        await self.send_command(command)

utec_client/exceptions.py

@@ -0,0 +1,40 @@
+"""U-Home API exceptions."""
+
+
+class UHomeError(Exception):
+    """Base exception for U-Home API."""
+
+    pass
+
+
+class AuthenticationError(UHomeError):
+    """Authentication failed."""
+
+    pass
+
+
+class ApiError(UHomeError):
+    """API call failed."""
+
+    def __init__(self, status_code, message) -> None:
+        super().__init__(f"API call failed: {status_code} - {message}")
+        self.status_code = status_code
+        self.message = message
+
+
+class ValidationError(UHomeError):
+    """Validation failed."""
+
+    pass
+
+
+class DeviceError(Exception):
+    """Base exception for device-related errors."""
+
+    pass
+
+
+class UnsupportedFeatureError(DeviceError):
+    """Exception raised when a feature is not supported by the device."""
+
+    pass

utec_client-0.5.0.dist-info/METADATA

@@ -0,0 +1,99 @@
+Metadata-Version: 2.4
+Name: utec-client
+Version: 0.5.0
+Summary: An independently maintained U-Tec/U-Home API client library.
+Author-email: Luke Wallis <wallis.luke4@gmail.com>
+Maintainer: Geoff Franks
+License-Expression: MIT
+Project-URL: Homepage, https://github.com/geofffranks/utec-client
+Project-URL: Issues, https://github.com/geofffranks/utec-client/issues
+Keywords: utec,uhome,home automation,api client
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Operating System :: OS Independent
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3.11
+Classifier: Programming Language :: Python :: 3.12
+Classifier: Programming Language :: Python :: 3.13
+Classifier: Programming Language :: Python :: 3.14
+Requires-Python: >=3.11
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: aiohttp<4.0.0,>=3.7.4
+Provides-Extra: dev
+Requires-Dist: aioresponses>=0.7.6; extra == "dev"
+Requires-Dist: aiohttp<3.13,>=3.7.4; extra == "dev" and extra == "dev"
+Requires-Dist: build>=1.2; extra == "dev"
+Requires-Dist: coverage[toml]>=7.4; extra == "dev"
+Requires-Dist: pytest>=8.0; extra == "dev"
+Requires-Dist: pytest-asyncio>=0.24; extra == "dev"
+Requires-Dist: pytest-cov>=5.0; extra == "dev"
+Requires-Dist: ruff>=0.8; extra == "dev"
+Dynamic: license-file
+
+# utec-client
+
+> **Fork notice:** This is an independently maintained fork of [LF2b2w/utec-py](https://github.com/LF2b2w/utec-py), the original repository by [@LF2b2w](https://github.com/LF2b2w). The upstream project currently appears to be unmaintained, so this fork exists to keep the library working alongside the companion [Uhome-HA](https://github.com/LF2b2w/Uhome-HA) integration. It is not vendor-official. Any changes made here will be offered back to the upstream repository should it become responsive again. See [MIGRATION.md](MIGRATION.md) if you are coming from `utec_py` — the import name changed.
+
+Python API client for U-Tec/U-Home devices. Primarily for Home Assistant, but usable anywhere.
+
+## Install
+
+```sh
+pip install utec-client
+```
+
+Imports use the `utec_client` namespace:
+
+```python
+from utec_client.api import UHomeApi
+from utec_client.auth import AbstractAuth
+from utec_client.devices.lock import Lock
+from utec_client.devices.light import Light
+from utec_client.devices.sensor import Sensor
+from utec_client.devices.switch import Switch
+from utec_client.exceptions import ApiError
+```
+
+## API overview
+
+### `UHomeApi` (`utec_client.api`)
+
+U-Tec's API is a single endpoint (`https://api.utec.com/action`) that uses
+variable header information in the JSON payload to reach different API
+interfaces. `UHomeApi` handles packaging the variables responsible for the
+different interfaces/actions correctly within the request payload.
+
+### `AbstractAuth` (`utec_client.auth`)
+
+Abstract base class handling most of the OAuth2 process: generating the auth
+request URL, token exchange, token management, expiry validation, and token
+refresh. Subclass it and implement the abstract token-retrieval method to
+control how the initial auth request is handled. `UHomeApi` uses an
+`AbstractAuth` implementation to perform authenticated requests.
+
+### Device modules (`utec_client.devices`)
+
+Device info is organized with minimal change from the raw API response
+(`id`, `name`, `category`, `handleType`, `deviceInfo`, `capabilities`,
+`customData`, `attributes`, `state`). Device type classes (`Light`, `Lock`,
+`Sensor`, `Switch`) pre-format and pre-fill API requests for simple
+integration downstream. Locks are the most fully supported device type;
+switches and lights have limited functionality.
+
+## Development
+
+Requires Python 3.11–3.14.
+
+```sh
+pip install -e .[dev]
+ruff check . && ruff format --check .
+pytest                # includes the 90% branch-coverage floor
+```
+
+See [docs/RELEASES.md](docs/RELEASES.md) for the release process and
+[MIGRATION.md](MIGRATION.md) for the `utec_py` → `utec_client` rename guide.
+
+## License
+
+MIT. Upstream authorship (Luke Wallis) is preserved; see [LICENSE](LICENSE).

utec_client-0.5.0.dist-info/RECORD

@@ -0,0 +1,17 @@
+utec_client/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+utec_client/api.py,sha256=nplR2DBAKcMDLfWlWkoAGyomDojGFxra75pFf47bym8,4991
+utec_client/auth.py,sha256=Z2Jjbdq84SkCmM6zsrkbqLOOIhebFMO_BTSEDzCg2fI,1299
+utec_client/const.py,sha256=24ltBHK8zC4NHMA8uVv4rXQ1SSCqfDHNhf21LjMZlVg,801
+utec_client/exceptions.py,sha256=R23pyFu5qjZ94wYuXitJFYQRNbd1ErO4TvB6WgRs1D8,749
+utec_client/devices/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+utec_client/devices/device.py,sha256=zx58agvQaxv-_K_tBjIPyKmIjtItvU9Y-EJ1Qi1gDrg,9397
+utec_client/devices/device_const.py,sha256=Oh6stzy5v3wUrwmksDT00aF_kHtwnoi7dYemj-3MEFY,5838
+utec_client/devices/light.py,sha256=YiS1gtPGvYODDhDGIgWSPY1NBcYbZnNt4XncrjwOJBI,4506
+utec_client/devices/lock.py,sha256=m1ExHQs_R-HzXoLA-aNVEgjUN_35mj-gJymvu5P7Vgg,3571
+utec_client/devices/sensor.py,sha256=IeTC28gZdE16kDpcrv-h8uJ4PtX79rT-IxDFjOnOKSY,212
+utec_client/devices/switch.py,sha256=9lZt3Gi8c2mn9DNQ4MZjCcqrz98f7qyIHGtHx-jioYE,1343
+utec_client-0.5.0.dist-info/licenses/LICENSE,sha256=h7k2EO0ogHiMCoUXZ7U8xj5vYWe67WQRyZnVvlVDvgw,1063
+utec_client-0.5.0.dist-info/METADATA,sha256=s2mxOKOflFUCWUiexaaMxlOfJn2d6StaOyMf9gWNg34,4089
+utec_client-0.5.0.dist-info/WHEEL,sha256=YVMoNqKzERt-wjUZwJ33xBGAwnFl-4cqbYkTtWa4itE,91
+utec_client-0.5.0.dist-info/top_level.txt,sha256=ReH0PiV5wVRG0Rn088iunoAcchcPXuVSjDTq0WRXn8Q,12
+utec_client-0.5.0.dist-info/RECORD,,

utec_client-0.5.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (84.0.0)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

utec_client-0.5.0.dist-info/licenses/LICENSE

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

utec_client-0.5.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+utec_client