USB Drive Printing Guide

FLYOS-FAST can automatically mount USB drives and allows you to browse and print G-code files from them in the web file manager or the on-device screen. The logic described in this article has been verified against the v1.3.10 official images for H3, H5, H618, and the v1.4.0 test image for H618.

How It Works

The USB drive partition will be mounted as a folder starting with U_ in the G-code directory. When you select a file from it to start printing, the system will first copy the complete file locally:

/usr/share/printer_data/gcodes/.UDISK/tmp.gcode

Only after the copy is complete will Klipper execute the print from this local temporary file. The temporary file will be overwritten when starting the next USB drive print.

Wait for the copy to complete before unplugging the USB drive

When the copy first starts, the web interface may already show "Printing". This status does not mean the file copy has finished. Please wait until you see the following message in the console before unplugging the USB drive:

Copy files from removable disk completed

You can also wait until the printer has started heating or moving before unplugging. Unplugging the USB drive during the copy process will cause the copy to fail, and the current print will not start properly.

USB Drive and File Requirements

Item	Supported Range	Recommendation
File System	FAT32, exFAT, NTFS	Prefer FAT32 or exFAT
File Format	.gcode, .g, .gco	Prefer .gcode
File Location	USB drive root directory or multiple subfolders	Organize by model as needed
USB Drive Capacity	No fixed minimum capacity limit	Ensure sufficient free space and verify file integrity
File Names	UTF-8, spaces, and Chinese supported	Short file names recommended for better cross-platform compatibility

Model files such as .stl, .obj, or slicer project files are not supported for direct printing; G-code must first be generated using slicing software.

Windows file extension display

Windows may hide extensions for known file types. Please enable File name extensions in File Explorer to confirm that the final file extension is indeed .gcode, .g, or .gco, and avoid files like Model.gcode.txt.

Usage Steps

1. Copy the G-code files generated by your slicer to the USB drive root directory or into a folder.
2. Insert the USB drive into the host's USB port.
3. Open Fluidd, Mainsail, or the on-device screen's file list.
4. Locate the folder starting with U_; if it does not appear immediately, refresh the file list.
5. Open the USB drive folder and select the G-code file you want to print.
6. After confirming the file and preview information, click "Start Print" only once.
7. Wait for the console to show that the copy is complete; the system will then automatically begin executing the local temporary file.

Start only one copy task at a time

Do not click "Start Print" repeatedly or select a second USB drive file during the copy process. All USB drive print tasks in the current version share the same tmp.gcode file; concurrent copies may overwrite the file and cause print errors.

Unplugging the USB Drive

• Once the file copy is confirmed to be complete, a standard USB drive can be unplugged; the current task will continue reading from the local temporary file.
• If the console still shows Copying file, do not unplug the USB drive.
• If there is no copy progress or completion prompt, do not unplug during printing. Some USB drive enclosures or USB SSDs may not be recognized as removable devices by the system, in which case Klipper may read the external file directly.
• If you performed upload, delete, or rename operations on the USB drive through the web interface, wait for those operations to finish before unplugging.

Known Limitations

• Auto-mounting only handles USB storage devices with a regular partition table. USB drives without a partition table may not appear; you can recreate a partition and format it on a computer.
• Do not insert two USB drives that are completely identical in brand, model, capacity, and partition structure at the same time; they may generate the same mount directory and cause a conflict.
• The current auto-detection rules only cover common single-digit partitions, such as /dev/sda1. Special multi-partition storage devices may not have all partitions automatically mounted.
• USB drive printing relies on local free space. The larger the G-code file, the longer the wait for copying before printing starts.

Files appear but printing cannot start

1. Confirm the file extension is .gcode, .g, or .gco.

2. Verify that the G-code file can be previewed normally in your slicer software.

3. Check the host's local free space:

   df -h /usr/share/printer_data/gcodes

4. Check the Klipper log for file copy or open errors:

   tail -n 100 /usr/share/printer_data/logs/klippy.log

Local uploads work, but USB drive printing cannot start

Some slicer software saves Chinese comments in non-UTF-8 encodings such as GBK or ANSI:

• When uploaded locally to the G-code directory via the web interface, Klipper ignores characters it cannot decode, so the file may print normally.
• When selecting a file from a USB drive, the system first copies it to .UDISK/tmp.gcode and then reads it strictly as UTF-8; if it encounters non-UTF-8 bytes, printing may fail to start.

Klipper may log an error similar to:

UnicodeDecodeError: 'utf-8' codec can't decode byte

Chinese file names are usually not the cause

Chinese characters, underscores, and hyphens can be used normally in file names. Simply renaming the file to English will not change the file's internal encoding and cannot resolve this issue.

Use any of the following methods to handle this:

1. Prioritize re-exporting from the slicer software and set the G-code text encoding to UTF-8.
2. Use a text editor that supports encoding conversion to convert and save the entire G-code file as UTF-8; do not only change the file extension.
3. If the slicer software cannot select an encoding, delete the non-UTF-8 Chinese comments at the top of the file and save it again. Do not modify the actual motion, temperature, or extrusion commands.
4. As a temporary workaround, upload the file to the local G-code directory via the web interface and then print.

For large G-code files, it is recommended to re-slice or use dedicated text conversion tools rather than editing the entire file directly in a browser.

Stuck on "Printing" after a copy failure

First confirm that the printer is not executing heating, motion, or other print operations, then restart Klipper:

systemctl restart klipper

Re-insert the USB drive and try printing again. If the issue persists, 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