lifx-emulator 1.0.2__py3-none-any.whl → 2.1.0__py3-none-any.whl

lifx_emulator/__init__.py

@@ -6,7 +6,7 @@ Implements the binary UDP protocol documented at https://lan.developer.lifx.com
 
 from importlib.metadata import version as get_version
 
-from lifx_emulator.device import EmulatedLifxDevice
+from lifx_emulator.devices import EmulatedLifxDevice
 from lifx_emulator.factories import (
     create_color_light,
     create_color_temperature_light,

lifx_emulator/__main__.py

@@ -8,8 +8,12 @@ from typing import Annotated
 import cyclopts
 from rich.logging import RichHandler
 
-from lifx_emulator.async_storage import AsyncDeviceStorage
 from lifx_emulator.constants import LIFX_UDP_PORT
+from lifx_emulator.devices import (
+    DEFAULT_STORAGE_DIR,
+    DeviceManager,
+    DevicePersistenceAsyncFile,
+)
 from lifx_emulator.factories import (
     create_color_light,
     create_color_temperature_light,
@@ -19,7 +23,9 @@ from lifx_emulator.factories import (
     create_multizone_light,
     create_tile_device,
 )
-from lifx_emulator.products.registry import ProductInfo, get_registry
+from lifx_emulator.products.registry import get_registry
+from lifx_emulator.repositories import DeviceRepository
+from lifx_emulator.scenarios import ScenarioPersistenceAsyncFile
 from lifx_emulator.server import EmulatedLifxServer
 
 app = cyclopts.App(
@@ -78,49 +84,6 @@ def _format_capabilities(device) -> str:
     return ", ".join(capabilities)
 
 
-def _format_product_capabilities(product: ProductInfo) -> str:
-    """Format product capabilities as a human-readable string."""
-    caps = []
-
-    # Determine base light type
-    if product.has_relays:
-        # Devices with relays are switches, not lights
-        caps.append("switch")
-    elif product.has_color:
-        caps.append("full color")
-    else:
-        # Check temperature range to determine white light type
-        if product.temperature_range:
-            if product.temperature_range.min != product.temperature_range.max:
-                caps.append("color temperature")
-            else:
-                caps.append("brightness only")
-        else:
-            # No temperature range info, assume basic brightness
-            caps.append("brightness only")
-
-    # Add additional capabilities
-    if product.has_infrared:
-        caps.append("infrared")
-    # Extended multizone is backwards compatible with multizone,
-    # so only show multizone if extended multizone is not present
-    if product.has_extended_multizone:
-        caps.append("extended-multizone")
-    elif product.has_multizone:
-        caps.append("multizone")
-    if product.has_matrix:
-        caps.append("matrix")
-    if product.has_hev:
-        caps.append("HEV")
-    if product.has_chain:
-        caps.append("chain")
-    if product.has_buttons and not product.has_relays:
-        # Only show buttons if not already identified as switch
-        caps.append("buttons")
-
-    return ", ".join(caps) if caps else "unknown"
-
-
 @app.command
 def list_products(
     filter_type: str | None = None,
@@ -177,8 +140,7 @@ def list_products(
     print("─" * 4 + "─┼─" + "─" * 40 + "─┼─" + "─" * 40)
 
     for product in all_products:
-        caps = _format_product_capabilities(product)
-        print(f"{product.pid:>4} │ {product.name:<40} │ {caps}")
+        print(f"{product.pid:>4} │ {product.name:<40} │ {product.caps}")
 
     print()
     print("Use --product <PID> to emulate a specific product")
@@ -213,13 +175,11 @@ def clear_storage(
     """
     from pathlib import Path
 
-    from lifx_emulator.async_storage import DEFAULT_STORAGE_DIR, AsyncDeviceStorage
-
     # Use default storage directory if not specified
     storage_path = Path(storage_dir) if storage_dir else DEFAULT_STORAGE_DIR
 
     # Create storage instance
-    storage = AsyncDeviceStorage(storage_path)
+    storage = DevicePersistenceAsyncFile(storage_path)
 
     # List devices
     devices = storage.list_devices()
@@ -369,7 +329,7 @@ async def run(
         return False
 
     # Initialize storage if persistence is enabled
-    storage = AsyncDeviceStorage() if persistent else None
+    storage = DevicePersistenceAsyncFile() if persistent else None
     if persistent and storage:
         logger.info("Persistent storage enabled at %s", storage.storage_dir)
 
@@ -531,14 +491,29 @@ async def run(
         caps = _format_capabilities(device)
         logger.info("  • %s (%s) - %s", label, serial, caps)
 
+    # Create device manager with repository
+    device_repository = DeviceRepository()
+    device_manager = DeviceManager(device_repository)
+
+    # Load scenarios from storage if persistence is enabled
+    scenario_manager = None
+    scenario_storage = None
+    if persistent_scenarios:
+        scenario_storage = ScenarioPersistenceAsyncFile()
+        scenario_manager = await scenario_storage.load()
+        logger.info("Loaded scenarios from persistent storage")
+
     # Start LIFX server
     server = EmulatedLifxServer(
         devices,
+        device_manager,
         bind,
         port,
         track_activity=api_activity if api else False,
         storage=storage,
+        scenario_manager=scenario_manager,
         persist_scenarios=persistent_scenarios,
+        scenario_storage=scenario_storage,
     )
     await server.start()
 

lifx_emulator/api/__init__.py

@@ -0,0 +1,18 @@
+"""FastAPI-based management API for LIFX emulator.
+
+This package provides a comprehensive REST API for managing the LIFX emulator:
+- Monitoring server statistics and activity
+- Creating, listing, and deleting devices
+- Managing test scenarios for protocol testing
+
+The API is built with FastAPI and organized into routers for clean separation
+of concerns.
+"""
+
+# Import from new refactored structure
+from lifx_emulator.api.app import create_api_app, run_api_server
+
+# Note: HTML_UI remains in the old lifx_emulator/api.py file temporarily
+# TODO: Phase 1.1d - extract HTML template to separate file
+
+__all__ = ["create_api_app", "run_api_server"]

lifx_emulator/api/app.py

@@ -0,0 +1,154 @@
+"""FastAPI application factory for LIFX emulator management API.
+
+This module creates the main FastAPI application by assembling routers for:
+- Monitoring (server stats, activity)
+- Devices (CRUD operations)
+- Scenarios (test scenario management)
+"""
+
+from __future__ import annotations
+
+import logging
+from pathlib import Path
+from typing import TYPE_CHECKING
+
+from fastapi import FastAPI, Request
+from fastapi.responses import HTMLResponse
+from fastapi.templating import Jinja2Templates
+
+if TYPE_CHECKING:
+    from lifx_emulator.server import EmulatedLifxServer
+
+from lifx_emulator.api.routers.devices import create_devices_router
+from lifx_emulator.api.routers.monitoring import create_monitoring_router
+from lifx_emulator.api.routers.scenarios import create_scenarios_router
+
+logger = logging.getLogger(__name__)
+
+# Template directory for web UI
+TEMPLATES_DIR = Path(__file__).parent / "templates"
+templates = Jinja2Templates(directory=str(TEMPLATES_DIR))
+
+
+def create_api_app(server: EmulatedLifxServer) -> FastAPI:
+    """Create FastAPI application for emulator management.
+
+    This factory function assembles the complete API by:
+    1. Creating the FastAPI app with metadata
+    2. Including routers for monitoring, devices, and scenarios
+    3. Serving the embedded web UI at the root endpoint
+
+    Args:
+        server: The LIFX emulator server instance
+
+    Returns:
+        Configured FastAPI application
+
+    Example:
+        >>> from lifx_emulator.server import EmulatedLifxServer
+        >>> server = EmulatedLifxServer(bind="127.0.0.1", port=56700)
+        >>> app = create_api_app(server)
+        >>> # Run with: uvicorn app:app --host 127.0.0.1 --port 8080
+    """
+    app = FastAPI(
+        title="LIFX Emulator API",
+        description="""
+Runtime management and monitoring API for LIFX device emulator.
+
+This API provides read-only monitoring of the emulator state and device management
+capabilities (add/remove devices). Device state changes must be performed via the
+LIFX LAN protocol.
+
+## Features
+- Real-time server statistics and packet monitoring
+- Device inspection and management
+- Test scenario management for protocol testing
+- Recent activity tracking
+- OpenAPI 3.1.0 compliant schema
+
+## Architecture
+The API is organized into three main routers:
+- **Monitoring**: Server stats and activity logs
+- **Devices**: Device CRUD operations
+- **Scenarios**: Test scenario configuration
+        """,
+        version="1.0.0",
+        contact={
+            "name": "LIFX Emulator",
+            "url": "https://github.com/Djelibeybi/lifx-emulator",
+        },
+        license_info={
+            "name": "UPL-1.0",
+            "url": "https://opensource.org/licenses/UPL",
+        },
+        openapi_tags=[
+            {
+                "name": "monitoring",
+                "description": "Server statistics and activity monitoring",
+            },
+            {
+                "name": "devices",
+                "description": "Device management and inspection",
+            },
+            {
+                "name": "scenarios",
+                "description": "Test scenario management",
+            },
+        ],
+    )
+
+    @app.get("/", response_class=HTMLResponse, include_in_schema=False)
+    async def root(request: Request):
+        """Serve embedded web UI dashboard."""
+        return templates.TemplateResponse(request, "dashboard.html")
+
+    # Include routers with server dependency injection
+    monitoring_router = create_monitoring_router(server)
+    devices_router = create_devices_router(server)
+    scenarios_router = create_scenarios_router(server)
+
+    app.include_router(monitoring_router)
+    app.include_router(devices_router)
+    app.include_router(scenarios_router)
+
+    logger.info(
+        "API application created with 3 routers (monitoring, devices, scenarios)"
+    )
+
+    return app
+
+
+async def run_api_server(
+    server: EmulatedLifxServer, host: str = "127.0.0.1", port: int = 8080
+):
+    """Run the FastAPI server with uvicorn.
+
+    Args:
+        server: The LIFX emulator server instance
+        host: Host to bind to (default: 127.0.0.1)
+        port: Port to bind to (default: 8080)
+
+    Example:
+        >>> import asyncio
+        >>> from lifx_emulator.server import EmulatedLifxServer
+        >>> server = EmulatedLifxServer(bind="127.0.0.1", port=56700)
+        >>> asyncio.run(run_api_server(server, host="0.0.0.0", port=8080))
+    """
+    import uvicorn
+
+    app = create_api_app(server)
+
+    config = uvicorn.Config(
+        app,
+        host=host,
+        port=port,
+        log_level="info",
+        access_log=True,
+    )
+    api_server = uvicorn.Server(config)
+
+    logger.info("Starting API server on http://%s:%s", host, port)
+    logger.info("OpenAPI docs available at http://%s:%s/docs", host, port)
+    logger.info("ReDoc docs available at http://%s:%s/redoc", host, port)
+
+    await api_server.serve()

lifx_emulator/api/mappers/__init__.py

@@ -0,0 +1,5 @@
+"""Mappers for converting domain models to API models."""
+
+from lifx_emulator.api.mappers.device_mapper import DeviceMapper
+
+__all__ = ["DeviceMapper"]

lifx_emulator/api/mappers/device_mapper.py

@@ -0,0 +1,114 @@
+"""Mapper for converting EmulatedLifxDevice to DeviceInfo API model."""
+
+from __future__ import annotations
+
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from lifx_emulator.devices import EmulatedLifxDevice
+
+from lifx_emulator.api.models import ColorHsbk, DeviceInfo
+
+
+class DeviceMapper:
+    """Maps domain device models to API response models.
+
+    This mapper eliminates duplication across multiple API endpoints by
+    providing a single, consistent way to convert device state to API responses.
+
+    **Eliminates**: 150+ lines of duplicated code across list_devices(),
+    get_device(), and create_device() endpoints.
+    """
+
+    @staticmethod
+    def to_device_info(device: EmulatedLifxDevice) -> DeviceInfo:
+        """Convert an EmulatedLifxDevice to a DeviceInfo API model.
+
+        Args:
+            device: The emulated LIFX device to convert
+
+        Returns:
+            DeviceInfo model ready for API response
+
+        Example:
+            >>> device = create_color_light(serial="d073d5000001")
+            >>> info = DeviceMapper.to_device_info(device)
+            >>> info.serial
+            'd073d5000001'
+        """
+        return DeviceInfo(
+            # Core identification
+            serial=device.state.serial,
+            label=device.state.label,
+            product=device.state.product,
+            vendor=device.state.vendor,
+            # Power state
+            power_level=device.state.power_level,
+            # Capability flags
+            has_color=device.state.has_color,
+            has_infrared=device.state.has_infrared,
+            has_multizone=device.state.has_multizone,
+            has_extended_multizone=device.state.has_extended_multizone,
+            has_matrix=device.state.has_matrix,
+            has_hev=device.state.has_hev,
+            # Zone/tile counts
+            zone_count=device.state.multizone.zone_count
+            if device.state.multizone is not None
+            else 0,
+            tile_count=device.state.matrix.tile_count
+            if device.state.matrix is not None
+            else 0,
+            # Color state (if applicable)
+            color=ColorHsbk(
+                hue=device.state.color.hue,
+                saturation=device.state.color.saturation,
+                brightness=device.state.color.brightness,
+                kelvin=device.state.color.kelvin,
+            )
+            if device.state.has_color
+            else None,
+            # Multizone colors (if applicable)
+            zone_colors=[
+                ColorHsbk(
+                    hue=c.hue,
+                    saturation=c.saturation,
+                    brightness=c.brightness,
+                    kelvin=c.kelvin,
+                )
+                for c in device.state.multizone.zone_colors
+            ]
+            if device.state.multizone is not None
+            else [],
+            # Matrix/tile devices (if applicable)
+            tile_devices=device.state.matrix.tile_devices
+            if device.state.matrix is not None
+            else [],
+            # Firmware/version metadata
+            version_major=device.state.version_major,
+            version_minor=device.state.version_minor,
+            build_timestamp=device.state.build_timestamp,
+            # Location/group metadata
+            group_label=device.state.group.group_label,
+            location_label=device.state.location.location_label,
+            # Runtime metadata
+            uptime_ns=device.state.uptime_ns,
+            wifi_signal=device.state.wifi_signal,
+        )
+
+    @staticmethod
+    def to_device_info_list(devices: list[EmulatedLifxDevice]) -> list[DeviceInfo]:
+        """Convert a list of EmulatedLifxDevice to DeviceInfo API models.
+
+        Args:
+            devices: List of emulated LIFX devices to convert
+
+        Returns:
+            List of DeviceInfo models ready for API response
+
+        Example:
+            >>> devices = [create_color_light(), create_multizone_light()]
+            >>> info_list = DeviceMapper.to_device_info_list(devices)
+            >>> len(info_list)
+            2
+        """
+        return [DeviceMapper.to_device_info(device) for device in devices]

lifx_emulator/api/models.py

@@ -0,0 +1,133 @@
+"""Pydantic models for API requests and responses."""
+
+from pydantic import BaseModel, Field, field_validator
+
+# Import shared domain models
+from lifx_emulator.scenarios import ScenarioConfig
+
+
+class DeviceCreateRequest(BaseModel):
+    """Request to create a new device."""
+
+    product_id: int = Field(
+        ..., description="Product ID from LIFX registry", gt=0, lt=10000
+    )
+    serial: str | None = Field(
+        None,
+        description="Optional serial (auto-generated if not provided)",
+        min_length=12,
+        max_length=12,
+    )
+    zone_count: int | None = Field(
+        None, description="Number of zones for multizone devices", ge=0, le=1000
+    )
+    tile_count: int | None = Field(
+        None, description="Number of tiles for matrix devices", ge=0, le=100
+    )
+    tile_width: int | None = Field(
+        None, description="Width of each tile in pixels", ge=1, le=256
+    )
+    tile_height: int | None = Field(
+        None, description="Height of each tile in pixels", ge=1, le=256
+    )
+    firmware_major: int | None = Field(
+        None, description="Firmware major version", ge=0, le=255
+    )
+    firmware_minor: int | None = Field(
+        None, description="Firmware minor version", ge=0, le=255
+    )
+
+    @field_validator("serial")
+    @classmethod
+    def validate_serial_format(cls, v: str | None) -> str | None:
+        """Validate serial number format (12 hex characters)."""
+        if v is None:
+            return v
+        if len(v) != 12:
+            raise ValueError("Serial must be exactly 12 characters")
+        try:
+            # Validate it's valid hexadecimal by parsing as base-16 integer
+            int(v, 16)
+        except ValueError as e:
+            raise ValueError("Serial must be valid hexadecimal (0-9, a-f, A-F)") from e
+        return v.lower()  # Normalize to lowercase
+
+
+class ColorHsbk(BaseModel):
+    """HSBK color representation."""
+
+    hue: int = Field(..., ge=0, le=65535, description="Hue (0-65535)")
+    saturation: int = Field(..., ge=0, le=65535, description="Saturation (0-65535)")
+    brightness: int = Field(..., ge=0, le=65535, description="Brightness (0-65535)")
+    kelvin: int = Field(
+        ..., ge=1500, le=9000, description="Color temperature in Kelvin (1500-9000)"
+    )
+
+
+class DeviceInfo(BaseModel):
+    """Device information response."""
+
+    serial: str
+    label: str
+    product: int
+    vendor: int
+    power_level: int
+    has_color: bool
+    has_infrared: bool
+    has_multizone: bool
+    has_extended_multizone: bool
+    has_matrix: bool
+    has_hev: bool
+    zone_count: int
+    tile_count: int
+    color: ColorHsbk | None = None
+    zone_colors: list[ColorHsbk] = Field(default_factory=list)
+    tile_devices: list[dict] = Field(default_factory=list)
+    # Metadata fields
+    version_major: int = 0
+    version_minor: int = 0
+    build_timestamp: int = 0
+    group_label: str = ""
+    location_label: str = ""
+    uptime_ns: int = 0
+    wifi_signal: float = 0.0
+
+
+class ServerStats(BaseModel):
+    """Server statistics response."""
+
+    uptime_seconds: float
+    start_time: float
+    device_count: int
+    packets_received: int
+    packets_sent: int
+    packets_received_by_type: dict[int, int]
+    packets_sent_by_type: dict[int, int]
+    error_count: int
+    activity_enabled: bool
+
+
+class ActivityEvent(BaseModel):
+    """Recent activity event."""
+
+    timestamp: float
+    direction: str
+    packet_type: int
+    packet_name: str
+    device: str | None = None
+    target: str | None = None
+    addr: str
+
+
+class ScenarioResponse(BaseModel):
+    """Response model for scenario operations."""
+
+    scope: str = Field(
+        ..., description="Scope of the scenario (global, device, type, location, group)"
+    )
+    identifier: str | None = Field(
+        None, description="Identifier for the scope (serial, type name, etc.)"
+    )
+    scenario: ScenarioConfig | None = Field(
+        None, description="The scenario configuration (None if not set)"
+    )

lifx_emulator/api/routers/__init__.py

@@ -0,0 +1,11 @@
+"""API routers for LIFX emulator endpoints."""
+
+from lifx_emulator.api.routers.devices import create_devices_router
+from lifx_emulator.api.routers.monitoring import create_monitoring_router
+from lifx_emulator.api.routers.scenarios import create_scenarios_router
+
+__all__ = [
+    "create_monitoring_router",
+    "create_devices_router",
+    "create_scenarios_router",
+]