Extruders are used to push plastic filament through a hotend, to achieve the awesome feat of 3D Printing.
This module controls the motor that pushes the filament, it does not take care of the hotend itself, which is the job of TemperatureControl.
Steps Per Millimeter Configuration:
The most important parameter to get your extruder module to work properly is the steps per millimeter setting:
extruder.hotend.steps_per_mm 140
[extruder]
hotend.steps_per_mm = 140
You can create as many Extruder modules as you want (although you may run out of memory and Smoothie will no longer boot), as long as you give them different module names.
You can name those modules whatever you want (as long as you stick to only alphanumerical characters).
make AXIS=6.
We need to find the number of steps the stepper motor drivers have to generate in order to move the filament 1 millimeter.
This value depends on your stepper motor, the microstepping on your stepper motor drivers, the gear reduction ratio on the extruder assembly if any, and the diameter of your hobbed pulley/bolt.
A very good guide on how to find this value can be found here: Triffid Hunter’s Calibration Guide.
extruder.hotend.steps_per_mm 140
[extruder]
hotend.steps_per_mm = 140
This is an optional parameter for those who want to use volumetric extrusion, but are too lazy to do their own math. ;)
Simply enter the machine’s filament diameter here and set your slicer’s filament diameter to 1.128379mm (2*sqrt(1/pi)) and enjoy portable gcode!
Further explanation can be found in Triffid Hunter’s guide, linked above.
extruder.hotend.filament_diameter 3.0
[extruder]
hotend.filament_diameter = 3.0
The filament diameter can also be saved at runtime with this M code:
| Set E units for volumetric extrusion - D |
and saved with
Note this is optional, you are not obligated to set this up, but it is a nice feature if you want to use it.
The amounts of extrusion and speed can be set with the following M codes:
| set retract length S[positive|mm] F[feedrate|mm/min] Z[additional|zlift/hop] Q[zlift|feedrate mm/min] | ||
| set retract recover length S[positive|mm surplus to the M207 S*] F[feedrate|mm/min] |
or can be set in config with the following settings:
extruder.hotend.retract_length 3 # retract length in mm
extruder.hotend.retract_feedrate 45 # retract feedrate in mm/sec
extruder.hotend.retract_recover_length 0 # additional length for recover
extruder.hotend.retract_recover_feedrate 8 # recover feedrate in mm/sec (should be less than retract feedrate)
extruder.hotend.retract_zlift_length 0 # zlift on retract in mm, 0 disables
extruder.hotend.retract_zlift_feedrate 6000 # zlift feedrate in mm/min (Note mm/min NOT mm/sec)
[extruder]
hotend.retract_length = 3 # retract length in mm
hotend.retract_feedrate = 45 # retract feedrate in mm/sec
hotend.retract_recover_length = 0 # additional length for recover
hotend.retract_recover_feedrate = 8 # recover feedrate in mm/sec (should be less than retract feedrate)
hotend.retract_zlift_length = 0 # zlift on retract in mm, 0 disables
hotend.retract_zlift_feedrate = 6000 # zlift feedrate in mm/min (Note mm/min NOT mm/sec)
These can be set differently for each extruder defined.
As all stepper motors, the extruder stepper motor needs 3 pins to be controlled: step, direction, and enable (See Pin Reference and Pinout):
1st Extruder (delta, or M4)
extruder.hotend.step_pin 2.3
extruder.hotend.dir_pin 0.22
extruder.hotend.en_pin 0.21
[extruder]
hotend.step_pin = PD3
hotend.dir_pin = PD4
hotend.en_pin = PD5
2nd Extruder (epsilon, or M5)
extruder.hotend2.step_pin 2.8
extruder.hotend2.dir_pin 2.13
extruder.hotend2.en_pin 4.29
On boards which feature current control of the stepper motor drivers (Smoothieboard or 4pi), you have to set that value for the extruder too.
This is handled by the Currentcontrol module, but usually, the line for the configuration of a given stepper motor is written along with its pins, for clarity.
delta_current 1.5
[tmc2660]
delta.current = 1500 # Current in milliamps (mA), not Amps
[tmc2660] or [tmc2590] section depending on your driver type.
Set the value to the exact value your stepper motor is rated for (or less, for less noise, but less torque).
Setting the current to a value higher than the recommended one causes overheating, and skipped steps.
Here is an example of a common configuration and wiring of an extruder with a Smoothieboard.
This example setup is of an extruder (stepper motor) connected to the M4 stepper motor driver.
If your machine has multiple extruders, you also want to look at multiple-extruders.
The default Smoothie configuration example contains an example extruder section, this means you do not need to create a new one, but you can just re-use the sample one.
The configuration looks like this:
## Extruder module configuration
# See /extruder
extruder.hotend.enable true # Whether to activate the extruder module at all. All configuration is ignored if false
extruder.hotend.steps_per_mm 140 # Steps per mm for extruder stepper
extruder.hotend.acceleration 500 # Acceleration for the stepper motor mm/sec²
extruder.hotend.max_speed 50 # Maximum speed in mm/s
extruder.hotend.step_pin 2.3 # Pin for extruder step signal
extruder.hotend.dir_pin 0.22 # Pin for extruder dir signal (add '!' to reverse direction)
extruder.hotend.en_pin 0.21 # Pin for extruder enable signal
delta_current 1.5 # Current setting in Amperes for this motor driver
## Extruder module configuration
# See /extruder
[extruder]
hotend.enable = true # Whether to activate the extruder module at all
hotend.steps_per_mm = 140 # Steps per mm for extruder stepper
hotend.step_pin = PD3 # Pin for extruder step signal
hotend.dir_pin = PD4 # Pin for extruder dir signal (add '!' to reverse direction)
hotend.en_pin = PD5 # Pin for extruder enable signal
[actuator delta]
acceleration = 500 # Acceleration for the stepper motor mm/sec²
[motion control]
max_speed = 50 # Maximum speed in mm/s
[tmc2660]
delta.current = 1500 # Current setting in milliamps for this motor driver
Now that your extruder is configured, you can wire it:
Wiring your extruder stepper motor is very similar to how you wire your X, Y, and Z stepper motors (see adequate documentation):
you just wire the 4 wires of the stepper motor, to the output connector of the M4 stepper motor driver.
All of the options currently supported by the Extruder module:
| V1 Setting | V2 Setting | Description |
|---|---|---|
|
Whether to activate this extruder instance. All configuration for it is ignored if set to Each enabled extruder creates a separate extruder module instance that can be controlled with tool change commands ( Use the |
||
|
Number of stepper motor steps required to move one millimeter of filament through the extruder — a critical calibration value. Depends on your stepper motor steps/revolution (typically 200 for 1.8° motors), microstepping setting (e.g. 16x = 3200 steps/rev), and your extruder gear ratio/hobbed bolt diameter. Calculate as: Fine-tune by extruding a known length and measuring actual extrusion. Can be adjusted at runtime with |
||
|
Filament diameter in millimeters for volumetric extrusion mode. When set to a value greater than
Can be changed at runtime with |
||
|
Maximum acceleration for the extruder stepper motor in Higher values allow faster speed changes but may cause filament grinding or skipped steps if too aggressive; lower values produce smoother extrusion but may cause artifacts during rapid direction changes. Typical values: Affects extruder-only moves (retractions) and the E-axis component of combined moves. Adjust based on your extruder's mechanical capabilities and filament characteristics. Can be changed at runtime with |
||
|
Maximum allowable speed for the extruder stepper motor in Typical values: Too high a value may cause grinding or skipped steps; too low limits print speed. Affects both printing moves and retractions, and can be set per-extruder for multi-extruder setups. |
||
|
Pin for the extruder stepper motor driver's step signal. Each step pulse moves the motor one microstep according to the driver's microstepping configuration, toggling high/low to create the pulse train that drives the motor.
Step frequency equals |
||
|
Pin for the extruder stepper motor driver's direction signal. Controls whether the motor rotates forward (extrude) or backward (retract); the direction pin must be set before step pulses are sent. Typical Smoothieboard pins: Test direction by sending |
||
|
Pin for the extruder stepper motor driver's enable signal. When active, the motor driver is powered and holds position with full torque; when inactive, the driver is disabled and the motor freewheels (no holding torque). Typical Smoothieboard pins: The motor automatically enables before moves and can disable after a timeout (see |
||
|
X-axis offset of this extruder's nozzle from the primary extruder (T0), in millimeters. Used only in multi-extruder setups to compensate for physical nozzle position differences; the firmware automatically applies these offsets when switching tools with Positive values mean this extruder's nozzle is to the right of T0. Measure the offset by homing, moving to a reference point with T0, switching to this tool, and measuring the distance needed to return to the same point. The primary extruder (T0) should always have offsets of |
||
|
Y-axis offset of this extruder's nozzle from the primary extruder (T0), in millimeters. Used only in multi-extruder setups to compensate for physical nozzle position differences. Positive values mean this extruder's nozzle is toward the back (away from Y=0) compared to T0. See Must be accurately calibrated for proper layer alignment when switching between extruders during multi-material or multi-color prints. |
||
|
Z-axis offset of this extruder's nozzle from the primary extruder (T0), in millimeters. Used only in multi-extruder setups to compensate for different nozzle heights — critical for proper first layer when switching extruders. Positive values mean this extruder's nozzle is higher (further from the bed) than T0. Calibrate by homing Z, moving to a known position with T0, switching to this tool, and measuring the height difference. Even small differences (0.05mm) can cause first layer problems. Some slicers can compensate for Z-offset in G-code, but it's best to configure it in firmware for consistent behavior across all print jobs. |
||
|
Amount of filament to retract during firmware retraction, in millimeters. Used by
Too little retraction causes stringing; too much can cause clogs or air gaps. The total retract amount includes this length plus |
||
|
Speed at which filament is retracted during firmware retraction, in
Faster retractions reduce stringing but may cause grinding or skipped steps if too fast. Direct drive can typically handle faster retractions than Bowden. Speed should be fast enough to quickly relieve pressure but not so fast that it damages filament or causes extruder jamming. Can be changed at runtime with |
||
|
Additional length of filament to extrude when recovering (unretract) beyond the retracted amount. Used by
Compensates for material properties, oozing during travel, or pressure changes in the melt zone. Fine-tune to eliminate blobs (reduce value) or gaps (increase value) after travel moves. Can be changed at runtime with |
||
|
Speed at which filament is recovered (unretracted) during firmware unretraction, in
Slower recovery speeds help prevent blobs and allow time for pressure in the nozzle to build back up smoothly. Too fast can cause blobs; too slow can cause gaps at the start of extrusion. Should generally be less than |
||
|
Amount to lift the Z-axis during retraction, in millimeters (Z-hop / Z-lift feature). When
Z-hop reduces the chance of the nozzle dragging through or knocking over printed parts during travel moves — especially useful for tall thin features, parts with significant Z-variation, or materials prone to warping. Trade-off: increases print time due to extra Z movements. Can be changed at runtime with |
||
|
Speed for Z-axis movement during Z-lift operations, in
Faster Z-lift reduces travel time overhead but may cause ringing or mechanical stress on Z-axis components. Should not exceed the Z-axis maximum speed. Can be changed at runtime with |
Smoothieware V1 and V2 use different configuration file formats. Understanding these differences is important when setting up your extruder.
Smoothieware V1: Flat Format
V1 uses a flat configuration format where all settings are on one line with spaces separating the key and value:
# Basic extruder configuration
extruder.hotend.enable true
extruder.hotend.steps_per_mm 140
extruder.hotend.acceleration 500
extruder.hotend.max_speed 50
# Pin assignments
extruder.hotend.step_pin 2.3
extruder.hotend.dir_pin 0.22
extruder.hotend.en_pin 0.21
# Firmware retraction settings
extruder.hotend.retract_length 3
extruder.hotend.retract_feedrate 45
extruder.hotend.retract_recover_length 0
extruder.hotend.retract_recover_feedrate 8
Key characteristics:
#Smoothieware V2: INI Format
V2 uses an INI-style configuration format with section headers and equals signs:
# Basic extruder configuration
[extruder]
hotend.enable = true
hotend.steps_per_mm = 140
[actuator delta]
acceleration = 500
[motion control]
max_speed = 50
# Pin assignments
[extruder]
hotend.step_pin = 2.3
hotend.dir_pin = 0.22
hotend.en_pin = 0.21
# Firmware retraction settings
[extruder]
hotend.retract_length = 3
hotend.retract_feedrate = 45
hotend.retract_recover_length = 0
hotend.retract_recover_feedrate = 8
Key characteristics:
[section name]key = value format#[actuator delta])When configuring multiple extruders, V1 and V2 handle naming and enable flags differently:
V1 Extruder Naming:
In V1, each extruder is configured by choosing a unique name (like hotend, hotend2, extruder1, etc.) and using that name consistently across all settings:
# First extruder (uses delta/M4 driver)
extruder.hotend.enable true
extruder.hotend.steps_per_mm 140
extruder.hotend.step_pin 2.3
extruder.hotend.dir_pin 0.22
extruder.hotend.en_pin 0.21
# Second extruder (uses epsilon/M5 driver)
extruder.hotend2.enable true
extruder.hotend2.steps_per_mm 140
extruder.hotend2.step_pin 2.8
extruder.hotend2.dir_pin 2.13
extruder.hotend2.en_pin 4.29
extruder.hotend2.x_offset 25.0
extruder.hotend2.y_offset 0.0
extruder.hotend2.z_offset 0.0
Important V1 details:
hotend, hotend2) is arbitrary but must be uniqueextruder.<name>.enable true to be activatedhotend/hotend2, extruder/extruder2, e0/e1extruder.<name>.*V2 Extruder Naming:
In V2, extruders are configured within [extruder] sections, and the naming follows the INI format:
# First extruder (uses delta/M4 driver)
[extruder]
hotend.enable = true
hotend.steps_per_mm = 140
hotend.step_pin = 2.3
hotend.dir_pin = 0.22
hotend.en_pin = 0.21
# Second extruder (uses epsilon/M5 driver)
[extruder]
hotend2.enable = true
hotend2.steps_per_mm = 140
hotend2.step_pin = 2.8
hotend2.dir_pin = 2.13
hotend2.en_pin = 4.29
hotend2.x_offset = 25.0
hotend2.y_offset = 0.0
hotend2.z_offset = 0.0
Important V2 details:
[extruder] section headershotend, hotend2)<name>.enable = true[actuator delta], max_speed in [motion control])Here’s a complete basic configuration for a single extruder in both formats:
# Extruder module configuration (V1)
extruder.hotend.enable true
extruder.hotend.steps_per_mm 140
extruder.hotend.acceleration 500
extruder.hotend.max_speed 50
extruder.hotend.step_pin 2.3
extruder.hotend.dir_pin 0.22
extruder.hotend.en_pin 0.21
# Current control for delta driver (M4)
delta_current 1.5
# Extruder module configuration (V2)
[extruder]
hotend.enable = true
hotend.steps_per_mm = 140
hotend.step_pin = 2.3
hotend.dir_pin = 0.22
hotend.en_pin = 0.21
[actuator delta]
acceleration = 500
[motion control]
max_speed = 50
[current control]
delta = 1.5
For dual extruder setups, here’s how to configure both extruders:
# First extruder (T0) on delta/M4 driver
extruder.hotend.enable true
extruder.hotend.steps_per_mm 140
extruder.hotend.acceleration 500
extruder.hotend.max_speed 50
extruder.hotend.step_pin 2.3
extruder.hotend.dir_pin 0.22
extruder.hotend.en_pin 0.21
# Second extruder (T1) on epsilon/M5 driver
extruder.hotend2.enable true
extruder.hotend2.steps_per_mm 140
extruder.hotend2.acceleration 500
extruder.hotend2.max_speed 50
extruder.hotend2.step_pin 2.8
extruder.hotend2.dir_pin 2.13
extruder.hotend2.en_pin 4.29
extruder.hotend2.x_offset 25.0
extruder.hotend2.y_offset 0.0
extruder.hotend2.z_offset 0.0
# Current control
delta_current 1.5
epsilon_current 1.5
# First extruder (T0) on delta/M4 driver
[extruder]
hotend.enable = true
hotend.steps_per_mm = 140
hotend.step_pin = 2.3
hotend.dir_pin = 0.22
hotend.en_pin = 0.21
# Second extruder (T1) on epsilon/M5 driver
[extruder]
hotend2.enable = true
hotend2.steps_per_mm = 140
hotend2.step_pin = 2.8
hotend2.dir_pin = 2.13
hotend2.en_pin = 4.29
hotend2.x_offset = 25.0
hotend2.y_offset = 0.0
hotend2.z_offset = 0.0
[actuator delta]
acceleration = 500
[actuator epsilon]
acceleration = 500
[motion control]
max_speed = 50
[current control]
delta = 1.5
epsilon = 1.5
acceleration (moved to [actuator] sections) and max_speed (moved to [motion control]). Refer to the options table above for the exact V2 location of each setting.
Here are the G-code commands currently supported by the Extruder module:
| Code | Description |
|---|---|
| Move to the given coordinates. The |
|
| Do firmware extruder retract | |
| Do firmware extruder un-retract | |
| Absolute mode (default): passed coordinates will be considered absolute (command is modal) | |
| Relative mode: passed coordinates will be considered relative to the current point (command is modal). Make sure you use |
|
| Set current position to specified coordinates (example: |
|
| Turn the active stepper motor driver's off | |
| Turn the active stepper motor driver's on | |
| Set absolute mode for extruder only | |
| Set relative mode for extruder only | |
| Turn off stepper motor drivers | |
| Set this axis' steps per millimetre. For example |
|
| Displays |
|
| Set |
|
| Set maximum rate for axis, set |
|
| Set acceleration in mm/sec², |
|
| Set retract length |
|
| Set retract recover length |
|
| Save volatile settings to an override file | |
| Display volatile settings |