Initial commit: Location Management Flask app

app/drivers/base.py

@@ -0,0 +1,76 @@
+"""Base class every board driver must implement.
+
+To create a new board driver:
+1. Make a subfolder inside ``app/drivers/`` (e.g. ``my_custom_board/``)
+2. Add a ``driver.py`` that subclasses ``BoardDriver``
+3. Set the class-level metadata attributes
+4. The registry will auto-discover and register it at startup — no other
+   changes needed anywhere in the application.
+"""
+from __future__ import annotations
+from abc import ABC, abstractmethod
+from typing import TYPE_CHECKING
+
+if TYPE_CHECKING:
+    from app.models.board import Board
+
+
+class BoardDriver(ABC):
+    """Abstract interface all board drivers must satisfy."""
+
+    # ── Metadata (override in subclass) ──────────────────────────────────────
+    #: Unique identifier stored in Board.board_type column
+    DRIVER_ID: str = ""
+    #: Human-readable name shown in the UI
+    DISPLAY_NAME: str = ""
+    #: Short description shown on the Add-board form
+    DESCRIPTION: str = ""
+    #: Default I/O counts pre-filled when this type is selected
+    DEFAULT_NUM_RELAYS: int = 4
+    DEFAULT_NUM_INPUTS: int = 4
+    #: Firmware download link shown in the UI (optional)
+    FIRMWARE_URL: str = ""
+
+    # ── Core API ──────────────────────────────────────────────────────────────
+
+    @abstractmethod
+    def get_relay_status(self, board: "Board", relay_num: int) -> bool | None:
+        """Return current relay state or None on comm error."""
+
+    @abstractmethod
+    def set_relay(self, board: "Board", relay_num: int, state: bool) -> bool:
+        """Set relay ON/OFF.  Return True on success."""
+
+    @abstractmethod
+    def toggle_relay(self, board: "Board", relay_num: int) -> bool | None:
+        """Toggle relay.  Return new state or None on error."""
+
+    @abstractmethod
+    def poll(self, board: "Board") -> dict:
+        """Fetch all I/O states.
+
+        Must return::
+
+            {
+                "relay_states": {"relay_1": True, ...},
+                "input_states": {"input_1": False, ...},
+                "is_online": True,
+                "firmware_version": "1.0.0",   # optional
+            }
+        """
+
+    @abstractmethod
+    def register_webhook(self, board: "Board", callback_url: str) -> bool:
+        """Tell the board where to POST input events.  Return True on success."""
+
+    # ── Optional hooks ────────────────────────────────────────────────────────
+
+    def on_board_added(self, board: "Board", server_base_url: str) -> None:
+        """Called once right after a board is created in the DB."""
+        self.register_webhook(board, f"{server_base_url}/api/webhook/{board.id}")
+
+    def on_board_deleted(self, board: "Board") -> None:
+        """Called just before a board is deleted from the DB."""
+
+    def __repr__(self) -> str:
+        return f"<Driver {self.DRIVER_ID}>"