Marlin Planner 101

This is a new post about FW movement, specifically, about Marlin planner.

“THE PLANNER  buffers movement commands and manages the acceleration profile plan”

For me its easier to understand the planner as a black box that translates movement commands into the DESIRED movement profile that motors understand.

The goal of the planner is to maximize the speed profile between all the GCode movement making sure we only have one constant acceleration for all the speed movement profiles. This ensure that our printer moves as fast as is possible within the kinematic constant constrains (ACCELERATION and JERK @Configuration).

Fig. By

To start explaining how the planner works it is important to understand the main data structure and what is used for. This data structure type is called block_t (@planner.h). It has three groups of variables used for different purposes:

steps_x, steps_y, steps_z, steps_e; step_event_count; accelerate_until; decelerate_after;  acceleration_rate; direction_bits and active_extruder. 

All this variables are used @stepper.cpp during ISR execution. This ISR, as previously mentioned, takes care of direct control of the stepper motors. This set of variable allow the ISR to calculate the right amount of time in between each motor step to fit the desired movement profile.

  • Manage acceleration

nominal_speed; entry_speed;  max_entry_speed;  millimeters;  acceleration;  recalculate_flag and nominal_length_flag.

This are the variables used by the motion planner to manage acceleration. We will explain them in deeper as we keep going through the planner explanation.

  • Trapezoid generator

nominal_rate;  initial_rate;  final_rate and acceleration_st.

As we explained in the last post, each movement command (target position and feedrate) is hopefully composed by a trapezoid acceleration profile. This variables describe the trapezoid.
We need to keep our stepper motors working within their torque/speed curve specification.  That is why we use an acceleration deceleration trapezoid algorithm to ensure our steppers do not loose any steps.

Once a movement command arrives to the FW, the main function executed from the planner is plan_buffer_line (…). This function does:

  • Calculate most of block’s variables for the received movement command

steps_x, steps_y, steps_z, steps_e, step_event_count, direction_bits, active_extruder, millimetres, nominal_speed, nominal_rate, acceleration_st, acceleration, accelaration_rate, max_entry_speed,  nominal_length_flag and recalculate_flag.

Special attention to understand the planner operation to max_entry_speed and entry_speed.

max_entry_speed is maximum allowable trapezoid junction entry speed (mm/sec). The max_entry_speed in the best case would be equal to nominal speed. But if the speed increment (jerk) between previous and current movement is bigger than the Jerk max constant (defined @Configuration.h) max_entry_speed is reduced by a factor (max_constant_jerk/jerk).

Jerk max constants (aka DEFAULT_XYJERK, DEFAULT_ZJERK, DEFAULT_EJERK [mm/s]). Represent the instant speed increment (infinite acceleration) that an axis can handle without skipping steps.

Entry_speed is the speed junction between previous and current block. Equals minimum value between max_entry_speed and a speed v_allowable calculated with the movement distance (millimeter), acceleration (depends on acceleration constants @Configuration.h DEFAULT_MAX_ACCELERATION and DEFAULT_ACCELERATION ) and MINIMUM_PLANNER_SPEED (constant defined @Configuration_adv.h).

This v_allowable is the maximum speed for a movement that is accelerating or decelerating during all the millimeters travel.


  • Calculate trapezoid values for this block

Accelerate_until, decelerate_after, initial_rate and final_rate.

Next figure shows the trapezoid values:


  • Recalculate planner

Planner recalculation is pretty cool. Actually is my favourite part.It has 3 steps.

  1. Reverse scanning the buffer from latest (head) entry block to the oldest (tail).*
  2. Forward scanning the buffer from oldest (tail) to the newest block (head).*
  3. Recalculate trapezoids for the buffer blocks to adapt to new entry speeds.

*Both Reverse and Forward scanning what do is to evaluate weather or not a junction speed reduction is needed to keep the printer with a constant acceleration and within its jerk constraints.

There is a lot more to explain. Actually we feel we have a long way to go before we could fully understand the planner but we hope this is helpful even as simple introduction to Marlin planner.


Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.