USB Drive Printing Function Usage Guide
FLYOS-FAST automatically mounts USB drives, allowing you to browse and print G-code files from them in the web file manager or on the local screen. This article has been verified against the v1.3.10 images for H3, H5, and H618, and the v1.4.0 image for H618.
How It Works
The USB drive partition is mounted to the G-code directory as a folder starting with U_. When printing begins, the system first copies the complete file locally:
/usr/share/printer_data/gcodes/.UDISK/tmp.gcode
Only after the copy is complete does Klipper execute the print from this temporary file; the next USB drive print will overwrite it.
The web page showing "Printing" does not mean the file has finished copying. Please wait until Copy files from removable disk completed appears in the console, or until the printer has started heating and moving, before unplugging. Unplugging during the copy will prevent this print from starting.
File Requirements
| Item | Supported Range | Recommendation |
|---|---|---|
| File system | FAT32, exFAT, NTFS | Prefer FAT32 or exFAT |
| File format | .gcode, .g, .gco | Prefer .gcode |
| File location | Root directory or multi-level folders | Organize by model |
| File name | Supports UTF-8, spaces, and Chinese characters | Keep it short for cross-platform convenience |
Model files such as .stl and .obj, as well as slicer project files, are not supported. You need to export G-code using slicing software first.
This feature does not support USB 3.0. Please plug the USB drive into a USB 2.0 port, and do not use a USB 3.0 USB drive; when using 3.0, the transfer speed will become very slow, and the copy wait time will be noticeably longer.
Please check File name extensions in File Explorer to confirm that the suffix is indeed .gcode, .g, or .gco, avoiding cases like model.gcode.txt.
Usage Steps
- Copy the G-code generated by slicing to a USB flash drive.
- Insert the USB flash drive into the USB port of the host computer.
- Open the file list in Fluidd, Mainsail, or on the local screen, and find the folder starting with
U_; if it does not appear immediately, refresh the list. - Enter the folder and select the G-code file, confirm the preview information, and then click "Start Printing" only once.
- Wait for the console to indicate that copying is complete; the system will then automatically start printing.
Do not repeatedly click "Start Printing" during copying, and do not select a second USB flash drive file: all USB flash drive printing shares the same tmp.gcode, and concurrent copying will overwrite each other.
Removing the Drive and Limitations
- After confirming the copy is complete, you can unplug the USB drive; printing will continue by reading the local temporary file. Do not unplug while the console is still displaying
Copying file. - Do not unplug the drive when there is no copy progress indication at all: some USB hard drive enclosures or SSDs may not be recognized as removable devices, and Klipper will read the external file directly.
- When the web page is uploading, deleting, or renaming files on the USB drive, wait for the operation to complete before unplugging.
- A USB drive without a partition table may not be displayed; you can repartition and format it. Two USB drives with identical manufacturer, model, capacity, and partition structure may be mounted to the same directory and conflict.
- Automatic detection only covers common single-digit partitions (such as
/dev/sda1); special multi-partition devices may not be fully mounted. - The larger the file, the longer the copy wait before printing starts, and it depends on the remaining local space on the host.
Frequently Asked Questions
The file is visible but printing cannot start
Confirm that the extension is .gcode, .g, or .gco, and that the file can be previewed normally in the slicing software; check the remaining local space:
df -h /usr/share/printer_data/gcodes
Then check the Klipper log for copy or open errors:
tail -n 100 /usr/share/printer_data/logs/klippy.log
Web upload can print, but USB drive cannot
Some slicing software saves Chinese comments in GBK or ANSI, while USB drive files are first copied to .UDISK/tmp.gcode and then read strictly as UTF-8, which may report an error when encountering non-UTF-8 bytes:
UnicodeDecodeError: 'utf-8' codec can't decode byte
Chinese file names are usually not the cause, and changing them to English will not change the file's internal encoding. Handle it in any of the following ways:
- Re-export in the slicing software and set the encoding to UTF-8.
- Use an editor that supports encoding conversion to save the entire file as UTF-8; do not just change the extension.
- If the encoding cannot be selected, delete the non-UTF-8 Chinese comments at the beginning of the file and save it; do not modify motion, temperature, or extrusion commands.
- As a temporary workaround, first upload from the web page to the local G-code directory and then print.
After a copy failure, it keeps showing "Printing"
Confirm that the printer is not heating or moving, then restart Klipper:
systemctl restart klipper
Reinsert the USB drive and try again; if it occurs repeatedly, replace the USB drive and provide the following two logs to technical support:
/var/log/flyos-auto-mount.log
/usr/share/printer_data/logs/klippy.log