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

palletizer_full/__init__.py

@@ -0,0 +1,37 @@
+# Palletizer Full Stack — Open-Source Industrial Palletising Software
+# https://github.com/iceccarelli/palletizer
+
+"""
+Palletizer Full Stack
+=====================
+
+A modular software stack for high-throughput end-of-line palletising cells:
+control logic, perception pipeline, task planning, power management, and a
+real mixed-SKU pallet optimizer.
+
+The optimizer is the core capability and is dependency-free:
+
+    from palletizer_full import optimize_pallet, Box
+    plan = optimize_pallet([Box("A", 400, 300, 250, 8.5), ...])
+    print(plan.volume_density, plan.stability_score)
+"""
+
+from .optimizer import (
+    Box,
+    Pallet,
+    Placement,
+    PalletPlan,
+    optimize_pallet,
+    load_boxes_csv,
+)
+
+__version__ = "0.2.0"
+__all__ = [
+    "__version__",
+    "Box",
+    "Pallet",
+    "Placement",
+    "PalletPlan",
+    "optimize_pallet",
+    "load_boxes_csv",
+]

palletizer_full/config.py

@@ -0,0 +1,122 @@
+"""
+High-level configuration for the palletiser control system.
+
+This module defines a :class:`Config` dataclass that centralises
+parameters for the control loop, power management and safety.  Values
+can be overridden via environment variables so that the same codebase
+adapts to different factory environments without code changes.
+"""
+
+from __future__ import annotations
+
+import os
+from dataclasses import dataclass, field
+
+# ---------------------------------------------------------------------------
+# Environment-variable helpers
+# ---------------------------------------------------------------------------
+
+def _env_float(name: str, default: float) -> float:
+    """Parse a float from an environment variable or return *default*."""
+    try:
+        raw = os.getenv(name)
+        return float(raw) if raw not in (None, "") else default
+    except Exception:
+        return default
+
+
+def _env_int(name: str, default: int) -> int:
+    """Parse an int from an environment variable or return *default*."""
+    try:
+        raw = os.getenv(name)
+        return int(raw) if raw not in (None, "") else default
+    except Exception:
+        return default
+
+
+def _env_bool(name: str, default: bool = False) -> bool:
+    """Parse a boolean from an environment variable."""
+    val = os.getenv(name)
+    if val is None:
+        return default
+    return str(val).strip().lower() in {"1", "true", "t", "yes", "y", "on"}
+
+
+# ---------------------------------------------------------------------------
+# Config dataclass
+# ---------------------------------------------------------------------------
+
+@dataclass
+class Config:
+    """Top-level configuration for the palletiser.
+
+    Parameters can be overridden via environment variables.  The
+    defaults here are suitable for a typical single-cell palletiser
+    using a 50 Hz control loop.
+    """
+
+    cycle_hz: float = field(
+        default_factory=lambda: _env_float("CYCLE_HZ", 50.0),
+    )
+    """Control loop frequency in Hertz."""
+
+    battery_capacity_wh: float = field(
+        default_factory=lambda: _env_float("BATTERY_CAPACITY_WH", 1000.0),
+    )
+    """Total energy capacity of the power system in watt-hours."""
+
+    low_battery_threshold: float = field(
+        default_factory=lambda: _env_float("LOW_BATTERY_THRESHOLD", 0.2),
+    )
+    """Fractional charge level below which the system should initiate
+    orderly shutdown or trigger a recharge.  Range: 0-1."""
+
+    max_temperature_c: float = field(
+        default_factory=lambda: _env_float("MAX_TEMPERATURE_C", 70.0),
+    )
+    """Maximum safe temperature (deg C) for motors and electronics."""
+
+    cooling_hysteresis_c: float = field(
+        default_factory=lambda: _env_float("COOLING_HYSTERESIS_C", 10.0),
+    )
+    """Temperature difference (deg C) between activating and
+    deactivating cooling."""
+
+    total_memory_bytes: int = field(
+        default_factory=lambda: _env_int("TOTAL_MEMORY_BYTES", 16 * 1024 * 1024),
+    )
+    """Amount of memory (bytes) reserved for deterministic buffers."""
+
+    safety_margin_m: float = field(
+        default_factory=lambda: _env_float("SAFETY_MARGIN_M", 0.4),
+    )
+    """Minimum allowable distance (metres) to human operators or
+    obstacles."""
+
+    safety_thresholds: tuple[float, ...] = field(
+        default_factory=lambda: tuple(
+            float(x)
+            for x in os.getenv("SAFETY_THRESHOLDS", "").split(",")
+            if x.strip()
+        ),
+    )
+    """Generic thresholds for hazards (e.g. gas, voltage)."""
+
+    power_budget_w: float = field(
+        default_factory=lambda: _env_float("POWER_BUDGET_W", 2000.0),
+    )
+    """Power budget (watts) allocated for the cell."""
+
+    enable_monitoring_ui: bool = field(
+        default_factory=lambda: _env_bool("ENABLE_MONITORING_UI", True),
+    )
+    """Whether to launch a simple monitoring server."""
+
+    monitor_port: int = field(
+        default_factory=lambda: _env_int("MONITOR_PORT", 8080),
+    )
+    """Port number for the monitoring UI, if enabled."""
+
+    def cycle_time(self) -> float:
+        """Return the period of the control loop in seconds."""
+        return 1.0 / max(self.cycle_hz, 1e-3)

palletizer_full/control/__init__.py

@@ -0,0 +1 @@
+# Low-level motion and actuator control.

palletizer_full/control/gripper_controller.py

@@ -0,0 +1,75 @@
+"""
+Gripper Controller Module
+=========================
+
+The :class:`GripperController` provides a high-level API for
+controlling a vacuum or mechanical gripper.  It monitors vacuum
+pressure (if available), triggers retries on failed picks and
+detects drops.
+
+The gripper is abstracted by callbacks passed during construction.
+Users should provide functions to open/close the gripper and to
+read pressure or force feedback.
+"""
+
+from __future__ import annotations
+
+import logging
+import math
+import time
+from collections.abc import Callable
+
+
+class GripperController:
+    """Control and monitor a gripper.
+
+    Parameters
+    ----------
+    close_fn : Callable[[], None]
+        Function that closes the gripper.
+    open_fn : Callable[[], None]
+        Function that opens the gripper.
+    read_pressure_fn : Callable[[], float] | None
+        Function that returns the current vacuum pressure.
+    """
+
+    def __init__(
+        self,
+        close_fn: Callable[[], None],
+        open_fn: Callable[[], None],
+        read_pressure_fn: Callable[[], float] | None = None,
+    ) -> None:
+        self._close_fn = close_fn
+        self._open_fn = open_fn
+        self._read_pressure = read_pressure_fn
+        self._logger = logging.getLogger(self.__class__.__name__)
+
+    def pick(self, retries: int = 3, wait_s: float = 0.1) -> bool:
+        """Close the gripper and verify suction/grasp.
+
+        Returns ``True`` on success, ``False`` on failure.
+        """
+        for attempt in range(retries):
+            self._close_fn()
+            time.sleep(wait_s)
+            if self._read_pressure is None:
+                return True
+            try:
+                pressure = float(self._read_pressure())
+            except Exception:
+                self._logger.exception("Pressure read error")
+                pressure = None
+            threshold = -0.2  # negative pressure in bar
+            if pressure is not None and pressure < threshold:
+                return True
+            self._logger.warning(
+                "Grip attempt %d failed (pressure=%.3f bar)",
+                attempt + 1,
+                pressure if pressure is not None else math.nan,
+            )
+        self._logger.error("Failed to achieve vacuum after %d attempts", retries)
+        return False
+
+    def release(self) -> None:
+        """Open the gripper to release the load."""
+        self._open_fn()

palletizer_full/control/joint_synchronization.py

@@ -0,0 +1,77 @@
+"""
+Joint Synchronisation Module
+============================
+
+Functions to synchronise motion of multiple joints so that the
+end effector follows a coordinated path and all joints finish at
+the same time.  These functions are hardware-agnostic.
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable
+
+
+def synchronise_velocities(
+    positions: Iterable[tuple[float, ...]],
+    max_velocities: tuple[float, ...],
+) -> list[tuple[float, ...]]:
+    """Synchronise motion velocities across joints.
+
+    Given a sequence of joint position tuples and per-joint maximum
+    velocities, compute adjusted positions such that each segment
+    completes in the same time across all joints.
+
+    Parameters
+    ----------
+    positions : iterable of tuple of float
+        Sequence of joint positions defining a trajectory.
+    max_velocities : tuple of float
+        Maximum allowed velocity for each joint.
+
+    Returns
+    -------
+    list of tuple of float
+        Synchronised joint positions.
+    """
+    positions_list = list(positions)
+    if not positions_list:
+        return []
+
+    # Compute per-joint deltas between consecutive points
+    deltas: list[list[float]] = []
+    for i in range(1, len(positions_list)):
+        prev = positions_list[i - 1]
+        curr = positions_list[i]
+        deltas.append([abs(c - p) for p, c in zip(prev, curr, strict=False)])
+
+    # Determine maximum required velocity ratio
+    ratios: list[float] = []
+    for delta in deltas:
+        for d, max_v in zip(delta, max_velocities, strict=False):
+            if max_v <= 0:
+                continue
+            ratios.append(d / max_v)
+
+    longest_time = max(ratios) if ratios else 0.0
+    if longest_time <= 0:
+        return positions_list
+
+    # Scale each joint's motion to match the slowest
+    synchronised: list[tuple[float, ...]] = [positions_list[0]]
+    for i in range(1, len(positions_list)):
+        prev = positions_list[i - 1]
+        curr = positions_list[i]
+        scaled: list[float] = []
+        for p, c, max_v in zip(prev, curr, max_velocities, strict=False):
+            delta_val = c - p
+            if max_v <= 0:
+                scaled.append(c)
+                continue
+            scale = longest_time * max_v
+            if abs(delta_val) <= abs(scale):
+                scaled.append(c)
+            else:
+                scaled.append(p + (scale if delta_val > 0 else -scale))
+        synchronised.append(tuple(scaled))
+    return synchronised

palletizer_full/control/motion_controller.py

@@ -0,0 +1,87 @@
+"""
+Motion Controller Module
+========================
+
+The :class:`MotionController` orchestrates low-level joint commands
+to the robot arm.  It delegates actual actuation to an injected
+:class:`RobotInterface`, allowing you to simulate the robot or swap
+hardware without changing the rest of the stack.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Iterable
+
+from .joint_synchronization import synchronise_velocities
+
+
+class RobotInterface:
+    """Abstract base class for robot arm APIs.
+
+    Implement this interface to connect your robot SDK to the
+    palletiser control stack.
+    """
+
+    def get_joint_positions(self) -> tuple[float, ...]:
+        """Return current joint positions."""
+        raise NotImplementedError
+
+    def command_joint_positions(self, positions: tuple[float, ...]) -> None:
+        """Command the robot to move to *positions*."""
+        raise NotImplementedError
+
+    def execute_trajectory(
+        self,
+        trajectory: list[tuple[float, ...]],
+        dt: float,
+    ) -> None:
+        """Execute a trajectory at a fixed time interval *dt*."""
+        raise NotImplementedError
+
+
+class MotionController:
+    """High-level motion controller for a palletising robot arm."""
+
+    def __init__(
+        self,
+        robot: RobotInterface,
+        max_velocities: tuple[float, ...],
+    ) -> None:
+        self._robot = robot
+        self._max_velocities = max_velocities
+        self._logger = logging.getLogger(self.__class__.__name__)
+
+    def move_to(self, target: tuple[float, ...], duration: float = 2.0) -> None:
+        """Move the robot to *target* over *duration* seconds."""
+        current = self._robot.get_joint_positions()
+        if len(current) != len(target):
+            msg = "Target joint tuple length mismatch"
+            raise ValueError(msg)
+
+        trajectory = [current, target]
+        synced = synchronise_velocities(trajectory, self._max_velocities)
+        steps = max(int(duration / 0.1), 1)
+        for i in range(1, steps + 1):
+            alpha = i / steps
+            interp = tuple(
+                p + alpha * (t - p) for p, t in zip(synced[0], synced[-1], strict=False)
+            )
+            self._robot.command_joint_positions(interp)
+            time.sleep(duration / steps)
+        self._robot.command_joint_positions(target)
+
+    def execute_trajectory(
+        self,
+        trajectory: Iterable[tuple[float, ...]],
+        dt: float,
+    ) -> None:
+        """Execute a pre-computed joint trajectory."""
+        positions = list(trajectory)
+        if not positions:
+            return
+        synced = synchronise_velocities(positions, self._max_velocities)
+        for pos in synced:
+            self._robot.command_joint_positions(pos)
+            time.sleep(dt)

palletizer_full/core/__init__.py

@@ -0,0 +1 @@
+# Core services for the palletiser control stack.

palletizer_full/core/communication.py

@@ -0,0 +1,70 @@
+"""
+Communication Interface Module
+===============================
+
+The :class:`CommunicationInterface` abstracts telemetry publishing
+and remote command reception.  In this reference implementation it
+logs messages; extend it to support Ethernet, serial, CAN bus or
+MQTT transports as needed.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import Any
+
+from ..config import Config
+
+
+class CommunicationInterface:
+    """Publish telemetry and receive remote commands.
+
+    Parameters
+    ----------
+    config : Config
+        System configuration (used to read endpoint settings).
+    """
+
+    def __init__(self, config: Config) -> None:
+        self._config = config
+        self._connected = False
+        self._logger = logging.getLogger(self.__class__.__name__)
+
+    def connect(self) -> None:
+        """Establish the communication channel.
+
+        In a real deployment this would open a socket, serial port or
+        message-broker connection.
+        """
+        self._connected = True
+        self._logger.info("Communication channel connected")
+
+    def disconnect(self) -> None:
+        """Close the communication channel."""
+        self._connected = False
+        self._logger.info("Communication channel disconnected")
+
+    def send_telemetry(self, data: dict[str, Any]) -> None:
+        """Publish a telemetry payload.
+
+        Parameters
+        ----------
+        data : dict
+            Key-value telemetry data to publish.
+        """
+        if not self._connected:
+            self._logger.warning("Cannot send telemetry: not connected")
+            return
+        self._logger.debug("Telemetry: %s", data)
+
+    def receive_command(self) -> dict[str, Any] | None:
+        """Poll for an incoming remote command.
+
+        Returns ``None`` if no command is available.
+        """
+        return None
+
+    @property
+    def is_connected(self) -> bool:
+        """Return ``True`` if the channel is active."""
+        return self._connected

palletizer_full/core/concurrency_management.py

@@ -0,0 +1,39 @@
+"""
+Concurrency Management Module
+==============================
+
+Provides thread-safe primitives for coordinating access to shared
+resources in a multi-threaded control loop.  The
+:class:`ReentrantLock` wraps Python's ``threading.RLock`` and can be
+used as a context manager.
+"""
+
+from __future__ import annotations
+
+import threading
+
+
+class ReentrantLock:
+    """A reentrant lock that can be used as a context manager.
+
+    This thin wrapper around :class:`threading.RLock` provides a
+    consistent API for the palletiser control stack.
+    """
+
+    def __init__(self) -> None:
+        self._lock = threading.RLock()
+
+    def acquire(self, blocking: bool = True, timeout: float = -1) -> bool:
+        """Acquire the lock."""
+        return self._lock.acquire(blocking=blocking, timeout=timeout)
+
+    def release(self) -> None:
+        """Release the lock."""
+        self._lock.release()
+
+    def __enter__(self) -> ReentrantLock:
+        self._lock.acquire()
+        return self
+
+    def __exit__(self, *args: object) -> None:
+        self._lock.release()

palletizer_full/core/consistency_verification.py

@@ -0,0 +1,53 @@
+"""
+Consistency Verification Module
+================================
+
+The :class:`ConsistencyVerifier` validates that sensor readings and
+actuator states are within expected ranges.  It is used during
+commissioning and at runtime to detect calibration drift or hardware
+faults.
+"""
+
+from __future__ import annotations
+
+import logging
+
+
+class ConsistencyVerifier:
+    """Validate sensor/actuator consistency."""
+
+    def __init__(self) -> None:
+        self._logger = logging.getLogger(self.__class__.__name__)
+
+    def verify_range(self, name: str, value: float, low: float, high: float) -> bool:
+        """Check that *value* is within [*low*, *high*].
+
+        Returns ``True`` if the value is in range, ``False`` otherwise.
+        """
+        if low <= value <= high:
+            return True
+        self._logger.warning(
+            "%s out of range: %.3f not in [%.3f, %.3f]",
+            name,
+            value,
+            low,
+            high,
+        )
+        return False
+
+    def verify_monotonic(self, name: str, values: list[float]) -> bool:
+        """Check that *values* are strictly increasing.
+
+        Useful for verifying encoder readings or timestamps.
+        """
+        for i in range(1, len(values)):
+            if values[i] <= values[i - 1]:
+                self._logger.warning(
+                    "%s not monotonic at index %d: %.3f <= %.3f",
+                    name,
+                    i,
+                    values[i],
+                    values[i - 1],
+                )
+                return False
+        return True

palletizer_full/core/environment_adapter.py

@@ -0,0 +1,53 @@
+"""
+Environment Adapter Module
+===========================
+
+Provides helpers to adapt system behaviour to different factory
+environments.  The :class:`EnvironmentAdapter` reads the current
+environment profile and applies adjustments to safety margins,
+cycle rates and other parameters.
+"""
+
+from __future__ import annotations
+
+import logging
+from typing import ClassVar
+
+from ..config import Config
+
+
+class EnvironmentAdapter:
+    """Adapt system parameters to the deployment environment.
+
+    Parameters
+    ----------
+    config : Config
+        System configuration to adjust.
+    environment : str
+        Environment identifier (e.g. ``"FACTORY"``, ``"WAREHOUSE"``).
+    """
+
+    PROFILES: ClassVar[dict[str, dict[str, float]]] = {
+        "FACTORY": {"safety_margin_m": 0.4, "cycle_hz": 50.0},
+        "WAREHOUSE": {"safety_margin_m": 0.6, "cycle_hz": 30.0},
+        "LAB": {"safety_margin_m": 0.2, "cycle_hz": 100.0},
+    }
+
+    def __init__(self, config: Config, environment: str = "FACTORY") -> None:
+        self._config = config
+        self._environment = environment.upper()
+        self._logger = logging.getLogger(self.__class__.__name__)
+
+    def apply(self) -> Config:
+        """Apply environment-specific overrides and return the config."""
+        profile = self.PROFILES.get(self._environment, {})
+        for key, value in profile.items():
+            if hasattr(self._config, key):
+                object.__setattr__(self._config, key, value)
+                self._logger.info(
+                    "Environment %s: set %s = %s",
+                    self._environment,
+                    key,
+                    value,
+                )
+        return self._config

palletizer_full/core/execution_stack.py

@@ -0,0 +1,70 @@
+"""
+Execution Stack Module
+======================
+
+The :class:`ExecutionStack` manages the deterministic control loop.
+It sequences sensor polling, planning, control and actuation at a
+fixed cycle rate, invokes health checks and publishes telemetry.
+"""
+
+from __future__ import annotations
+
+import logging
+import time
+from collections.abc import Callable
+from typing import Any
+
+from ..config import Config
+
+
+class ExecutionStack:
+    """Manage the main control loop.
+
+    Parameters
+    ----------
+    config : Config
+        Global configuration for the system.
+    on_cycle : Callable[[float], None]
+        Callback invoked every cycle with the elapsed time.
+    on_health_check : Callable[[], dict[str, Any]]
+        Callback invoked each cycle to collect telemetry.
+    """
+
+    def __init__(
+        self,
+        config: Config,
+        on_cycle: Callable[[float], None],
+        on_health_check: Callable[[], dict[str, Any]],
+    ) -> None:
+        self._config = config
+        self._on_cycle = on_cycle
+        self._on_health_check = on_health_check
+        self._logger = logging.getLogger(self.__class__.__name__)
+
+    def run(self, cycles: int | None = None) -> None:
+        """Run the control loop.
+
+        Parameters
+        ----------
+        cycles : int | None
+            Number of cycles to run.  If ``None``, runs indefinitely.
+        """
+        cycle_time = self._config.cycle_time()
+        next_time = time.monotonic()
+        cycle_count = 0
+        while cycles is None or cycle_count < cycles:
+            now = time.monotonic()
+            dt = now - next_time + cycle_time
+            try:
+                self._on_cycle(dt)
+            except Exception:
+                self._logger.exception("Error in control cycle")
+            try:
+                self._on_health_check()
+            except Exception:
+                self._logger.exception("Error collecting health metrics")
+            next_time += cycle_time
+            sleep_time = next_time - time.monotonic()
+            if sleep_time > 0:
+                time.sleep(sleep_time)
+            cycle_count += 1