arthexis 0.1.16__py3-none-any.whl → 0.1.28__py3-none-any.whl

ocpp/models.py

@@ -1,20 +1,33 @@
+from __future__ import annotations
+
+import binascii
+import hashlib
+import json
+import os
 import re
+import secrets
 import socket
+import uuid
+from datetime import datetime, timedelta
 from decimal import Decimal, InvalidOperation
 
 from django.conf import settings
 from django.contrib.sites.models import Site
 from django.db import models
-from django.db.models import Q
+from django.db.models import DecimalField, OuterRef, Prefetch, Q, Subquery
 from django.core.exceptions import ValidationError
 from django.urls import reverse
 from django.utils.translation import gettext_lazy as _
+from django.utils import timezone
+
+from asgiref.sync import async_to_sync
 
 from core.entity import Entity, EntityManager
 from nodes.models import Node
 
 from core.models import (
     EnergyAccount,
+    EnergyTariff,
     Reference,
     RFID as CoreRFID,
     ElectricVehicle as CoreElectricVehicle,
@@ -22,6 +35,7 @@ from core.models import (
     EVModel as CoreEVModel,
     SecurityGroup,
 )
+from . import store
 from .reference_utils import url_targets_local_loopback
 
 
@@ -35,6 +49,22 @@ class Location(Entity):
     longitude = models.DecimalField(
         max_digits=9, decimal_places=6, null=True, blank=True
     )
+    zone = models.CharField(
+        max_length=3,
+        choices=EnergyTariff.Zone.choices,
+        blank=True,
+        null=True,
+        help_text=_("CFE climate zone used to select matching energy tariffs."),
+    )
+    contract_type = models.CharField(
+        max_length=16,
+        choices=EnergyTariff.ContractType.choices,
+        blank=True,
+        null=True,
+        help_text=_(
+            "CFE service contract type required to match energy tariff pricing."
+        ),
+    )
 
     def __str__(self) -> str:  # pragma: no cover - simple representation
         return self.name
@@ -48,6 +78,7 @@ class Charger(Entity):
     """Known charge point."""
 
     _PLACEHOLDER_SERIAL_RE = re.compile(r"^<[^>]+>$")
+    _AUTO_LOCATION_SANITIZE_RE = re.compile(r"[^0-9A-Za-z_-]+")
 
     OPERATIVE_STATUSES = {
         "Available",
@@ -82,6 +113,13 @@ class Charger(Entity):
         default=True,
         help_text="Display this charger on the public status dashboard.",
     )
+    language = models.CharField(
+        _("Language"),
+        max_length=12,
+        choices=settings.LANGUAGES,
+        default="es",
+        help_text=_("Preferred language for the public landing page."),
+    )
     require_rfid = models.BooleanField(
         _("Require RFID Authorization"),
         default=False,
@@ -197,6 +235,35 @@ class Charger(Entity):
         related_name="chargers",
     )
     last_path = models.CharField(max_length=255, blank=True)
+    configuration = models.ForeignKey(
+        "ChargerConfiguration",
+        null=True,
+        blank=True,
+        on_delete=models.SET_NULL,
+        related_name="chargers",
+        help_text=_(
+            "Latest GetConfiguration response received from this charge point."
+        ),
+    )
+    local_auth_list_version = models.PositiveIntegerField(
+        _("Local list version"),
+        null=True,
+        blank=True,
+        help_text=_("Last RFID list version acknowledged by the charge point."),
+    )
+    local_auth_list_updated_at = models.DateTimeField(
+        _("Local list updated at"),
+        null=True,
+        blank=True,
+        help_text=_("When the charge point reported or accepted the RFID list."),
+    )
+    node_origin = models.ForeignKey(
+        "nodes.Node",
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="origin_chargers",
+    )
     manager_node = models.ForeignKey(
         "nodes.Node",
         on_delete=models.SET_NULL,
@@ -204,6 +271,22 @@ class Charger(Entity):
         blank=True,
         related_name="managed_chargers",
     )
+    forwarded_to = models.ForeignKey(
+        "nodes.Node",
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="forwarded_chargers",
+        help_text=_("Remote node receiving forwarded transactions."),
+    )
+    forwarding_watermark = models.DateTimeField(
+        null=True,
+        blank=True,
+        help_text=_("Timestamp of the last forwarded transaction."),
+    )
+    allow_remote = models.BooleanField(default=False)
+    export_transactions = models.BooleanField(default=False)
+    last_online_at = models.DateTimeField(null=True, blank=True)
     owner_users = models.ManyToManyField(
         settings.AUTH_USER_MODEL,
         blank=True,
@@ -258,6 +341,24 @@ class Charger(Entity):
         user_group_ids = user.groups.values_list("pk", flat=True)
         return self.owner_groups.filter(pk__in=user_group_ids).exists()
 
+    @property
+    def is_local(self) -> bool:
+        """Return ``True`` when this charger originates from the local node."""
+
+        local = Node.get_local()
+        if not local:
+            return False
+        if self.node_origin_id is None:
+            return True
+        return self.node_origin_id == local.pk
+
+    def save(self, *args, **kwargs):
+        if self.node_origin_id is None:
+            local = Node.get_local()
+            if local:
+                self.node_origin = local
+        super().save(*args, **kwargs)
+
     class Meta:
         verbose_name = _("Charge Point")
         verbose_name_plural = _("Charge Points")
@@ -307,6 +408,16 @@ class Charger(Entity):
             )
         return normalized
 
+    @classmethod
+    def sanitize_auto_location_name(cls, value: str) -> str:
+        """Return a location name containing only safe characters."""
+
+        sanitized = cls._AUTO_LOCATION_SANITIZE_RE.sub("_", value)
+        sanitized = re.sub(r"_+", "_", sanitized).strip("_")
+        if not sanitized:
+            return "Charger"
+        return sanitized
+
     AGGREGATE_CONNECTOR_SLUG = "all"
 
     def identity_tuple(self) -> tuple[str, int | None]:
@@ -442,7 +553,8 @@ class Charger(Entity):
             if existing:
                 self.location = existing.location
             else:
-                location, _ = Location.objects.get_or_create(name=self.charger_id)
+                auto_name = type(self).sanitize_auto_location_name(self.charger_id)
+                location, _ = Location.objects.get_or_create(name=auto_name)
                 self.location = location
             if update_list is not None and "location" not in update_list:
                 update_list.append("location")
@@ -452,11 +564,17 @@ class Charger(Entity):
         ref_value = self._full_url()
         if url_targets_local_loopback(ref_value):
             return
-        if not self.reference or self.reference.value != ref_value:
+        if not self.reference:
             self.reference = Reference.objects.create(
                 value=ref_value, alt_text=self.charger_id
             )
             super().save(update_fields=["reference"])
+        elif self.reference.value != ref_value:
+            Reference.objects.filter(pk=self.reference_id).update(
+                value=ref_value, alt_text=self.charger_id
+            )
+            self.reference.value = ref_value
+            self.reference.alt_text = self.charger_id
 
     def refresh_manager_node(self, node: Node | None = None) -> Node | None:
         """Ensure ``manager_node`` matches the provided or local node."""
@@ -527,24 +645,58 @@ class Charger(Entity):
             return qs
         return qs.filter(pk=self.pk)
 
+    def total_kw_for_range(
+        self,
+        start=None,
+        end=None,
+    ) -> float:
+        """Return total energy delivered within ``start``/``end`` window."""
+
+        from . import store
+
+        total = 0.0
+        for charger in self._target_chargers():
+            total += charger._total_kw_range_single(store, start, end)
+        return total
+
     def _total_kw_single(self, store_module) -> float:
         """Return total kW for this specific charger identity."""
 
+        return self._total_kw_range_single(store_module)
+
+    def _total_kw_range_single(self, store_module, start=None, end=None) -> float:
+        """Return total kW for a date range for this charger."""
+
         tx_active = None
         if self.connector_id is not None:
             tx_active = store_module.get_transaction(self.charger_id, self.connector_id)
+
         qs = self.transactions.all()
+        if start is not None:
+            qs = qs.filter(start_time__gte=start)
+        if end is not None:
+            qs = qs.filter(start_time__lt=end)
         if tx_active and tx_active.pk is not None:
             qs = qs.exclude(pk=tx_active.pk)
+        qs = annotate_transaction_energy_bounds(qs)
+
         total = 0.0
-        for tx in qs:
+        for tx in qs.iterator():
             kw = tx.kw
             if kw:
                 total += kw
+
         if tx_active:
-            kw = tx_active.kw
-            if kw:
-                total += kw
+            start_time = getattr(tx_active, "start_time", None)
+            include = True
+            if start is not None and start_time and start_time < start:
+                include = False
+            if end is not None and start_time and start_time >= end:
+                include = False
+            if include:
+                kw = tx_active.kw
+                if kw:
+                    total += kw
         return total
 
     def purge(self):
@@ -578,6 +730,141 @@ class Charger(Entity):
         super().delete(*args, **kwargs)
 
 
+class ConfigurationKey(models.Model):
+    """Single configurationKey entry from a GetConfiguration payload."""
+
+    configuration = models.ForeignKey(
+        "ChargerConfiguration",
+        on_delete=models.CASCADE,
+        related_name="configuration_entries",
+    )
+    position = models.PositiveIntegerField(default=0)
+    key = models.CharField(max_length=255)
+    readonly = models.BooleanField(default=False)
+    has_value = models.BooleanField(default=False)
+    value = models.JSONField(null=True, blank=True)
+    extra_data = models.JSONField(default=dict, blank=True)
+
+    class Meta:
+        ordering = ["position", "id"]
+        verbose_name = _("Configuration Key")
+        verbose_name_plural = _("Configuration Keys")
+
+    def __str__(self) -> str:  # pragma: no cover - simple representation
+        return self.key
+
+    def as_dict(self) -> dict[str, object]:
+        data: dict[str, object] = {"key": self.key, "readonly": self.readonly}
+        if self.has_value:
+            data["value"] = self.value
+        if self.extra_data:
+            data.update(self.extra_data)
+        return data
+
+
+class ChargerConfigurationManager(models.Manager):
+    def get_queryset(self):
+        return super().get_queryset().prefetch_related("configuration_entries")
+
+
+class ChargerConfiguration(models.Model):
+    """Persisted configuration package returned by a charge point."""
+
+    charger_identifier = models.CharField(_("Serial Number"), max_length=100)
+    connector_id = models.PositiveIntegerField(
+        _("Connector ID"),
+        null=True,
+        blank=True,
+        help_text=_("Connector that returned this configuration (if specified)."),
+    )
+    unknown_keys = models.JSONField(
+        default=list,
+        blank=True,
+        help_text=_("Keys returned in the unknownKey list."),
+    )
+    evcs_snapshot_at = models.DateTimeField(
+        _("EVCS snapshot at"),
+        null=True,
+        blank=True,
+        help_text=_(
+            "Timestamp when this configuration was received from the charge point."
+        ),
+    )
+    raw_payload = models.JSONField(
+        default=dict,
+        blank=True,
+        help_text=_("Raw payload returned by the GetConfiguration call."),
+    )
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    objects = ChargerConfigurationManager()
+
+    class Meta:
+        ordering = ["-created_at"]
+        verbose_name = _("CP Configuration")
+        verbose_name_plural = _("CP Configurations")
+
+    def __str__(self) -> str:  # pragma: no cover - simple representation
+        connector = (
+            _("connector %(number)s") % {"number": self.connector_id}
+            if self.connector_id is not None
+            else _("all connectors")
+        )
+        return _("%(serial)s configuration (%(connector)s)") % {
+            "serial": self.charger_identifier,
+            "connector": connector,
+        }
+
+    @property
+    def configuration_keys(self) -> list[dict[str, object]]:
+        return [entry.as_dict() for entry in self.configuration_entries.all()]
+
+    def replace_configuration_keys(self, entries: list[dict[str, object]] | None) -> None:
+        ConfigurationKey.objects.filter(configuration=self).delete()
+        if not entries:
+            if hasattr(self, "_prefetched_objects_cache"):
+                self._prefetched_objects_cache.pop("configuration_entries", None)
+            return
+
+        key_objects: list[ConfigurationKey] = []
+        for position, entry in enumerate(entries):
+            if not isinstance(entry, dict):
+                continue
+            key_text = str(entry.get("key") or "").strip()
+            if not key_text:
+                continue
+            readonly = bool(entry.get("readonly"))
+            has_value = "value" in entry
+            value = entry.get("value") if has_value else None
+            extras = {
+                field_key: field_value
+                for field_key, field_value in entry.items()
+                if field_key not in {"key", "readonly", "value"}
+            }
+            key_objects.append(
+                ConfigurationKey(
+                    configuration=self,
+                    position=position,
+                    key=key_text,
+                    readonly=readonly,
+                    has_value=has_value,
+                    value=value,
+                    extra_data=extras,
+                )
+            )
+        created_keys = ConfigurationKey.objects.bulk_create(key_objects)
+        if hasattr(self, "_prefetched_objects_cache"):
+            if created_keys:
+                refreshed = list(
+                    ConfigurationKey.objects.filter(configuration=self)
+                    .order_by("position", "id")
+                )
+                self._prefetched_objects_cache["configuration_entries"] = refreshed
+            else:
+                self._prefetched_objects_cache.pop("configuration_entries", None)
+
+
 class Transaction(Entity):
     """Charging session data stored for each charger."""
 
@@ -592,7 +879,18 @@ class Transaction(Entity):
         blank=True,
         verbose_name=_("RFID"),
     )
-    vin = models.CharField(max_length=17, blank=True)
+    vid = models.CharField(
+        max_length=64,
+        blank=True,
+        default="",
+        verbose_name=_("VID"),
+        help_text=_("Vehicle identifier reported by the charger."),
+    )
+    vin = models.CharField(
+        max_length=17,
+        blank=True,
+        help_text=_("Deprecated. Use VID instead."),
+    )
     connector_id = models.PositiveIntegerField(null=True, blank=True)
     meter_start = models.IntegerField(null=True, blank=True)
     meter_stop = models.IntegerField(null=True, blank=True)
@@ -638,6 +936,26 @@ class Transaction(Entity):
         verbose_name = _("Transaction")
         verbose_name_plural = _("CP Transactions")
 
+    @property
+    def vehicle_identifier(self) -> str:
+        """Return the preferred vehicle identifier for this transaction."""
+
+        vid = (self.vid or "").strip()
+        if vid:
+            return vid
+
+        return (self.vin or "").strip()
+
+    @property
+    def vehicle_identifier_source(self) -> str:
+        """Return which field supplies :pyattr:`vehicle_identifier`."""
+
+        if (self.vid or "").strip():
+            return "vid"
+        if (self.vin or "").strip():
+            return "vin"
+        return ""
+
     @property
     def kw(self) -> float:
         """Return consumed energy in kW for this session."""
@@ -649,17 +967,63 @@ class Transaction(Entity):
         if self.meter_stop is not None:
             end_val = float(self.meter_stop) / 1000.0
 
-        readings = list(
-            self.meter_values.filter(energy__isnull=False).order_by("timestamp")
-        )
-        if readings:
+        def _coerce(value):
+            if value in {None, ""}:
+                return None
+            try:
+                return float(value)
+            except (TypeError, ValueError, InvalidOperation):
+                return None
+
+        if start_val is None:
+            annotated_start = getattr(self, "meter_energy_start", None)
+            if annotated_start is None:
+                annotated_start = getattr(self, "report_meter_energy_start", None)
+            start_val = _coerce(annotated_start)
+
+        if end_val is None:
+            annotated_end = getattr(self, "meter_energy_end", None)
+            if annotated_end is None:
+                annotated_end = getattr(self, "report_meter_energy_end", None)
+            end_val = _coerce(annotated_end)
+
+        readings: list[MeterValue] | None = None
+        if start_val is None or end_val is None:
+            if hasattr(self, "prefetched_meter_values"):
+                readings = [
+                    reading
+                    for reading in getattr(self, "prefetched_meter_values")
+                    if getattr(reading, "energy", None) is not None
+                ]
+            else:
+                cache = getattr(self, "_prefetched_objects_cache", None)
+                if cache and "meter_values" in cache:
+                    readings = [
+                        reading
+                        for reading in cache["meter_values"]
+                        if getattr(reading, "energy", None) is not None
+                    ]
+
+            if readings is not None:
+                readings.sort(key=lambda reading: reading.timestamp)
+
+        if readings is not None and readings:
+            if start_val is None:
+                start_val = _coerce(readings[0].energy)
+            if end_val is None:
+                end_val = _coerce(readings[-1].energy)
+        elif start_val is None or end_val is None:
+            readings_qs = self.meter_values.filter(energy__isnull=False).order_by(
+                "timestamp"
+            )
             if start_val is None:
-                start_val = float(readings[0].energy or 0)
-            # Always use the latest available reading for the end value when a
-            # stop meter has not been recorded yet. This allows active
-            # transactions to report totals using their most recent reading.
+                first_energy = readings_qs.values_list("energy", flat=True).first()
+                start_val = _coerce(first_energy)
             if end_val is None:
-                end_val = float(readings[-1].energy or 0)
+                last_energy = readings_qs.order_by("-timestamp").values_list(
+                    "energy", flat=True
+                ).first()
+                end_val = _coerce(last_energy)
 
         if start_val is None or end_val is None:
             return 0.0
@@ -668,6 +1032,49 @@ class Transaction(Entity):
         return max(total, 0.0)
 
 
+class RFIDSessionAttempt(Entity):
+    """Record RFID authorisation attempts received via StartTransaction."""
+
+    class Status(models.TextChoices):
+        ACCEPTED = "accepted", _("Accepted")
+        REJECTED = "rejected", _("Rejected")
+
+    charger = models.ForeignKey(
+        "Charger",
+        on_delete=models.CASCADE,
+        related_name="rfid_attempts",
+        null=True,
+        blank=True,
+    )
+    rfid = models.CharField(_("RFID"), max_length=255, blank=True)
+    status = models.CharField(max_length=16, choices=Status.choices)
+    attempted_at = models.DateTimeField(auto_now_add=True)
+    account = models.ForeignKey(
+        EnergyAccount,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="rfid_attempts",
+    )
+    transaction = models.ForeignKey(
+        "Transaction",
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="rfid_attempts",
+    )
+
+    class Meta:
+        ordering = ["-attempted_at"]
+        verbose_name = _("RFID Session Attempt")
+        verbose_name_plural = _("RFID Session Attempts")
+
+    def __str__(self) -> str:  # pragma: no cover - simple representation
+        status = self.get_status_display() or ""
+        tag = self.rfid or "-"
+        return f"{tag} ({status})"
+
+
 class MeterValue(Entity):
     """Parsed meter values reported by chargers."""
 
@@ -756,6 +1163,28 @@ class MeterReading(MeterValue):
         verbose_name_plural = _("Meter Values")
 
 
+def annotate_transaction_energy_bounds(
+    queryset, *, start_field: str = "meter_energy_start", end_field: str = "meter_energy_end"
+):
+    """Annotate transactions with their earliest and latest energy readings."""
+
+    energy_qs = MeterValue.objects.filter(
+        transaction=OuterRef("pk"), energy__isnull=False
+    )
+    start_subquery = energy_qs.order_by("timestamp").values("energy")[:1]
+    end_subquery = energy_qs.order_by("-timestamp").values("energy")[:1]
+
+    annotations = {
+        start_field: Subquery(
+            start_subquery, output_field=DecimalField(max_digits=12, decimal_places=3)
+        ),
+        end_field: Subquery(
+            end_subquery, output_field=DecimalField(max_digits=12, decimal_places=3)
+        ),
+    }
+    return queryset.annotate(**annotations)
+
+
 class Simulator(Entity):
     """Preconfigured simulator that can be started from the admin."""
 
@@ -886,6 +1315,8 @@ class DataTransferMessage(models.Model):
 
     class Meta:
         ordering = ["-created_at"]
+        verbose_name = _("Data Message")
+        verbose_name_plural = _("Data Messages")
         indexes = [
             models.Index(
                 fields=["ocpp_message_id"],
@@ -900,6 +1331,526 @@ class DataTransferMessage(models.Model):
         return f"{self.get_direction_display()} {self.vendor_id or 'DataTransfer'}"
 
 
+class CPFirmware(Entity):
+    """Persisted firmware packages associated with charge points."""
+
+    class Source(models.TextChoices):
+        DOWNLOAD = "download", _("Downloaded")
+        UPLOAD = "upload", _("Uploaded")
+
+    name = models.CharField(_("Name"), max_length=200, blank=True)
+    description = models.TextField(_("Description"), blank=True)
+    source = models.CharField(
+        max_length=16,
+        choices=Source.choices,
+        default=Source.DOWNLOAD,
+        verbose_name=_("Source"),
+    )
+    source_node = models.ForeignKey(
+        Node,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="downloaded_firmware",
+        verbose_name=_("Source node"),
+    )
+    source_charger = models.ForeignKey(
+        "Charger",
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="downloaded_firmware",
+        verbose_name=_("Source charge point"),
+    )
+    content_type = models.CharField(
+        _("Content type"),
+        max_length=100,
+        default="application/octet-stream",
+        blank=True,
+    )
+    filename = models.CharField(_("Filename"), max_length=255, blank=True)
+    payload_json = models.JSONField(null=True, blank=True)
+    payload_binary = models.BinaryField(null=True, blank=True)
+    payload_encoding = models.CharField(_("Encoding"), max_length=32, blank=True)
+    payload_size = models.PositiveIntegerField(_("Payload size"), default=0)
+    checksum = models.CharField(_("Checksum"), max_length=128, blank=True)
+    metadata = models.JSONField(default=dict, blank=True)
+    download_vendor_id = models.CharField(
+        _("Vendor ID"), max_length=255, blank=True
+    )
+    download_message_id = models.CharField(
+        _("Message ID"), max_length=64, blank=True
+    )
+    downloaded_at = models.DateTimeField(_("Downloaded at"), null=True, blank=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        ordering = ["-created_at"]
+        verbose_name = _("CP Firmware")
+        verbose_name_plural = _("CP Firmware")
+
+    def __str__(self) -> str:  # pragma: no cover - simple representation
+        label = self.name or self.filename or ""
+        if label:
+            return label
+        return f"Firmware #{self.pk}" if self.pk else "Firmware"
+
+    def save(self, *args, **kwargs):
+        if self.filename:
+            self.filename = os.path.basename(self.filename)
+        payload_bytes = self.get_payload_bytes()
+        self.payload_size = len(payload_bytes)
+        if payload_bytes:
+            self.checksum = hashlib.sha256(payload_bytes).hexdigest()
+        elif not self.checksum:
+            self.checksum = ""
+        if not self.content_type:
+            if self.payload_binary:
+                self.content_type = "application/octet-stream"
+            elif self.payload_json is not None:
+                self.content_type = "application/json"
+        if not self.payload_encoding:
+            self.payload_encoding = ""
+        super().save(*args, **kwargs)
+
+    def get_payload_bytes(self) -> bytes:
+        if self.payload_binary:
+            return bytes(self.payload_binary)
+        if self.payload_json is not None:
+            try:
+                return json.dumps(
+                    self.payload_json,
+                    ensure_ascii=False,
+                    separators=(",", ":"),
+                    sort_keys=True,
+                ).encode("utf-8")
+            except (TypeError, ValueError):
+                return str(self.payload_json).encode("utf-8")
+        return b""
+
+    @property
+    def has_binary(self) -> bool:
+        return bool(self.payload_binary)
+
+    @property
+    def has_json(self) -> bool:
+        return self.payload_json is not None
+
+
+class CPFirmwareDeployment(Entity):
+    """Track firmware rollout attempts for specific charge points."""
+
+    TERMINAL_STATUSES = {"Installed", "InstallationFailed", "DownloadFailed"}
+
+    firmware = models.ForeignKey(
+        CPFirmware,
+        on_delete=models.CASCADE,
+        related_name="deployments",
+        verbose_name=_("Firmware"),
+    )
+    charger = models.ForeignKey(
+        "Charger",
+        on_delete=models.PROTECT,
+        related_name="firmware_deployments",
+        verbose_name=_("Charge point"),
+    )
+    node = models.ForeignKey(
+        Node,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="firmware_deployments",
+        verbose_name=_("Node"),
+    )
+    ocpp_message_id = models.CharField(
+        _("OCPP message ID"), max_length=64, blank=True
+    )
+    status = models.CharField(_("Status"), max_length=32, blank=True)
+    status_info = models.CharField(_("Status details"), max_length=255, blank=True)
+    status_timestamp = models.DateTimeField(_("Status timestamp"), null=True, blank=True)
+    requested_at = models.DateTimeField(_("Requested at"), auto_now_add=True)
+    completed_at = models.DateTimeField(_("Completed at"), null=True, blank=True)
+    retrieve_date = models.DateTimeField(_("Retrieve date"), null=True, blank=True)
+    retry_count = models.PositiveIntegerField(_("Retries"), default=0)
+    retry_interval = models.PositiveIntegerField(
+        _("Retry interval (seconds)"), default=0
+    )
+    download_token = models.CharField(_("Download token"), max_length=64, blank=True)
+    download_token_expires_at = models.DateTimeField(
+        _("Token expires at"), null=True, blank=True
+    )
+    downloaded_at = models.DateTimeField(_("Downloaded at"), null=True, blank=True)
+    request_payload = models.JSONField(default=dict, blank=True)
+    response_payload = models.JSONField(default=dict, blank=True)
+    created_at = models.DateTimeField(auto_now_add=True)
+    updated_at = models.DateTimeField(auto_now=True)
+
+    class Meta:
+        ordering = ["-requested_at"]
+        verbose_name = _("CP Firmware Deployment")
+        verbose_name_plural = _("CP Firmware Deployments")
+        indexes = [
+            models.Index(fields=["ocpp_message_id"]),
+            models.Index(fields=["download_token"]),
+        ]
+
+    def __str__(self) -> str:  # pragma: no cover - simple representation
+        return f"{self.firmware} → {self.charger}" if self.pk else "Firmware Deployment"
+
+    def issue_download_token(self, *, lifetime: timedelta | None = None) -> str:
+        if lifetime is None:
+            lifetime = timedelta(hours=1)
+        deadline = timezone.now() + lifetime
+        token = secrets.token_urlsafe(24)
+        while type(self).all_objects.filter(download_token=token).exists():
+            token = secrets.token_urlsafe(24)
+        self.download_token = token
+        self.download_token_expires_at = deadline
+        self.save(
+            update_fields=["download_token", "download_token_expires_at", "updated_at"]
+        )
+        return token
+
+    def mark_status(
+        self,
+        status: str,
+        info: str = "",
+        timestamp: datetime | None = None,
+        *,
+        response: dict | None = None,
+    ) -> None:
+        timestamp_value = timestamp or timezone.now()
+        self.status = status
+        self.status_info = info
+        self.status_timestamp = timestamp_value
+        if response is not None:
+            self.response_payload = response
+        if status in self.TERMINAL_STATUSES and not self.completed_at:
+            self.completed_at = timezone.now()
+        self.save(
+            update_fields=[
+                "status",
+                "status_info",
+                "status_timestamp",
+                "response_payload",
+                "completed_at",
+                "updated_at",
+            ]
+        )
+
+    @property
+    def is_terminal(self) -> bool:
+        return self.status in self.TERMINAL_STATUSES and bool(self.completed_at)
+
+
+class CPReservation(Entity):
+    """Track connector reservations dispatched to an EVCS."""
+
+    location = models.ForeignKey(
+        Location,
+        on_delete=models.PROTECT,
+        related_name="reservations",
+        verbose_name=_("Location"),
+    )
+    connector = models.ForeignKey(
+        Charger,
+        on_delete=models.PROTECT,
+        related_name="reservations",
+        verbose_name=_("Connector"),
+    )
+    account = models.ForeignKey(
+        EnergyAccount,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="cp_reservations",
+        verbose_name=_("Energy account"),
+    )
+    rfid = models.ForeignKey(
+        CoreRFID,
+        on_delete=models.SET_NULL,
+        null=True,
+        blank=True,
+        related_name="cp_reservations",
+        verbose_name=_("RFID"),
+    )
+    id_tag = models.CharField(
+        _("Id Tag"),
+        max_length=255,
+        blank=True,
+        default="",
+        help_text=_("Identifier sent to the EVCS when reserving the connector."),
+    )
+    start_time = models.DateTimeField(verbose_name=_("Start time"))
+    duration_minutes = models.PositiveIntegerField(
+        verbose_name=_("Duration (minutes)"),
+        default=120,
+        help_text=_("Reservation window length in minutes."),
+    )
+    evcs_status = models.CharField(
+        max_length=32,
+        blank=True,
+        default="",
+        verbose_name=_("EVCS status"),
+    )
+    evcs_error = models.CharField(
+        max_length=255,
+        blank=True,
+        default="",
+        verbose_name=_("EVCS error"),
+    )
+    evcs_confirmed = models.BooleanField(
+        default=False,
+        verbose_name=_("Reservation confirmed"),
+    )
+    evcs_confirmed_at = models.DateTimeField(
+        null=True,
+        blank=True,
+        verbose_name=_("Confirmed at"),
+    )
+    ocpp_message_id = models.CharField(
+        max_length=36,
+        blank=True,
+        default="",
+        editable=False,
+        verbose_name=_("OCPP message id"),
+    )
+    created_on = models.DateTimeField(auto_now_add=True, verbose_name=_("Created on"))
+    updated_on = models.DateTimeField(auto_now=True, verbose_name=_("Updated on"))
+
+    class Meta:
+        ordering = ["-start_time"]
+        verbose_name = _("CP Reservation")
+        verbose_name_plural = _("CP Reservations")
+
+    def __str__(self) -> str:  # pragma: no cover - simple representation
+        start = timezone.localtime(self.start_time) if self.start_time else ""
+        return f"{self.location} @ {start}" if self.location else str(start)
+
+    @property
+    def end_time(self):
+        duration = max(int(self.duration_minutes or 0), 0)
+        return self.start_time + timedelta(minutes=duration)
+
+    @property
+    def connector_label(self) -> str:
+        if self.connector_id:
+            return self.connector.connector_label
+        return ""
+
+    @property
+    def id_tag_value(self) -> str:
+        if self.id_tag:
+            return self.id_tag.strip()
+        if self.rfid_id:
+            return (self.rfid.rfid or "").strip()
+        return ""
+
+    def allocate_connector(self, *, force: bool = False) -> Charger:
+        """Select an available connector for this reservation."""
+
+        if not self.location_id:
+            raise ValidationError({"location": _("Select a location for the reservation.")})
+        if not self.start_time:
+            raise ValidationError({"start_time": _("Provide a start time for the reservation.")})
+        if self.duration_minutes <= 0:
+            raise ValidationError(
+                {"duration_minutes": _("Reservation window must be at least one minute.")}
+            )
+
+        candidates = list(
+            Charger.objects.filter(
+                location=self.location, connector_id__isnull=False
+            ).order_by("connector_id")
+        )
+        if not candidates:
+            raise ValidationError(
+                {"location": _("No connectors are configured for the selected location.")}
+            )
+
+        def _priority(charger: Charger) -> tuple[int, int]:
+            connector_id = charger.connector_id or 0
+            if connector_id == 2:
+                return (0, connector_id)
+            if connector_id == 1:
+                return (1, connector_id)
+            return (2, connector_id)
+
+        def _is_available(charger: Charger) -> bool:
+            existing = type(self).objects.filter(connector=charger).exclude(pk=self.pk)
+            start = self.start_time
+            end = self.end_time
+            for entry in existing:
+                if entry.start_time < end and entry.end_time > start:
+                    return False
+            return True
+
+        if self.connector_id:
+            current = next((c for c in candidates if c.pk == self.connector_id), None)
+            if current and _is_available(current) and not force:
+                return current
+
+        for charger in sorted(candidates, key=_priority):
+            if _is_available(charger):
+                self.connector = charger
+                return charger
+
+        raise ValidationError(
+            _("All connectors at this location are reserved for the selected time window.")
+        )
+
+    def clean(self):
+        super().clean()
+        if self.start_time and timezone.is_naive(self.start_time):
+            self.start_time = timezone.make_aware(
+                self.start_time, timezone.get_current_timezone()
+            )
+        if self.duration_minutes <= 0:
+            raise ValidationError(
+                {"duration_minutes": _("Reservation window must be at least one minute.")}
+            )
+        try:
+            self.allocate_connector(force=bool(self.pk))
+        except ValidationError as exc:
+            raise ValidationError(exc) from exc
+
+    def save(self, *args, **kwargs):
+        if self.start_time and timezone.is_naive(self.start_time):
+            self.start_time = timezone.make_aware(
+                self.start_time, timezone.get_current_timezone()
+            )
+        update_fields = kwargs.get("update_fields")
+        relevant_fields = {"location", "start_time", "duration_minutes", "connector"}
+        should_allocate = True
+        if update_fields is not None and not relevant_fields.intersection(update_fields):
+            should_allocate = False
+        if should_allocate:
+            self.allocate_connector(force=bool(self.pk))
+        super().save(*args, **kwargs)
+
+    def send_reservation_request(self) -> str:
+        """Dispatch a ReserveNow request to the associated connector."""
+
+        if not self.pk:
+            raise ValidationError(_("Save the reservation before sending it to the EVCS."))
+        connector = self.connector
+        if connector is None or connector.connector_id is None:
+            raise ValidationError(_("Unable to determine which connector to reserve."))
+        id_tag = self.id_tag_value
+        if not id_tag:
+            raise ValidationError(
+                _("Provide an RFID or idTag before creating the reservation.")
+            )
+        connection = store.get_connection(connector.charger_id, connector.connector_id)
+        if connection is None:
+            raise ValidationError(
+                _("The selected charge point is not currently connected to the system.")
+            )
+
+        message_id = uuid.uuid4().hex
+        expiry = timezone.localtime(self.end_time)
+        payload = {
+            "connectorId": connector.connector_id,
+            "expiryDate": expiry.isoformat(),
+            "idTag": id_tag,
+            "reservationId": self.pk,
+        }
+        frame = json.dumps([2, message_id, "ReserveNow", payload])
+
+        log_key = store.identity_key(connector.charger_id, connector.connector_id)
+        store.add_log(
+            log_key,
+            f"ReserveNow request: reservation={self.pk}, expiry={expiry.isoformat()}",
+            log_type="charger",
+        )
+        async_to_sync(connection.send)(frame)
+
+        metadata = {
+            "action": "ReserveNow",
+            "charger_id": connector.charger_id,
+            "connector_id": connector.connector_id,
+            "log_key": log_key,
+            "reservation_pk": self.pk,
+            "requested_at": timezone.now(),
+        }
+        store.register_pending_call(message_id, metadata)
+        store.schedule_call_timeout(message_id, action="ReserveNow", log_key=log_key)
+
+        self.ocpp_message_id = message_id
+        self.evcs_status = ""
+        self.evcs_error = ""
+        self.evcs_confirmed = False
+        self.evcs_confirmed_at = None
+        super().save(
+            update_fields=[
+                "ocpp_message_id",
+                "evcs_status",
+                "evcs_error",
+                "evcs_confirmed",
+                "evcs_confirmed_at",
+                "updated_on",
+            ]
+        )
+        return message_id
+
+    def send_cancel_request(self) -> str:
+        """Dispatch a CancelReservation request for this reservation."""
+
+        if not self.pk:
+            raise ValidationError(_("Save the reservation before sending it to the EVCS."))
+        connector = self.connector
+        if connector is None or connector.connector_id is None:
+            raise ValidationError(_("Unable to determine which connector to cancel."))
+        connection = store.get_connection(connector.charger_id, connector.connector_id)
+        if connection is None:
+            raise ValidationError(
+                _("The selected charge point is not currently connected to the system.")
+            )
+
+        message_id = uuid.uuid4().hex
+        payload = {"reservationId": self.pk}
+        frame = json.dumps([2, message_id, "CancelReservation", payload])
+
+        log_key = store.identity_key(connector.charger_id, connector.connector_id)
+        store.add_log(
+            log_key,
+            f"CancelReservation request: reservation={self.pk}",
+            log_type="charger",
+        )
+        async_to_sync(connection.send)(frame)
+
+        metadata = {
+            "action": "CancelReservation",
+            "charger_id": connector.charger_id,
+            "connector_id": connector.connector_id,
+            "log_key": log_key,
+            "reservation_pk": self.pk,
+            "requested_at": timezone.now(),
+        }
+        store.register_pending_call(message_id, metadata)
+        store.schedule_call_timeout(
+            message_id, action="CancelReservation", log_key=log_key
+        )
+
+        self.ocpp_message_id = message_id
+        self.evcs_status = ""
+        self.evcs_error = ""
+        self.evcs_confirmed = False
+        self.evcs_confirmed_at = None
+        super().save(
+            update_fields=[
+                "ocpp_message_id",
+                "evcs_status",
+                "evcs_error",
+                "evcs_confirmed",
+                "evcs_confirmed_at",
+                "updated_on",
+            ]
+        )
+        return message_id
+
+
 class RFID(CoreRFID):
     class Meta:
         proxy = True