Joystick Module

What is Joystick?

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:

  • Moving your machine to set up the part origin (see jogging)
  • Retracting an extruder on a 3D-printer
  • Focusing a laser cutter
  • Manually overriding your machine's speed with a knob/slider (see feed rate override)
  • Controlling spindle speed with a knob on a mill

Getting Started

Not yet completed or released

Note this page is a work in progress and the joystick functionality is not yet released in smoothieware. To test it you need to use pull request https://github.com/Smoothieware/Smoothieware/pull/1122, and instructions on how to test a Pull request are here http://smoothieware.org/third-party-branches#checking-out-pull-requests

Hardware Requirements

https.cdn.sparkfun.com.assets.parts.7.6.5.5.11621.01.jpg.150.image.from.sparkfun.electronics.cc.by.nc.sa.3.0 https.cdn.sparkfun.com.assets.parts.4.0.4.9.09939.01.jpg.150.image.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).

https.cdn.sparkfun.com.assets.6.3.e.5.e.511ac8f5ce395f5846000000.png.300.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).

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.

The analog pins on the SmoothieBoard which can be connected to a wiper (Pin 2 in above schematic) are shown in the table below:

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-up1))
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).

Configuration

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.

Example Mapping from joystick position to output with Zero_offset = 1.5 V and Endpoint = 0 V

Auto-Zeroing

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.

Warning

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
joystick.module-name.enable true If true, create and enable a new Joystick module with the name “module_name”
joystick.module-name.pin 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
2022/07/17 17:35

Usage

Jogging

To use the joystick for jogging, configure two different modules with two different names. For example, one module will be called “horizontal” and the other “vertical”. An example config file for the joystick is shown below:

joystick-2D.config
joystick.horizontal.enable                     true				#enable the horizontal axis joystick
joystick.horizontal.pin                        1.30				#use pin 1.30 connected to potentiometer wiper
joystick.horizontal.endpoint                   3.20				#3.2 V maps to +1 in joystick reading
joystick.horizontal.auto_zero                  true				#automatically determine the zero point
joystick.horizontal.startup_time               1000				#take readings for 1 second at startup to get auto-zero point
joystick.horizontal.refresh_rate               100				#update the joystick position 100 times per second
joystick.horizontal.start_value                0				#when auto-zeroing, force joystick output to be 0

joystick.vertical.enable                       true				#enable the vertical axis joystick
joystick.vertical.pin                          1.31
joystick.vertical.endpoint                     3.20
joystick.vertical.auto_zero                    true
joystick.vertical.startup_time                 1000
joystick.vertical.refresh_rate                 100
joystick.vertical.start_value                  0

With the joystick configuration done, you will simply need to configure the Jogger. The only pertinent config for the joystick/jogger connection is setting the Data_source_xxx configs for the Jogger. An example of those options is shown below: 

jogger.enable                                  true
jogger.data_source_alpha                       horizontal
jogger.data_source_beta                        vertical

These options tell the jogger the names of the joystick modules to read when jogging.

You're all set! For more jogging configuration options, see Jogger.

Feed Rate Override

Not yet completed or released

Note: no feed rate override has been implemented in smoothie yet. The following example is purely hypothetical.

To use the joystick to override your machine's feed rate (to go faster or slower while cutting/printing), set up a single joystick axis. An example snippet of the configuration file is shown below:

feedrate-override.config
joystick.fro.enable                            true				#enable the feed-rate override joystick
joystick.fro.pin                               1.30				#use pin 1.30 connected to potentiometer wiper
joystick.fro.endpoint                          3.20				#3.2 V maps to +1 in joystick reading
joystick.fro.zero_offset                       0				#0 V maps to 0 in joystick reading
joystick.fro.refresh_rate                      100				#update the joystick position 100 times per second

With the joystick properly configured, you will simply need to tell the Feed Rate Override module2) which joystick to read: 

feedoverride.data_source                       fro
You're all set! For more feed-rate override configuration options, see Feed Rate Override.

Developer Documentation

For information on how to write your own module which uses a joystick, see the joystick developer documentation.

1)
Thermistor pins could be used if the pull-up is desoldered, do so at your own risk.
2)
Doesn't exist yet