Differences

This shows you the differences between two versions of the page.

Link to this comparison view

Both sides previous revision Previous revision
Next revision 		Previous revision
joystick [2017/01/25 15:06]
arthur 		joystick [2021/02/22 16:52] (current)
Line 1: Line 1:
-[[div style="float:right"]] +<WRAP right round box> 
-[[f>image joystick.png width="420px"]] +[[https://www.sparkfun.com/products/9110|{{ ://joystick:joystick.png?200}}]] 
-Image modified from [https://www.sparkfun.com/products/9110 SparkFun Electronics] [http://creativecommons.org/licenses/by-nc-sa/3.0/ (CC BY-NC-SA 3.0)]+</WRAP>
  
 += Joystick Module
  
-= 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]] 
 == What is Joystick? == 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 [[https://learn.sparkfun.com/tutorials/analog-vs-digital|analog]] voltage (things like joysticks, sliders, knobs, force sensitive resistors, etc).
-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 [*https://learn.sparkfun.com/tutorials/analog-vs-digital analog] voltage (things like joysticks, sliders, knobs, force sensitive resistors, etc).+
  
 Some possible uses for the Joystick module: Some possible uses for the Joystick module:
-* Moving your machine around manually (see [#Jogging jogging]) +* Moving your machine to set up the part origin (see [[#Jogging|jogging]]) 
-* Manually overriding your machine's speed with a knob/slider (see [#FRO feed rate override])+* Retracting an extruder on a 3D-printer 
 +* Focusing a laser cutter 
 +* Manually overriding your machine's speed with a knob/slider (see [[#FRO|feed rate override]]) 
 +* Controlling spindle speed with a knob on a mill
  
  
 == Getting Started == Getting Started
-<callout type="danger" icon="true" title=" Not yet completed or released">+<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. 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]]
 </callout> </callout>
 === Hardware Requirements === Hardware Requirements
-[[div style="float:right"]] 
-[[f>image joystick.png height="150px"]] 
-[[f>image https://cdn.sparkfun.com//assets/parts/7/6/5/5/11621-01.jpg height="150px"]] 
-[[f>image https://cdn.sparkfun.com//assets/parts/4/0/4/9/09939-01.jpg height="150px"]] 
-Images from SparkFun Electronics [http://creativecommons.org/licenses/by-nc-sa/3.0/ (CC BY-NC-SA 3.0)] 
  
 +{{ ://joystick:joystick.png?150}}
 +{{ //external/https.cdn.sparkfun.com.assets.parts.7.6.5.5.11621.01.jpg.150.image.from.sparkfun.electronics.cc.by.nc.sa.3.0.}}
 +{{ //external/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 [*https://learn.sparkfun.com/tutorials/voltage-dividers/ SparkFun's tutorial].+ 
 +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 [[https://learn.sparkfun.com/tutorials/voltage-dividers/|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). 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).
Line 38: Line 36:
 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). 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"]] +{{//external/https.cdn.sparkfun.com.assets.6.3.e.5.e.511ac8f5ce395f5846000000.png.300.image.from.sparkfun.electronics.cc.by.nc.sa.3.0.}}
-[[image https://cdn.sparkfun.com/assets/6/3/e/5/e/511ac8f5ce395f5846000000.png width="300px"]] +
-Image from SparkFun Electronics [http://creativecommons.org/licenses/by-nc-sa/3.0/ (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). 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"> <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.+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> </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: 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 ^ 
-||~ Analog Pin ||~ Smoothie Assignment ||~ Comments || +| 0.2 | uart0 txd | Not recommended (used for ISP programming of the bootloader and for debugging) | 
-|| 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.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((Thermistor pins could be used if the pull-up is desoldered, do so at your own risk.))) | 
-|| 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.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.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) | 
-|| 0.26 || thermistor3 || Not recommended (used for thermistors and has built-in 4.7 kΩ pull-up) || +| **1.30** | spare | Recommended pin | 
-|| 1.30 || spare || Recommended pin || +| **1.31** | spare | Recommended pin |
-|| 1.31 || spare || Recommended pin || +
  
 See [[Pinout]] for a diagram of the SmoothieBoard with the pins labeled. 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). 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).
- +{{://joystick:joystick_connections.png?nolink&400}}
-(image of joystick connection)+
  
 == Configuration == Configuration
Line 73: Line 65:
 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 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 way the Joystick module performs this conversion is to first measure the voltage coming in. The module then subtracts off an offset, called <kbd>zero_offset</kbd>. The module then scales the voltage reading so that the <kbd>zero_offset</kbd> voltage becomes 0, and the <kbd>endpoint</kbd> voltage becomes 1 or -1 (depends on if <kbd>endpoint</kbd> is greater or less than <kbd>zero_offset</kbd>). Any values which end up outside the -1 to 1 range are fixed to be at +/- 1.
  
-[[div style="margin:2em"]] +<WRAP center round box 80%> 
-[[=]] +{{ ://joystick:joystick_mapping_diagram.png?1000 }}
-[[image Joystick%20Mapping%20Diagram.png width="700px"]] +
-//Example Mapping from joystick position to output with {{zero_offset}} = 1.5 V and {{endpoint}} = 0 V// +
-[[/=]]+
  
 +Example Mapping from joystick position to output with <kbd>zero_offset</kbd> = 1.5 V and <kbd>endpoint</kbd> = 0 V
 +</WRAP>
  
 === Auto-Zeroing === 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}}.+The joystick module has an optional feature which automatically determines <kbd>zero_offset</kbd>. For a short period of time (<kbd>startup_time</kbd>) 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 <kbd>zero_offset</kbd>.
  
-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.+This feature is useful for joysticks, where the <kbd>zero_offset</kbd> 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.
  
-<callout type="warning" icon="true" title=" Warning"> +<callout type="warning" icon="true" title="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.+Be careful not to move the joystick during the <kbd>startup_time</kbd>, otherwise the <kbd>zero_offset</kbd> will be wrong and the joystick will have undesirable behavior.
 </callout> </callout>
  
 === All Configuration Options === All Configuration Options
  
-[[div style="margin:2em"]] 
-||~ Option ||~ Example Value ||~ Explanation || 
 {{page>joystick-options}} {{page>joystick-options}}
  
 +== Usage
 +=== Jogging 
 +<html><a name='Jogging'></a></html>
  
-== Examples+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:
  
-[[code]] +<file - joystick-2D.config> 
-example block of code +joystick.horizontal.enable                     true #enable the horizontal axis joystick 
-[[/code]]+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
  
-{{example G code}}+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 
 +</file>
  
-<callout type="primary" icon="true" title=" Callout Title (asterisk to leave out of TOC)"> +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 <kbd>data_source_xxx</kbd> configs for the [[Jogger]]. An example of those options is shown below:
-Example primary callout text. +
-</callout>+
  
-<callout type="info" icon="true" title=" Info Title"> +<file> 
-Example info callout text. +jogger.enable                                  true 
-</callout>+jogger.data_source_alpha                       horizontal 
 +jogger.data_source_beta                        vertical 
 +</file> 
 + 
 +These options tell the jogger the names of the joystick modules to read when jogging.
  
-<callout type="warning" icon="true" title=" Warning Title"> +<callout type="success" icon="true"> 
-Example warning text.+You're all set! For more jogging configuration options, see [[Jogger]].
 </callout> </callout>
  
-<callout type="danger" icon="true" title=" Danger Title"> +=== Feed Rate Override  
-Text+<html><a name='fro'></a></html> 
 +<callout type="warning" icon="true" title="Not yet completed or released"> 
 +Note: no feed rate override has been implemented in smoothie yet. The following example is purely hypothetical.
 </callout> </callout>
  
-<callout type="success" icon="true" title=" Title Success"> +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:
-Text Success +
-</callout>+
  
-== Usage +<file - feedrate-override.config> 
-=== Jogging [[# Jogging]] +joystick.fro.enable                            true #enable the feed-rate override joystick 
-Describes how to use the joystick with the jog module to move the machine around.+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 
 +</file> 
 + 
 +With the joystick properly configured, you will simply need to tell the Feed Rate Override module((Doesn't exist yet)) which joystick to read: 
 + 
 +<file> 
 +feedoverride.data_source                       fro 
 +</file> 
 + 
 +<callout type="success" icon="true"> 
 +You're all set! For more feed-rate override configuration options, see [[Feed Rate Override]]. 
 +</callout>
  
-=== Feed Rate Override [[# FRO]] 
-Describes how to use the joystick to override the feed rate. 
 == Developer Documentation == Developer Documentation
-Link to Joystick developer doc page which gives info on how to interface with the module when writing other modules.+For information on how to write your own module which uses a joystick, see the [[joystick-dev|joystick developer documentation]].