palletizer-full-stack 0.2.0__py3-none-any.whl

palletizer_full/orchestrator.py

@@ -0,0 +1,153 @@
+"""
+Orchestrator for the Palletiser
+===============================
+
+The :class:`PalletiserOrchestrator` instantiates and wires together
+all subsystems: sensor IO, processing, planning, motion control,
+gripper control, power and thermal management, hazard detection and
+communication.  It runs these subsystems in a deterministic loop
+via the :class:`ExecutionStack`.
+
+Usage::
+
+    from palletizer_full.orchestrator import PalletiserOrchestrator
+
+    config = Config()
+    robot = MyRobotSDKInterface()  # implements RobotInterface
+    orchestrator = PalletiserOrchestrator(config, robot)
+    orchestrator.run()
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from typing import Any
+
+from .config import Config
+from .control.gripper_controller import GripperController
+from .control.motion_controller import MotionController, RobotInterface
+from .core.communication import CommunicationInterface
+from .core.concurrency_management import ReentrantLock
+from .core.consistency_verification import ConsistencyVerifier
+from .core.execution_stack import ExecutionStack
+from .core.fault_detection import FaultDetector
+from .core.hazard_manager import HazardManager
+from .core.memory_management import MemoryManager
+from .perception.sensor_io import SensorIO
+from .perception.sensor_processing import SensorProcessor
+from .planning.mission_planner import MissionPlanner
+from .planning.pattern_manager import PatternManager
+from .power.battery_management import BatteryManager
+from .power.thermal_management import ThermalManager
+
+
+class PalletiserOrchestrator:
+    """High-level orchestrator for the palletising cell."""
+
+    def __init__(self, config: Config, robot: RobotInterface) -> None:
+        self.config = config
+
+        # Subsystems
+        self.memory = MemoryManager(config.total_memory_bytes)
+        self.hazard_manager = HazardManager(config)
+        self.fault_detector = FaultDetector()
+        self.consistency = ConsistencyVerifier()
+        self.communication = CommunicationInterface(config)
+        self.battery = BatteryManager(
+            config.battery_capacity_wh,
+            config.low_battery_threshold,
+        )
+        self.thermal = ThermalManager(
+            config.max_temperature_c,
+            config.cooling_hysteresis_c,
+        )
+        self.sensor_io = SensorIO()
+        self.sensor_processor = SensorProcessor()
+        self.pattern_manager = PatternManager()
+        self.planner = MissionPlanner(self.pattern_manager)
+
+        # Robot motion and gripper
+        default_velocities = tuple(1.0 for _ in robot.get_joint_positions())
+        self.motion = MotionController(robot, default_velocities)
+        self.gripper = GripperController(
+            close_fn=lambda: None,
+            open_fn=lambda: None,
+            read_pressure_fn=None,
+        )
+
+        # Concurrency primitive protecting shared state
+        self._lock = ReentrantLock()
+        self._logger = logging.getLogger(self.__class__.__name__)
+
+        # Execution stack
+        self._stack = ExecutionStack(
+            config=self.config,
+            on_cycle=self._on_cycle,
+            on_health_check=self._collect_metrics,
+        )
+
+    # ------------------------------------------------------------------
+    # Public API
+    # ------------------------------------------------------------------
+
+    def run(self, cycles: int | None = None) -> None:
+        """Start the main control loop."""
+        self.communication.connect()
+        self._stack.run(cycles)
+
+    def add_order(self, sku: str, quantity: int) -> None:
+        """Add a new palletising order to the planner."""
+        with self._lock:
+            self.planner.add_order(sku, quantity)
+
+    # ------------------------------------------------------------------
+    # Internal callbacks invoked by ExecutionStack
+    # ------------------------------------------------------------------
+
+    def _on_cycle(self, dt: float) -> None:
+        """Perform one control cycle."""
+        with self._lock:
+            # 1. Poll sensors
+            raw = self.sensor_io.read_all()
+            processed = self.sensor_processor.process(raw)
+
+            # 2. Update power and thermal subsystems
+            self.battery.update(current_draw_w=100.0)
+            self.thermal.update()
+
+            # 3. Evaluate hazards
+            hazard_inputs: dict[str, Any] = {
+                "proximity": processed.get("proximity"),
+                "faults": self.fault_detector.get_active_faults(),
+                "high_voltage": None,
+                "gas": None,
+                "radiation": None,
+            }
+            self.hazard_manager.update(hazard_inputs)
+
+            # 4. If safe and there is a pending order, perform a task
+            if self.hazard_manager.is_safe() and self.planner.has_next_task():
+                task = self.planner.next_task()
+                if task:
+                    picked = self.gripper.pick()
+                    if not picked:
+                        self.fault_detector.report_fault("gripper_pick_failure")
+                        return
+                    time.sleep(0.01)
+                    self.gripper.release()
+
+            # 5. Fault handling: if SOC is low, trigger a fault
+            if self.battery.is_low():
+                self.fault_detector.report_fault("low_battery")
+
+    def _collect_metrics(self) -> dict[str, Any]:
+        """Collect telemetry and health metrics."""
+        metrics: dict[str, Any] = {}
+        metrics.update(self.battery.telemetry())
+        metrics.update(self.thermal.telemetry())
+        metrics["memory_ok"] = self.memory.check_health()
+        metrics["faults"] = list(self.fault_detector.get_active_faults())
+        metrics["hazards"] = self.hazard_manager.current_hazards()
+        self.communication.send_telemetry(metrics)
+        return metrics

palletizer_full/perception/__init__.py

@@ -0,0 +1 @@
+# Sensor IO and basic perception pipeline.

palletizer_full/perception/sensor_io.py

@@ -0,0 +1,32 @@
+"""
+Sensor IO Module
+================
+
+The :class:`SensorIO` class is the entry point for reading raw data
+from cameras, lidars, proximity sensors and other devices.  In this
+reference implementation it returns placeholder data; replace the
+``read_all`` method with calls to your sensor SDKs.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+
+class SensorIO:
+    """Read raw sensor data from hardware devices."""
+
+    def __init__(self) -> None:
+        self._logger = logging.getLogger(self.__class__.__name__)
+
+    def read_all(self) -> dict[str, Any]:
+        """Poll all sensors and return a dictionary of raw readings.
+
+        Override this method to integrate real sensor hardware.
+        """
+        return {
+            "proximity": 1.0,
+            "box_present": False,
+            "weight_kg": 0.0,
+        }

palletizer_full/perception/sensor_processing.py

@@ -0,0 +1,45 @@
+"""
+Sensor Processing Module
+========================
+
+The :class:`SensorProcessor` fuses raw sensor inputs to extract
+higher-level information such as box presence, alignment and
+orientation.  For a palletiser the perception stack is intentionally
+simple; you may add machine-learning-based detection later.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+
+class SensorProcessor:
+    """Process and fuse raw sensor readings."""
+
+    def __init__(self) -> None:
+        self._logger = logging.getLogger(self.__class__.__name__)
+
+    def process(self, raw: dict[str, Any]) -> dict[str, Any]:
+        """Process raw sensor data and return fused results.
+
+        Parameters
+        ----------
+        raw : dict
+            Raw sensor readings from :class:`SensorIO`.
+
+        Returns
+        -------
+        dict
+            Processed data including ``proximity``, ``box_detected``
+            and ``weight_kg``.
+        """
+        proximity = raw.get("proximity")
+        box_present = raw.get("box_present", False)
+        weight = raw.get("weight_kg", 0.0)
+
+        return {
+            "proximity": proximity,
+            "box_detected": bool(box_present) or (weight is not None and weight > 0.1),
+            "weight_kg": weight,
+        }

palletizer_full/planning/__init__.py

@@ -0,0 +1 @@
+# Task and trajectory planning.

palletizer_full/planning/mission_planner.py

@@ -0,0 +1,74 @@
+"""
+Mission Planner Module
+======================
+
+The :class:`MissionPlanner` breaks down orders into pick/stack
+sequences.  It tracks progress, handles errors and recovers from
+faults by re-planning or pausing the cell.
+"""
+
+from __future__ import annotations
+
+import logging
+from collections import deque
+from typing import Any
+
+from .pattern_manager import PatternManager
+
+
+class MissionPlanner:
+    """Plan and sequence palletising tasks.
+
+    Parameters
+    ----------
+    pattern_manager : PatternManager
+        Manager providing stacking patterns for each SKU.
+    """
+
+    def __init__(self, pattern_manager: PatternManager) -> None:
+        self._pattern_manager = pattern_manager
+        self._task_queue: deque[dict[str, Any]] = deque()
+        self._completed: int = 0
+        self._logger = logging.getLogger(self.__class__.__name__)
+
+    def add_order(self, sku: str, quantity: int) -> None:
+        """Add a palletising order for *quantity* cases of *sku*.
+
+        The planner looks up the stacking pattern for the SKU and
+        generates one task per case.
+        """
+        try:
+            pattern = self._pattern_manager.get_pattern(sku)
+        except KeyError:
+            self._logger.error("No pattern for SKU '%s'", sku)
+            return
+        for i in range(quantity):
+            pose = pattern[i % len(pattern)]
+            self._task_queue.append({
+                "sku": sku,
+                "index": i,
+                "pose": pose,
+            })
+        self._logger.info("Queued %d tasks for SKU '%s'", quantity, sku)
+
+    def has_next_task(self) -> bool:
+        """Return ``True`` if there are pending tasks."""
+        return len(self._task_queue) > 0
+
+    def next_task(self) -> dict[str, Any] | None:
+        """Pop and return the next task, or ``None`` if empty."""
+        if not self._task_queue:
+            return None
+        task = self._task_queue.popleft()
+        self._completed += 1
+        return task
+
+    @property
+    def completed_count(self) -> int:
+        """Number of tasks completed so far."""
+        return self._completed
+
+    @property
+    def pending_count(self) -> int:
+        """Number of tasks remaining in the queue."""
+        return len(self._task_queue)

palletizer_full/planning/pattern_manager.py

@@ -0,0 +1,56 @@
+"""
+Pattern Manager Module
+======================
+
+The :class:`PatternManager` generates and stores pallet patterns.
+Patterns are lists of ``(x, y, rotation)`` tuples describing where
+each case should be placed on a layer.  Patterns can be saved as
+JSON and loaded into the planner.
+"""
+
+from __future__ import annotations
+
+import json
+import logging
+from pathlib import Path
+
+
+class PatternManager:
+    """Manage pallet stacking patterns."""
+
+    def __init__(self) -> None:
+        self._patterns: dict[str, list[tuple[float, float, float]]] = {}
+        self._logger = logging.getLogger(self.__class__.__name__)
+
+    def load_pattern(
+        self,
+        name: str,
+        poses: list[tuple[float, float, float]],
+    ) -> None:
+        """Register a pattern under *name*."""
+        self._patterns[name] = list(poses)
+        self._logger.info("Loaded pattern '%s' with %d poses", name, len(poses))
+
+    def get_pattern(self, name: str) -> list[tuple[float, float, float]]:
+        """Return the poses for pattern *name*."""
+        if name not in self._patterns:
+            msg = f"Unknown pattern: {name}"
+            raise KeyError(msg)
+        return list(self._patterns[name])
+
+    def list_patterns(self) -> list[str]:
+        """Return names of all registered patterns."""
+        return list(self._patterns.keys())
+
+    def save_to_json(self, path: str | Path) -> None:
+        """Persist all patterns to a JSON file."""
+        with open(path, "w") as fh:
+            json.dump(self._patterns, fh, indent=2)
+
+    def load_from_json(self, path: str | Path) -> None:
+        """Load patterns from a JSON file."""
+        with open(path) as fh:
+            data = json.load(fh)
+        for name, poses in data.items():
+            self._patterns[name] = [tuple(p) for p in poses]
+        self._logger.info("Loaded %d patterns from %s", len(data), path)

palletizer_full/power/__init__.py

@@ -0,0 +1 @@
+# Energy and thermal management.

palletizer_full/power/battery_management.py

@@ -0,0 +1,65 @@
+"""
+Battery Management Module
+=========================
+
+The :class:`BatteryManager` monitors state-of-charge and available
+energy.  It uses LiFePO4 battery models by default, as these cells
+offer high energy density, long cycle life and excellent safety
+characteristics.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+
+class BatteryManager:
+    """Monitor battery state-of-charge and energy.
+
+    Parameters
+    ----------
+    capacity_wh : float
+        Total battery capacity in watt-hours.
+    low_threshold : float
+        Fractional charge level (0-1) below which the battery is
+        considered low.
+    """
+
+    def __init__(self, capacity_wh: float, low_threshold: float = 0.2) -> None:
+        self._capacity_wh = capacity_wh
+        self._remaining_wh = capacity_wh
+        self._low_threshold = low_threshold
+        self._logger = logging.getLogger(self.__class__.__name__)
+
+    def update(self, current_draw_w: float, dt_s: float = 0.02) -> None:
+        """Update the remaining energy based on current draw.
+
+        Parameters
+        ----------
+        current_draw_w : float
+            Instantaneous power draw in watts.
+        dt_s : float
+            Time step in seconds (defaults to 50 Hz cycle).
+        """
+        consumed = current_draw_w * (dt_s / 3600.0)
+        self._remaining_wh = max(0.0, self._remaining_wh - consumed)
+
+    @property
+    def soc(self) -> float:
+        """State of charge as a fraction (0-1)."""
+        if self._capacity_wh <= 0:
+            return 0.0
+        return self._remaining_wh / self._capacity_wh
+
+    def is_low(self) -> bool:
+        """Return ``True`` if the battery is below the low threshold."""
+        return self.soc < self._low_threshold
+
+    def telemetry(self) -> dict[str, Any]:
+        """Return battery telemetry data."""
+        return {
+            "battery_soc": round(self.soc, 4),
+            "battery_remaining_wh": round(self._remaining_wh, 2),
+            "battery_low": self.is_low(),
+        }

palletizer_full/power/thermal_management.py

@@ -0,0 +1,69 @@
+"""
+Thermal Management Module
+=========================
+
+The :class:`ThermalManager` monitors actuator temperatures and
+triggers cooling when thresholds are exceeded.  It applies a
+hysteresis strategy to avoid rapid cycling of fans or pumps.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+
+class ThermalManager:
+    """Monitor temperatures and control cooling.
+
+    Parameters
+    ----------
+    max_temp_c : float
+        Maximum safe temperature in degrees Celsius.
+    hysteresis_c : float
+        Temperature difference between activating and deactivating
+        cooling.
+    """
+
+    def __init__(self, max_temp_c: float = 70.0, hysteresis_c: float = 10.0) -> None:
+        self._max_temp = max_temp_c
+        self._hysteresis = hysteresis_c
+        self._current_temp = 25.0  # ambient default
+        self._cooling_active = False
+        self._logger = logging.getLogger(self.__class__.__name__)
+
+    def update(self, temperature_c: float | None = None) -> None:
+        """Update the current temperature reading.
+
+        If *temperature_c* is ``None``, the manager simulates a
+        small temperature increase for demonstration purposes.
+        """
+        if temperature_c is not None:
+            self._current_temp = temperature_c
+        else:
+            self._current_temp += 0.01  # placeholder drift
+
+        if self._current_temp >= self._max_temp:
+            if not self._cooling_active:
+                self._logger.warning(
+                    "Temperature %.1f C exceeds max %.1f C — activating cooling",
+                    self._current_temp,
+                    self._max_temp,
+                )
+            self._cooling_active = True
+        elif self._current_temp <= self._max_temp - self._hysteresis:
+            if self._cooling_active:
+                self._logger.info("Temperature normalised — deactivating cooling")
+            self._cooling_active = False
+
+    @property
+    def is_cooling(self) -> bool:
+        """Return ``True`` if cooling is currently active."""
+        return self._cooling_active
+
+    def telemetry(self) -> dict[str, Any]:
+        """Return thermal telemetry data."""
+        return {
+            "temperature_c": round(self._current_temp, 2),
+            "cooling_active": self._cooling_active,
+        }

palletizer_full/robot_config.py

@@ -0,0 +1,125 @@
+"""
+Robot Configuration Parser
+==========================
+
+Reads configuration from environment variables and exposes a
+strongly-typed, frozen :class:`RobotConfig` dataclass.  This allows
+the system to adapt to different factory environments, hardware
+configurations and operating modes without changing code.
+
+Boolean values accept ``1``, ``true``, ``t``, ``yes``, ``y`` or
+``on`` (case-insensitive) as true; everything else is false.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass
+
+# ---------------------------------------------------------------------------
+# Helpers
+# ---------------------------------------------------------------------------
+
+def _env(name: str, default: str) -> str:
+    return os.getenv(name, default)
+
+
+def _env_bool(name: str, default: bool) -> bool:
+    val = os.getenv(name)
+    if val is None:
+        return default
+    return str(val).strip().lower() in {"1", "true", "t", "yes", "y", "on"}
+
+
+def _env_floats(name: str, default: tuple[float, ...]) -> tuple[float, ...]:
+    raw = os.getenv(name)
+    if not raw:
+        return default
+    out: list[float] = []
+    for part in raw.split(","):
+        part = part.strip()
+        if not part:
+            continue
+        try:
+            out.append(float(part))
+        except ValueError:
+            msg = f"Invalid float in {name}: {part}"
+            raise ValueError(msg) from None
+    return tuple(out)
+
+
+def _env_csv(name: str, default: tuple[str, ...]) -> tuple[str, ...]:
+    raw = os.getenv(name)
+    if not raw:
+        return default
+    return tuple(s.strip() for s in raw.split(",") if s.strip())
+
+
+# ---------------------------------------------------------------------------
+# RobotConfig
+# ---------------------------------------------------------------------------
+
+@dataclass(frozen=True)
+class RobotConfig:
+    """Configuration for the palletiser control stack.
+
+    Fields correspond to environment variables prefixed with
+    ``PALLETIZER_``.
+    """
+
+    robot_environment: str
+    operation_mode: str
+    simulator_enabled: bool
+    joint_ids: tuple[str, ...]
+    actuator_types: tuple[str, ...]
+    max_velocity_per_joint: tuple[float, ...]
+    max_torque_per_joint: tuple[float, ...]
+    min_safety_margin: float
+    safety_thresholds: tuple[float, ...]
+    control_frequency_hz: float
+    communication_endpoint: str | None
+
+    def __init__(self) -> None:
+        object.__setattr__(self, "robot_environment", _env("PALLETIZER_ENV", "FACTORY"))
+        object.__setattr__(self, "operation_mode", _env("PALLETIZER_MODE", "PRODUCTION"))
+        object.__setattr__(self, "simulator_enabled", _env_bool("PALLETIZER_SIM", False))
+        object.__setattr__(
+            self,
+            "joint_ids",
+            _env_csv("PALLETIZER_JOINT_IDS", ("j0", "j1", "j2", "j3", "j4", "j5")),
+        )
+        object.__setattr__(
+            self,
+            "actuator_types",
+            _env_csv("PALLETIZER_ACTUATORS", ("REVOLUTE",) * 6),
+        )
+        object.__setattr__(
+            self,
+            "max_velocity_per_joint",
+            _env_floats("PALLETIZER_MAX_VEL", (1.0,) * 6),
+        )
+        object.__setattr__(
+            self,
+            "max_torque_per_joint",
+            _env_floats("PALLETIZER_MAX_TORQUE", (100.0,) * 6),
+        )
+        object.__setattr__(
+            self,
+            "min_safety_margin",
+            float(os.getenv("PALLETIZER_SAFETY_MARGIN", "0.4")),
+        )
+        object.__setattr__(
+            self,
+            "safety_thresholds",
+            _env_floats("PALLETIZER_SAFETY_THRESHOLDS", ()),
+        )
+        object.__setattr__(
+            self,
+            "control_frequency_hz",
+            float(os.getenv("PALLETIZER_FREQ", "50.0")),
+        )
+        object.__setattr__(
+            self,
+            "communication_endpoint",
+            os.getenv("PALLETIZER_COMM_ENDPOINT"),
+        )