AI Guard Extension Description

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

Testing feature, extremely high risk of print failure

AI Guard continuously captures camera images and performs local AI inference, significantly increasing CPU, memory, and storage load. Once system load becomes too high, there is a high probability of Klipper scheduling errors, MCU communication interruptions, or direct print task failures.

• Do not enable it during formal printing, long-duration printing, unattended printing, or printing of important models.
• Only use it for 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. It cannot replace manual monitoring and should not be used as a printer safety protection mechanism.

Version and Default Status

• Only confirmed in the FLYOS-FAST v1.4.0 beta image.
• The system includes the fly_ai_guard extension, model files, and a fly-ai.cfg example.
• By 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 v1.4.0 beta feature; recognition accuracy and long-term stability have not yet been fully verified.
• Inference load will stack with KlipperScreen, camera, timelapse, remote agents, and other plugins.
• No camera signal, incorrect snapshot URLs, or network snapshot timeouts will affect detection.
• The current example does not enable automatic pausing by default; even when enabled, false positives may still interrupt normal printing.
• When system load is too high, both AI Guard itself and print control may become ineffective.