CFSync

A local web dashboard for managing filament spools on Creality K1 series printers with CFS (Colour Filament System), including the K1, K1C, K1 Max, K1 SE, and K2 Plus. CFSync connects directly to the printer over WebSocket, reads live spool data from all CFS slots, and optionally syncs consumption back to Spoolman.

Features

• Live CFS slot view — filament colour, material, and fill level per slot
• RFID spool percent from printer sensor; calculated percent for non-RFID spools via Spoolman
• Spoolman integration — link spools, track remaining weight, auto-report usage at job end
• Two Spoolman sync modes — direct reporting or Moonraker plugin (SET_ACTIVE_SPOOL)
• Serial-number-based auto-linking via SSH (CFTag-written spools link instantly on insert)
• Moonraker job tracking — attributes filament_used proportionally across active slots at print completion
• Printer name and firmware version shown in header (read from WebSocket)
• Dark UI, no build step, runs as a systemd service

Requirements

• Linux host on the same network as the printer (e.g. a Pi or the printer's companion board)
• Creality K1 series printer with CFS (K1, K1C, K1 Max, K1 SE, K2 Plus)
• Python 3.10+
• Optional: Spoolman for spool tracking

Install

curl -fsSL https://raw.githubusercontent.com/koen01/CFSync/refs/heads/spoolman/install.sh | sudo bash

The installer will prompt for:

Prompt	Example
UI port	8005
Printer IP	192.168.1.144
Spoolman URL (optional)	http://192.168.1.10:7912

After install, open http://<host-ip>:<port> in your browser.

Configuration

All settings are available through the cogwheel (⚙) modal in the UI. They are stored in data/config.json:

{
  "printer_url": "192.168.1.144",
  "filament_diameter_mm": 1.75,
  "spoolman_url": "http://192.168.1.10:7912",
  "spoolman_mode": "direct"
}

Spoolman integration

Sync modes

CFSync supports two ways to report filament consumption to Spoolman. Set the mode in the settings modal (⚙).

Direct mode (default)

CFSync calls PUT /api/v1/spool/{id}/use directly on Spoolman when a print finishes or a manual allocation is made. No Moonraker configuration needed.

Moonraker plugin mode

CFSync calls the SET_ACTIVE_SPOOL / CLEAR_ACTIVE_SPOOL G-code macros via Moonraker. Moonraker's built-in Spoolman plugin then tracks consumption itself. This requires the [spoolman] section in moonraker.conf — see setup below.

Moonraker plugin setup

1. Configure Moonraker — add to moonraker.conf:

[spoolman]
server: http://192.168.1.10:7912

2. Restart Moonraker after saving.

3. In CFSync settings (⚙), set Spoolman URL to the same address and switch the sync mode to Moonraker plugin.

Moonraker must be reachable from the CFSync host. CFSync uses the printer IP (port 7125) for Moonraker API calls. If your setup uses a different Moonraker URL you can configure it separately in data/config.json under moonraker_url.

Trusted clients: CFSync's host IP must be in Moonraker's trusted_clients list. The default Moonraker config already includes 192.168.0.0/16 and 10.0.0.0/8, so most LAN setups work without changes.

Auto-linking via serial number (SSH)

When an RFID-tagged spool is inserted, CFSync SSHes into the printer and reads the spool data file to extract the chip's serial number. If it matches a Spoolman spool ID, the slot is linked immediately.

This is the primary auto-link mechanism and works out of the box with CFTag — a companion Android app that creates the Spoolman entry and writes the spool ID onto the RFID chip in one flow.

Spools without a Creality RFID chip skip auto-linking and must be linked manually via the slot modal.

Workflow — adding a new spool with RFID

1. Open CFTag → fill in filament details → tap Create in Spoolman. CFTag creates the spool entry and immediately prompts you to write the first RFID tag. Hold your phone to the tag, flip the spool, write the second tag — done in one flow.
2. Load the spool into a CFS slot.
3. CFSync auto-links the slot via the serial number — no manual action needed.

From this point on, inserting that spool into any CFS slot will auto-link it instantly. Filament consumption is reported back to Spoolman after each print.

Fluidd panel

CFSync can inject a spool status panel into the Fluidd web UI. The panel script and setup instructions are available in the settings modal (⚙) under Fluidd panel.

Two delivery methods are supported:

• Bookmarklet — paste a one-liner into your browser's bookmarks bar and click it to activate
• Tampermonkey — install the userscript for automatic injection on every page load

Update

curl -fsSL https://raw.githubusercontent.com/koen01/CFSync/refs/heads/spoolman/update.sh | sudo bash

Logs

sudo journalctl -u filament-management -f

Credits

• jkef80/Filament-Management — original Moonraker-based filament management that this project evolved from
• DaviBe92/k2-websocket-re — reverse-engineered Creality K2 WebSocket protocol documentation that made the CFS integration possible