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:
Not yet completed or releasedNote this page is a work in progress and the joystick functionality is not yet released in smoothieware.
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).
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).
CautionUse 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)|
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.
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.
WarningBe 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
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.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.
Feed Rate Override
Not yet completed or releasedNote: 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:
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:
For information on how to write your own module which uses a joystick, see the joystick developer documentation.