Playing G-code files

The Player module allows you to play files from the SD card.

Files are read one line at a time, and each line is executed as if it had been received from a controlling host.

Important Notes

Mac users beware: it appears that the play function does not accept files that have a space in their name.

Files on sdcard MUST be line terminated by \n ONLY, not \r (Note for MAC users).

On the very latest version of smoothieware it will tolerate \r\n terminated lines.

Configuration

Here are all the available options for the Player module:

Player Options

The Player module in Smoothie allows you to play G-code files from the SD card and control various aspects of playback behavior.

These configuration options control what happens during boot, suspend, and resume operations.

Configuration Options

Option Value Description
on_boot_gcode /sd/on_boot.gcode G-code file to play when the board boots. This file will automatically be played when the board is done booting up. Useful for example if you want to home your printer when it boots, or do similar tasks. For more information see on_boot.gcode
on_boot_gcode_enable true If set to true, play the on_boot_gcode file when the board boots up
after_suspend_gcode G91 G0 E-5 G0 Z10 G90 G0 X-50 Y-50 G-code to execute automatically right after the suspend command is received, this is useful if you want to retract, or turn off heaters etc. The _ character gets converted into space
before_resume_gcode G91 G1 E1 G90 G-code to execute automatically right after the resume command is received, but before resuming execution. However, NOTE this is generally not needed as the resume will restore the state it was in before the suspend. The _ character gets converted into space
leave_heaters_on_suspend false If set to true, heaters are left ON when suspend is received. If set to false, heaters are turned OFF when suspend is received, and then turned back ON when resume is received.

Usage Examples

Boot Sequence

To automatically home your printer on boot, create a file at /sd/on_boot.gcode with:

G28 ; Home all axes

Then enable it in your config:

on_boot_gcode_enable true
on_boot_gcode /sd/on_boot.gcode

Suspend and Resume

The suspend/resume feature is useful for:

  • Pausing prints to change filament
  • Temporarily stopping for inspection
  • Emergency stops with state preservation

The after_suspend_gcode typically includes commands to:

  • Retract filament to prevent oozing
  • Raise the Z axis to prevent damage
  • Move the toolhead to a safe position

Commands

play

You can use the play command to execute files stored on the SD card.

You must specify a file name and its path, for example:

play /sd/gcodefile.gcode

By default, the command will be quiet.

If you want the command to output every G-code in the file to the serial port ( the command was called from ), add the -v ( verbose ) parameter:

play /sd/gcodefile.gcode -v
Pronterface Note: Pronterface will ignore commands it does not understand, unless you prefix them with @. Therefore, send your command as @play /sd/gcodefile.gcode and it will work. Repetier Warning: Repetier will act kind of mean, and ignore any command it doesn't understand. Unlike Pronterface it won't give you a method to pass commands anyway. You can possibly use the M24 G-code instead.

progress

When a file is playing, you can use the progress command to get a report of the current position in the file, and elapsed time.

abort

You can also use the abort command to stop the execution of the file.

suspend

Can be used for either sd card playing or when streaming from Pronterface or Octoprint.

Will suspend a print in progress. It does the following:

  1. Send pause to upstream host, or pause if printing from sd
  2. Wait for empty queue
  3. Save the current position, extruder position, temperatures - any state that would need to be restored
  4. –retract by specified amount either on command line or in config– - not implemented yet
  5. Turn off heaters (unless the config has leave_heaters_on_suspend true)
  6. Optionally run after_suspend gcode (set in config defines gcode to run eg. after_suspend G91G0E20G90)

User may jog or remove and insert filament at this point, extruding or retracting as needed.

This could be triggered by a Switch module to setup a simple out of filament detector.

NOTE: Issuing a home after a suspend will cancel the suspend and you will not be able to resume. Performance Note: The queue must drain before it will suspend. If you need to have the system suspend quicker the only way to do it is to set the config variable mm_per_line_segment 1. This will mean it will stop within 32mm, but there is a performance penalty for segmenting when you do not need to.

layout: default title: Stopping Smoothie —

Stopping Smoothie

There are several different ways to stop Smoothie during operation, each with different behaviors and use cases.

Understanding these methods is important for safe operation and troubleshooting.

Stop Methods Comparison

Command G-code Movement Heaters File playing Recoverable Documentation
abort M26 Stops SDCARD print immediately Not affected Aborts Position maintained, file must be restarted Player
suspend M600 Stops once queue is empty Turned off (if option enabled) Paused, can be resumed Yes, with resume or M601 Player
Kill button M112 Stops instantly (if button), waits for buffer (if host) Turned off Aborted No, position lost, home required supported-g-codes
Control-X - Stops instantly, works during streaming Turned off Aborted No, position lost, home required -

Detailed Method Descriptions

Abort Command (abort / M26)

Stops the execution of a file being played from SDCARD.

Behavior:

  • Completes the current G-code
  • Stops immediately after that
  • Discards the rest of the queued commands
  • Attempts to maintain the correct position after the abort
  • Heaters remain at their current state

Use Case: Quick stop of a print job while preserving position and keeping heaters on.

Recovery: Position is maintained, but the file must be restarted from the beginning.

Documentation: Player module

Suspend Command (suspend / M600)

Suspends the execution of a file being played from SDCARD or being streamed from a host.

Behavior:

  • Stops once the movement queue is empty
  • All state is saved
  • Heaters turned off by default (configurable)
  • Jogging and extruding are allowed during suspension
  • Can be resumed with resume or M601

Use Case: Mid-print filament change or filament out detection.

Host Support: Requires upstream support. Currently Pronterface and OctoPrint support it. Other hosts need to be manually paused.

Recovery: Yes, fully recoverable with position maintained.

Documentation: Player module

Kill Button / M112

Emergency stop that instantly halts all operations.

Behavior:

  • If kill button pressed: Stops instantly
  • If M112 issued from host: Has to wait for the receive buffer to have room
  • All heaters turned off
  • File playing aborted
  • Position is lost
  • System enters Halt state until M999 is sent

Use Case: Emergency situations requiring immediate stop.

Recovery: No, position is lost. Homing will be required.

Documentation: Supported G-codes, Kill Button

Warning: Using the kill button or M112 will cause position loss. You must home all axes before continuing normal operation.

Control-X

Sends a control character to stop Smoothie instantly.

Behavior:

  • Works at any time, even when streaming
  • Same effect as the kill button
  • All heaters turned off
  • File playing aborted
  • Position is lost
  • System enters Halt state until M999 or $X is sent

Use Case: Emergency stop from terminal/console when streaming G-code.

Recovery: No, position is lost. Homing will be required.

Halt State

When the kill button is pressed (or there is a temperature fault, M112 is issued, a limit switch is hit, or other error), the system enters the Halt state.

Halt State Behavior

Halt State Indicators:
  • Play LED flashes
  • Any command issued from host gets a !! response (with a few exceptions)
  • PSU may be turned off if a PSU Switch is defined

Clearing Halt State

The Halt state can be cleared by:

  1. Issuing M999 from the host
  2. Holding the flashing kill button for 2 seconds
  3. Using the LCD panel (if equipped)

Using Buttons and Sensors

Tip: All stop commands can be triggered by a button or a sensor if a Switch module is configured to do so. This allows for physical emergency stop buttons or automatic stopping based on sensor conditions.

Best Practices

For Normal Operation

  • Use suspend/resume (M600/M601) for planned interruptions like filament changes
  • Use abort when you need to stop quickly but keep heaters on

For Emergencies

  • Use the kill button or Control-X for immediate emergency stops
  • Remember that position will be lost and homing will be required

Recovery After Emergency Stop

  1. Clear the Halt state with M999
  2. Home all axes before attempting further movement
  3. Check that heaters are at safe temperatures before proceeding
  4. Verify machine state before resuming work

Further Reading

resume

Will resume a suspended print. It does the following:

  1. Restore the temperatures and wait for them to get up to temp
  2. Optionally run before_resume gcode if specified
  3. Restore the position it was at and E and any other saved state
  4. Resume sd print or send resume upstream

G-codes

The following G-codes are supported by the Player module:

  • M21 : Initialize the SD card. This does nothing in Smoothie but is kept for compatibility
  • M23 : Select a file, for example : M23 file.gcode
  • M24 : Start or resume SD card print
  • M25 : Pause SD card print
  • M26 : Abort a SD card print
  • M27 : Report print progress
  • M32 : Select a file, and start playing it, for example : M32 file.gcode
  • M600 : Suspend print in progress (use console command resume or M601 to continue)
  • M600.1 : Suspend print in progress, but leave heaters on
  • M601 : Resume print after suspend