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:

V1 Setting V2 Setting Description
If set to true, automatically plays the on_boot_gcode file when the board boots up. This allows for automated startup routines like homing or initial positioning.
Path to the G-code file to play when the board boots. Default is /sd/on_boot.gcode. Useful for automating startup tasks like homing the printer or setting initial temperatures.
G-code to execute automatically right after a suspend command is received. Use underscores (_) instead of spaces in G-code commands. Commonly used to retract filament and move the toolhead away from the print. Example: G91_G0_E-5_G0_Z10_G90_G0_X-50_Y-50 (retracts 5mm, raises Z by 10mm, moves to safe position).
G-code to execute automatically after a resume command but before resuming the print. Use underscores (_) instead of spaces. Generally not needed since resume restores the previous state automatically. Example: G91_G1_E1_G90 (extrudes 1mm to prime the nozzle).
Controls heater behavior during suspend. When false (default), heaters turn OFF on suspend and back ON on resume. When true, heaters remain ON during suspend. Set to true for short pauses to avoid waiting for heaters to reheat.

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 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 to 1. This will mean it will stop within 32mm, but there is a performance penalty for segmenting when you do not need to.

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
This is a wiki! If you'd like to improve this page, you can edit it on GitHub.