netbox-pdu-control 0.2.0__py3-none-any.whl

netbox_pdu_control/__init__.py

@@ -0,0 +1,56 @@
+"""
+NetBox PDU Control
+
+Plugin configuration for NetBox PDU Control.
+
+For a complete list of PluginConfig attributes, see:
+https://docs.netbox.dev/en/stable/plugins/development/#pluginconfig-attributes
+"""
+
+__author__ = "tak-55"
+__email__ = "8895617+tak-55@users.noreply.github.com"
+__version__ = "0.2.0"
+
+
+from netbox.plugins import PluginConfig
+
+
+class PduConfig(PluginConfig):
+    name = "netbox_pdu_control"
+    verbose_name = "NetBox PDU Control"
+    description = "NetBox plugin for Managed PDUs (Raritan / Ubiquiti)."
+    author = "tak-55"
+    author_email = "8895617+tak-55@users.noreply.github.com"
+    version = __version__
+    base_url = "pdu"
+    min_version = "4.5.0"
+    max_version = "4.5.99"
+    graphql_schema = "graphql.schema"
+    queues = ["default"]
+
+    def ready(self):
+        super().ready()
+        from . import jobs  # noqa: F401 — registers @system_job if metrics_poll_interval is set
+
+        self._cleanup_stuck_jobs()
+
+    def _cleanup_stuck_jobs(self):
+        """Mark any stuck 'running' PDU jobs as errored on startup (e.g. after container restart or laptop sleep)."""
+        try:
+            from core.choices import JobStatusChoices
+            from core.models import Job
+
+            stuck = Job.objects.filter(
+                name__in=["PDU Get Metrics", "PDU Sync"],
+                status=JobStatusChoices.STATUS_RUNNING,
+            )
+            count = stuck.update(status=JobStatusChoices.STATUS_ERRORED)
+            if count:
+                import logging
+
+                logging.getLogger(__name__).warning("Cleaned up %d stuck PDU job(s) on startup", count)
+        except Exception:
+            pass  # Do not block startup if cleanup fails
+
+
+config = PduConfig

netbox_pdu_control/api/__init__.py

@@ -0,0 +1,6 @@
+"""
+REST API for NetBox PDU Plugin.
+
+For more information on developing NetBox REST APIs, see:
+https://docs.netbox.dev/en/stable/plugins/development/rest-api/
+"""

netbox_pdu_control/api/serializers.py

@@ -0,0 +1,101 @@
+from dcim.api.serializers import DeviceSerializer
+from netbox.api.serializers import NetBoxModelSerializer
+from rest_framework import serializers
+
+from ..models import ManagedPDU, PDUInlet, PDUOutlet
+
+
+class ManagedPDUSerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(view_name="plugins-api:netbox_pdu_control-api:managedpdu-detail")
+    device = DeviceSerializer(nested=True)
+    outlet_count = serializers.IntegerField(read_only=True)
+    api_password = serializers.CharField(write_only=True)
+
+    class Meta:
+        model = ManagedPDU
+        fields = (
+            "id",
+            "url",
+            "display",
+            "device",
+            "vendor",
+            "api_url",
+            "api_username",
+            "api_password",
+            "verify_ssl",
+            "sync_enabled",
+            "metrics_enabled",
+            "sync_status",
+            "last_synced",
+            "outlet_count",
+            "comments",
+            "tags",
+            "custom_fields",
+            "created",
+            "last_updated",
+        )
+        brief_fields = ("id", "url", "display", "device")
+        # api_password is write-only — accepted on POST/PATCH but never returned in responses
+
+
+class PDUOutletSerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(view_name="plugins-api:netbox_pdu_control-api:pduoutlet-detail")
+    managed_pdu = ManagedPDUSerializer(nested=True)
+    connected_device = DeviceSerializer(nested=True, required=False, allow_null=True)
+
+    class Meta:
+        model = PDUOutlet
+        fields = (
+            "id",
+            "url",
+            "display",
+            "managed_pdu",
+            "outlet_number",
+            "outlet_name",
+            "connected_device",
+            "status",
+            "current_a",
+            "power_w",
+            "voltage_v",
+            "power_factor",
+            "energy_wh",
+            "energy_reset_at",
+            "last_updated_from_pdu",
+            "comments",
+            "tags",
+            "custom_fields",
+            "created",
+            "last_updated",
+        )
+        brief_fields = ("id", "url", "display", "outlet_number", "outlet_name")
+
+
+class PDUInletSerializer(NetBoxModelSerializer):
+    url = serializers.HyperlinkedIdentityField(view_name="plugins-api:netbox_pdu_control-api:pduinlet-detail")
+    managed_pdu = ManagedPDUSerializer(nested=True)
+
+    class Meta:
+        model = PDUInlet
+        fields = (
+            "id",
+            "url",
+            "display",
+            "managed_pdu",
+            "inlet_number",
+            "inlet_name",
+            "current_a",
+            "power_w",
+            "apparent_power_va",
+            "voltage_v",
+            "power_factor",
+            "frequency_hz",
+            "energy_wh",
+            "energy_reset_at",
+            "last_updated_from_pdu",
+            "comments",
+            "tags",
+            "custom_fields",
+            "created",
+            "last_updated",
+        )
+        brief_fields = ("id", "url", "display", "inlet_number", "inlet_name")

netbox_pdu_control/api/urls.py

@@ -0,0 +1,12 @@
+from netbox.api.routers import NetBoxRouter
+
+from . import views
+
+app_name = "netbox_pdu_control"
+
+router = NetBoxRouter()
+router.register("managed-pdus", views.ManagedPDUViewSet)
+router.register("outlets", views.PDUOutletViewSet)
+router.register("inlets", views.PDUInletViewSet)
+
+urlpatterns = router.urls

netbox_pdu_control/api/views.py

@@ -0,0 +1,23 @@
+from django.db.models import Count
+from netbox.api.viewsets import NetBoxModelViewSet
+
+from .. import filtersets, models
+from .serializers import ManagedPDUSerializer, PDUInletSerializer, PDUOutletSerializer
+
+
+class ManagedPDUViewSet(NetBoxModelViewSet):
+    queryset = models.ManagedPDU.objects.annotate(outlet_count=Count("outlets")).prefetch_related("tags")
+    serializer_class = ManagedPDUSerializer
+    filterset_class = filtersets.ManagedPDUFilterSet
+
+
+class PDUOutletViewSet(NetBoxModelViewSet):
+    queryset = models.PDUOutlet.objects.select_related("managed_pdu", "connected_device").prefetch_related("tags")
+    serializer_class = PDUOutletSerializer
+    filterset_class = filtersets.PDUOutletFilterSet
+
+
+class PDUInletViewSet(NetBoxModelViewSet):
+    queryset = models.PDUInlet.objects.select_related("managed_pdu").prefetch_related("tags")
+    serializer_class = PDUInletSerializer
+    filterset_class = filtersets.PDUInletFilterSet

netbox_pdu_control/backends/__init__.py

@@ -0,0 +1,25 @@
+from .base import BasePDUClient, PDUClientError
+from .raritan import RaritanPDUClient
+from .unifi import UniFiPDUClient
+
+_VENDOR_BACKENDS = {
+    "raritan": RaritanPDUClient,
+    "ubiquiti": UniFiPDUClient,
+}
+
+
+def get_pdu_client(managed_pdu) -> BasePDUClient:
+    """
+    Return the appropriate PDU client for the given ManagedPDU instance.
+    Raises PDUClientError if no backend is registered for the vendor.
+    """
+    backend_class = _VENDOR_BACKENDS.get(managed_pdu.vendor)
+    if not backend_class:
+        raise PDUClientError(f"No backend registered for vendor: {managed_pdu.vendor!r}")
+    return backend_class(
+        base_url=managed_pdu.api_url,
+        username=managed_pdu.api_username,
+        password=managed_pdu.api_password,
+        verify_ssl=managed_pdu.verify_ssl,
+        managed_pdu=managed_pdu,
+    )

netbox_pdu_control/backends/base.py

@@ -0,0 +1,139 @@
+"""
+Base interface for PDU vendor backends.
+
+To add a new vendor:
+1. Create backends/<vendor>.py implementing BasePDUClient
+2. Register it in backends/__init__._VENDOR_BACKENDS
+3. Add the vendor to choices.VendorChoices
+"""
+
+from abc import ABC, abstractmethod
+
+
+class PDUClientError(Exception):
+    """Raised when communication with a PDU fails."""
+
+    pass
+
+
+class BasePDUClient(ABC):
+    """
+    Abstract base class for PDU vendor backends.
+
+    All backends must implement these methods so that views and sync logic
+    can work with any vendor without modification.
+    """
+
+    def __init__(self, base_url: str, username: str, password: str, verify_ssl: bool = True, **kwargs):
+        self.base_url = base_url
+        self.username = username
+        self.password = password
+        self.verify_ssl = verify_ssl
+
+    #: Set to True in backends that implement get_all_metrics_prometheus().
+    supports_prometheus_metrics: bool = False
+
+    @abstractmethod
+    def get_pdu_info(self) -> dict:
+        """
+        Return basic PDU hardware information.
+
+        Must contain:
+            model            (str) - PDU model name
+            serial_number    (str) - Serial number
+            firmware_version (str) - Firmware version string
+            pdu_name         (str) - Device name configured on the PDU hardware (may be empty)
+            network_interfaces (list[dict]) - each dict:
+                name        (str) - interface name (e.g. 'ETH1')
+                mac_address (str) - MAC address
+                ip_address  (str) - IP address (may be empty)
+        """
+
+    @abstractmethod
+    def get_all_outlet_data(self) -> list[dict]:
+        """
+        Return status and sensor data for all outlets.
+
+        Each dict must contain:
+            outlet_number (int)   - 1-indexed
+            name          (str)   - outlet label (may be empty)
+            switchingState(str)   - 'on', 'off', or 'unknown'
+            current_a     (float|None)
+            power_w       (float|None)
+            voltage_v     (float|None)
+            power_factor  (float|None)
+            energy_wh     (float|None)
+            energy_reset_epoch (float|None)
+        """
+
+    @abstractmethod
+    def get_single_outlet_data(self, outlet_index: int) -> dict:
+        """Return data for one outlet (0-indexed). Same dict format as get_all_outlet_data."""
+
+    @abstractmethod
+    def get_all_inlet_data(self) -> list[dict]:
+        """
+        Return power data for all inlets.
+
+        Each dict must contain:
+            inlet_number      (int)
+            name              (str)
+            current_a         (float|None)
+            power_w           (float|None)
+            apparent_power_va (float|None)
+            voltage_v         (float|None)
+            power_factor      (float|None)
+            frequency_hz      (float|None)
+            energy_wh         (float|None)
+            energy_reset_epoch(float|None)
+        """
+
+    @abstractmethod
+    def get_single_inlet_data(self, inlet_index: int) -> dict:
+        """Return data for one inlet (0-indexed). Same dict format as get_all_inlet_data."""
+
+    @abstractmethod
+    def set_outlet_power_state(self, outlet_index: int, state: str) -> None:
+        """
+        Change the power state of an outlet.
+
+        Args:
+            outlet_index: 0-indexed outlet number
+            state: 'on', 'off', or 'cycle'
+        """
+
+    @abstractmethod
+    def get_outlet_power_state_by_index(self, outlet_index: int) -> str:
+        """Return the current power state of an outlet: 'on', 'off', or 'unknown'."""
+
+    @abstractmethod
+    def set_outlet_name(self, outlet_index: int, name: str) -> None:
+        """Push a display name to the PDU outlet (0-indexed)."""
+
+    @abstractmethod
+    def set_inlet_name(self, inlet_index: int, name: str) -> None:
+        """Push a display name to the PDU inlet (0-indexed)."""
+
+    def get_outlet_thresholds(self, outlet_index: int) -> list[dict]:
+        """
+        Return threshold data for one outlet (0-indexed).
+
+        Each dict must contain:
+            label          (str)        - sensor label (e.g. 'Current')
+            unit           (str)        - unit string (e.g. 'A')
+            lower_critical (float|None)
+            lower_warning  (float|None)
+            upper_warning  (float|None)
+            upper_critical (float|None)
+
+        Default implementation returns [] (vendor does not support thresholds).
+        Override in backends that support threshold retrieval.
+        """
+        return []
+
+    def get_inlet_thresholds(self, inlet_index: int) -> list[dict]:
+        """
+        Return threshold data for one inlet (0-indexed). Same dict format as get_outlet_thresholds.
+        Default implementation returns [].
+        """
+        return []