Motion control

Smoothie reads G-code instructions and converts those into movement, typically by turning motors.

While that might sound pretty trivial to do, the laws of physics actually make this a bit more challenging than one might expect.

This page explains how to configure the different motion control parameters you can tune in Smoothie.

[!NOTICE] NOTE you MUST define at least alpha, beta, and gamma in a valid config file, do not comment out gamma even if you are not using it.



Or “the increase of speed”. You experience it every day.

When you ask Smoothie to move a certain distance at a certain speed, it starts at a speed of 0 (not moving).

If it goes instantly to the requested speed, in most cases, that won’t work: A motor cannot go from a speed of 0 to several rotations per second instantly. It needs to accelerate to that speed.

Similarly, the axis which is controlled itself has a given weight that needs to be moved. The faster you accelerate, the more force is required to accelerate the mass to the target speed.

This means that for any given machine, you must tune your acceleration. And that acceleration’s value is a function of the torque of your motors and the weight of whatever needs to move.

You set the acceleration value by modifying the acceleration value in your configuration file:

acceleration                                 3000             # Acceleration in mm/second/second.

Force is mass times acceleration

The units are millimeters per second per second, which means how many “millimeters per second” worth of speed is added every second.

3000 is a pretty common value for a 3D printer or laser cutter since they have very little mass to move.

200 is a common value for CNC mills or routers since they have much more mass to move and have to apply forces to their tool.

There is no mathematical/easy way of determining a perfect value: you are going to need to try values and find the one that works best for you.

If you feel like your machine is too slow, you increase acceleration. If your machine starts losing steps, losing its position, or shakes too much, you reduce acceleration.

Note that you do not need to reset your Smoothieboard to try new values. You can start a “job”, and while the job is executing, try new values using the M204 M-code. For example, M204 S2000 sets acceleration to 2000 (it takes a few seconds for this to take effect after the command is sent).

[!NOTE] On some machines, your Z axis is very different from the others and has different requirements and capabilities.

On those machines, you can set the acceleration for Z separately, by editing the gamma.acceleration value.

Junction deviation

Smoothie accelerates when it starts a move and decelerates when it stops the move.

But what about if you move forward, then need to move somewhat to the right? Do you really want to decelerate to a speed of zero before moving to the right? That’d be a huge waste of time.

Junction deviation determines how much to slow down, proportional to how much the direction changes.

It doesn’t really have a unit, it’s just an arbitrary ratio. The smaller junction deviation is, the more we slow down on direction changes. The larger it is, the less we slow down on direction changes.

This generally means you can configure how much the machine “shakes” when moving: The less the machine slows down when changing direction, the more force is transferred to the structure of the machine, and the more the machine will shake.

But the more sturdy the machine it is, the higher junction deviation it will be able to handle without shaking.

Like acceleration, this is a value you will have to “play with” to find the right value for you.

You change it by changing the junction_deviation value in config.

junction_deviation       0.05       # Similar to the old "max_jerk", in millimeters,

0.05 is a typical value for a 3D printer. If your printer is very sturdy, you could use 0.1. 0.005 is a typical value for a CNC mill or router, though for some machine you might need to go to smaller values like 0.001.

You can learn more about Junction Deviation in this forum post.

Maximum speeds

Where speeds are concerned, Smoothie makes the distinction between two very important things: axes and actuators.

An actuator and an axis are two different things. An actuator is the thing that the motor causes to move directly. The axes are pretty much the coordinate system for the “tool”, and the system the Gcode uses.

On a cartesian machine, they are the same thing (X is alpha, Y is beta, etc. See Greek_alphabet). But on a linear delta machine, for example, they are different.

On a linear delta, the actuator is the linear axis that moves along a tower, while the axis (or effector) is the thing at the end of the arms that moves the tool.

In Smoothie, you can set maximum speeds for both of those systems separately.

Setting a maximum speed ensures that Smoothie will never go higher than that speed for that axis or actuator. This is useful if the machine would “skip” steps or have other problems if too high a speed was required, which is the case in most machines.

To set the maximum speed for an axis, edit the max_speed configuration option for that axis:

x_axis_max_speed            30000      # mm/min

The units for the speed limit are millimeters per minute.

To limit the speed for an actuator, set the max_rate for that actuator:

alpha_max_rate       30000.0         # mm/min

[!SUCCESS] Note that increasing acceleration allows reaching higher maximum speeds, in general.

But decreasing acceleration also decreases the average movement speed over a whole G-code file.

This is because of physics and inertia.

Adjusting Z once printing starts (sometimes called babysteps)

You can adjust the Z while it is printing by using the WCS offsets. For instance, to raise the head 0.1mm:

  1. G10 P0 L2 Z0.1 - this will set the Z WCS to 0.1mm higher, however, it will NOT move the head immediately as it only takes effect on the next G1 that has a Z in it
  2. G0 Znnn - this will move the Z after the last received G-code to nnn, you will need to make sure that nnn is the actual Z height you want right now (usually the Z it is currently at, as 0.1mm will be added to that due to step 1)

A better and easier way is in the very latest edge build. G43.2 Z0.1 will raise the Z by 0.1mm by setting the Z tool offset and also queuing a move by 0.1mm, this is not instant but will happen when the previous G-codes have executed. It can be canceled with G49. NOTE as this uses tool offsets a multi-extruder setup executing a T0 or T1 will reset the offset to the default for that tool.

If you want to do baby steps from the panel menus, you can easily do this using the custom_menu (see panel) feature of panels:

custom_menu.babystepup.enable               true              #                 Baby step up      #
custom_menu.babystepup.command              G43.2 Z0.05       #

custom_menu.babystepdown.enable             true              #               Baby step down    #
custom_menu.babystepdown.command            G43.2 Z-0.05      #

All options

Here are all the options related to motion control:

| Option | Example value | Explanation | | —— | ————- | ———– |

Motion Control Options

Option Default Value Description
default_feed_rate 4000 Default rate for G1/G2/G3 moves in millimetres/minute. This is overridden by the first F (feedrate) parameter after reset, and never used again.
default_seek_rate 4000 Default rate for G0 moves in millimetres/minute
mm_max_arc_error 0.01 Arcs are cut into segments (lines), This is the maximum error for line segments that divide arcs
mm_per_line_segment 5 Lines can be cut into segments (generally not useful with cartesian coordinates robots), this sets the maximum length of any given segment. Segments longer than this will be cut into several segments.
delta_segments_per_second 100 Instead of cutting lines into segments based on a distance, cut them based on time: segments will be cut so that Smoothie executes -about- delta_segments_per_second segments each second. This is mostly useful when using linear_delta arm solutions.
planner_queue_size 32 Defines how many blocks (line segments) are stored in RAM for look-ahead acceleration calculation. Do not change this unless you know exactly what you are doing, the reason why is increasing the size of the queue makes it take up more RAM space and can result in Smoothie running out of RAM, depending on your configuration and how much the rest of your modules take up space.
acceleration 3000 Acceleration in millimetres/second/second. Higher values make your machine faster and shakier, lower values make your machine slower and sturdier. This is generally proportional to the weight of the tool you are trying to move.
alpha_acceleration   Acceleration in millimetres/second/second for the alpha actuator (X axis on cartesian), do not set on deltas
beta_acceleration   Acceleration in millimetres/second/second for the beta actuator (Y axis on cartesian), do not set on deltas
gamma_acceleration   Acceleration in millimetres/second/second for the gamma actuator (Z axis on cartesian), do not set on deltas
junction_deviation 0.05 Similar to the old “max_jerk”, in millimeters. Defines how much the machine slows down when decelerating proportional to the vector angle of change of direction. See here and here. Lower values mean being more careful, higher values means being faster and have more jerk
z_junction_deviation 0 Junction deviation for Z only moves, -1 uses junction_deviation, 0 disables junction_deviation on z moves. Do not set this value if you use a delta arm solution.
minimum_planner_speed 0 Sets the minimum planner speed in millimetres/sec. This is the lowest speed the planner will ever set a move to. Not generally useful.
microseconds_per_step_pulse 1 Duration of step pulses to the stepper motor drivers, in microseconds. Actual step pulse is generally 2us above this (so 1 will actually be 2-3us). Setting this over about 8us will cause severe issues with step generation
base_stepping_frequency 100000 Base frequency for stepping, higher values gives smoother movement. Do not modify unless you know exactly what you are doing, 100khz is the only officially supported value.

For devs

[!NOTE] Smoothie’s main job is to convert G-code into movement. Motion control modules (in the source code src/modules/robot) are the various steps in that process. For more on that process, see Howitworks, for general use and configuration documentation on Smoothie’s motion control, see below:

External resources

Video about maximum speeds