Differences

This shows you the differences between two versions of the page.


jogger [2022/07/17 17:35] (current) – created - external edit 127.0.0.1
Line 1: Line 1:
 += Jogger Module
  
 +<callout type="danger" icon="true" title="Abandoned">
 +This module no longer works and has been abandoned, and there are no plans to integrate it.
 +</callout>
 +
 +== 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
 +<callout type="danger" icon="true" title="Not yet completed or released">
 +Note this page is a work in progress and the joystick functionality is not yet released in smoothieware.
 +</callout>
 +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-name|module names]] of the joystick axes you want to link to the jogger.
 +
 +== Configuration
 +=== All Configuration Options
 +{{page>jogger-options}}
 +
 +=== 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: <kbd>max_speed</kbd> and <kbd>nonlinearity</kbd>.
 +
 +* <kbd>max_speed</kbd>: tells the jogger how fast to go when the joystick is pushed as far as possible
 +* <kbd>nonlinearity</kbd>: 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:
 +
 +{{//jogger:jogger_speed_map.png?800}}
 +
 +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 <kbd>dead_zone</kbd> configuration, which is used to make sure the joystick has actually moved before jogging. If undesired jogging occurs, increase the <kbd>dead_zone</kbd> value.
 +
 +== Examples
 +=== Set Jog Axes
 +The command to set the jog axes is M777 by default, unless changed by the <kbd>m_code_set</kbd> 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 ^
 +|<code>M777 XY</code> | X | Y |
 +|<code>M777 XZ</code> | X | Z |
 +|<code>M777 -Z</code> | none | Z |
 +
 +=== Toggle Jog Axes
 +The command to toggle the jog axes is M778 by default, unless changed by the <kbd>m_code_toggle</kbd> configuration. Toggling the axes will cycle between the axes set in the <kbd>jog_axes</kbd> configuration.
 +<code>
 +M778
 +</code>
 +
 +An example line of configuration is shown below:
 +<file>
 +jogger.jog_axes             XY,XZ,-Z         #cycle between the joystick horz/vert controlling axes XY, XZ, and nothing/Z when using M778
 +</file>
 +
 +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.
 +
 +== Developer Documentation
 +For information on how to write a module which the jogger can read, see the [[jogger-dev|jogger developer documentation]].