Jogger Module
The Jogger module is deprecated in Smoothieware V2. For V2, please see the MPG module documentation for jogging functionality.
This is historical documentation for Smoothieware V1. This module is not available in V2.
What is Jogger?
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
Getting Started
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.
Configuration
All Configuration Options
| V1 Setting | V2 Setting | Description |
|---|---|---|
| Not available in v2 | If true, enable the Jogger module. The Jogger module allows you to control machine movement using joystick input, providing smooth continuous motion in the direction of the joystick rather than discrete steps. | |
| Not available in v2 | Specifies the module name of the Joystick module that the alpha (first) jog axis will read from. This connects a joystick instance to the first axis of jogging control. The value should be the name of a configured joystick module (e.g., "horizontal", "vertical"). | |
| Not available in v2 | Specifies the module name of the Joystick module that the beta (second) jog axis will read from. This connects a joystick instance to the second axis of jogging control. The value should be the name of a configured joystick module (e.g., "horizontal", "vertical"). | |
| Not available in v2 | Sets a comma-separated list of 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. Example: "XY,XZ,-Z" allows toggling between XY control, XZ control, and no alpha axis with Z beta axis. | |
| Not available in v2 | Sets which M-code number the "set axes" command will use. For example, if set to 777, use M777 to set the jog axes. This command allows you to directly specify which axes to control with the joystick (e.g., M777 XY sets jogging to control X and Y axes). | |
| Not available in v2 | Sets which M-code number the "toggle axes" command will use. For example, if set to 778, use M778 to toggle the jog axes. This command cycles through the axis combinations specified in the jog_axes setting, allowing you to switch between different control modes (e.g., XY mode, XZ mode, etc.). | |
| Not available in v2 | Sets the maximum speed the machine will jog in mm/min. This is the speed reached when the joystick is pushed to its maximum extent. If not specified, the Jogger uses the general configuration "default_seek_rate" ( |
|
| Not available in v2 | Sets the threshold the joystick must cross before movement occurs. This is a value between 0 and 1 representing the fraction of joystick movement required to start jogging. For example, 0.05 means the joystick must be moved 5% from center before motion begins. This prevents unwanted motion from small joystick movements or electrical noise. Increase this value if you experience drift or unwanted motion. | |
| Not available in v2 | Sets the non-linearity of the joystick to speed conversion function. Values greater than 1.0 create a curved response where small joystick movements result in proportionally slower speeds, giving finer control near center. A value of 1.0 is linear (50% joystick movement = 50% max speed). Typical values: 1.0 (linear), 1.5 (slight curve for better control), 2.0 (more pronounced curve), 3.0 (very sensitive near center). Higher values provide more precise control for small adjustments but require larger movements to reach full speed. | |
| Not available in v2 | Specifies how many times per second to read the joysticks and update the jog motion. Higher values provide smoother, more responsive control but use more CPU time. Typical value is 100 Hz. Must be coordinated with the joystick module's refresh_rate setting. | |
| Not available in v2 | Sets the number of tiny movement segments per second while jogging. The jogger breaks continuous motion into small discrete segments for smooth execution. Higher values create smoother motion but require more processing. Typical value is 10 Hz. This is different from refresh_rate - refresh_rate determines how often joystick position is read, while segment_frequency determines how often new movement commands are generated. |
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:
-
: tells the jogger how fast to go when the joystick is pushed as far as possible
-
: 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
If undesired jogging occurs, increase the
Examples
Set Jog Axes
The command to set the jog axes is| Example | Alpha Jog Axis | Beta Jog Axis |
|---|---|---|
| X | Y | |
| X | Z | |
| none | Z |
Toggle Jog Axes
The command to toggle the jog axes isM778
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
NOTE: This references
Developer Documentation
For information on how to write a module which the jogger can read, see the jogger developer documentation.