feat(creator5): correct material-mapping, upload, and temp wire formats

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>

Author: GhostTypes

CHANGELOG.md

@@ -7,6 +7,18 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.6.0] - 2026-06-26
+
+### Added
+
+- **`JobControl.uploadFileCreator5(params)`** — Creator 5 / Creator 5 Pro file upload (`POST /uploadGcode`) with the C5-specific material-station headers. Unlike the AD5X, the C5 splits the multi-material workflow across two requests: the upload carries `useMatlStation` / `gcodeToolCnt` (the firmware reads them here to register a multi-tool job), and the per-tool mapping is sent separately at print-start via `startCreator5Job` (`POST /printGcode`). This path sends **no** `firstLayerInspection` header (the field doesn't exist on the C5) and **no** `materialMappings` header (mappings go on the print-start call), and the booleans are sent as the string `"true"`/`"false"` (the firmware checks for `"true"`, not `"1"`). `Creator5UploadParams` type exported.
+
+### Changed
+
+- **`Creator5MaterialMapping` now carries `toolMaterialColor` / `slotMaterialColor`.** A live C5 `/printGcode` capture confirmed the mapping shape is identical to the AD5X (it includes the tool/slot colors), not the 3-field `{ toolId, slotId, materialName }` we previously assumed. `startCreator5Job` validates the colors (`#RRGGBB`) like the AD5X path. **Breaking** for callers constructing `Creator5MaterialMapping` by hand — add the two color fields.
+- **`startCreator5Job` `/printGcode` body now always includes `flowCalibration` and `timeLapseVideo`** (default `false`), matching the exact body the FlashForge app sends. It still omits `useMatlStation` / `gcodeToolCnt` (those live on the upload) and `firstLayerInspection` (absent on the C5).
+- **Creator 5 `temperatureCtl_cmd` now always carries the 4-entry `nozzles` array**, even on a bed- or chamber-only command (unspecified tools default to `-200`/no-change). The confirmed C5 payload always includes the array; previously bed/chamber-only commands omitted it, which the firmware's `size() == 4` check could reject.
+
 ## [1.4.0] - 2026-06-25
 
 ### Added

src/api/controls/JobControl.test.ts

@@ -518,35 +518,64 @@ describe('JobControl', () => {
       (mockFiveMClient as { isCreator5: boolean }).isCreator5 = true;
     });
 
-    it('POSTs the Creator 5-native /printGcode body with 3-field mappings', async () => {
+    it('POSTs the Creator 5-native /printGcode body matching the captured shape', async () => {
       mockedAxios.post.mockResolvedValue({ status: 200, data: { code: 0, message: 'Success' } });
 
       const result = await jobControl.startCreator5Job({
         fileName: 'multi.3mf',
         levelingBeforePrint: true,
         materialMappings: [
-          { toolId: 0, slotId: 1, materialName: 'PLA' },
-          { toolId: 1, slotId: 3, materialName: 'PETG' },
+          {
+            toolId: 0,
+            slotId: 2,
+            materialName: 'PLA',
+            toolMaterialColor: '#2E54DD',
+            slotMaterialColor: '#2E54DD',
+          },
+          {
+            toolId: 1,
+            slotId: 3,
+            materialName: 'PETG',
+            toolMaterialColor: '#FF0000',
+            slotMaterialColor: '#FF0000',
+          },
         ],
       });
 
       expect(result).toBe(true);
       expect(mockedAxios.post).toHaveBeenCalledTimes(1);
       const [url, body] = mockedAxios.post.mock.calls[0];
       expect(url).toBe(`http://printer:8898${Endpoints.GCodePrint}`);
-      // Only Creator 5 fields — no AD5X-only useMatlStation/gcodeToolCnt/colors.
+      // Confirmed C5 capture: flowCalibration/timeLapseVideo always present, mappings
+      // carry colors (same shape as AD5X), and no useMatlStation/gcodeToolCnt (those
+      // live on the upload) or firstLayerInspection (doesn't exist on the C5).
       expect(body).toEqual({
         serialNumber: 'SN123456',
         checkCode: 'CC123456',
         fileName: 'multi.3mf',
         levelingBeforePrint: true,
+        flowCalibration: false,
+        timeLapseVideo: false,
         materialMappings: [
-          { toolId: 0, slotId: 1, materialName: 'PLA' },
-          { toolId: 1, slotId: 3, materialName: 'PETG' },
+          {
+            toolId: 0,
+            slotId: 2,
+            materialName: 'PLA',
+            toolMaterialColor: '#2E54DD',
+            slotMaterialColor: '#2E54DD',
+          },
+          {
+            toolId: 1,
+            slotId: 3,
+            materialName: 'PETG',
+            toolMaterialColor: '#FF0000',
+            slotMaterialColor: '#FF0000',
+          },
         ],
       });
       expect(body).not.toHaveProperty('useMatlStation');
       expect(body).not.toHaveProperty('gcodeToolCnt');
+      expect(body).not.toHaveProperty('firstLayerInspection');
     });
 
     it('omits materialMappings for a single-tool print', async () => {
@@ -566,7 +595,15 @@ describe('JobControl', () => {
       const result = await jobControl.startCreator5Job({
         fileName: 'bad.3mf',
         levelingBeforePrint: true,
-        materialMappings: [{ toolId: 0, slotId: 0, materialName: 'PLA' }],
+        materialMappings: [
+          {
+            toolId: 0,
+            slotId: 0,
+            materialName: 'PLA',
+            toolMaterialColor: '#2E54DD',
+            slotMaterialColor: '#2E54DD',
+          },
+        ],
       });
 
       expect(result).toBe(false);

src/api/controls/JobControl.ts

@@ -16,6 +16,7 @@ import type {
   AD5XUploadParams,
   Creator5JobParams,
   Creator5MaterialMapping,
+  Creator5UploadParams,
 } from '../../models/ff-models';
 import { NetworkUtils } from '../network/NetworkUtils';
 import { Endpoints } from '../server/Endpoints';
@@ -509,21 +510,113 @@ export class JobControl {
   }
 
   // --- Creator 5 / Creator 5 Pro ---
-  // The Creator 5 uploads files the same way as the AD5X (the extra IFS headers
-  // are simply ignored by its firmware), but it performs material matching at
-  // print-start via POST /printGcode rather than at upload time. So upload reuses
-  // the AD5X path, while starting a job uses the Creator 5-native body below.
+  // 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" (not "1"/"0").
+  //   2. Start the print (POST /printGcode) with the per-tool `materialMappings`.
+  // See {@link startCreator5Job} for step 2.
 
   /**
-   * Uploads a file to a Creator 5 / Creator 5 Pro. Reuses the AD5X upload path;
-   * the Creator 5 firmware ignores the IFS-specific headers. To run a multi-tool
-   * print, upload with `startPrint = false`, then call {@link startCreator5Job}
-   * with material mappings.
-   * @param params Upload parameters (material mappings are ignored by the C5 firmware).
+   * Uploads a file (.gcode or .3mf) to a Creator 5 / Creator 5 Pro via
+   * `POST /uploadGcode`, with the C5-specific material-station headers.
+   *
+   * For a multi-tool print, set `useMatlStation = true` and `gcodeToolCnt` to the
+   * tool count, upload with `startPrint = false`, then call {@link startCreator5Job}
+   * with the material mappings. For a single-tool print, `useMatlStation = false`
+   * and `gcodeToolCnt = 1`; `startPrint = true` will auto-start it.
+   *
+   * Unlike {@link uploadFileAD5X} this sends no `firstLayerInspection` header (the
+   * C5 has no such field) and no `materialMappings` header (the C5 maps materials at
+   * print-start, not upload).
+   * @param params Creator 5 upload parameters.
    * @returns Promise resolving to true on success.
    */
-  public async uploadFileWithMaterialMappings(params: AD5XUploadParams): Promise<boolean> {
-    return this.uploadFileAD5X(params);
+  public async uploadFileCreator5(params: Creator5UploadParams): Promise<boolean> {
+    if (!fs.existsSync(params.filePath)) {
+      console.error(`uploadFileCreator5 error: File not found at ${params.filePath}`);
+      return false;
+    }
+
+    const stats = fs.statSync(params.filePath);
+    const fileSize = stats.size;
+    const fileName = path.basename(params.filePath);
+
+    console.log(
+      `Starting Creator 5 upload for ${fileName}, Size: ${fileSize}, Start: ${params.startPrint}, ` +
+        `Level: ${params.levelingBeforePrint}, MatlStation: ${params.useMatlStation}, Tools: ${params.gcodeToolCnt}`
+    );
+
+    try {
+      const form = new FormData();
+      form.append('gcodeFile', fs.createReadStream(params.filePath), {
+        filename: fileName,
+        contentType: 'application/octet-stream',
+      });
+
+      // C5 upload headers. No firstLayerInspection (absent on the C5); booleans are
+      // sent as the string "true"/"false" (the firmware checks for "true", not "1").
+      const customHeaders: Record<string, string> = {
+        serialNumber: this.client.serialNumber,
+        checkCode: this.client.checkCode,
+        fileSize: fileSize.toString(),
+        printNow: params.startPrint.toString().toLowerCase(),
+        levelingBeforePrint: params.levelingBeforePrint.toString().toLowerCase(),
+        flowCalibration: (params.flowCalibration ?? false).toString().toLowerCase(),
+        timeLapseVideo: (params.timeLapseVideo ?? false).toString().toLowerCase(),
+        useMatlStation: params.useMatlStation.toString().toLowerCase(),
+        gcodeToolCnt: params.gcodeToolCnt.toString(),
+        Expect: '100-continue',
+      };
+
+      const formHeaders = form.getHeaders();
+      const requestHeaders = {
+        ...customHeaders,
+        'Content-Type': formHeaders['content-type'],
+      };
+
+      console.log('Creator 5 Upload Request Headers:', requestHeaders);
+
+      const response = await axios.post(
+        this.client.getEndpoint(Endpoints.UploadFile),
+        form,
+        { headers: requestHeaders }
+      );
+
+      console.log(`Creator 5 Upload Response Status: ${response.status}`);
+      console.log('Creator 5 Upload Response Data:', response.data);
+
+      if (response.status !== 200) {
+        console.error(`Creator 5 Upload failed: Printer responded with status ${response.status}`);
+        return false;
+      }
+
+      const result = response.data as GenericResponse;
+      if (NetworkUtils.isOk(result)) {
+        console.log('Creator 5 Upload successful according to printer response.');
+        return true;
+      }
+      console.error(
+        `Creator 5 Upload failed: Printer response code=${result.code}, message=${result.message}`
+      );
+      return false;
+    } catch (error) {
+      const err = error as Error & {
+        response?: { status: number; data: GenericResponse };
+        request?: unknown;
+      };
+      console.error(`uploadFileCreator5 error: ${err.message}`);
+      if (err.response) {
+        console.error(`Error Status: ${err.response.status}`);
+        console.error('Error Response Data:', err.response.data);
+      } else if (err.request) {
+        console.error('Error Request:', err.request);
+      }
+      console.error(err.stack);
+      return false;
+    }
   }
 
   /**
@@ -553,16 +646,19 @@ export class JobControl {
       return false;
     }
 
-    // Only the fields the /printGcode handler actually reads. fileName and
-    // levelingBeforePrint are required; the rest are optional.
+    // Fields the /printGcode handler reads, matching the exact body the FlashForge
+    // app sends (confirmed via a live C5 capture). The firmware does NOT read
+    // useMatlStation, gcodeToolCnt, or firstLayerInspection here — those live on the
+    // upload request (firstLayerInspection doesn't exist on the C5 at all). flowCalibration
+    // and timeLapseVideo are always present (default false) to mirror the captured body.
     const payload: Record<string, unknown> = {
       serialNumber: this.client.serialNumber,
       checkCode: this.client.checkCode,
       fileName: params.fileName,
       levelingBeforePrint: params.levelingBeforePrint,
+      flowCalibration: params.flowCalibration ?? false,
+      timeLapseVideo: params.timeLapseVideo ?? false,
     };
-    if (params.flowCalibration !== undefined) payload.flowCalibration = params.flowCalibration;
-    if (params.timeLapseVideo !== undefined) payload.timeLapseVideo = params.timeLapseVideo;
     if (hasMappings) payload.materialMappings = params.materialMappings;
 
     try {
@@ -584,7 +680,9 @@ export class JobControl {
 
   /**
    * Validates Creator 5 material mappings: toolId 0-3, slotId 1-4, non-empty
-   * materialName. (No color fields, unlike AD5X.)
+   * materialName, and #RRGGBB tool/slot colors. The C5 mapping shape is identical
+   * to the AD5X (confirmed via a live /printGcode capture — it carries the same
+   * toolMaterialColor / slotMaterialColor fields).
    * @param materialMappings Array of Creator 5 mappings to validate.
    * @returns True if all mappings are valid, false otherwise.
    * @private
@@ -595,6 +693,8 @@ export class JobControl {
       return false;
     }
 
+    const hexColorRegex = /^#[0-9A-Fa-f]{6}$/;
+
     for (let i = 0; i < materialMappings.length; i++) {
       const mapping = materialMappings[i];
 
@@ -618,6 +718,20 @@ export class JobControl {
         );
         return false;
       }
+
+      if (!hexColorRegex.test(mapping.toolMaterialColor)) {
+        console.error(
+          `Creator 5 material mappings error: toolMaterialColor must be in #RRGGBB format, got ${mapping.toolMaterialColor} at index ${i}`
+        );
+        return false;
+      }
+
+      if (!hexColorRegex.test(mapping.slotMaterialColor)) {
+        console.error(
+          `Creator 5 material mappings error: slotMaterialColor must be in #RRGGBB format, got ${mapping.slotMaterialColor} at index ${i}`
+        );
+        return false;
+      }
     }
 
     return true;

src/api/controls/TempControl.test.ts

@@ -335,5 +335,35 @@ describe('TempControl', () => {
         nozzles: [-100, -200, -200, -200],
       });
     });
+
+    // The confirmed C5 payload always carries a 4-entry `nozzles` array, even on a
+    // bed- or chamber-only command. Unspecified tools default to TEMP_NO_CHANGE so
+    // the tools are left untouched.
+    it('setBedTemp still includes a 4-entry nozzles[] array (all unchanged)', async () => {
+      const result = await c5TempControl.setBedTemp(60);
+
+      expect(result).toBe(true);
+      expect(mockTcpClient.setBedTemp).not.toHaveBeenCalled();
+      expect(mockSendControlCommand).toHaveBeenCalledWith('temperatureCtl_cmd', {
+        rightNozzle: -200,
+        leftNozzle: -200,
+        platform: 60,
+        chamber: -200,
+        nozzles: [-200, -200, -200, -200],
+      });
+    });
+
+    it('setChamberTemp still includes a 4-entry nozzles[] array (all unchanged)', async () => {
+      const result = await c5TempControl.setChamberTemp(50);
+
+      expect(result).toBe(true);
+      expect(mockSendControlCommand).toHaveBeenCalledWith('temperatureCtl_cmd', {
+        rightNozzle: -200,
+        leftNozzle: -200,
+        platform: -200,
+        chamber: 50,
+        nozzles: [-200, -200, -200, -200],
+      });
+    });
   });
 });

src/api/controls/TempControl.ts

@@ -66,10 +66,14 @@ export class TempControl {
       platform: args.platform ?? TEMP_NO_CHANGE,
       chamber: args.chamber ?? TEMP_NO_CHANGE,
     };
-    // Per-tool targets for Creator 5 tool-changers. Only included when supplied so
-    // the firmware's `size() == 4` check doesn't reject a partial/absent array.
+    // The `nozzles` array is Creator 5-only (its 4-nozzle tool changer). The
+    // confirmed C5 payload ALWAYS carries a 4-entry array, even on a bed- or
+    // chamber-only command, so always include it on the C5 — defaulting unspecified
+    // tools to TEMP_NO_CHANGE so a bed/chamber adjustment leaves the tools untouched.
     if (args.nozzles !== undefined) {
       payload.nozzles = args.nozzles;
+    } else if (this.client.isCreator5) {
+      payload.nozzles = new Array<number>(NOZZLE_COUNT).fill(TEMP_NO_CHANGE);
     }
     return await this.client.control.sendControlCommand(Commands.TempControlCmd, payload);
   }