Jogger Module

Jogger is a module for SmoothieBoard which adds the ability to move your machine around: a process referred to as “jogging”. This module is different from most jogging tools in that it accepts input from a joystick. This means your machine will move smoothly in the direction of the joystick, rather than take a small step in a certain direction each time a button is pressed.

Some possible uses for the Jogger module:

  • Moving a cutting tool to the origin of a part
  • Moving your print head to clear a jam, inspect the nozzle, or perform bed leveling
  • Moving extruders to retract the filament
  • Moving a laser cutter to focus the beam

Not yet completed or released

Note this page is a work in progress and the joystick functionality is not yet released in smoothieware.

You will need some kind of joystick-like device that the Jogger module will use to tell your steppers where to go. See the joystick page for information on how to set up an analog joystick. Once you have the joystick modules set up, you will need to know the module names of the joystick axes you want to link to the jogger.

All Configuration Options

Option Example Value Explanation
jogger.enable true If true, enable the Jogger module
jogger.data_source_alpha horizontal Specifies the module name of the Joystick module the alpha/first jog axis will read from
jogger.data_source_beta vertical Specifies the module name of the Joystick module the beta/second jog axis will read from
jogger.jog_axes Xy,XZ,-Z Sets a list of the machine axes which will be controlled by the jogger
Axis letters are given in order of jog axis alpha, beta, etc.
The first item in the list will be used on startup
Issuing the toggle axes command (M778 by default) will cycle between the items in the list
Valid machine letters are X, Y, Z, A, B, C.
Use “-” for no axis controlled
Do not use spaces in the list
jogger.m_code_set 777 Sets which M-code number the set axes command will use (777 means use M777 to set the jog axes)
jogger.m_code_toggle 778 Sets which M-code number the toggle axes command will use (778 means use M778 to toggle the jog axes)
jogger.max_speed 600 Sets the maximum speed the machine will jog
If not given, the Jogger uses the general configuration “default_seek_rate” (G0 speed)
jogger.dead_zone 0.05 Sets the threshold the joystick must cross before movement occurs (see description below)
jogger.nonlinearity 1.5 Sets the non-linearity of the joystick to speed conversion function (see description below)
jogger.refresh_rate 100 Specifies how many times per second to read the joysticks
jogger.segment_frequency 10 Sets the number of tiny movement segments per second while jogging
2017/02/20 09:56

Mapping Joystick Position to Jog Speed

The jogger module must figure out how to convert the -1 to 1 range of the joystick into meaningful jog speeds. To do this, two main configuration parameters come into play: Max_speed and Nonlinearity.

  • Max_speed: tells the jogger how fast to go when the joystick is pushed as far as possible
  • Nonlinearity: tells the jogger how to go from not moving to max speed

The maximum speed should be relatively straightforward, however the nonlinearity is more difficult to explain. To see how it works, consider the following graph:

On the X-axis is the joystick position, from not moved on the left (0.00) to fully moved on the right (1.00). On the Y-axis is the jogging speed, where 0% is not moving and 100% is moving as fast as possible. The different colored lines show how the nonlinearity parameter affects the jog speed. The table below describes the values demonstrated in the chart above:

Nonlinearity Comments
1.0 Linear change, moving the joystick halfway will go half of max speed
1.2 Tiny nonlinearity, will likely be indistinguishable from linear
1.5 Small nonlinearity, speed will be slightly slower for small joystick movement
2.0 Normal nonlinearity, jogging will be very slow and controlled for small joystick movement, and quickly gain speed for large movements
3.0 Large nonlinearity, jogger will barely move until joystick is pushed to ~%20, and speed will gain very quickly from here. This might be too large a value for most users

Notice for all the example values in the chart above, there is a region below ~0.05 on the joystick axis where the jogger does not move at all. This is the Dead_zone configuration, which is used to make sure the joystick has actually moved before jogging. If undesired jogging occurs, increase the Dead_zone value.

Set Jog Axes

The command to set the jog axes is M777 by default, unless changed by the M_code_set configuration. To use the command, type the M-code followed by the letters to use for jog axes (in order of alpha, beta, etc.).

Example Alpha Jog Axis Beta Jog Axis
M777 XY
M777 XZ
M777 -Z
none Z

Toggle Jog Axes

The command to toggle the jog axes is M778 by default, unless changed by the M_code_toggle configuration. Toggling the axes will cycle between the axes set in the Jog_axes configuration.


An example line of configuration is shown below:

jogger.jog_axes             XY,XZ,-Z         #cycle between the joystick horz/vert controlling axes XY, XZ, and nothing/Z when using M778

In this example, the jogger will start controlling by controlling XY. When M778 is issued, it will change to XZ. If issued again, it will change to nothing/Z, and if issued once more, go back to XY.

For information on how to write a module which the jogger can read, see the jogger developer documentation.