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
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).
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).
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).
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)|
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.
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
|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|
|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|
example block of code
example G code
Callout Title (asterisk to leave out of TOC)
Example primary callout text.
Example info callout text.
Example warning text.
Describes how to use the joystick with the jog module to move the machine around.
Link to Joystick developer doc page which gives info on how to interface with the module when writing other modules.