pi-pm3/app/backend/websocket/notifications.py

"""Helper functions for sending WebSocket notifications."""
from .manager import ws_manager


# System Stats
async def notify_system_stats(
    cpu_percent: float,
    cpu_per_core: list,
    load_average: list,
    memory_percent: float,
    temperature: float | None
) -> None:
    """Notify clients of system stats update."""
    await ws_manager.broadcast("system_stats", {
        "cpu_percent": cpu_percent,
        "cpu_per_core": cpu_per_core,
        "load_average": load_average,
        "memory_percent": memory_percent,
        "temperature": temperature
    })


# PM3 Notifications
async def notify_pm3_status(connected: bool, message: str) -> None:
    """Notify clients of PM3 status changes."""
    await ws_manager.broadcast("pm3_status", {
        "connected": connected,
        "message": message
    })


async def notify_pm3_devices(devices: list) -> None:
    """Notify clients of PM3 device list changes (connect/disconnect)."""
    await ws_manager.broadcast("pm3_devices", {
        "devices": devices,
        "count": len(devices)
    })


async def notify_pm3_flash_progress(
    device_id: str,
    status: str,
    progress: int,
    message: str
) -> None:
    """Notify clients of PM3 firmware flash progress.

    Args:
        device_id: The device being flashed
        status: Flash status - "starting", "bootrom", "fullimage", "verifying", "complete", "error"
        progress: Progress percentage 0-100
        message: Human-readable status message
    """
    await ws_manager.broadcast("pm3_flash_progress", {
        "device_id": device_id,
        "status": status,
        "progress": progress,
        "message": message
    })


# UPS Notifications
async def notify_ups_battery(percentage: float, voltage: float) -> None:
    """Notify clients of UPS battery status."""
    await ws_manager.broadcast("ups_battery", {
        "percentage": percentage,
        "voltage": voltage
    })


async def notify_ups_warning(percentage: float, threshold: float) -> None:
    """Notify clients of low battery warning."""
    await ws_manager.broadcast("ups_warning", {
        "percentage": percentage,
        "threshold": threshold,
        "message": f"Battery low: {percentage}%"
    })


async def notify_ups_critical(percentage: float) -> None:
    """Notify clients of critical battery level."""
    await ws_manager.broadcast("ups_critical", {
        "percentage": percentage,
        "message": f"Battery critical: {percentage}%"
    })


async def notify_ups_shutdown(delay: int, percentage: float) -> None:
    """Notify clients that shutdown has been initiated."""
    await ws_manager.broadcast("ups_shutdown", {
        "delay": delay,
        "percentage": percentage,
        "message": f"Shutdown initiated due to low battery ({percentage}%)"
    })


async def notify_ups_config_required(model: str, message: str, hint: str) -> None:
    """Notify clients that UPS configuration is required."""
    await ws_manager.broadcast("ups_config_required", {
        "model": model,
        "message": message,
        "hint": hint
    })


# Update Notifications
async def notify_update_available(version: str, url: str) -> None:
    """Notify clients that an update is available."""
    await ws_manager.broadcast("update_available", {
        "version": version,
        "url": url
    })


async def notify_update_progress(progress: float, status: str) -> None:
    """Notify clients of update download progress."""
    await ws_manager.broadcast("update_downloading", {
        "progress": progress,
        "status": status
    })


async def notify_backup_complete(backup_path: str, size_bytes: int) -> None:
    """Notify clients that backup is complete."""
    await ws_manager.broadcast("backup_complete", {
        "path": backup_path,
        "size": size_bytes
    })


# Plugin Notifications
async def notify_plugin_event(
    plugin_id: str,
    event_type: str,
    data: dict
) -> None:
    """Notify clients of a plugin event.

    Plugin events are namespaced with 'plugin.{plugin_id}.{event_type}'.
    This function is called by PluginBase.broadcast_event() and should
    not be called directly by plugins.

    Args:
        plugin_id: The ID of the plugin sending the event
        event_type: Full event type (already namespaced)
        data: Event data dictionary
    """
    await ws_manager.broadcast(event_type, {
        "plugin_id": plugin_id,
        **data
    })


# Widget Notifications
async def notify_widget_added(widget_id: str, severity: str, message: str) -> None:
    """Notify clients that a header widget was added."""
    await ws_manager.broadcast("widget_added", {
        "widget_id": widget_id,
        "severity": severity,
        "message": message
    })


async def notify_widget_removed(widget_id: str) -> None:
    """Notify clients that a header widget was removed."""
    await ws_manager.broadcast("widget_removed", {
        "widget_id": widget_id
    })