feat(creator5): HTTP-only mode for Creator 5 / 5 Pro (no legacy TCP)

The Creator 5 / 5 Pro run no legacy TCP server (no port 8899) — they are
HTTP-only (OrcaServer on 8898). Add an httpOnly mode to FiveMClient so it can
drive them without the TCP control channel.

- FiveMClientConnectionOptions.httpOnly + FiveMClient.httpOnly; auto-enabled in
  verifyConnection() when a Creator 5 / 5 Pro is detected from /detail.
- initControl() succeeds on the HTTP product command alone in httpOnly mode;
  verifyConnection() skips the TCP getPrinterInfo() probe; dispose() skips TCP.
- TempControl set/cancel route through HTTP temperatureCtl_cmd (rightNozzle/
  leftNozzle/platform/chamber; -200 = no change, -100 = off) instead of TCP
  g-code; waitForPartCool() is a no-op in httpOnly.
- Files.getLocalFileList() falls back to HTTP /gcodeList when no TCP channel.
- Control TCP-only ops (home/runout/filament-load) return false (logged) in
  httpOnly instead of hanging on a dead socket.
- Backfill CHANGELOG for 1.3.3 / 1.3.4; +13 tests (364 total).

Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
Claude-Session: https://claude.ai/code/session_01LEiNF9KzwvnF4kAinmvu2a

Author: GhostTypes

CHANGELOG.md

@@ -7,6 +7,31 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.5] - 2026-06-24
+
+### Added
+
+- **HTTP-only mode for the Creator 5 / Creator 5 Pro.** These printers run no legacy TCP server (no port 8899) — they are HTTP-only (`OrcaServer` on 8898). `FiveMClient` now supports an `httpOnly` connection so it can drive them:
+  - New `FiveMClientConnectionOptions.httpOnly?: boolean` and public `FiveMClient.httpOnly`. Set it explicitly (e.g. when the model is known from discovery's USB product ID), or let `verifyConnection()` auto-enable it when a Creator 5 / 5 Pro is detected from `/detail`.
+  - In HTTP-only mode `initControl()` succeeds on the HTTP product command alone (never opens the TCP control channel), `verifyConnection()` skips the TCP `getPrinterInfo()` probe (no connect timeout), and `dispose()` skips TCP teardown.
+  - `TempControl` set/cancel extruder/bed temperatures route through the HTTP `temperatureCtl_cmd` (args `rightNozzle`/`leftNozzle`/`platform`/`chamber`; `-200` = leave unchanged, `-100` = off) instead of TCP G-code. `waitForPartCool()` is a no-op in HTTP-only mode (poll `info.get()` instead).
+  - `Files.getLocalFileList()` falls back to the HTTP `/gcodeList` (10 most-recent files) when there is no TCP channel.
+  - `Control` TCP-only operations (`homeAxes`, `homeAxesRapid`, `turnRunoutSensorOn/Off`, `prepareFilamentLoad`/`loadFilament`/`finishFilamentLoad`) return `false` with a clear log in HTTP-only mode rather than hanging on a dead socket.
+
+## [1.3.4] - 2026-06-22
+
+### Added
+
+- `JobControl.startCreator5Job(params)` — Creator 5 native print start via `POST /printGcode` (the Creator 5 does material matching at print-start, not at upload time), with optional per-tool `materialMappings` (`{ toolId, slotId, materialName }`). `Creator5JobParams` / `Creator5MaterialMapping` types exported.
+
+## [1.3.3] - 2026-06-22
+
+### Added
+
+- Creator 5 / Creator 5 Pro `/detail` model support: `nozzleTemps[]` / `nozzleTargetTemps[]` (per-tool arrays), `lidar`, `model`, and `FFMachineInfo` fields `IsCreator5`, `IsCreator5Pro`, `Model`, `HasCamera`, `HasLidar`, `HasDoorSensor`, `ToolTemps`.
+- `FiveMClient` Creator 5 flags (`isCreator5`, `isCreator5Pro`, `model`, `hasCamera`, `hasLidar`, `hasDoorSensor`, `toolTemps`) and capability derivation (`deriveCapabilities`, `ProductCapabilities`) from `/product` (polarity `1` = available), with a Creator 5 Pro filtration force-enable (its `/product` under-reports the fan control states).
+- Creator 5 PIDs added to model detection (`0x28` Creator 5, `0x29` Creator 5 Pro).
+
 ## [1.3.2] - 2026-06-05
 
 ### Added

package.json

@@ -1,6 +1,6 @@
 {
   "name": "@ghosttypes/ff-api",
-  "version": "1.3.4",
+  "version": "1.3.5",
   "description": "FlashForge 3D Printer API for Node.js",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",

src/FiveMClient.test.ts

@@ -181,4 +181,38 @@ describe('FiveMClient', () => {
       });
     });
   });
+
+  // Creator 5 / 5 Pro run no legacy TCP server; initControl must succeed on the
+  // HTTP product command alone and never touch the TCP client.
+  describe('HTTP-only mode', () => {
+    const okProduct = { status: 200, data: { code: 0, message: 'Success', product: {} } };
+
+    it('initControl skips TCP init when constructed with httpOnly: true', async () => {
+      httpPost.mockResolvedValue(okProduct);
+      const client = new FiveMClient('192.168.1.10', 'SN-1', 'CHK-1', { httpOnly: true });
+
+      await expect(client.initControl()).resolves.toBe(true);
+      expect(client.httpOnly).toBe(true);
+      expect((client.tcpClient as unknown as { initControl: ReturnType<typeof vi.fn> }).initControl)
+        .not.toHaveBeenCalled();
+    });
+
+    it('initControl still initializes TCP for dual-API printers (default)', async () => {
+      httpPost.mockResolvedValue(okProduct);
+      const client = new FiveMClient('192.168.1.10', 'SN-1', 'CHK-1');
+
+      await expect(client.initControl()).resolves.toBe(true);
+      expect(client.httpOnly).toBe(false);
+      expect((client.tcpClient as unknown as { initControl: ReturnType<typeof vi.fn> }).initControl)
+        .toHaveBeenCalled();
+    });
+
+    it('dispose does not touch the TCP client in HTTP-only mode', async () => {
+      const client = new FiveMClient('192.168.1.10', 'SN-1', 'CHK-1', { httpOnly: true });
+
+      await client.dispose();
+      expect((client.tcpClient as unknown as { dispose: ReturnType<typeof vi.fn> }).dispose)
+        .not.toHaveBeenCalled();
+    });
+  });
 });

src/FiveMClient.ts

@@ -22,6 +22,15 @@ export interface FiveMClientConnectionOptions {
   httpPort?: number;
   /** Legacy TCP command port override used by the embedded tcp client (defaults to 8899). */
   tcpPort?: number;
+  /**
+   * Force HTTP-only mode: never open or use the legacy TCP control channel.
+   * Required for the Creator 5 / 5 Pro, which run no TCP server on 8899 (HTTP
+   * `OrcaServer` on 8898 only). When omitted, HTTP-only mode is auto-enabled
+   * once the printer is detected as a Creator 5 during {@link FiveMClient.verifyConnection}.
+   * Pass `true` up-front (e.g. when the model is already known from discovery's
+   * USB product ID) to skip the TCP probe entirely and avoid its connect timeout.
+   */
+  httpOnly?: boolean;
 }
 
 /**
@@ -46,6 +55,15 @@ export class FiveMClient {
   /** Instance for lower-level TCP communication with the printer. */
   public tcpClient: FlashForgeClient;
 
+  /**
+   * When true, the legacy TCP control channel is never used (HTTP API only).
+   * Set from the `httpOnly` constructor option, and auto-enabled for the
+   * Creator 5 / 5 Pro during {@link verifyConnection}. TCP-only operations
+   * (homing, jog, direct g-code, runout sensor, filament load) are unavailable
+   * while this is true.
+   */
+  public httpOnly: boolean = false;
+
   public serialNumber: string;
   public checkCode: string;
   /** HTTP client for making requests to the printer's API. */
@@ -117,6 +135,7 @@ export class FiveMClient {
     this.serialNumber = serialNumber;
     this.checkCode = checkCode;
     this.PORT = options?.httpPort ?? 8898;
+    this.httpOnly = options?.httpOnly ?? false;
 
     this.httpClient = axios.create({
       timeout: 5000,
@@ -168,12 +187,17 @@ export class FiveMClient {
 
   /**
    * Initializes the control interface with the printer.
-   * This involves sending a product command and initializing TCP control.
+   * Sends the product command (HTTP) and, unless in HTTP-only mode, initializes
+   * the legacy TCP control channel. HTTP-only printers (Creator 5 / 5 Pro) have
+   * no TCP server, so success is determined solely by the product command.
    * @returns A Promise that resolves to true if control initialization is successful, false otherwise.
    */
   public async initControl(): Promise<boolean> {
     //console.log("InitControl()");
     if (await this.sendProductCommand()) {
+      // Creator 5 / 5 Pro expose no TCP control channel; verifyConnection runs
+      // before initControl and sets httpOnly when such a model is detected.
+      if (this.httpOnly) return true;
       return await this.tcpClient.initControl();
     }
     console.log('New API control failed!');
@@ -185,6 +209,8 @@ export class FiveMClient {
    */
   public async dispose(): Promise<void> {
     this.cameraStreamUrl = '';
+    // No TCP channel was opened in HTTP-only mode, so nothing to tear down.
+    if (this.httpOnly) return;
     await this.tcpClient.dispose();
   }
 
@@ -317,24 +343,34 @@ export class FiveMClient {
         return false;
       }
 
+      // The Creator 5 / 5 Pro run no legacy TCP server, so auto-enable HTTP-only
+      // mode here (before any TCP probe) once the model is detected from /detail.
+      // initControl() runs after this and relies on the flag being set.
+      if (machineInfo.IsCreator5 || machineInfo.IsCreator5Pro) {
+        this.httpOnly = true;
+      }
+
       // Check for Pro model with the machine TypeName (can't be changed by user)
       // We now rely on MachineInfo.fromDetail to set IsPro and IsAD5X based on detail.name
       // So, the TCP check for "Pro" might be redundant or could be a fallback.
       // For now, let's keep it but prioritize what's in machineInfo.
-      const tcpInfo = await this.tcpClient.getPrinterInfo();
-      if (tcpInfo) {
-        // If machineInfo hasn't already set isPro, we can use TCP info as a fallback.
-        // However, machineInfo.IsPro (derived from detail.name) should be more reliable.
-        // This line effectively gets overridden by cacheDetails if machineInfo.IsPro is set.
-        if (tcpInfo.TypeName.includes('Pro') && !machineInfo.IsPro && !machineInfo.IsAD5X) {
-          // Only set this if not already determined by machineInfo, and it's not an AD5X
-          this.isPro = true;
+      // HTTP-only printers have no TCP API to probe — skip it (avoids a connect timeout).
+      if (!this.httpOnly) {
+        const tcpInfo = await this.tcpClient.getPrinterInfo();
+        if (tcpInfo) {
+          // If machineInfo hasn't already set isPro, we can use TCP info as a fallback.
+          // However, machineInfo.IsPro (derived from detail.name) should be more reliable.
+          // This line effectively gets overridden by cacheDetails if machineInfo.IsPro is set.
+          if (tcpInfo.TypeName.includes('Pro') && !machineInfo.IsPro && !machineInfo.IsAD5X) {
+            // Only set this if not already determined by machineInfo, and it's not an AD5X
+            this.isPro = true;
+          }
+        } else {
+          console.error('Unable to get PrinterInfo from TcpAPI, some details might be incomplete');
         }
-      } else {
-        console.error('Unable to get PrinterInfo from TcpAPI, some details might be incomplete');
+        // we should probably return false if tcpInfo is null here, like we do for machineInfo,
+        // but for now, we'll let cacheDetails be the primary source of truth for these flags.
       }
-      // we should probably return false if tcpInfo is null here, like we do for machineInfo,
-      // but for now, we'll let cacheDetails be the primary source of truth for these flags.
 
       return this.cacheDetails(machineInfo);
     } catch (error: unknown) {

src/api/controls/Control.test.ts

@@ -615,4 +615,48 @@ describe('Control', () => {
       );
     });
   });
+
+  // HTTP-only printers (Creator 5 / 5 Pro) have no TCP control channel, so the
+  // TCP-bound operations must fail cleanly (return false) without touching the
+  // dead socket, rather than hang.
+  describe('HTTP-only mode (no TCP channel)', () => {
+    let httpControl: Control;
+
+    beforeEach(() => {
+      const httpClient = { ...mockFiveMClient, httpOnly: true } as any;
+      httpControl = new Control(httpClient);
+    });
+
+    it('homeAxes returns false without calling the TCP client', async () => {
+      const result = await httpControl.homeAxes();
+      expect(result).toBe(false);
+      expect(mockTcpClient.homeAxes).not.toHaveBeenCalled();
+    });
+
+    it('homeAxesRapid returns false without calling the TCP client', async () => {
+      const result = await httpControl.homeAxesRapid();
+      expect(result).toBe(false);
+      expect(mockTcpClient.rapidHome).not.toHaveBeenCalled();
+    });
+
+    it('turnRunoutSensorOn/Off return false without calling the TCP client', async () => {
+      expect(await httpControl.turnRunoutSensorOn()).toBe(false);
+      expect(await httpControl.turnRunoutSensorOff()).toBe(false);
+      expect(mockTcpClient.turnRunoutSensorOn).not.toHaveBeenCalled();
+      expect(mockTcpClient.turnRunoutSensorOff).not.toHaveBeenCalled();
+    });
+
+    it('filament load operations return false without calling the TCP client', async () => {
+      expect(await httpControl.loadFilament()).toBe(false);
+      expect(await httpControl.finishFilamentLoad()).toBe(false);
+      expect(mockTcpClient.loadFilament).not.toHaveBeenCalled();
+      expect(mockTcpClient.finishFilamentLoad).not.toHaveBeenCalled();
+    });
+
+    it('HTTP-based controls (LED) still dispatch over HTTP', async () => {
+      mockedAxios.post.mockResolvedValue({ status: 200, data: { code: 0, message: 'ok' } });
+      await httpControl.setLedOn();
+      expect(mockedAxios.post).toHaveBeenCalled();
+    });
+  });
 });

src/api/controls/Control.ts

@@ -40,11 +40,29 @@ export class Control {
     this.tcpClient = client.tcpClient;
   }
 
+  /**
+   * Guards a TCP-only operation. HTTP-only printers (Creator 5 / 5 Pro) have no
+   * legacy TCP control channel, so these operations cannot run. Logs and returns
+   * false rather than hanging on a dead socket. The Creator 5 exposes some of
+   * these via its HTTP API (Klipper g-code), but the request schemas are not yet
+   * confirmed; route them here once they are.
+   * @param op Human-readable operation name for the log message.
+   * @returns True if a TCP operation may proceed, false if it must be skipped.
+   */
+  private canUseTcp(op: string): boolean {
+    if (this.client.httpOnly) {
+      console.log(`${op}() unavailable: printer has no TCP control channel (HTTP-only).`);
+      return false;
+    }
+    return true;
+  }
+
   /**
    * Homes the X, Y, and Z axes of the printer.
    * @returns A Promise that resolves to true if the command is successful, false otherwise.
    */
   public async homeAxes(): Promise<boolean> {
+    if (!this.canUseTcp('homeAxes')) return false;
     return await this.tcpClient.homeAxes();
   }
 
@@ -53,6 +71,7 @@ export class Control {
    * @returns A Promise that resolves to true if the command is successful, false otherwise.
    */
   public async homeAxesRapid(): Promise<boolean> {
+    if (!this.canUseTcp('homeAxesRapid')) return false;
     return await this.tcpClient.rapidHome();
   }
 
@@ -182,6 +201,7 @@ export class Control {
    * @returns A Promise that resolves to true if the command is successful, false otherwise.
    */
   public async turnRunoutSensorOn(): Promise<boolean> {
+    if (!this.canUseTcp('turnRunoutSensorOn')) return false;
     return await this.tcpClient.turnRunoutSensorOn();
   }
 
@@ -190,6 +210,7 @@ export class Control {
    * @returns A Promise that resolves to true if the command is successful, false otherwise.
    */
   public async turnRunoutSensorOff(): Promise<boolean> {
+    if (!this.canUseTcp('turnRunoutSensorOff')) return false;
     return await this.tcpClient.turnRunoutSensorOff();
   }
 
@@ -201,6 +222,7 @@ export class Control {
    * @returns A Promise that resolves to true if the command is successful, false otherwise.
    */
   public async prepareFilamentLoad(filament: Filament): Promise<boolean> {
+    if (!this.canUseTcp('prepareFilamentLoad')) return false;
     return await this.tcpClient.prepareFilamentLoad(filament);
   }
 
@@ -209,6 +231,7 @@ export class Control {
    * @returns A Promise that resolves to true if the command is successful, false otherwise.
    */
   public async loadFilament(): Promise<boolean> {
+    if (!this.canUseTcp('loadFilament')) return false;
     return await this.tcpClient.loadFilament();
   }
 
@@ -217,6 +240,7 @@ export class Control {
    * @returns A Promise that resolves to true if the command is successful, false otherwise.
    */
   public async finishFilamentLoad(): Promise<boolean> {
+    if (!this.canUseTcp('finishFilamentLoad')) return false;
     return await this.tcpClient.finishFilamentLoad();
   }
 

src/api/controls/Files.ts

@@ -27,10 +27,17 @@ export class Files {
   }
 
   /**
-   * Retrieves a list of all G-code files stored locally on the printer via TCP.
+   * Retrieves a list of G-code files stored locally on the printer.
+   * Dual-API printers use the TCP file list; HTTP-only printers (Creator 5 /
+   * 5 Pro) have no TCP channel, so this falls back to the HTTP `/gcodeList`
+   * (the 10 most-recent files) and returns their names.
    * @returns A Promise that resolves to an array of file names (strings).
    */
   public async getLocalFileList(): Promise<string[]> {
+    if (this.client.httpOnly) {
+      const recent = await this.getRecentFileList();
+      return recent.map((entry) => entry.gcodeFileName);
+    }
     return await this.client.tcpClient.getFileListAsync();
   }