feat(ad5x): add IFS material-station slot write commands

Backport configureSlot (msConfig_cmd) and slotAction (ms_cmd) from
ff-5mp-api-kt so AD5X consumers can set the material/color of an IFS
slot and drive load/unload/cancel over HTTP. Releases 1.3.2.

- Control.configureSlot(slot, materialName, hexRgb): sends msConfig_cmd;
  strips a leading "#" from the color to match the RRGGBB wire format.
- Control.slotAction(slot, action): sends ms_cmd (load/unload/cancel).
- SlotAction enum (Load=0, Unload=1, Cancel=2), exported from the root.
- Both methods gate on isAD5X and return false on non-AD5X printers.
- Commands.MaterialStationConfigCmd / MaterialStationCmd constants.

Tests cover the hex-prefix strip, all three action codes, and AD5X gating.

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

Author: GhostTypes

CHANGELOG.md

@@ -7,6 +7,17 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [1.3.2] - 2026-06-05
+
+### Added
+
+- AD5X Intelligent Filament Station (IFS) slot write commands, backported from `ff-5mp-api-kt`:
+  - `Control.configureSlot(slot, materialName, hexRgb)` — sends `msConfig_cmd` to set a slot's material name and color (a leading `#` on the color is stripped to match the `RRGGBB` wire format).
+  - `Control.slotAction(slot, action)` — sends `ms_cmd` to load / unload / cancel a slot.
+  - `SlotAction` enum (`Load = 0`, `Unload = 1`, `Cancel = 2`) exported from the package root.
+  - Both methods are gated on `isAD5X` and return `false` on non-AD5X printers.
+  - `Commands.MaterialStationConfigCmd` (`msConfig_cmd`) and `Commands.MaterialStationCmd` (`ms_cmd`) constants.
+
 ## [1.3.1] - 2026-05-08
 
 ### Fixed

package.json

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

src/api/controls/Control.test.ts

@@ -6,6 +6,7 @@
 import axios from 'axios';
 import { beforeEach, describe, expect, it, vi } from 'vitest';
 import type { FiveMClient } from '../../FiveMClient';
+import { SlotAction } from '../../models/ff-models';
 import type { FlashForgeClient } from '../../tcpapi/FlashForgeClient';
 import { Commands } from '../server/Commands';
 import { Endpoints } from '../server/Endpoints';
@@ -495,6 +496,100 @@ describe('Control', () => {
     });
   });
 
+  describe('AD5X material station (IFS) slot operations', () => {
+    beforeEach(() => {
+      mockedAxios.post.mockResolvedValue({
+        status: 200,
+        data: { code: 0, message: 'Success' },
+      });
+      mockFiveMClient.isAD5X = true;
+    });
+
+    it('should configure a slot and strip the leading # from the color', async () => {
+      const result = await control.configureSlot(1, 'PLA', '#FF0000');
+
+      expect(result).toBe(true);
+      expect(mockedAxios.post).toHaveBeenCalledWith(
+        `http://printer:8898${Endpoints.Control}`,
+        expect.objectContaining({
+          payload: {
+            cmd: Commands.MaterialStationConfigCmd,
+            args: { slot: 1, mt: 'PLA', rgb: 'FF0000' },
+          },
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should accept a color that already lacks a # prefix', async () => {
+      await control.configureSlot(2, 'PETG', '46328E');
+
+      expect(mockedAxios.post).toHaveBeenCalledWith(
+        `http://printer:8898${Endpoints.Control}`,
+        expect.objectContaining({
+          payload: {
+            cmd: Commands.MaterialStationConfigCmd,
+            args: { slot: 2, mt: 'PETG', rgb: '46328E' },
+          },
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should send a load slot action', async () => {
+      const result = await control.slotAction(1, SlotAction.Load);
+
+      expect(result).toBe(true);
+      expect(mockedAxios.post).toHaveBeenCalledWith(
+        `http://printer:8898${Endpoints.Control}`,
+        expect.objectContaining({
+          payload: {
+            cmd: Commands.MaterialStationCmd,
+            args: { slot: 1, action: 0 },
+          },
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should send unload and cancel slot actions with the correct codes', async () => {
+      await control.slotAction(3, SlotAction.Unload);
+      expect(mockedAxios.post).toHaveBeenLastCalledWith(
+        `http://printer:8898${Endpoints.Control}`,
+        expect.objectContaining({
+          payload: {
+            cmd: Commands.MaterialStationCmd,
+            args: { slot: 3, action: 1 },
+          },
+        }),
+        expect.any(Object)
+      );
+
+      await control.slotAction(0, SlotAction.Cancel);
+      expect(mockedAxios.post).toHaveBeenLastCalledWith(
+        `http://printer:8898${Endpoints.Control}`,
+        expect.objectContaining({
+          payload: {
+            cmd: Commands.MaterialStationCmd,
+            args: { slot: 0, action: 2 },
+          },
+        }),
+        expect.any(Object)
+      );
+    });
+
+    it('should refuse slot operations on non-AD5X printers', async () => {
+      mockFiveMClient.isAD5X = false;
+
+      const configResult = await control.configureSlot(1, 'PLA', '#FF0000');
+      const actionResult = await control.slotAction(1, SlotAction.Load);
+
+      expect(configResult).toBe(false);
+      expect(actionResult).toBe(false);
+      expect(mockedAxios.post).not.toHaveBeenCalled();
+    });
+  });
+
   describe('sendJobControlCmd', () => {
     it('should send job control command', async () => {
       mockedAxios.post.mockResolvedValue({

src/api/controls/Control.ts

@@ -7,6 +7,7 @@
 import axios from 'axios';
 import type { FiveMClient } from '../../FiveMClient';
 import type { FlashForgeClient } from '../../tcpapi/FlashForgeClient';
+import type { SlotAction } from '../../models/ff-models';
 import type { Filament } from '../filament/Filament';
 import { NetworkUtils } from '../network/NetworkUtils';
 import { Commands } from '../server/Commands';
@@ -219,6 +220,58 @@ export class Control {
     return await this.tcpClient.finishFilamentLoad();
   }
 
+  // AD5X Intelligent Filament Station (IFS) slot operations
+
+  /**
+   * Configures the material name and color metadata for an AD5X material station slot.
+   * This information is shown on the printer UI and used for print validation; it does
+   * not move any filament. Only available on AD5X printers.
+   *
+   * The firmware accepts arbitrary material/color strings, but only the recognized
+   * materials and the 24-color UI palette render an icon on the printer — callers that
+   * want a clean display should map to the nearest recognized values first.
+   *
+   * @param slot The slot number (1-4).
+   * @param materialName The material type (e.g., "PLA", "PETG").
+   * @param hexRgb The color as a hex string; a leading "#" is stripped to match the wire format ("RRGGBB").
+   * @returns A Promise that resolves to true if the command is successful, false otherwise.
+   */
+  public async configureSlot(
+    slot: number,
+    materialName: string,
+    hexRgb: string
+  ): Promise<boolean> {
+    if (!this.client.isAD5X) {
+      console.log('configureSlot() error, material station only available on AD5X.');
+      return false;
+    }
+    return await this.sendControlCommand(Commands.MaterialStationConfigCmd, {
+      slot,
+      mt: materialName,
+      rgb: hexRgb.replace(/^#/, ''),
+    });
+  }
+
+  /**
+   * Performs a load, unload, or cancel operation on an AD5X material station slot.
+   * Only available on AD5X printers. Operations are asynchronous — poll
+   * `info.get()` / `matlStationInfo.stateAction` to monitor completion.
+   *
+   * @param slot The target slot number (1-4). For {@link SlotAction.Cancel} the slot is ignored by firmware.
+   * @param action The slot action to perform (load/unload/cancel).
+   * @returns A Promise that resolves to true if the command is successful, false otherwise.
+   */
+  public async slotAction(slot: number, action: SlotAction): Promise<boolean> {
+    if (!this.client.isAD5X) {
+      console.log('slotAction() error, material station only available on AD5X.');
+      return false;
+    }
+    return await this.sendControlCommand(Commands.MaterialStationCmd, {
+      slot,
+      action,
+    });
+  }
+
   // Internal methods for sending commands
 
   /**

src/api/server/Commands.ts

@@ -23,4 +23,8 @@ export class Commands {
   static readonly CameraControlCmd = 'streamCtrl_cmd';
   /** Command for controlling the printer's temperatures (e.g., setting extruder or bed temperature via HTTP, if supported). */
   static readonly TempControlCmd = 'temperatureCtl_cmd';
+  /** Command for configuring an AD5X material station slot's material name and color (IFS). */
+  static readonly MaterialStationConfigCmd = 'msConfig_cmd';
+  /** Command for AD5X material station slot load/unload/cancel actions (IFS). */
+  static readonly MaterialStationCmd = 'ms_cmd';
 }

src/index.ts

@@ -44,6 +44,7 @@ export {
   FFPrinterDetail,
   MachineState,
   MatlStationInfo,
+  SlotAction,
   SlotInfo,
   Temperature as TemperatureInterface,
 } from './models/ff-models';

src/models/ff-models.ts

@@ -378,6 +378,18 @@ export interface FFGcodeFileEntry {
   // For now, focusing on AD5X structure.
 }
 
+/**
+ * AD5X material station (IFS) slot operation, carrying the on-wire `ms_cmd` action code.
+ * - `Load` (0): load filament from the slot into the extruder.
+ * - `Unload` (1): retract filament from the extruder back into the slot.
+ * - `Cancel` (2): cancel the current IFS operation.
+ */
+export enum SlotAction {
+  Load = 0,
+  Unload = 1,
+  Cancel = 2,
+}
+
 // --- AD5X Local Job Start Interfaces ---
 
 /**