voidremote 1.0.0__py3-none-any.whl

voidremote/models/device.py

@@ -0,0 +1,263 @@
+"""
+Device data models for VoidRemote.
+
+Defines strongly-typed Pydantic models for Android device representation,
+connection state, and device capabilities.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from datetime import datetime
+from enum import Enum, auto
+from typing import Optional
+
+from pydantic import BaseModel, Field, field_validator
+
+
+class DeviceState(str, Enum):
+    """Connection state of an ADB device."""
+
+    ONLINE = "online"
+    OFFLINE = "offline"
+    UNAUTHORIZED = "unauthorized"
+    CONNECTING = "connecting"
+    PAIRING = "pairing"
+    DISCONNECTED = "disconnected"
+    UNKNOWN = "unknown"
+
+
+class ConnectionType(str, Enum):
+    """How the device is connected."""
+
+    USB = "usb"
+    WIRELESS = "wireless"
+    EMULATOR = "emulator"
+
+
+class DeviceCapability(str, Enum):
+    """Optional capabilities a device may support."""
+
+    SCREEN_MIRROR = "screen_mirror"
+    FILE_TRANSFER = "file_transfer"
+    SHELL = "shell"
+    INPUT_CONTROL = "input_control"
+    PACKAGE_MANAGER = "package_manager"
+    MONITORING = "monitoring"
+
+
+class BatteryInfo(BaseModel):
+    """Battery status information."""
+
+    level: int = Field(default=0, ge=0, le=100, description="Battery percentage 0-100")
+    is_charging: bool = Field(default=False)
+    is_ac_powered: bool = Field(default=False)
+    is_usb_powered: bool = Field(default=False)
+    voltage: float = Field(default=0.0, description="Voltage in mV")
+    temperature: float = Field(default=0.0, description="Temperature in tenths of degree Celsius")
+    health: str = Field(default="unknown")
+    technology: str = Field(default="unknown")
+
+    @property
+    def temperature_celsius(self) -> float:
+        """Return temperature in Celsius."""
+        return self.temperature / 10.0
+
+    @property
+    def voltage_volts(self) -> float:
+        """Return voltage in Volts."""
+        return self.voltage / 1000.0
+
+
+class StorageInfo(BaseModel):
+    """Storage usage information."""
+
+    total_bytes: int = Field(default=0, ge=0)
+    available_bytes: int = Field(default=0, ge=0)
+    used_bytes: int = Field(default=0, ge=0)
+    mount_point: str = Field(default="/data")
+
+    @property
+    def total_gb(self) -> float:
+        return self.total_bytes / (1024**3)
+
+    @property
+    def available_gb(self) -> float:
+        return self.available_bytes / (1024**3)
+
+    @property
+    def used_gb(self) -> float:
+        return self.used_bytes / (1024**3)
+
+    @property
+    def usage_percent(self) -> float:
+        if self.total_bytes == 0:
+            return 0.0
+        return (self.used_bytes / self.total_bytes) * 100.0
+
+
+class CpuInfo(BaseModel):
+    """CPU information."""
+
+    abi: str = Field(default="unknown", description="CPU ABI (e.g. arm64-v8a)")
+    abi_list: list[str] = Field(default_factory=list)
+    cores: int = Field(default=0, ge=0)
+    governor: str = Field(default="unknown")
+    usage_percent: float = Field(default=0.0, ge=0.0, le=100.0)
+    frequency_mhz: float = Field(default=0.0, ge=0.0)
+
+
+class NetworkInfo(BaseModel):
+    """Network connection information."""
+
+    ip_address: str = Field(default="")
+    wifi_ssid: str = Field(default="")
+    wifi_signal: int = Field(default=0, description="WiFi signal strength in dBm")
+    mac_address: str = Field(default="")
+    interface: str = Field(default="wlan0")
+
+
+class DeviceInfo(BaseModel):
+    """Complete device information."""
+
+    serial: str = Field(description="ADB serial identifier")
+    model: str = Field(default="Unknown")
+    manufacturer: str = Field(default="Unknown")
+    brand: str = Field(default="Unknown")
+    product: str = Field(default="Unknown")
+    device_name: str = Field(default="Unknown")
+    android_version: str = Field(default="Unknown")
+    sdk_version: int = Field(default=0)
+    build_id: str = Field(default="Unknown")
+    build_fingerprint: str = Field(default="")
+    screen_width: int = Field(default=0, ge=0)
+    screen_height: int = Field(default=0, ge=0)
+    screen_density: int = Field(default=0, ge=0, description="DPI")
+    battery: BatteryInfo = Field(default_factory=BatteryInfo)
+    storage: StorageInfo = Field(default_factory=StorageInfo)
+    cpu: CpuInfo = Field(default_factory=CpuInfo)
+    network: NetworkInfo = Field(default_factory=NetworkInfo)
+    ram_total_bytes: int = Field(default=0, ge=0)
+    ram_available_bytes: int = Field(default=0, ge=0)
+    features: list[str] = Field(default_factory=list)
+
+    @field_validator("serial")
+    @classmethod
+    def validate_serial(cls, v: str) -> str:
+        """Ensure serial is not empty."""
+        if not v.strip():
+            raise ValueError("Device serial cannot be empty")
+        return v.strip()
+
+    @property
+    def display_name(self) -> str:
+        """Human-readable device name."""
+        if self.model and self.model != "Unknown":
+            return f"{self.manufacturer} {self.model}".strip()
+        return self.serial
+
+    @property
+    def screen_resolution(self) -> str:
+        """Screen resolution as string."""
+        if self.screen_width and self.screen_height:
+            return f"{self.screen_width}x{self.screen_height}"
+        return "Unknown"
+
+    @property
+    def ram_total_gb(self) -> float:
+        return self.ram_total_bytes / (1024**3)
+
+    @property
+    def ram_available_gb(self) -> float:
+        return self.ram_available_bytes / (1024**3)
+
+
+class Device(BaseModel):
+    """A connected ADB device with full state."""
+
+    info: DeviceInfo
+    state: DeviceState = Field(default=DeviceState.UNKNOWN)
+    connection_type: ConnectionType = Field(default=ConnectionType.USB)
+    host: str = Field(default="")
+    port: int = Field(default=5555, ge=1, le=65535)
+    is_trusted: bool = Field(default=False)
+    connected_at: Optional[datetime] = Field(default=None)
+    last_seen: Optional[datetime] = Field(default=None)
+    capabilities: list[DeviceCapability] = Field(default_factory=list)
+    tags: list[str] = Field(default_factory=list)
+    alias: Optional[str] = Field(default=None)
+
+    @property
+    def serial(self) -> str:
+        return self.info.serial
+
+    @property
+    def display_name(self) -> str:
+        return self.alias or self.info.display_name
+
+    @property
+    def is_connected(self) -> bool:
+        return self.state == DeviceState.ONLINE
+
+    @property
+    def adb_address(self) -> str:
+        """Return ADB network address for wireless devices."""
+        if self.connection_type == ConnectionType.WIRELESS and self.host:
+            return f"{self.host}:{self.port}"
+        return self.serial
+
+    def has_capability(self, cap: DeviceCapability) -> bool:
+        """Check if device supports a capability."""
+        return cap in self.capabilities
+
+    class Config:
+        use_enum_values = False
+
+
+@dataclass
+class PairingInfo:
+    """Information needed to pair a device over wireless debugging."""
+
+    host: str
+    port: int
+    pairing_code: str
+    timeout: float = 30.0
+
+    def __post_init__(self) -> None:
+        if not self.host:
+            raise ValueError("Host cannot be empty")
+        if not (1 <= self.port <= 65535):
+            raise ValueError(f"Invalid port: {self.port}")
+        if not self.pairing_code:
+            raise ValueError("Pairing code cannot be empty")
+
+
+@dataclass
+class ConnectionConfig:
+    """Configuration for an ADB connection."""
+
+    host: str
+    port: int = 5555
+    timeout: float = 10.0
+    retry_count: int = 3
+    retry_delay: float = 1.0
+    keep_alive: bool = True
+
+    def __post_init__(self) -> None:
+        if not self.host:
+            raise ValueError("Host cannot be empty")
+        if not (1 <= self.port <= 65535):
+            raise ValueError(f"Invalid port: {self.port}")
+
+
+@dataclass
+class TrustedDevice:
+    """A remembered/trusted device for auto-reconnect."""
+
+    serial: str
+    host: str
+    port: int
+    alias: Optional[str] = None
+    last_connected: Optional[datetime] = None
+    auto_connect: bool = True
+    tags: list[str] = field(default_factory=list)

voidremote/network/__init__.py

@@ -0,0 +1 @@
+"""VoidRemote network utilities."""

voidremote/network/discovery.py

@@ -0,0 +1,116 @@
+"""
+Network device discovery utilities.
+
+Scans the local subnet for Android devices with ADB enabled
+using TCP port scanning on common ADB ports.
+"""
+
+from __future__ import annotations
+
+import ipaddress
+import logging
+import socket
+import threading
+from typing import Callable, Optional
+
+logger = logging.getLogger(__name__)
+
+ADB_PORTS = [5555, 5556, 5557, 5558, 5559]
+DEFAULT_TIMEOUT = 0.5
+
+
+def _check_port(host: str, port: int, timeout: float = DEFAULT_TIMEOUT) -> bool:
+    """Return True if TCP port is open on host."""
+    try:
+        with socket.create_connection((host, port), timeout=timeout):
+            return True
+    except (OSError, ConnectionRefusedError, TimeoutError):
+        return False
+
+
+def scan_host(host: str, ports: list[int] = ADB_PORTS) -> list[tuple[str, int]]:
+    """
+    Scan a single host for open ADB ports.
+
+    Returns:
+        List of (host, port) tuples where ADB appears to be listening.
+    """
+    results: list[tuple[str, int]] = []
+    for port in ports:
+        if _check_port(host, port):
+            results.append((host, port))
+    return results
+
+
+def scan_subnet(
+    subnet: str,
+    ports: list[int] = ADB_PORTS,
+    timeout: float = DEFAULT_TIMEOUT,
+    max_workers: int = 64,
+    on_found: Optional[Callable[[str, int], None]] = None,
+    on_progress: Optional[Callable[[int, int], None]] = None,
+) -> list[tuple[str, int]]:
+    """
+    Scan an entire subnet for ADB devices.
+
+    Args:
+        subnet: CIDR notation subnet (e.g. "192.168.1.0/24").
+        ports: List of ports to check.
+        timeout: Per-connection timeout in seconds.
+        max_workers: Maximum concurrent scan threads.
+        on_found: Optional callback called when a device is discovered.
+        on_progress: Optional callback(scanned, total) for progress.
+
+    Returns:
+        List of (host, port) tuples with open ADB ports.
+    """
+    try:
+        network = ipaddress.ip_network(subnet, strict=False)
+    except ValueError as exc:
+        raise ValueError(f"Invalid subnet: {subnet!r}") from exc
+
+    hosts = list(network.hosts())
+    total = len(hosts)
+    results: list[tuple[str, int]] = []
+    scanned = 0
+    lock = threading.Lock()
+    semaphore = threading.Semaphore(max_workers)
+
+    def scan_one(host: str) -> None:
+        nonlocal scanned
+        with semaphore:
+            found = scan_host(host, ports)
+            with lock:
+                scanned += 1
+                results.extend(found)
+                if on_found and found:
+                    for h, p in found:
+                        on_found(h, p)
+                if on_progress:
+                    on_progress(scanned, total)
+
+    threads = [threading.Thread(target=scan_one, args=(str(h),), daemon=True) for h in hosts]
+    for t in threads:
+        t.start()
+    for t in threads:
+        t.join()
+
+    logger.info("Subnet scan %s complete: %d hosts scanned, %d found", subnet, total, len(results))
+    return results
+
+
+def get_local_subnet() -> Optional[str]:
+    """
+    Attempt to determine the local network subnet.
+
+    Returns:
+        CIDR string like "192.168.1.0/24", or None if not determinable.
+    """
+    try:
+        with socket.socket(socket.AF_INET, socket.SOCK_DGRAM) as s:
+            s.connect(("8.8.8.8", 80))
+            local_ip = s.getsockname()[0]
+        parts = local_ip.split(".")
+        return f"{parts[0]}.{parts[1]}.{parts[2]}.0/24"
+    except Exception:
+        return None

voidremote/services/__init__.py

@@ -0,0 +1,13 @@
+"""VoidRemote service layer."""
+
+from voidremote.services.device_service import DeviceService
+from voidremote.services.input_service import InputService, KeyCode
+from voidremote.services.monitor_service import DeviceSnapshot, MonitorService
+
+__all__ = [
+    "DeviceService",
+    "DeviceSnapshot",
+    "InputService",
+    "KeyCode",
+    "MonitorService",
+]