flashforge-python-api 1.2.3__tar.gz → 1.3.1__tar.gz

{flashforge_python_api-1.2.3 → flashforge_python_api-1.3.1}/CHANGELOG.md

@@ -7,6 +7,34 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.1] - 2026-06-28
+
+### Fixed
+
+- **README "Supported Printers" table now lists the Creator 5 and Creator 5 Pro** that shipped in 1.3.0 (the table predated the Creator 5 work and omitted them). The Capabilities section now also reflects per-nozzle and chamber temperature control and the shared AD5X / Creator 5 material-station surface.
+
+## [1.3.0] - 2026-06-28
+
+### Added
+
+- **Creator 5 / Creator 5 Pro support.** The library now detects and fully drives the Creator 5 and Creator 5 Pro (firmware PIDs `40` / `41`) over HTTP, bringing the Python port to parity with `ff-5mp-api-ts` v1.6.1 for these models. The port previously detected these printers via USB product ID during discovery but could not control them.
+- **HTTP-only mode** for printers without a legacy TCP/8899 service (Creator 5 family). `FlashForgeClient` now exposes `is_creator5`, `is_creator5_pro`, and `http_only`; on an HTTP-only printer it skips the TCP bootstrap handshake and guards TCP-delegating control/temperature methods (`can_use_tcp`) so they no-op cleanly instead of hanging on a dead socket.
+- **Structured Creator 5 machine info.** `FFMachineInfo` now surfaces `model`, `tool_temps` (per-nozzle), `nozzle_count`, `chamber`, and capability flags `has_camera`, `has_lidar`, and `has_door_sensor`; raw `/detail` fields `nozzle_temps`, `nozzle_target_temps`, and `lidar` are parsed on `FFPrinterDetail`.
+- **HTTP temperature control transport** (`temperatureCtl_cmd`) for modern printers: `set_tool_temp`, `set_tool_temps`, `cancel_tool_temp` (per-nozzle, via the `nozzles[]` array), and `set_chamber_temp` / `cancel_chamber_temp` (Creator 5 only).
+- **`creator5_palette`** — 24-entry Creator 5 color palette with CIEDE2000 nearest-color snapping (`snap_to_creator5_palette`). The color math was fuzz-verified against the TypeScript reference build across 4000 random RGB inputs with zero mismatches.
+- **`configure_slot`** (`msConfig_cmd`) for material-station slot configuration, with model-gated color formatting: the Creator 5 snaps the color to its palette (sending `#RRGGBB` with the `#`), while the AD5X sends freeform `#`-stripped hex as before.
+- **Creator 5 print-start and upload flows:** `start_creator5_job` (`/printGcode`) and `upload_file_creator5` (`/uploadGcode`) with the C5-native request shapes (no `firstLayerInspection`; booleans as the strings `"true"`/`"false"`; materials mapped at print-start rather than upload). New `Creator5JobParams` and `Creator5UploadParams` models.
+
+### Fixed
+
+- **`_is_new_firmware_version` no longer misreads the Creator 5 (and AD5X) as "old firmware".** These models always use the new payload/header format and their firmware versioning (e.g. the C5 reports `1.9.2`) isn't comparable to the 5M family's `3.x` line, so the numeric `3.1.3` threshold now short-circuits to the new format for them. Previously a Creator 5 would send a malformed legacy `/printGcode` body.
+- **`get_file_list` / `get_local_file_list` no longer hang on HTTP-only printers.** They now fall back to the HTTP `/gcodeList` recent-file list (mirroring `Files.ts`) instead of blocking for ~10s on the dead TCP/8899 socket.
+- **Creator 5 Pro is no longer mis-classified as a 5M Pro** by the legacy `"Pro" in name` heuristic when no firmware `pid` is present; the Creator 5 family is now checked first.
+
+### Changed
+
+- `AD5XMaterialMapping` is reused as the shared material-mapping type for both the AD5X and Creator 5 flows (both use the same 5-field wire shape). The two per-model validators now delegate to a single shared `_validate_mappings` helper.
+- `set_chamber_temp` / `cancel_chamber_temp` are gated to Creator 5 / Creator 5 Pro (they return `False` on other models). This is a deliberate, documented divergence from the TypeScript client, which sends the chamber command unconditionally; see `docs/parity.md`.
 ## [1.2.3] - 2026-05-08
 
 ### Fixed
@@ -157,7 +185,9 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 - Type hints for all public APIs
 - Inline code documentation
 
-[Unreleased]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.2.3...HEAD
+[Unreleased]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.3.1...HEAD
+[1.3.1]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.3.0...v1.3.1
+[1.3.0]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.2.3...v1.3.0
 [1.2.3]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.2.2...v1.2.3
 [1.2.2]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.2.1...v1.2.2
 [1.2.1]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.2.0...v1.2.1

{flashforge_python_api-1.2.3 → flashforge_python_api-1.3.1}/CLAUDE.md

@@ -84,7 +84,7 @@ flashforge/
 
 **Dual Protocol Strategy**: HTTP is used for high-level operations (printer status, file listing, job control commands) while TCP/G-code is used for real-time operations (temperature monitoring via M105, print progress via M27, thumbnails via M662).
 
-**Model Detection**: The client sets `_is_ad5x` flag by checking printer name for "5M" or "5X" which enables/disables certain API features (LED control, camera, filtration).
+**Model Detection**: `MachineInfoParser.from_detail()` derives `is_pro` / `is_ad5x` on `FFMachineInfo` from the firmware-set integer `pid` field on `/detail` (35 = Adventurer 5M, 36 = 5M Pro, 38 = AD5X — see `KNOWN_HTTP_PIDS` in `flashforge/api/controls/info.py`). The `pid` value is also passed through to `FFMachineInfo.pid` for downstream consumers. When `pid` is absent (older firmware) the parser falls back to a name+capability heuristic, but new code should NOT rely on substring-matching `detail.name` — that field is user-mutable via the printer's LCD or cloud account and changing it broke detection in pre-1.2.3 builds (see CHANGELOG entry for 1.2.3, ref `ff-5mp-hass#13`).
 
 **Parser Pattern**: TCP responses are parsed by specialized parser classes in `tcp/parsers/` that extract structured data from text responses (e.g., `M105` returns text like `T0:25/0 T1:25/0 B:25/0` which TempInfo parses).
 
@@ -206,7 +206,7 @@ twine check dist/*
 ```
 
 **Version Management**:
-- Current version: **1.0.2** (as of 2025-12-26)
+- Current version: **1.3.0** (as of 2026-06-28)
 - Package name: `flashforge-python-api`
 - PyPI: https://pypi.org/project/flashforge-python-api/
 - Build system: Hatchling (defined in `pyproject.toml`)
@@ -270,6 +270,15 @@ Certain features only work on specific models:
 - **LED control**: Adventurer 5M/5X only (check `client.led_control`)
 - **Filtration**: Adventurer 5M Pro only (check `client.filtration_control`)
 
+Capability flags (`client.is_pro`, `client.is_ad5x`) are populated from `FFMachineInfo` after `verify_connection()`, which itself reads `pid` off `/detail`. Trust those flags — do not re-derive them from `info.name`.
+
+### Why TCP Bootstrap Is Still Required for Modern Printers
+The HTTP `/detail` endpoint requires authentication (`serialNumber` + `checkCode` via `FNetCode`). During discovery and the very first connection attempt — before a check code has been entered — there are no credentials, so the parser cannot read `pid` from `/detail`. The library handles this by:
+
+1. Discovery (UDP) returns the printer's USB-style PID in the broadcast packet, which `discovery/discovery.py` already maps to a `PrinterModel`. Consumers can use this to pre-select a model class before pairing.
+2. After a check code is provided, `client.initialize()` performs both an authenticated `/detail` call and an unauthenticated TCP `M115` (`tcp_client.get_printer_info()`). The TCP `M115` response carries `Machine Type` (firmware-controlled, e.g. `"FlashForge Adventurer 5M Pro"`) which is safe to substring-match for capability inference; do NOT use the M115 `Machine Name` field for that — like `detail.name` it is user-set.
+3. Once `verify_connection()` finishes, `FFMachineInfo.pid` / `is_pro` / `is_ad5x` are authoritative. All later capability gating should read those, not re-parse strings.
+
 ### Error Handling
 - HTTP errors: Wrapped in aiohttp exceptions
 - TCP errors: Socket timeouts, connection refused

{flashforge_python_api-1.2.3 → flashforge_python_api-1.3.1}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: flashforge-python-api
-Version: 1.2.3
+Version: 1.3.1
 Summary: A comprehensive Python library for controlling FlashForge 3D printers
 Project-URL: Homepage, https://github.com/GhostTypes/ff-5mp-api-py
 Project-URL: Documentation, https://github.com/GhostTypes/ff-5mp-api-py#readme
@@ -57,6 +57,8 @@ Python library for controlling FlashForge 3D printers with async support for the
 | Adventurer 5M | Full |
 | Adventurer 5M Pro | Full |
 | AD5X | Full |
+| Creator 5 | Full (HTTP-only) |
+| Creator 5 Pro | Full (HTTP-only) |
 | Adventurer 3 / 4 | Dedicated TCP clients |
 
 ## Installation
@@ -138,9 +140,9 @@ asyncio.run(main())
 - printer status and machine information
 - job control
 - file listing, uploads, and thumbnails
-- temperature and motion control
+- temperature and motion control, including per-nozzle and chamber temperature control (Creator 5)
 - LED, camera, and filtration control where supported
-- AD5X-specific job and material-station support
+- AD5X and Creator 5 / Creator 5 Pro material-station, slot configuration, and material mapping
 
 ## Documentation
 

{flashforge_python_api-1.2.3 → flashforge_python_api-1.3.1}/README.md

@@ -9,6 +9,8 @@ Python library for controlling FlashForge 3D printers with async support for the
 | Adventurer 5M | Full |
 | Adventurer 5M Pro | Full |
 | AD5X | Full |
+| Creator 5 | Full (HTTP-only) |
+| Creator 5 Pro | Full (HTTP-only) |
 | Adventurer 3 / 4 | Dedicated TCP clients |
 
 ## Installation
@@ -90,9 +92,9 @@ asyncio.run(main())
 - printer status and machine information
 - job control
 - file listing, uploads, and thumbnails
-- temperature and motion control
+- temperature and motion control, including per-nozzle and chamber temperature control (Creator 5)
 - LED, camera, and filtration control where supported
-- AD5X-specific job and material-station support
+- AD5X and Creator 5 / Creator 5 Pro material-station, slot configuration, and material mapping
 
 ## Documentation
 

{flashforge_python_api-1.2.3 → flashforge_python_api-1.3.1}/docs/parity.md

@@ -33,6 +33,12 @@ The TypeScript library intentionally includes its own TypeScript-shaped surface:
 - `PrinterDiscovery` as the primary discovery entry point
 - fewer high-level convenience wrappers on the top-level client
 
+## Known Divergences
+
+These are deliberate, documented differences from the TypeScript wire behavior:
+
+- **`set_chamber_temp` / `cancel_chamber_temp` are Creator 5-only.** The TypeScript client sends the chamber temperature command unconditionally (printers without a chamber heater ignore the field). The Python client gates these methods to Creator 5 / Creator 5 Pro and returns `False` otherwise, since only the Creator 5 family has a chamber heater. Practical impact on other models is near-zero.
+
 ## Guidance
 
 - Prefer `PrinterDiscovery` for new code in both languages.

{flashforge_python_api-1.2.3 → flashforge_python_api-1.3.1}/flashforge/__init__.py

@@ -127,7 +127,7 @@ from .tcp import (
 )
 
 FiveMClient = FlashForgeClient
-__version__ = "1.2.3"
+__version__ = "1.3.1"
 __author__ = "FlashForge Python API Contributors"
 __email__ = "notghosttypes@gmail.com"
 __description__ = "Python library for controlling FlashForge 3D printers"

{flashforge_python_api-1.2.3 → flashforge_python_api-1.3.1}/flashforge/api/constants/commands.py

@@ -9,3 +9,7 @@ class Commands:
     CIRCULATION_CONTROL_CMD = "circulateCtl_cmd"
     CAMERA_CONTROL_CMD = "streamCtrl_cmd"
     TEMP_CONTROL_CMD = "temperatureCtl_cmd"
+    # AD5X + Creator 5 material-station slot metadata (name + color). Filament
+    # load/unload (`ms_cmd`) stays AD5X-only — the Creator 5 firmware has no
+    # `ms_cmd` (confirmed via Ghidra RE).
+    MATERIAL_STATION_CONFIG_CMD = "msConfig_cmd"

{flashforge_python_api-1.2.3 → flashforge_python_api-1.3.1}/flashforge/api/constants/endpoints.py

@@ -1,6 +1,5 @@
 from typing import Final
 
-
 CAMERA_STREAM_PORT: Final[int] = 8080
 
 

{flashforge_python_api-1.2.3 → flashforge_python_api-1.3.1}/flashforge/api/controls/control.py

@@ -8,6 +8,7 @@ from ...models.responses import FilamentArgs
 from ..constants.commands import Commands
 from ..constants.endpoints import Endpoints
 from ..network.utils import NetworkUtils, json_from_response
+from .creator5_palette import snap_to_creator5_palette
 
 if TYPE_CHECKING:
     from ...client import FlashForgeClient
@@ -43,8 +44,11 @@ class Control:
         Homes the X, Y, and Z axes of the printer.
 
         Returns:
-            True if the command is successful, False otherwise.
+            True if the command is successful, False otherwise (including when the
+            printer has no TCP control channel, e.g. Creator 5).
         """
+        if not self.client.can_use_tcp("home_axes"):
+            return False
         return await self.tcp_client.home_axes()
 
     async def home_axes_rapid(self) -> bool:
@@ -52,8 +56,11 @@ class Control:
         Performs a rapid homing of the X, Y, and Z axes.
 
         Returns:
-            True if the command is successful, False otherwise.
+            True if the command is successful, False otherwise (including when the
+            printer has no TCP control channel, e.g. Creator 5).
         """
+        if not self.client.can_use_tcp("home_axes_rapid"):
+            return False
         return await self.tcp_client.rapid_home()
 
     async def set_external_filtration_on(self) -> bool:
@@ -202,8 +209,11 @@ class Control:
         Turns on the filament runout sensor.
 
         Returns:
-            True if the command is successful, False otherwise.
+            True if the command is successful, False otherwise (including when the
+            printer has no TCP control channel, e.g. Creator 5).
         """
+        if not self.client.can_use_tcp("turn_runout_sensor_on"):
+            return False
         return await self.tcp_client.turn_runout_sensor_on()
 
     async def turn_runout_sensor_off(self) -> bool:
@@ -211,10 +221,61 @@ class Control:
         Turns off the filament runout sensor.
 
         Returns:
-            True if the command is successful, False otherwise.
+            True if the command is successful, False otherwise (including when the
+            printer has no TCP control channel, e.g. Creator 5).
         """
+        if not self.client.can_use_tcp("turn_runout_sensor_off"):
+            return False
         return await self.tcp_client.turn_runout_sensor_off()
 
+    async def configure_slot(self, slot: int, material_name: str, hex_rgb: str) -> bool:
+        """
+        Configures the material name and color metadata for a material-station slot.
+        This information is shown on the printer UI and used for print validation; it
+        does not move any filament. Available on the AD5X and the Creator 5 / Creator 5 Pro.
+
+        The ``msConfig_cmd`` handler is firmware-confirmed present on the Creator 5
+        (Ghidra RE of ``firmwareExe`` 1.9.2). The Creator 5 has no removable IFS; it
+        surfaces its 4 tool heads as the 4 "slots", so this sets per-tool material
+        metadata. Both models share the same ``OrcaServer`` command path and wire
+        format. Note that **filament load/unload (``slotAction`` / ``ms_cmd``)
+        remains AD5X-only** — the Creator 5 firmware has no ``ms_cmd``.
+
+        The firmware accepts arbitrary material strings, but the two models render
+        the slot color icon differently:
+
+         - AD5X: accepts freeform hex (the leading "#" is stripped before sending).
+         - Creator 5 / 5 Pro: renders an icon ONLY when ``rgb`` is a byte-for-byte,
+           case-sensitive match against the firmware's 24-entry palette (WITH the
+           "#"); any other value falls back to White. This method snaps the
+           caller's color to the nearest palette entry automatically for the Creator 5.
+
+        Args:
+            slot: The slot number (1-4).
+            material_name: The material type (e.g., "PLA", "PETG").
+            hex_rgb: The color as a hex string.
+
+        Returns:
+            True if the command is successful, False otherwise.
+        """
+        if not self.client.is_ad5x and not self.client.is_creator5:
+            print("configure_slot() error, material station only available on AD5X / Creator 5.")
+            return False
+        # The AD5X and Creator 5 use MUTUALLY EXCLUSIVE color wire formats (see
+        # creator5_palette for the firmware match rules), so model-gate here:
+        #  - AD5X: freeform hex, the leading "#" stripped ("RRGGBB"). Unchanged.
+        #  - Creator 5 / 5 Pro: the firmware renders an icon ONLY on a byte-for-byte
+        #    match against its 24-entry palette (case-sensitive, WITH the "#"). Snap
+        #    the caller's color to the nearest palette entry in uppercase "#RRGGBB".
+        if self.client.is_creator5:
+            rgb = snap_to_creator5_palette(hex_rgb).hex
+        else:
+            rgb = hex_rgb[1:] if hex_rgb.startswith("#") else hex_rgb
+        return await self.send_control_command(
+            Commands.MATERIAL_STATION_CONFIG_CMD,
+            {"slot": slot, "mt": material_name, "rgb": rgb},
+        )
+
     async def send_control_command(self, command: str, args: dict[str, Any]) -> bool:
         """
         Sends a generic control command to the printer via HTTP POST.

flashforge_python_api-1.3.1/flashforge/api/controls/creator5_palette.py

@@ -0,0 +1,255 @@
+"""
+FlashForge Python API - Creator 5 / Creator 5 Pro material-station slot color
+palette and perceptual nearest-color snapping.
+
+The Creator 5 ``msConfig_cmd`` only renders a color icon when the ``rgb`` field is
+an EXACT, case-sensitive, byte-for-byte match against one of the firmware's 24
+built-in palette strings (compared via ``std::operator==`` in ``firmwareExe``
+1.9.2). A non-match leaves the slot's color index at 0 (White). These values
+DIFFER from the AD5X palette (e.g. Blue is ``#4CAAF8`` here vs ``#45A8F9`` on the
+AD5X), so callers must snap against THIS list specifically.
+
+By contrast the AD5X accepts freeform hex (with the ``#`` stripped), so the two
+wire formats are mutually exclusive — see :func:`flashforge.api.controls.control.Control.configure_slot`
+for the model-gating that splits them.
+"""
+
+from __future__ import annotations
+
+import math
+import re
+from dataclasses import dataclass
+
+# The color-space math in this module mirrors the published CIEDE2000 / CIE L*a*b*
+# notation (L, a, b, C', h', etc.) verbatim so it can be checked against the
+# reference. PEP 8 lowercase locals are therefore relaxed here on purpose.
+# ruff: noqa: N806
+
+
+@dataclass(frozen=True)
+class Creator5PaletteColor:
+    """A single entry in the Creator 5 firmware color palette."""
+
+    index: int
+    """Firmware palette index (0 = White = the no-match fallback)."""
+
+    name: str
+    """Color name as shown on the printer UI."""
+
+    hex: str  # noqa: N815 - field mirrors the TS `hex` property name
+    """Wire value sent to the printer, always uppercase ``#RRGGBB``."""
+
+
+#: The firmware's 24-entry UI palette (firmwareExe 1.9.2, Ghidra-confirmed).
+#: Index 0 (White) is also what the firmware falls back to on a no-match.
+CREATOR5_PALETTE: tuple[Creator5PaletteColor, ...] = (
+    Creator5PaletteColor(0, "White", "#FFFFFF"),
+    Creator5PaletteColor(1, "Yellow", "#FFF245"),
+    Creator5PaletteColor(2, "Light Green", "#DEF578"),
+    Creator5PaletteColor(3, "Green", "#21CC3D"),
+    Creator5PaletteColor(4, "Dark Green", "#167A4B"),
+    Creator5PaletteColor(5, "Teal", "#156682"),
+    Creator5PaletteColor(6, "Cyan", "#24E4A0"),
+    Creator5PaletteColor(7, "Light Blue", "#7BD9F0"),
+    Creator5PaletteColor(8, "Blue", "#4CAAF8"),
+    Creator5PaletteColor(9, "Dark Blue", "#2E54DD"),
+    Creator5PaletteColor(10, "Purple", "#48358C"),
+    Creator5PaletteColor(11, "Violet", "#A341F7"),
+    Creator5PaletteColor(12, "Magenta", "#F435F6"),
+    Creator5PaletteColor(13, "Pink", "#D5B4DE"),
+    Creator5PaletteColor(14, "Coral", "#FA6173"),
+    Creator5PaletteColor(15, "Red", "#F82D29"),
+    Creator5PaletteColor(16, "Brown", "#805003"),
+    Creator5PaletteColor(17, "Orange", "#F9903B"),
+    Creator5PaletteColor(18, "Cream", "#FCEBD7"),
+    Creator5PaletteColor(19, "Tan", "#D5C5A1"),
+    Creator5PaletteColor(20, "Dark Brown", "#B17C38"),
+    Creator5PaletteColor(21, "Gray", "#8C8C89"),
+    Creator5PaletteColor(22, "Light Gray", "#BEBEBE"),
+    Creator5PaletteColor(23, "Black", "#1B1B1B"),
+)
+
+# 25^7, the CIEDE2000 chroma weighting constant.
+_25_POW_7 = 25.0 ** 7
+
+# D65 reference white point used by the sRGB -> XYZ transform.
+_D65_XN = 0.95047
+_D65_YN = 1.0
+_D65_ZN = 1.08883
+
+
+def _srgb_to_linear(channel: float) -> float:
+    """sRGB component (0-255) channel transfer function -> linear value (0-1)."""
+    c = channel / 255.0
+    return c / 12.92 if c <= 0.04045 else ((c + 0.055) / 1.055) ** 2.4
+
+
+def _rgb_to_lab(r: float, g: float, b: float) -> tuple[float, float, float]:
+    """
+    Converts an sRGB color (0-255 channels) to CIE L*a*b* under a D65 illuminant.
+    Used as the perceptual basis for the CIEDE2000 nearest-color match.
+    """
+    R = _srgb_to_linear(r)
+    G = _srgb_to_linear(g)
+    B = _srgb_to_linear(b)
+
+    x = R * 0.4124564 + G * 0.3575761 + B * 0.1804375
+    y = R * 0.2126729 + G * 0.7151522 + B * 0.072175
+    z = R * 0.0193339 + G * 0.119192 + B * 0.9503041
+
+    x /= _D65_XN
+    y /= _D65_YN
+    z /= _D65_ZN
+
+    def f(t: float) -> float:
+        return math.cbrt(t) if t > 0.008856 else 7.787 * t + 16.0 / 116.0
+
+    fx = f(x)
+    fy = f(y)
+    fz = f(z)
+
+    return (116.0 * fy - 16.0, 500.0 * (fx - fy), 200.0 * (fy - fz))
+
+
+def _atan2_deg(ordinate: float, abscissa: float) -> float:
+    """atan2 -> hue in degrees, normalized to [0, 360)."""
+    h = math.degrees(math.atan2(ordinate, abscissa))
+    if h < 0:
+        h += 360.0
+    return h
+
+
+def _delta_e_2000(c1: tuple[float, float, float], c2: tuple[float, float, float]) -> float:
+    """
+    CIEDE2000 color difference between two L*a*b* colors (kL=kC=kH=1). This is the
+    most accurate standard delta-E metric and is preferred here because the
+    firmware renders only an exact palette match — snapping to the wrong
+    perceptual neighbor would display the wrong color on the printer.
+    """
+    L1, a1, b1 = c1
+    L2, a2, b2 = c2
+
+    C1 = math.sqrt(a1 * a1 + b1 * b1)
+    C2 = math.sqrt(a2 * a2 + b2 * b2)
+    Cbar = (C1 + C2) / 2.0
+    Cbar7 = Cbar ** 7
+    G = 0.5 * (1 - math.sqrt(Cbar7 / (Cbar7 + _25_POW_7)))
+
+    a1p = (1 + G) * a1
+    a2p = (1 + G) * a2
+    C1p = math.sqrt(a1p * a1p + b1 * b1)
+    C2p = math.sqrt(a2p * a2p + b2 * b2)
+    h1p = _atan2_deg(b1, a1p)
+    h2p = _atan2_deg(b2, a2p)
+
+    dLp = L2 - L1
+    dCp = C2p - C1p
+    if C1p * C2p == 0:
+        dhp = 0.0
+    else:
+        diff = h2p - h1p
+        if abs(diff) <= 180:
+            dhp = diff
+        elif diff > 180:
+            dhp = diff - 360
+        else:
+            dhp = diff + 360
+    dHp = 2 * math.sqrt(C1p * C2p) * math.sin(math.radians(dhp) / 2.0)
+
+    Lbarp = (L1 + L2) / 2.0
+    Cbarp = (C1p + C2p) / 2.0
+    if C1p * C2p == 0:
+        hbarp = h1p + h2p
+    else:
+        diff = abs(h1p - h2p)
+        if diff <= 180:
+            hbarp = (h1p + h2p) / 2.0
+        elif h1p + h2p < 360:
+            hbarp = (h1p + h2p + 360) / 2.0
+        else:
+            hbarp = (h1p + h2p - 360) / 2.0
+
+    T = (
+        1
+        - 0.17 * math.cos(math.radians(hbarp - 30))
+        + 0.24 * math.cos(math.radians(2 * hbarp))
+        + 0.32 * math.cos(math.radians(3 * hbarp + 6))
+        - 0.20 * math.cos(math.radians(4 * hbarp - 63))
+    )
+
+    dTheta = 30 * math.exp(-(((hbarp - 275) / 25.0) ** 2))
+    Cbarp7 = Cbarp ** 7
+    RC = 2 * math.sqrt(Cbarp7 / (Cbarp7 + _25_POW_7))
+    SL = 1 + (0.015 * (Lbarp - 50) ** 2) / math.sqrt(20 + (Lbarp - 50) ** 2)
+    SC = 1 + 0.045 * Cbarp
+    SH = 1 + 0.015 * Cbarp * T
+    RT = -math.sin(math.radians(2 * dTheta)) * RC
+
+    termL = dLp / SL
+    termC = dCp / SC
+    termH = dHp / SH
+
+    return math.sqrt(termL * termL + termC * termC + termH * termH + RT * termC * termH)
+
+
+_HEX_RE = re.compile(r"^[0-9a-fA-F]{3}([0-9a-fA-F]{3})?$")
+
+
+def _hex_to_rgb(hex_str: str) -> tuple[int, int, int] | None:
+    """
+    Parses a hex color string (``#RRGGBB``, ``RRGGBB``, 3-digit shorthand, any
+    case) into its RGB channels. Returns None for unparseable input.
+    """
+    clean = hex_str.strip()
+    # Remove a single leading "#" (matches the TS replace(/^#/, '')).
+    if clean.startswith("#"):
+        clean = clean[1:]
+    if not _HEX_RE.match(clean):
+        return None
+    if len(clean) == 3:
+        clean = "".join(ch + ch for ch in clean)
+    return (int(clean[0:2], 16), int(clean[2:4], 16), int(clean[4:6], 16))
+
+
+# Palette entries with their L*a*b* values precomputed once at module load.
+_PALETTE_LAB: list[tuple[Creator5PaletteColor, tuple[float, float, float]]] = []
+for _color in CREATOR5_PALETTE:
+    _rgb = _hex_to_rgb(_color.hex)
+    if _rgb is None:
+        _rgb = (0, 0, 0)
+    _PALETTE_LAB.append((_color, _rgb_to_lab(_rgb[0], _rgb[1], _rgb[2])))
+
+
+def snap_to_creator5_palette(hex_str: str) -> Creator5PaletteColor:
+    """
+    Snaps an arbitrary hex color to the nearest entry in the Creator 5 firmware
+    palette using the CIEDE2000 perceptual distance in CIE L*a*b* space.
+
+    The returned :attr:`Creator5PaletteColor.hex` is always uppercase ``#RRGGBB``
+    and is guaranteed to be a byte-for-byte firmware match. Unparseable input
+    falls back to White (index 0, the firmware's own no-match fallback) with a
+    warning.
+
+    Args:
+        hex_str: The caller's color as a hex string (leading ``#`` optional, any case).
+
+    Returns:
+        The nearest Creator 5 palette entry.
+    """
+    rgb = _hex_to_rgb(hex_str)
+    if rgb is None:
+        print(
+            f'snap_to_creator5_palette: could not parse "{hex_str}" as hex; '
+            "falling back to White."
+        )
+        return CREATOR5_PALETTE[0]
+
+    target = _rgb_to_lab(rgb[0], rgb[1], rgb[2])
+    best = _PALETTE_LAB[0]
+    best_delta = float("inf")
+    for entry in _PALETTE_LAB:
+        delta = _delta_e_2000(target, entry[1])
+        if delta < best_delta:
+            best_delta = delta
+            best = entry
+    return best[0]

{flashforge_python_api-1.2.3 → flashforge_python_api-1.3.1}/flashforge/api/controls/files.py

@@ -35,10 +35,18 @@ class Files:
         """
         Retrieves a list of files stored locally on the printer.
 
+        HTTP-only printers (Creator 5 / 5 Pro) have no TCP/8899 file-listing
+        channel, so this falls back to the HTTP ``/gcodeList`` recent-file list
+        (mirroring ``Files.ts``) instead of hanging on a dead TCP socket.
+
         Returns:
             A list of file names, or empty list if retrieval fails.
         """
-        # This method uses the TCP client to get file list
+        if self.client.http_only:
+            entries = await self.get_recent_file_list()
+            return [e.gcode_file_name for e in entries if e.gcode_file_name]
+
+        # Legacy / 5M-family printers expose the file list over TCP.
         if hasattr(self.client, "tcp_client") and self.client.tcp_client:
             return await self.client.tcp_client.get_file_list_async()
         return []
@@ -47,6 +55,9 @@ class Files:
         """
         Retrieves a list of files stored locally on the printer.
 
+        HTTP-only printers (Creator 5 / 5 Pro) have no TCP/8899 file-listing
+        channel; see :meth:`get_file_list` for the HTTP fallback.
+
         Returns:
             A list of file names, or empty list if retrieval fails.
         """