flashforge-python-api 1.3.5__py3-none-any.whl → 1.5.0__py3-none-any.whl

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/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/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/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/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/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/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/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/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/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.

flashforge/models/machine_info.py

@@ -20,7 +20,7 @@ from pydantic import BaseModel, ConfigDict, Field, field_validator, model_valida
 # blast radius: pydantic fails a model as a unit, and `Info.get_detail_response`
 # turns any failure into "no data", which Home Assistant shows as an offline
 # printer. So a `ge=0` on a field nobody reads could take the whole integration
-# down. That is exactly what happened in issue #18, where a Creator 5 reporting
+# down. That is exactly what happened in ff-5mp-hass#18, where a Creator 5 reporting
 # `chamberTemp: -108` made every entity unavailable and the config flow report
 # `cannot_connect`.
 #
@@ -369,7 +369,7 @@ class FFPrinterDetail(BaseModel):
     z_axis_compensation: float | None = Field(default=None, alias="zAxisCompensation")
 
     # Firmware reports absent temperature hardware with a negative sentinel
-    # (-108 on a chamber-less Creator 5, issue #18) rather than by omitting the
+    # (-108 on a chamber-less Creator 5, ff-5mp-hass#18) rather than by omitting the
     # field. Map those to None here so "no sensor" reads as "not reported"
     # everywhere downstream, instead of as a -108 C reading or a hard failure.
     @field_validator(
@@ -514,7 +514,12 @@ class FFMachineInfo(BaseModel):
 
     # Extras
     print_eta: str = "00:00"
-    completion_time: datetime = Field(default_factory=datetime.now)
+    # None whenever the print is not advancing (paused, heating, ready, error,
+    # ...). The firmware freezes `estimatedTime` outside the PRINTING state, so
+    # an absolute timestamp derived from it would recede in real time rather
+    # than hold. Use `print_eta` / `estimated_time` for the remaining duration,
+    # which stays valid in every state.
+    completion_time: datetime | None = None
     formatted_run_time: str = "00:00"
     formatted_total_run_time: str = "0h:0m"
 

flashforge/models/responses.py

@@ -175,12 +175,12 @@ class AD5XUploadParams(BaseModel):
 class Creator5JobParams(BaseModel):
     """Parameters for starting a Creator 5 / Creator 5 Pro local print job.
 
-    Distinct from the AD5X job params: the Creator 5 maps materials at print-start
-    (POST /printGcode) rather than upload time, so the body carries NO
-    ``useMatlStation`` / ``gcodeToolCnt`` / ``firstLayerInspection`` (the latter
-    doesn't exist on the C5). ``flowCalibration`` and ``timeLapseVideo`` are always
-    present (default False); ``material_mappings`` is optional for a single-tool
-    print.
+    The body carries NO ``useMatlStation`` / ``gcodeToolCnt`` /
+    ``firstLayerInspection`` (the latter doesn't exist on the C5).
+    ``flowCalibration`` and ``timeLapseVideo`` are always present (default False).
+    Map 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). Mappings take effect only for a .3mf file.
     """
 
     model_config = ConfigDict(extra="forbid", populate_by_name=True)
@@ -196,16 +196,18 @@ class Creator5JobParams(BaseModel):
     material_mappings: list[AD5XMaterialMapping] | None = Field(
         default=None,
         max_length=4,
-        description="Optional per-tool material mappings (1-4 items); omit for single-tool",
+        description="Per-tool material mappings (1-4 items); recommended for every print",
     )
 
 
 class Creator5UploadParams(BaseModel):
     """Parameters for uploading a file to a Creator 5 / Creator 5 Pro.
 
-    Mirrors the AD5X upload but omits ``firstLayerInspection`` (absent on the C5)
-    and the ``materialMappings`` header (the C5 maps materials at print-start, not
-    upload). The C5 firmware checks the booleans as the string "true"/"false".
+    Mirrors the AD5X upload but omits ``firstLayerInspection`` (absent on the
+    C5). ``material_mappings`` is sent as the base64 ``materialMappings`` header
+    only when ``start_print`` is true. The firmware only logs ``use_matl_station``
+    and ``gcode_tool_cnt``. The C5 firmware checks the booleans as the string
+    "true"/"false".
     """
 
     model_config = ConfigDict(extra="forbid", populate_by_name=True)
@@ -223,6 +225,11 @@ class Creator5UploadParams(BaseModel):
     gcode_tool_cnt: int = Field(
         ge=1, le=4, description="Number of tools in the G-code (1-4 for the C5)"
     )
+    material_mappings: list[AD5XMaterialMapping] | None = Field(
+        default=None,
+        max_length=4,
+        description="Optional per-tool material mappings, sent only when start_print is true",
+    )
 
 
 class GCodeListResponse(GenericResponse):

{flashforge_python_api-1.3.5.dist-info → flashforge_python_api-1.5.0.dist-info}/METADATA

@@ -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.dist-info → flashforge_python_api-1.5.0.dist-info}/RECORD

@@ -1,17 +1,17 @@
-flashforge/__init__.py,sha256=rWsmx8X1akurtqwcS_cSeZGkzbSXc3Nnd1xeNsnAAj4,5472
-flashforge/client.py,sha256=nDtnv3y9XlEQknIkgIUiuOYAiyTEGbQ7tHBdCs2fg1I,21432
-flashforge/exceptions.py,sha256=rZwBJHyqqtoI6cgd8iGOvPH8EDcytA3lyU3FoVMJgyU,1732
+flashforge/__init__.py,sha256=dDzpUX4K063NRYBvhj1QkfFxxQpb1aSMMkSEFQTzxhI,5472
+flashforge/client.py,sha256=5DxKJyicq5LX8xfZUtIB0Q-_sh8kIFNzMMV_3Dos5fk,22519
+flashforge/exceptions.py,sha256=LQli1pAH2X8fm3jsRD4caz0Mn-nyBjNpaJh_En7YJw0,1737
 flashforge/api/__init__.py,sha256=vQz-DkG6LTH39bI4fyiUc0D9jQzemLh45pORLptSOlg,335
 flashforge/api/constants/__init__.py,sha256=Q0HL2tqSBYPd4Oz49VHLS3qUvRuv__GCvTGecaLrQ-Y,163
-flashforge/api/constants/commands.py,sha256=XM2rooBESPDaywlZrfW2ECTaLLFaSKXkJ7FQ-RBmVdY,578
+flashforge/api/constants/commands.py,sha256=9WggRLBgidf4cBBXMllQVAZr64UvHOf7gNHlPEKvo2g,579
 flashforge/api/constants/endpoints.py,sha256=oZtOFfkU64THDeCMUIVv6_0L-BOUZzgLKAUfjHkUhi8,337
 flashforge/api/controls/__init__.py,sha256=53s-H25Pjwr0kvPk8MZ2Twy8VHGqGcO6Q6uBphhEOh4,293
-flashforge/api/controls/control.py,sha256=OgE7K6NkFLwFN1r_q5g1RPwYC8MCt0f6L5CZxDW44d8,15151
-flashforge/api/controls/creator5_palette.py,sha256=zdD3PIXx7hCVj2Fmv1CSFOaqogRUPeBaymgY2DFiMxk,8835
-flashforge/api/controls/files.py,sha256=Jk2ySrJdw2QDk1CJlGfY4bTmZJocx4GXztkEqE4rRaI,8830
-flashforge/api/controls/info.py,sha256=O6NVGSRwhArUqxCGXHK5WV20-Nn_8rHGUMbZheXXEjs,23973
-flashforge/api/controls/job_control.py,sha256=NnACm4LPUz4n8lnRiUl33jilWekS1b6HQTbP--nDzZc,33225
-flashforge/api/controls/temp_control.py,sha256=EOO5TkODirjFcnQ7rZrirxAweHBdVin032AWj-Z8VQs,13040
+flashforge/api/controls/control.py,sha256=mK-k3SX53wrq3-aPmMaAbAnqcOaJgvuNSR-sm1aowJM,15099
+flashforge/api/controls/creator5_palette.py,sha256=1I6QfAYlCJcpqPzrySsXfn2EST04QYHZKVxCRnxu4AQ,8795
+flashforge/api/controls/files.py,sha256=tOqPgf9SBIvJBgno1GMAROdoDHF_ZJOmbEac1ikq_HI,8769
+flashforge/api/controls/info.py,sha256=E-VepEeTyquh50ssckpMGIkH9cagNZGUzn_Zb-bPplY,24846
+flashforge/api/controls/job_control.py,sha256=e_8A1-avghNGQ3OBzTbScDnUCUOJobdiulFCyXtyb8w,35294
+flashforge/api/controls/temp_control.py,sha256=_qrKCfjKJsPE4dj6bXZeJRH2FjLKx2T2V3pyG2oLrgI,12991
 flashforge/api/filament/__init__.py,sha256=isT2dl0hzUS0xMTXMm4Tip0GTG1gCsm8LKWa9xPu4Y8,104
 flashforge/api/filament/filament.py,sha256=TtcC2G2nD9Sq4cOrCZzFLZ6Q0Ve-zfrfuEF9uQ8M3eE,1214
 flashforge/api/misc/__init__.py,sha256=1AG7vOMRBZQtHp6QUzfr9alcJPeNv3JpU44NrznxDHs,211
@@ -24,8 +24,8 @@ flashforge/api/network/utils.py,sha256=Q5-Vj_1VN611QV_TGpDzrrZ2X8PqaGT0j00BhSHv5
 flashforge/discovery/__init__.py,sha256=G0WiP70EhfHdjXR1RNlv6xjhyHOdo-HWyOm9J0ds4SM,828
 flashforge/discovery/discovery.py,sha256=-hOmVIpn8gu-rPYo8FRBfhKb_tBqwamLfmoPVYaDzLI,27614
 flashforge/models/__init__.py,sha256=hdcK0E4KeDfv_A8Y2aPOHgHziwTjP1RPb_VP-89dOzQ,1086
-flashforge/models/machine_info.py,sha256=o0rpT6DPWojg8VMfYleMFIqEaidDvsY6E0MstaVHOT0,24065
-flashforge/models/responses.py,sha256=10-8yFfZtLuDmH1TK2xVYl-Uf-zT2WEJnpb2H5ZK3ZU,10637
+flashforge/models/machine_info.py,sha256=Chcpoeus1pppPKMDNsGIiCGGQ6tATezUT6ML5MjubD0,24407
+flashforge/models/responses.py,sha256=P0Zo8c6QywbS0_kEWq-8HsRwwQkCiG4MfeDcGADpPHg,10965
 flashforge/tcp/__init__.py,sha256=hpnqoWHeRtTwJPzdsVlwGt1njKbAkrgIHKADkLSIRec,1317
 flashforge/tcp/a3_client.py,sha256=Aqb6MuKkjnNUVdE2LbZKd7bPlFK8XPIm17C_BG_PuNU,15867
 flashforge/tcp/a4_client.py,sha256=snmAvTCpSWFjxb8h6V7H4tk5yOoMqKEzKoBY_1JaaPs,11213
@@ -42,8 +42,8 @@ flashforge/tcp/parsers/print_status.py,sha256=C-KzukhK0TR86AP3t3XrMH4dief6pa3I-y
 flashforge/tcp/parsers/printer_info.py,sha256=CHPs6nJfEByXyG3co7Nb8_ygggxkYuc7A9O9bpQEqXE,5441
 flashforge/tcp/parsers/temp_info.py,sha256=9wRGUM9cKvDiZD3SIxBx_qVLZbeXoYsoY3-R3vN3H4g,7938
 flashforge/tcp/parsers/thumbnail_info.py,sha256=1U1S_gcIZ2lDpEA4622ywUew6TVw0BnzjlBAiihQwzk,10478
-flashforge_python_api-1.3.5.dist-info/METADATA,sha256=oSmQO3OQPkDynC5evAjLOdK6jpCaD2SmT7DZk6lC5CY,4970
-flashforge_python_api-1.3.5.dist-info/WHEEL,sha256=lCkmxWfQsSc9CfIClYeavTdQeEX2toPqufh9gI35EQA,87
-flashforge_python_api-1.3.5.dist-info/entry_points.txt,sha256=AkOxlsLvQ7cvMLxn7tlzfKp_DCH2hXhbVceHIXxawpU,66
-flashforge_python_api-1.3.5.dist-info/licenses/LICENSE,sha256=-cTA-hrmvlb3pqlQrBZQXUnKayhUjsLJMPb7TD91frM,1067
-flashforge_python_api-1.3.5.dist-info/RECORD,,
+flashforge_python_api-1.5.0.dist-info/METADATA,sha256=hpoGseNvotHfDNDJXpItMUbp9Ehr75sj-wgOgO2jfDU,4970
+flashforge_python_api-1.5.0.dist-info/WHEEL,sha256=W3fkpkm7-wf9vBI5Z-7s0eWkeM-spu78I8Neb98DeEg,87
+flashforge_python_api-1.5.0.dist-info/entry_points.txt,sha256=AkOxlsLvQ7cvMLxn7tlzfKp_DCH2hXhbVceHIXxawpU,66
+flashforge_python_api-1.5.0.dist-info/licenses/LICENSE,sha256=-cTA-hrmvlb3pqlQrBZQXUnKayhUjsLJMPb7TD91frM,1067
+flashforge_python_api-1.5.0.dist-info/RECORD,,

{flashforge_python_api-1.3.5.dist-info → flashforge_python_api-1.5.0.dist-info}/WHEEL

@@ -1,4 +1,4 @@
 Wheel-Version: 1.0
-Generator: hatchling 1.31.0
+Generator: hatchling 1.32.4
 Root-Is-Purelib: true
 Tag: py3-none-any