flashforge-python-api 1.3.5__tar.gz → 1.5.0__tar.gz

{flashforge_python_api-1.3.5 → flashforge_python_api-1.5.0}/CHANGELOG.md

@@ -5,6 +5,32 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [Unreleased]
+
+## [1.5.0] - 2026-09-26
+
+### Added
+
+- **`Creator5UploadParams.material_mappings`.** The Creator 5 firmware reads a base64 `materialMappings` upload header, the same format as the AD5X, and applies it when the upload starts the print (confirmed by firmware analysis of 1.9.6 and 1.9.8, Creator 5 and Creator 5 Pro). `upload_file_creator5` now sends the header when `start_print` is true and the mappings are valid. With `start_print` false the mappings are not sent and a warning is logged: the firmware keeps upload mappings in memory until the next print ends, so they would apply to a later, unrelated print. The recommended flow is unchanged: upload without starting, then call `start_creator5_job` with the mappings.
+
+### Changed
+
+- **Creator 5 documentation corrected.** The firmware only logs `useMatlStation` and `gcodeToolCnt` on upload. `/printGcode` applies mappings to any file on the printer, not only the last upload. Without mappings, each tool prints from the slot with the slicer's filament number (filament 1 prints from slot 1), whatever is loaded there, so send a mapping for every tool, including a single-tool print. Mappings take effect only for a `.3mf` file.
+
+### Fixed
+
+- **Concurrent commands no longer interleave on the printer's HTTP API.** The Python port had no serialization on its command paths, so two commands sent at the same moment (say a light toggle racing a pause) could overlap in flight, and the printer — which handles one command at a time — could drop or mis-acknowledge one. Every command-submission POST (`/control`, `/product`, `/printGcode`) now holds one FIFO lock, so commands run one at a time, in the order callers sent them. Uploads (`/uploadGcode`) and read/poll requests (`/detail`, `/gcodeList`, `/gcodeThumb`, camera probes) stay outside the lock on purpose: an upload can run for minutes, and a pause or stop must never queue behind one. A command sent after a failing one still goes through; the lock releases on error. Matches the parallel fix in `ff-5mp-api-ts`. No public API changed.
+
+## [1.4.0] - 2026-08-10
+
+### Fixed
+
+- **`completion_time` no longer recedes while a print is paused.** It was derived as `datetime.now() + estimated_time` on every parse, which is only stable while the firmware is counting `estimatedTime` down. It isn't: the field freezes the moment the print stops advancing, so with the second term fixed and the first still moving, the derived timestamp stepped forward one minute per minute — after an hour of a clog pause it claimed the print would finish an hour later than it had when the pause began, and it never stopped receding. `completion_time` is now `None` unless `machine_state` is `PRINTING` — `HEATING` is excluded for the same reason as the paused states, since the pre-print warmup does not advance the job either and drifts identically, just for minutes rather than hours. Found while checking whether the Creator 5 Pro clog fix in 1.3.5 left the ETA sensible; the same derivation exists in `ff-5mp-api-ts` and in four display sites across FlashForgeUI-Electron and FlashForgeWebUI, all fixed alongside. It originates in the C# `ff-5mp-api` (`MachineInfo.cs:210`), which every port inherited it from.
+
+### Changed
+
+- **BREAKING: `FFMachineInfo.completion_time` is now `datetime | None`** (was `datetime`, defaulting to `datetime.now()`). Consumers that read it without a `None` check need one. `print_eta` and `estimated_time` are unchanged and stay correct in every state — the remaining *duration* was never wrong, only its conversion to an absolute timestamp. Prefer them where a duration will do.
+
 ## [1.3.5] - 2026-08-08
 
 ### Fixed
@@ -235,7 +261,10 @@ 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.3.3...HEAD
+[Unreleased]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.4.0...HEAD
+[1.4.0]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.3.5...v1.4.0
+[1.3.5]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.3.4...v1.3.5
+[1.3.4]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.3.3...v1.3.4
 [1.3.3]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.3.2...v1.3.3
 [1.3.2]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.3.1...v1.3.2
 [1.3.1]: https://github.com/GhostTypes/ff-5mp-api-py/compare/v1.3.0...v1.3.1

{flashforge_python_api-1.3.5 → flashforge_python_api-1.5.0}/CLAUDE.md

@@ -207,7 +207,8 @@ twine check dist/*
 ```
 
 **Version Management**:
-- Current version: **1.3.3** (as of 2026-07-26)
+- Current version: **1.4.0** (as of 2026-08-10)
+- Two files carry the version and both must be bumped together: `pyproject.toml` (`version = `) and `flashforge/__init__.py` (`__version__ = `). The publish workflow validates only the first, so a mismatched `__version__` ships silently.
 - Package name: `flashforge-python-api`
 - PyPI: https://pypi.org/project/flashforge-python-api/
 - Build system: Hatchling (defined in `pyproject.toml`)
@@ -312,6 +313,20 @@ TCP `M115` remains available for older printers that actually serve it, and its
 
 > Known gap: `client.initialize()` → `init_control()` (`client.py:262`) and `get_temperatures()` (`client.py:531`) call the TCP client unguarded and would hang on a Creator 5. Neither is used by `ff-5mp-hass`. Gate them before calling either from new code.
 
+### Derived Timestamps Are Gated on an Advancing Print
+
+`_ADVANCING_STATES` in `api/controls/info.py` contains `MachineState.PRINTING` and nothing else. `FFMachineInfo.completion_time` is `datetime | None` (nullable as of 1.4.0) and is derived only inside that set.
+
+`datetime.now() + estimated_time` only holds still while the firmware counts `estimated_time` down. It freezes that field the moment the print stops advancing, so with one term fixed and the clock still moving the timestamp walks forward a minute per minute — after an hour of a clog pause it claimed the print would finish an hour later than it had when the pause began, and it never stopped receding. **`HEATING` is deliberately excluded**: the pre-print warmup does not advance the job either and drifts identically, just for minutes rather than hours. Do not widen this set to "fix" a `None` during a pause — the `None` is the fix.
+
+`print_eta` and `estimated_time` are ungated and stay correct in every state; the remaining *duration* was never wrong, only its conversion to an absolute timestamp. Prefer them where a duration will do. The bad derivation originates in the C# `ff-5mp-api` (`MachineInfo.cs:210`) that every port inherited; the same gate now exists in `ff-5mp-api-ts`, `ff-5mp-hass`, FlashForgeUI-Electron, and FlashForgeWebUI.
+
+### Status Mapping: Reuse an Existing MachineState, Don't Add One
+
+Firmware sends statuses the documentation does not list. `"pause"` (Creator 5 Pro, firmware 1.9.4 — not the documented `"paused"`) maps to `PAUSED`, and `"downloading"` maps to `BUSY`, both added in 1.3.5. The `"pause"` case matters disproportionately because the printer pauses *itself* on a detected clog, so an unmapped value blanked the state at exactly the moment the user needed to know why the print stopped.
+
+**Map a new status onto an existing `MachineState` member rather than adding one.** A consumer that pins the enum to a fixed list breaks when a member appears; reusing one cannot break anyone. (`ff-5mp-hass` is not such a consumer — its `device_class=ENUM` sensor derives `options` from `MachineState` itself — but other downstreams are.) A dedicated `DOWNLOADING` state is a feature discussion, not a patch-release bugfix. Keep `"paused"` mapped alongside `"pause"`: firmware reporting one is no reason to drop the other.
+
 ### Error Handling
 - HTTP errors: Wrapped in aiohttp exceptions
 - TCP errors: Socket timeouts, connection refused

{flashforge_python_api-1.3.5 → flashforge_python_api-1.5.0}/PKG-INFO

@@ -1,6 +1,6 @@
-Metadata-Version: 2.4
+Metadata-Version: 2.5
 Name: flashforge-python-api
-Version: 1.3.5
+Version: 1.5.0
 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

{flashforge_python_api-1.3.5 → flashforge_python_api-1.5.0}/flashforge/__init__.py

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

{flashforge_python_api-1.3.5 → flashforge_python_api-1.5.0}/flashforge/api/constants/commands.py

@@ -11,5 +11,5 @@ class Commands:
     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).
+    # `ms_cmd` (verified in the firmware).
     MATERIAL_STATION_CONFIG_CMD = "msConfig_cmd"

{flashforge_python_api-1.3.5 → flashforge_python_api-1.5.0}/flashforge/api/controls/control.py

@@ -237,8 +237,8 @@ class Control:
         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
+        The ``msConfig_cmd`` handler is confirmed present on the Creator 5
+        (verified in firmware 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``)
@@ -303,24 +303,21 @@ class Control:
         logger.debug("Sending control command %s with args %s", command, args)
 
         try:
-            await self.client.is_http_client_busy()
-
             session = await self.client.get_http_session()
-            async with session.post(
-                self.client.get_endpoint(Endpoints.CONTROL),
-                json=payload,
-                headers={"Content-Type": "application/json"},
-            ) as response:
-                data = await json_from_response(response)
-                logger.debug("Control command %s reply: %s", command, data)
+            async with self.client.command_lock:
+                async with session.post(
+                    self.client.get_endpoint(Endpoints.CONTROL),
+                    json=payload,
+                    headers={"Content-Type": "application/json"},
+                ) as response:
+                    data = await json_from_response(response)
+                    logger.debug("Control command %s reply: %s", command, data)
 
-                return NetworkUtils.is_ok(data)
+                    return NetworkUtils.is_ok(data)
 
         except Exception as e:
             logger.warning("Error in send_control_command (%s): %s", command, e)
             return False
-        finally:
-            self.client.release_http_client()
 
     async def send_job_control_cmd(self, command: str) -> bool:
         """

{flashforge_python_api-1.3.5 → flashforge_python_api-1.5.0}/flashforge/api/controls/creator5_palette.py

@@ -4,8 +4,8 @@ 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
+built-in palette strings (verified in firmware 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.
 
@@ -43,7 +43,7 @@ class Creator5PaletteColor:
     """Wire value sent to the printer, always uppercase ``#RRGGBB``."""
 
 
-#: The firmware's 24-entry UI palette (firmwareExe 1.9.2, Ghidra-confirmed).
+#: The firmware's 24-entry UI palette (verified in firmware 1.9.2).
 #: Index 0 (White) is also what the firmware falls back to on a no-match.
 CREATOR5_PALETTE: tuple[Creator5PaletteColor, ...] = (
     Creator5PaletteColor(0, "White", "#FFFFFF"),

{flashforge_python_api-1.3.5 → flashforge_python_api-1.5.0}/flashforge/api/controls/files.py

@@ -78,10 +78,9 @@ class Files:
 
         The Creator 5 is the surprise there, and it is firmware, not a parsing gap:
         it is a newer printer than the AD5X but reports less (confirmed against a
-        Creator 5 Pro, 2026-08-05). Do not describe this method as "AD5X and newer" -
-        that phrasing cost a downstream integration three releases of chasing a bug
-        that was never in the code. Callers that need per-tool data on a Creator 5
-        must parse the 3mf themselves at upload time.
+        live Creator 5 Pro, 2026-08-05). Do not describe this method as "AD5X and
+        newer" - only the AD5X answers with `gcodeListDetail`. Callers that need
+        per-tool data on a Creator 5 must parse the 3mf themselves at upload time.
 
         Returns:
             A list of FFGcodeFileEntry objects. Returns an empty list if the request fails or an error occurs.

{flashforge_python_api-1.3.5 → flashforge_python_api-1.5.0}/flashforge/api/controls/info.py

@@ -46,6 +46,19 @@ PID_MODEL_NAMES: dict[int, str] = {
 }
 
 
+# The one state in which the firmware actually counts `estimatedTime` down.
+# Outside it the field freezes at its last value while the wall clock keeps
+# moving, so `now() + estimatedTime` walks forward one minute per minute instead
+# of holding still - a paused print appears to recede forever. The duration
+# stays correct throughout; only its conversion to an absolute timestamp is
+# invalid, which is why `print_eta` is ungated and `completion_time` is not.
+#
+# HEATING is deliberately excluded. The pre-print warmup does not advance the
+# job either, so the same drift applies - it just lasts minutes rather than
+# hours, which is why it is easy to miss.
+_ADVANCING_STATES = frozenset({MachineState.PRINTING})
+
+
 class MachineInfoParser:
     """
     Transforms printer detail data from the API response format into a structured FFMachineInfo object.
@@ -75,7 +88,14 @@ class MachineInfoParser:
             formatted_run_time = MachineInfoParser._format_time_from_seconds(
                 getattr(detail, "print_duration", 0) or 0
             )
-            completion_time = datetime.now() + timedelta(seconds=estimated_time)
+            machine_state = MachineInfoParser._get_machine_state(
+                getattr(detail, "status", "") or ""
+            )
+            completion_time = (
+                datetime.now() + timedelta(seconds=estimated_time)
+                if machine_state in _ADVANCING_STATES
+                else None
+            )
 
             total_minutes = getattr(detail, "cumulative_print_time", 0) or 0
             hours = total_minutes // 60
@@ -255,9 +275,7 @@ class MachineInfoParser:
                 print_speed_adjust=getattr(detail, "print_speed_adjust", 0) or 0,
                 filament_type=getattr(detail, "right_filament_type", "") or "",
                 # Machine state
-                machine_state=MachineInfoParser._get_machine_state(
-                    getattr(detail, "status", "") or ""
-                ),
+                machine_state=machine_state,
                 status=getattr(detail, "status", "") or "",
                 total_print_layers=getattr(detail, "target_print_layer", 0) or 0,
                 tvoc=getattr(detail, "tvoc", 0) or 0,
@@ -386,7 +404,7 @@ class Info:
         if machine_info is None:
             # We validated the payload but could not build our own model from
             # it - that is a bug on our side, not an unreachable printer, and
-            # reporting it as the latter is what issue #18 was about.
+            # reporting it as the latter is what ff-5mp-hass#18 was about.
             raise FlashForgeResponseError(
                 "The /detail payload was read but could not be converted into machine info",
                 endpoint=Endpoints.DETAIL,
@@ -444,7 +462,7 @@ class Info:
         This exists so callers can inspect identity fields - above all `pid` -
         without first having to successfully validate the ~50 unrelated fields
         in the payload. A supported printer must never be rejected because of a
-        field that has nothing to do with whether it is supported (issue #18).
+        field that has nothing to do with whether it is supported (ff-5mp-hass#18).
 
         Returns:
             The decoded response body, or None if the printer could not be

{flashforge_python_api-1.3.5 → flashforge_python_api-1.5.0}/flashforge/api/controls/job_control.py

@@ -253,16 +253,17 @@ class JobControl:
 
         try:
             session = await self.client.get_http_session()
-            async with session.post(
-                self.client.get_endpoint(Endpoints.GCODE_PRINT),
-                json=payload,
-                headers={"Content-Type": "application/json"},
-            ) as response:
-                if response.status != 200:
-                    return False
+            async with self.client.command_lock:
+                async with session.post(
+                    self.client.get_endpoint(Endpoints.GCODE_PRINT),
+                    json=payload,
+                    headers={"Content-Type": "application/json"},
+                ) as response:
+                    if response.status != 200:
+                        return False
 
-                result = await json_from_response(response)
-                return NetworkUtils.is_ok(result)
+                    result = await json_from_response(response)
+                    return NetworkUtils.is_ok(result)
 
         except Exception as error:
             logger.warning("print_local_file error: %s", error)
@@ -422,16 +423,17 @@ class JobControl:
 
         try:
             session = await self.client.get_http_session()
-            async with session.post(
-                self.client.get_endpoint(Endpoints.GCODE_PRINT),
-                json=payload,
-                headers={"Content-Type": "application/json"},
-            ) as response:
-                if response.status != 200:
-                    return False
+            async with self.client.command_lock:
+                async with session.post(
+                    self.client.get_endpoint(Endpoints.GCODE_PRINT),
+                    json=payload,
+                    headers={"Content-Type": "application/json"},
+                ) as response:
+                    if response.status != 200:
+                        return False
 
-                result = await json_from_response(response)
-                return NetworkUtils.is_ok(result)
+                    result = await json_from_response(response)
+                    return NetworkUtils.is_ok(result)
 
         except Exception as error:
             logger.warning("AD5X multi-color job error: %s", error)
@@ -474,40 +476,59 @@ class JobControl:
 
         try:
             session = await self.client.get_http_session()
-            async with session.post(
-                self.client.get_endpoint(Endpoints.GCODE_PRINT),
-                json=payload,
-                headers={"Content-Type": "application/json"},
-            ) as response:
-                if response.status != 200:
-                    return False
+            async with self.client.command_lock:
+                async with session.post(
+                    self.client.get_endpoint(Endpoints.GCODE_PRINT),
+                    json=payload,
+                    headers={"Content-Type": "application/json"},
+                ) as response:
+                    if response.status != 200:
+                        return False
 
-                result = await json_from_response(response)
-                return NetworkUtils.is_ok(result)
+                    result = await json_from_response(response)
+                    return NetworkUtils.is_ok(result)
 
         except Exception as error:
             logger.warning("AD5X single-color job error: %s", error)
             raise error
 
     # --- Creator 5 / Creator 5 Pro ---
-    # The Creator 5 splits the material-station workflow across two requests,
-    # unlike the AD5X (which maps materials at upload time). On the C5:
-    #   1. Upload the file (POST /uploadGcode). The firmware reads `useMatlStation`
-    #      and `gcodeToolCnt` here to register the file as a multi-tool job. There
-    #      is NO `firstLayerInspection` header (the field doesn't exist on the
-    #      C5), and the booleans are checked as the string "true"/"false".
-    #   2. Start the print (POST /printGcode) with the per-tool
-    #      `materialMappings`. See start_creator5_job.
+    # The Creator 5 firmware applies material mappings in two places:
+    #   - POST /printGcode reads `materialMappings` for any file already on the
+    #     printer (see start_creator5_job). This is the recommended path: upload
+    #     with start_print=False, then start with the mappings.
+    #   - POST /uploadGcode also reads a base64 `materialMappings` header, the
+    #     same format as the AD5X, and applies it when `printNow` is true.
+    # The firmware only logs `useMatlStation` and `gcodeToolCnt` on upload; they
+    # have no effect. There is NO `firstLayerInspection` header (the field doesn't
+    # exist on the C5), and the booleans are checked as the string "true"/"false".
+    #
+    # Mappings only take effect for a .3mf file. Without mappings, tool N prints
+    # from the slot with the slicer's filament number (filament 1 -> slot 1),
+    # whatever is loaded there. Send a mapping for every tool, including a
+    # single-tool print.
 
     async def upload_file_creator5(self, params: Creator5UploadParams) -> bool:
         """
         Uploads a file (.gcode or .3mf) to a Creator 5 / Creator 5 Pro via
         ``POST /uploadGcode``, with the C5-specific material-station headers.
 
-        Unlike :meth:`upload_file_ad5x` this sends no ``firstLayerInspection``
-        header (the C5 has no such field) and no ``materialMappings`` header (the
-        C5 maps materials at print-start, not upload). Booleans are sent as the
-        string "true"/"false".
+        Recommended flow: upload with ``start_print=False``, then call
+        :meth:`start_creator5_job` with a mapping for every tool. To start in one
+        request instead, pass ``material_mappings`` with ``start_print=True``: the
+        firmware reads them from a base64 ``materialMappings`` header, like the
+        AD5X.
+
+        ``material_mappings`` is sent only when ``start_print`` is true. The
+        firmware keeps upload mappings in memory until the next print ends, so
+        mappings on an upload that does not start would apply to a later,
+        unrelated print.
+
+        ``useMatlStation`` and ``gcodeToolCnt`` are sent for parity with
+        FlashForge's own clients; the firmware only logs them. Unlike
+        :meth:`upload_file_ad5x` this sends no ``firstLayerInspection`` header
+        (the C5 has no such field). Booleans are sent as the string
+        "true"/"false".
 
         Args:
             params: Creator 5 upload parameters.
@@ -537,8 +558,7 @@ class JobControl:
 
         try:
             # C5 upload headers. No firstLayerInspection (absent on the C5);
-            # booleans sent as "true"/"false" (firmware checks for "true"); no
-            # materialMappings header (C5 maps at print-start, not upload).
+            # booleans sent as "true"/"false" (firmware checks for "true").
             custom_headers = {
                 "serialNumber": self.client.serial_number,
                 "checkCode": self.client.check_code,
@@ -552,6 +572,20 @@ class JobControl:
                 "Expect": "100-continue",
             }
 
+            mappings = params.material_mappings or []
+            if mappings:
+                if not params.start_print:
+                    logger.warning(
+                        "upload_file_creator5: material_mappings ignored because start_print "
+                        "is False; pass them to start_creator5_job instead."
+                    )
+                else:
+                    if not self._validate_creator5_material_mappings(mappings):
+                        return False
+                    custom_headers["materialMappings"] = self._encode_material_mappings_to_base64(
+                        mappings
+                    )
+
             logger.debug("Creator 5 upload request headers: %s", redact_mapping(custom_headers))
 
             # Create multipart form data
@@ -600,13 +634,17 @@ class JobControl:
         """
         Starts a local print on a Creator 5 / Creator 5 Pro via ``POST /printGcode``.
 
-        This is the Creator 5's print-start material-matching command (distinct
-        from the AD5X, which maps materials at upload time). The file must already
-        be on the printer. Provide ``material_mappings`` for a multi-tool print, or
-        omit them for a single-tool print. Sends only the fields the Creator 5
-        firmware reads: NO ``useMatlStation`` / ``gcodeToolCnt`` (those live on the
-        upload) and NO ``firstLayerInspection`` (doesn't exist on the C5).
-        ``flowCalibration`` and ``timeLapseVideo`` are always present (default False).
+        This is the Creator 5's print-start material-matching command. The file
+        must already be on the printer; it can be a file uploaded long before, not
+        only the last upload. Sends only the fields the Creator 5 firmware reads:
+        NO ``useMatlStation`` / ``gcodeToolCnt`` and NO ``firstLayerInspection``
+        (doesn't exist on the C5). ``flowCalibration`` and ``timeLapseVideo`` are
+        always present (default False).
+
+        Provide a mapping for every tool, including a single-tool print. Without
+        mappings the firmware prints each tool from the slot with the slicer's
+        filament number (filament 1 -> slot 1), whatever is loaded there.
+        Mappings take effect only for a .3mf file.
 
         Args:
             params: File name, leveling flag, and optional flags / material mappings.
@@ -653,16 +691,17 @@ class JobControl:
 
         try:
             session = await self.client.get_http_session()
-            async with session.post(
-                self.client.get_endpoint(Endpoints.GCODE_PRINT),
-                json=payload,
-                headers={"Content-Type": "application/json"},
-            ) as response:
-                if response.status != 200:
-                    return False
+            async with self.client.command_lock:
+                async with session.post(
+                    self.client.get_endpoint(Endpoints.GCODE_PRINT),
+                    json=payload,
+                    headers={"Content-Type": "application/json"},
+                ) as response:
+                    if response.status != 200:
+                        return False
 
-                result = await json_from_response(response)
-                return NetworkUtils.is_ok(result)
+                    result = await json_from_response(response)
+                    return NetworkUtils.is_ok(result)
 
         except Exception as error:
             logger.warning("Creator 5 job error: %s", error)

{flashforge_python_api-1.3.5 → flashforge_python_api-1.5.0}/flashforge/api/controls/temp_control.py

@@ -27,12 +27,12 @@ TEMP_OFF = -100
 # Value that turns a tool/nozzle OFF inside the `nozzles` array. Unlike the scalar
 # heater fields (which accept TEMP_OFF = -100), the Creator 5 firmware's
 # per-nozzle parser only treats a literal 0 as "off" — it ignores -100 in the
-# `nozzles` array and the tool keeps heating. (Firmware-confirmed via tester
-# report; this is the v1.6.1 nozzle-off bugfix.)
+# `nozzles` array and the tool keeps heating (observed on live hardware;
+# this is the v1.6.1 nozzle-off bugfix).
 NOZZLE_OFF = 0
 # Number of tool/nozzle entries the Creator 5 firmware requires in the
 # `nozzles` array. The firmware ignores the array unless its length is exactly
-# this (confirmed via Ghidra: `size() == 4` check in the temp parser).
+# this (verified in the firmware).
 NOZZLE_COUNT = 4
 
 
@@ -188,7 +188,7 @@ class TempControl:
         """
         if self.client.http_only:
             # Creator 5 tools are driven ONLY via the `nozzles` array — the
-            # firmware's doTemperatureControl handler never reads
+            # firmware's temperature-control handler never reads
             # rightNozzle/leftNozzle. Target the primary tool (T0): the active
             # tool isn't reliably known over HTTP, so callers that need a
             # specific tool should use set_tool_temp(index, temp).

{flashforge_python_api-1.3.5 → flashforge_python_api-1.5.0}/flashforge/client.py

@@ -75,6 +75,15 @@ class FlashForgeClient:
         self._http_client_event = asyncio.Event()
         self._http_client_event.set()  # Not busy initially
 
+        # FIFO mutex for command submission. asyncio.Lock hands the lock to
+        # waiters in the order they asked for it. So command POSTs run one at
+        # a time, in submission order. Scope: command POSTs only (/control,
+        # /product, /printGcode). File uploads (/uploadGcode) and read/poll
+        # POSTs (/detail, /gcodeList, /gcodeThumb) stay outside the lock. An
+        # upload can run for minutes; pause and stop must never queue behind
+        # one.
+        self._command_lock = asyncio.Lock()
+
         # TCP client setup
         tcp_options = None
         if options and options.tcp_port is not None:
@@ -202,6 +211,19 @@ class FlashForgeClient:
             self._http_session = aiohttp.ClientSession(timeout=timeout, headers={"Accept": "*/*"})
         return self._http_session
 
+    @property
+    def command_lock(self) -> asyncio.Lock:
+        """
+        The FIFO lock that serializes command-submission HTTP POSTs.
+
+        Command POSTs (/control, /product, /printGcode) hold this lock while
+        the request is in flight. asyncio.Lock serves waiters in arrival order,
+        so concurrent commands run one at a time, first come first served.
+        Uploads and read/poll requests never take this lock. So a long upload
+        cannot delay a pause or stop command.
+        """
+        return self._command_lock
+
     async def initialize(self) -> bool:
         """
         Initializes the FlashForgeClient and verifies the connection to the printer.
@@ -442,43 +464,42 @@ class FlashForgeClient:
         """
         Sends a product command to the printer to retrieve control states.
 
-        This method sets the http_client_busy flag while the request is in progress.
+        This method holds the command lock while the request is in progress.
 
         Returns:
             True if the product command is sent successfully and valid data is received,
             False otherwise
         """
-        self._http_client_busy = True
-
         payload = {"serialNumber": self.serial_number, "checkCode": self.check_code}
 
         try:
             session = await self._ensure_http_session()
-            async with session.post(
-                self.get_endpoint(Endpoints.PRODUCT),
-                json=payload,
-                headers={"Content-Type": "application/json"},
-            ) as response:
-                if response.status != 200:
-                    return False
-
-                data = await json_from_response(response)
-
-                # Validate response structure
-                if not NetworkUtils.is_ok(data):
-                    return False
-
-                # Parse product response and set control states
-                product_response = ProductResponse(**data)
-                if product_response and product_response.product:
-                    product = product_response.product
-                    self.product_info = product
-                    self._detected_led_control = product.lightCtrlState != 0
-                    self._detected_filtration_control = not (
-                        product.internalFanCtrlState == 0 or product.externalFanCtrlState == 0
-                    )
-                    self._apply_feature_overrides()
-                    return True
+            async with self._command_lock:
+                async with session.post(
+                    self.get_endpoint(Endpoints.PRODUCT),
+                    json=payload,
+                    headers={"Content-Type": "application/json"},
+                ) as response:
+                    if response.status != 200:
+                        return False
+
+                    data = await json_from_response(response)
+
+                    # Validate response structure
+                    if not NetworkUtils.is_ok(data):
+                        return False
+
+                    # Parse product response and set control states
+                    product_response = ProductResponse(**data)
+                    if product_response and product_response.product:
+                        product = product_response.product
+                        self.product_info = product
+                        self._detected_led_control = product.lightCtrlState != 0
+                        self._detected_filtration_control = not (
+                            product.internalFanCtrlState == 0 or product.externalFanCtrlState == 0
+                        )
+                        self._apply_feature_overrides()
+                        return True
 
         except ValidationError as error:
             # Distinct from a rejected check code, and it must not read as one:
@@ -496,8 +517,6 @@ class FlashForgeClient:
         except Exception as error:
             logger.warning("Error in send_product_command: %s", error)
             return False
-        finally:
-            self._http_client_busy = False
 
         return False
 

{flashforge_python_api-1.3.5 → flashforge_python_api-1.5.0}/flashforge/exceptions.py

@@ -15,7 +15,7 @@ class FlashForgeResponseError(FlashForgeError):
 
     This is deliberately distinct from a ``None`` return, which every HTTP
     control method uses for "could not reach the printer / the printer refused
-    us". Collapsing the two is what made issue #18 take three releases to
+    us". Collapsing the two is what made ff-5mp-hass#18 take three releases to
     diagnose: a Creator 5 reporting ``chamberTemp: -108`` (the firmware's "no
     chamber sensor" sentinel) surfaced in Home Assistant as ``cannot_connect``,
     pointing the user at their network for a schema problem.