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 around manually (see jogging)
  • Manually overriding your machine's speed with a knob/slider

Getting Started

Hardware Requirements

joystick.png
11621-01.jpg
09939-01.jpg

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

511ac8f5ce395f5846000000.png
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-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)

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.

Joystick%20Mapping%20Diagram.png
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

Examples

example block of code

example G 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

Text

Title Success

Text Success

Usage

Jogging

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

Developer Documentation

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