AI Guard Extension Description

AI Guard is a Klipper image detection extension pre-installed in FLYOS-FAST v1.4.0. It can periodically capture camera frames and attempt to identify printing anomalies such as spaghetti and stringing.

Test feature, extremely high risk of print failure

AI Guard continuously acquires camera images and performs local AI inference, significantly increasing CPU, memory, and storage load. Once system load becomes too high, there is a very high probability of Klipper scheduling anomalies, MCU communication interruptions, or direct print job failure.

• Do not enable it during formal printing, long-duration printing, unattended printing, or printing important models.
• Use it only in short tests that can be stopped at any time, and continuously monitor system load and Klipper logs.
• AI detection may produce false positives or false negatives, cannot replace manual monitoring, and cannot serve as a printer safety protection mechanism.

Version and Default Status

• Only available in FLYOS-FAST v1.4.0.
• The system pre-installs the fly_ai_guard extension, model files, and a fly-ai.cfg example.
• The default printer.cfg does not load fly-ai.cfg, so AI Guard does not run by default.

Preparation Before Enabling

1. First, confirm that the camera snapshot URL returns a valid image.
2. Confirm that the printer is not currently executing a print job.
3. Back up printer.cfg and fly-ai.cfg.
4. Use top to observe the system load when AI Guard is not enabled, as a baseline for comparison.

Reference Configuration

The example file in the image is located at:

/usr/share/printer_data/config/fly-ai.cfg

When using GoCam, you can refer to:

[fly_ai_guard]
camera: http://127.0.0.1:8080/snapshot
cpu_affinity: 0,1,2
spaghetti_threshold: 0.5
stringing_threshold: 0.5
interval_time: 10.0
discover_count: 1
print_only: True
pause_on_discover: False
discover_gcode:
    M118 AI detection triggered

Parameter	v1.4.0 Image Default	Description
camera	http://127.0.0.1/webcam/?action=snapshot	Camera snapshot URL that AI Guard reads; change to http://127.0.0.1:8080/snapshot when using GoCam
cpu_affinity	0,1,2	CPU core numbers allowed for AI worker processes
spaghetti_threshold	0.5	Confidence threshold for spaghetti detection
stringing_threshold	0.5	Confidence threshold for stringing detection
interval_time	10.0	Interval between two detections, in seconds
discover_count	1	Number of consecutive hits required to trigger an anomaly event
print_only	True	When True, detection only runs during printing
pause_on_discover	False	Whether to pause printing after the trigger count is reached
discover_gcode	M118 AI detection triggered	G-code executed when the trigger condition is met

Keep conservative parameters

• For initial testing, keep pause_on_discover: False to avoid false detections directly pausing printing.
• Do not significantly shorten interval_time to improve response speed; the more frequent the detection, the higher the system load.
• Do not lower detection thresholds or enable automatic pausing based on a single test.

Enabling the Extension

Add the following to printer.cfg:

[include fly-ai.cfg]

Save and restart Klipper. Do not start printing during the first test. First, run the following via SSH:

top

Also check the Klipper log:

tail -f /usr/share/printer_data/logs/klippy.log

If persistent high load, Klipper scheduling errors, MCU disconnection, camera snapshot failures, or repeated restarting of the AI worker occur, disable AI Guard immediately.

Disabling the Extension

Remove or comment out the following in printer.cfg:

[include fly-ai.cfg]

Then restart Klipper. Simply modifying pause_on_discover does not disable AI inference; to stop resource consumption, you must stop loading the entire [fly_ai_guard] configuration section.

Known Limitations

• This is a test feature of v1.4.0, and the recognition accuracy and long-term stability have not yet been verified.
• The inference load will stack with KlipperScreen, camera, time-lapse photography, remote proxy, and other plugins.
• No camera signal, incorrect snapshot address, or network image retrieval timeout will affect detection.
• The current example does not enable auto-pause by default; once enabled, it may still interrupt normal printing due to false positives.
• When the system load is too high, AI Guard itself and print control may both fail.