Skip to content

Self-hosted homelab infrastructure visualizer — interactive network diagram with live status monitoring

5.1 KB
Raw Blame
"""Pydantic v2 schemas for Zigbee2MQTT import."""

from pydantic import BaseModel, Field, model_validator


class ZigbeeImportRequest(BaseModel):
    mqtt_host: str = Field(..., description="MQTT broker hostname or IP address")
    mqtt_port: int = Field(1883, ge=1, le=65535, description="MQTT broker port")
    mqtt_username: str | None = Field(None, description="MQTT username (optional)")
    mqtt_password: str | None = Field(None, description="MQTT password (optional)")
    base_topic: str = Field("zigbee2mqtt", description="Zigbee2MQTT base topic")
    mqtt_tls: bool = Field(False, description="Enable TLS (typically port 8883)")
    mqtt_tls_insecure: bool = Field(
        False, description="Skip TLS certificate verification (self-signed only)"
    )
    include_mesh_links: bool = Field(
        False,
        description=(
            "Also import neighbour-to-neighbour mesh links, not just the "
            "parent tree. Off by default: it turns a ~36-edge map into ~115 "
            "on a 37-device network."
        ),
    )

    @model_validator(mode="after")
    def _insecure_requires_tls(self) -> "ZigbeeImportRequest":
        if self.mqtt_tls_insecure and not self.mqtt_tls:
            raise ValueError("mqtt_tls_insecure requires mqtt_tls=true")
        return self


class ZigbeeTestConnectionRequest(BaseModel):
    mqtt_host: str
    mqtt_port: int = Field(1883, ge=1, le=65535)
    mqtt_username: str | None = None
    mqtt_password: str | None = None
    mqtt_tls: bool = False
    mqtt_tls_insecure: bool = False

    @model_validator(mode="after")
    def _insecure_requires_tls(self) -> "ZigbeeTestConnectionRequest":
        if self.mqtt_tls_insecure and not self.mqtt_tls:
            raise ValueError("mqtt_tls_insecure requires mqtt_tls=true")
        return self


class ZigbeeDeviceData(BaseModel):
    ieee_address: str
    friendly_name: str
    device_type: str  # Coordinator, Router, EndDevice
    model: str | None = None
    vendor: str | None = None
    description: str | None = None
    lqi: int | None = None
    last_seen: str | None = None


class ZigbeeNodeOut(BaseModel):
    """A homelable-ready node representation of a Zigbee device."""

    id: str
    label: str
    type: str  # zigbee_coordinator | zigbee_router | zigbee_enddevice
    ieee_address: str
    friendly_name: str
    device_type: str
    model: str | None = None
    vendor: str | None = None
    lqi: int | None = None
    parent_id: str | None = None
    # The Device Inventory row this node draws, stamped by the import. The
    # canvas carries it back on save so the node links to that row rather
    # than minting a second one for the same device.
    device_id: str | None = None


class ZigbeeEdgeOut(BaseModel):
    source: str
    target: str
    # Link quality for this link. It lives on the edge because that is what it
    # measures — a radio link between two devices, not a property of either.
    lqi: int | None = None
    # "tree" = the parent attachment drawn by default; "mesh" = a neighbour
    # link, only emitted when the import asked for them.
    kind: str = "tree"


class ZigbeeImportResponse(BaseModel):
    nodes: list[ZigbeeNodeOut]
    edges: list[ZigbeeEdgeOut]
    device_count: int


class ZigbeeImportJob(BaseModel):
    """Handle returned when a canvas import is queued."""

    job_id: str
    status: str  # running | done | error


class ZigbeeImportJobResult(BaseModel):
    """Poll response for a canvas import. ``result`` is set once done."""

    job_id: str
    status: str  # running | done
    result: ZigbeeImportResponse | None = None


class ZigbeeTestConnectionResponse(BaseModel):
    connected: bool
    message: str


class ZigbeeCoordinatorOut(BaseModel):
    id: str
    label: str
    ieee_address: str


class ZigbeeImportPendingResponse(BaseModel):
    """Result of importing a Z2M network into the pending section."""

    pending_created: int
    pending_updated: int
    coordinator: ZigbeeCoordinatorOut | None = None
    coordinator_already_existed: bool = False
    links_recorded: int
    device_count: int


class ZigbeeConfig(BaseModel):
    """Non-secret Zigbee connection + auto-sync config (GET response).

    MQTT connection fields (host/port/base_topic/tls) are env-only and
    read-only here — surfaced for display. ``host_configured`` reflects whether
    a server-side MQTT host is set (required for auto-sync). MQTT credentials
    (username/password) are never carried."""

    mqtt_host: str = ""
    mqtt_port: int = Field(1883, ge=1, le=65535)
    base_topic: str = "zigbee2mqtt"
    mqtt_tls: bool = False
    sync_enabled: bool = False
    sync_interval: int = Field(3600, ge=300)
    include_mesh_links: bool = False
    host_configured: bool = False


class ZigbeeSyncConfig(BaseModel):
    """User-editable auto-sync config (POST body). The ONLY persisted Zigbee
    settings. Connection fields (host/port/credentials/topic/tls) are env-only
    and are deliberately not accepted here."""

    sync_enabled: bool = False
    sync_interval: int = Field(3600, ge=300)
    # Import the neighbour (mesh) links too, like the manual dialog's checkbox.
    include_mesh_links: bool = False