dosync 0.4.1__py3-none-any.whl

dosync/executor.py

@@ -0,0 +1,97 @@
+"""
+DoSync — Device Executor
+Abstracts the actual sending of actions to physical devices.
+Provides a SimulatedExecutor for testing without hardware.
+"""
+
+from __future__ import annotations
+import asyncio
+import logging
+import random
+from abc import ABC, abstractmethod
+from typing import Any
+
+from .models import ActionResult, DeviceAction, Urgency
+
+log = logging.getLogger("dosync.executor")
+
+
+class DeviceExecutor(ABC):
+    """
+    Abstract executor. In production, subclass this for each transport:
+    WiFiExecutor, BLEExecutor, ZigbeeExecutor, etc.
+    """
+
+    @abstractmethod
+    async def execute(self, action: DeviceAction, urgency: Urgency) -> ActionResult:
+        ...
+
+
+class SimulatedExecutor(DeviceExecutor):
+    """
+    Simulates device responses for development and certification testing.
+    Each device_id can be configured with custom behaviors.
+    """
+
+    def __init__(self, failure_rate: float = 0.0):
+        """
+        Args:
+            failure_rate: probability [0.0–1.0] that a device randomly fails.
+                          Use 0.1 to simulate a 10% hardware failure rate.
+        """
+        self.failure_rate = failure_rate
+        self._custom: dict[str, Any] = {}
+
+    def set_device_behavior(self, device_id: str, always_fail: bool = False,
+                             latency_ms: int = 50) -> None:
+        self._custom[device_id] = {"always_fail": always_fail, "latency_ms": latency_ms}
+
+    async def execute(self, action: DeviceAction, urgency: Urgency) -> ActionResult:
+        behavior = self._custom.get(action.device_id, {})
+        latency  = behavior.get("latency_ms", 50) / 1000
+        await asyncio.sleep(latency)
+
+        if behavior.get("always_fail") or random.random() < self.failure_rate:
+            log.warning("Simulated failure: %s / %s", action.device_id, action.action)
+            return ActionResult(
+                device_id=action.device_id,
+                action=action.action,
+                success=False,
+                error="Simulated device failure",
+            )
+
+        response = self._simulate_response(action, urgency)
+        log.info("Executed: %s.%s → %s", action.device_id, action.action, response)
+
+        return ActionResult(
+            device_id=action.device_id,
+            action=action.action,
+            success=True,
+            response=response,
+        )
+
+    def _simulate_response(self, action: DeviceAction, urgency: Urgency) -> dict:
+        responses = {
+            # Seguridad
+            "unlock":          {"status": "unlocked", "duration_seconds": action.params.get("duration_seconds", 300)},
+            "lock":            {"status": "locked"},
+            "call":            {"status": "calling", "number": action.params.get("number", "911")},
+            "alarm":           {"status": "activated", "pattern": action.params.get("pattern", "alert")},
+            "arm":             {"status": "armed", "mode": action.params.get("mode", "away")},
+            # Notificaciones
+            "notify":          {"status": "sent", "channels": ["push", "sms"]},
+            "display":         {"status": "shown", "message": action.params.get("message", "")},
+            # Iluminacion
+            "light":           {"status": "on", "brightness": action.params.get("brightness", 100)},
+            "set_brightness":  {"status": "set", "brightness": action.params.get("brightness", 0)},
+            # Clima
+            "set_temperature": {"status": "set", "celsius": action.params.get("celsius", 21)},
+            "set_position":    {"status": "set", "position": action.params.get("position", 0)},
+            # Energia
+            "turn_off":        {"status": "off", "device": action.device_id},
+            "turn_on":         {"status": "on",  "device": action.device_id},
+            # Sensores
+            "read_sensors":    {"readings": {sid: round(random.uniform(15, 25), 1)
+                                             for sid in action.params.get("sensor_ids", [])}},
+        }
+        return responses.get(action.action, {"status": "ok"})

dosync/geo.py

@@ -0,0 +1,63 @@
+"""
+DoSync — shared geospatial helpers.
+===================================
+
+The single source of truth for the geofence math. Before this module the
+haversine formula was copied in three places (the GeofencePolicy, the MAVLink
+listener's waypoint-arrival check, and the RouteComposer). The expert panel flagged
+that as the one real trap: two defenses in two moments (admission + in-flight
+monitoring) are GOOD, but the same FORMULA living in several copies is a latent bug —
+fix it in one place and the others drift. So the rule lives here, once, and every
+caller invokes it.
+
+Pure functions, no dependencies beyond the stdlib, fully unit-testable.
+"""
+
+from __future__ import annotations
+
+import math
+
+# Mean Earth radius in meters. One constant, shared by every distance calculation.
+EARTH_RADIUS_M = 6371000.0
+
+
+def haversine_m(lat1: float, lon1: float, lat2: float, lon2: float) -> float:
+    """Great-circle distance between two lat/lon points, in meters.
+
+    The canonical distance function for DoSync. Accurate to well within a meter at
+    the scales the protocol cares about (perimeters of a few km).
+    """
+    p1, p2 = math.radians(lat1), math.radians(lat2)
+    dp = math.radians(lat2 - lat1)
+    dl = math.radians(lon2 - lon1)
+    a = (math.sin(dp / 2) ** 2
+         + math.cos(p1) * math.cos(p2) * math.sin(dl / 2) ** 2)
+    return EARTH_RADIUS_M * 2 * math.asin(math.sqrt(a))
+
+
+def is_within_perimeter(lat: float, lon: float,
+                        center_lat: float, center_lon: float,
+                        max_radius_m: float,
+                        alt: float | None = None,
+                        max_altitude_m: float | None = None) -> tuple[bool, str]:
+    """Is a point inside the permitted perimeter (a horizontal circle plus an
+    optional altitude ceiling)?
+
+    Returns (ok, reason). When ok is False, reason explains the breach in
+    human-readable terms — the same wording the GeofencePolicy (admission) and the
+    in-flight geofence guard (monitoring) both surface, so a breach reads identically
+    whether it was caught before takeoff or during flight.
+
+    This is the shared rule. The two callers differ only in WHEN they call it and on
+    WHICH point: the policy checks a go_to's *target* before dispatch; the guard
+    checks the vehicle's *reported position* during flight. Same rule, two moments.
+    """
+    distance = haversine_m(center_lat, center_lon, lat, lon)
+    if distance > max_radius_m:
+        return (False,
+                f"({lat:.5f}, {lon:.5f}) is {distance:.0f}m from center — "
+                f"outside the {max_radius_m:.0f}m geofence.")
+    if max_altitude_m is not None and alt is not None and alt > max_altitude_m:
+        return (False,
+                f"altitude {alt:.0f}m exceeds the ceiling of {max_altitude_m:.0f}m.")
+    return (True, "")