This is an old revision of the document!

style="float:right" joystick.png width="420px" Image modified from SparkFun Electronics] [[]|(CC BY-NC-SA 3.0)] = Joystick Module <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> [[f>toc

Joystick is a module for SmoothieBoard which adds the ability to use joysticks with your machine. It is much like the [Switch]|module, but can read from things which output an [* analog] voltage (things like joysticks, sliders, knobs, force sensitive resistors, etc).

Some possible uses for the Joystick module:

joystick.png height="150px" height="150px" height="150px" Images from SparkFun Electronics (CC BY-NC-SA 3.0)] To begin, you will need a device that you want to read. Some example devices are shown here, but really any variable resistor (potentiometer) or device that outputs 0-3.3 V should work. For more information on how potentiometers work, see [[*]|SparkFun's tutorial]. For the rest of the document, the examples will be for a 2-axis joystick like in the right-most picture. This joystick has two separate potentiometers for each axis, and has springs inside to return the knob to the center when released (think PlayStation controller knob). === Connections If you have a potentiometer, you will need to connect one side to 3.3 V, the other side to ground, and the wiper to a pin on the SmoothieBoard which supports analog reading (see table below). [[[div]|style="margin:2em" width="300px" Image from SparkFun Electronics (CC BY-NC-SA 3.0)] The above image shows a basic schematic of a potentiometer. Pins 1 and 3 are the ends of the potentiometer, and Pin 2 is the wiper. Vin should be 3.3 V for the SmoothieBoard, and Pin 2 will be connected to a compatible pin on the SmoothieBoard (see table below). <callout type="warning" icon="true" title=" Caution"> Use caution when connecting a potentiometer to your SmoothieBoard. If Vin is a higher voltage than the SmoothieBoard's pins can handle (-0.5 to 5.1 V for < 10 ms), you might ruin your board. Use Vin = 3.3 V unless you know what you are doing. </callout> The analog pins on the SmoothieBoard which can be connected to a wiper (Pin 2 in above schematic) are shown in the table below: [[[div]|style="margin:2em"

~ Analog Pin ~ Smoothie Assignment ~ Comments
0.2 uart0 txd Not recommended (used for ISP programming of the bootloader and for debugging)
0.3 uart0 rxd Not recommended (used for ISP programming of the bootloader and for debugging)
0.23 hotend.thermistor_pin Not recommended (used for thermistors and has built-in 4.7 kΩ pull-up)
0.24 bed.thermistor_pin Not recommended (used for thermistors and has built-in 4.7 kΩ pull-up)
0.25 thermistor2 Not recommended (used for thermistors and has built-in 4.7 kΩ pull-up)
0.26 thermistor3 Not recommended (used for thermistors and has built-in 4.7 kΩ pull-up)
1.30 spare Recommended pin
1.31 spare Recommended pin

See Pinout for a diagram of the SmoothieBoard with the pins labeled.

For a joystick, you will need to connect each wiper (the left/right and up/down) to different analog pins (e.g. 1.30 and 1.31).

(image of joystick connection)

Mapping Voltage to Position

The configuration file, at its most basic level, must tell the SmoothieBoard how to convert the 0 to 3.3 V that it reads into a more useful range of numbers. The range that the Joystick module uses is -1 to 1. It is also possible to use a 0 to 1 range if negative values don't make sense for your application.

The way the Joystick module performs this conversion is to first measure the voltage coming in. The module then subtracts off an offset, called zero_offset. The module then scales the voltage reading so that the zero_offset voltage becomes 0, and the endpoint voltage becomes 1 or -1 (depends on if endpoint is greater or less than zero_offset). Any values which end up outside the -1 to 1 range are fixed to be at +/- 1.

style="margin:2em" = Joystick%20Mapping%20Diagram.png width="700px" Example Mapping from joystick position to output with zero_offset

1.5 V and {{endpoint}} = 0 V//



The joystick module has an optional feature which automatically determines zero_offset. For a short period of time (startup_time) after the SmoothieBoard is powered on / reset, the joystick module averages the joystick readings. The average value at the end of the startup time is used as the zero_offset.

This feature is useful for joysticks, where the zero_offset is somewhat unknown (it is usually around 1.65 V but different devices have slightly different center values). It would not make sense to enable for sliders or knobs, since the knob doesn't have a known/default starting position.


Be careful not to move the joystick during the startup_time, otherwise the zero_offset will be wrong and the joystick will have undesirable behavior.

All Configuration Options


~ Option ~ Example Value ~ Explanation
Option Example Value Explanation
joystick.module-name.enable true If true, create and enable a new Joystick module with the name “module_name” 1.30 Which SmoothieBoard pin should be used to read the value. See table above for allowable pins.
joystick.module-name.refresh_rate 10 Sets how many times per second to update the joystick reading
joystick.module-name.zero_offset 1.65 Sets what voltage will map to zero output
joystick.module-name.endpoint 3.3 Sets what voltage will map to +/- 1
If endpoint is greater than zero_offset, it specifies what voltage maps to 1
If endpoint is less than zero_offset, it specifies what voltage maps to -1
Auto-Zero Configurations
joystick.module-name.auto_zero true If true, enables the auto-zeroing feature, which automatically determines the zero_offset
joystick.module-name.startup_time 1000 Sets how long (in milliseconds) after SmoothieBoard resets to obtain readings to average for zero_offset
It must be at least 1000 / refresh_rate, but shouldn't be too long,
otherwise the joystick might be moved during the measurement.
joystick.module-name.start_value 0 Sets the default value of the joystick output during the startup time. Should be between -1 and 1
2017/01/25 14:19 · arthur

code example block of code


Callout Title (asterisk to leave out of TOC)

Example primary callout text.

Info Title

Example info callout text.

Warning Title

Example warning text.

Danger Title


Title Success

Text Success

Jogging [[[#]|Jogging]]

Describes how to use the joystick with the jog module to move the machine around.

Feed Rate Override [[[#]|FRO]]

Describes how to use the joystick to override the feed rate.

Link to Joystick developer doc page which gives info on how to interface with the module when writing other modules.