Thumb Joystick Hookup Guide

Pages
Contributors: followr, MikeGrusin, bboyho
Favorited Favorite 4

Introduction

Heads up! This tutorial is for the thumb joystick breakout board and shield. For those that want to quickly connect to the thumb joystick without needing to solder, check out the Qwiic Joystick [COM-15168] to connect via I2C.

Whether you're blasting aliens, driving a robot, or write your awesome classic Arcade Game for your Arduino, you'll find the analog thumb joystick a very useful addition to your projects. This tutorial will go over the analog thumb joystick breakout board with some Arduino examples.

SparkFun Thumb Joystick Breakout

SparkFun Thumb Joystick Breakout

BOB-09110
$2.10
9
Thumb Joystick

Thumb Joystick

COM-09032
$4.50
5

Later, we'll also go over the thumb joystick shield for Arduino and Processing examples. You can follow along with the examples using the breakout board if you have some additional hardware!

SparkFun Joystick Shield Kit

DEV-09760
4 Retired

Suggested Viewing

For a simple demo of the thumb joystick, check out the video below!

Required Materials

To follow along with this tutorial, you will need the following materials. You may not need everything though depending on what you have. Add it to your cart, read through the guide, and adjust the cart as necessary. If you decide to use the breakout board, you'll need the parts from this wish list.

If you decide to use the shield, you'll need the parts from this wish list.

Tools

You will need a soldering iron, solder, and general soldering accessories.

Soldering Iron - 60W (Adjustable Temperature)

Soldering Iron - 60W (Adjustable Temperature)

TOL-14456
$16.50
16
Needle Nose Pliers

Needle Nose Pliers

TOL-08793
$3.50
1
Third Hand

Third Hand

TOL-09317
$10.95
11
Solder Lead Free - 15-gram Tube

Solder Lead Free - 15-gram Tube

TOL-09163
$3.95
4

Panavise Jr. - Vacuum Base

TOL-10410
2 Retired

Suggested Reading

If you aren’t familiar with the following concepts, we recommend checking out these tutorials before continuing.

Pull-up Resistors

A quick introduction to pull-up resistors - whey they're important, and how/when to use them.

How to Solder: Through-Hole Soldering

This tutorial covers everything you need to know about through-hole soldering.

Analog to Digital Conversion

The world is analog. Use analog to digital conversion to help digital devices interpret the world.

Voltage Dividers

Turn a large voltage into a smaller one with voltage dividers. This tutorial covers: what a voltage divider circuit looks like and how it is used in the real world.

What is an Arduino?

What is this 'Arduino' thing anyway? This tutorials dives into what an Arduino is and along with Arduino projects and widgets.

Installing Arduino IDE

A step-by-step guide to installing and testing the Arduino software on Windows, Mac, and Linux.

Connecting Arduino to Processing

Send serial data from Arduino to Processing and back - even at the same time!

Button and Switch Basics

A tutorial on electronics' most overlooked and underappreciated component: the switch! Here we explain the difference between momentary and maintained switches and what all those acronyms (NO, NC, SPDT, SPST, ...) stand for.

How Does an Analog Thumb Joystick Work?

Imagine a volume control or other knob. These controls are generally made from potentiometers, which are variable resistors. By connecting the potentiometer as a voltage divider, you can get a varying voltage out of the device, which can be fed to an analog to digital converter on a microprocessor. This allows the software to read the knob position.

Potentiometers

This joystick contains two potentiometers, connected with a gymbal mechanism that separates the "horizontal" and "vertical" movements. (If the joystick is flat on a table, these movements are more "front / back" and "left / right", but you get the idea.) The potentiometers are the two green/black boxes on the sides of the joystick. If you move the joystick while watching the center shaft of each potentiometer, you'll see that each of the potentiometers pick up movement in only one direction. Clever, isn't it!

Joystick Potentiometers Highlighted

Momentary Push Button

This joystick also contains a switch which activates when you push down on the cap. The switch is the small black box on the rear of the joystick. If you push down on the cap, you can see a lever pushing down on the head of the switch. The lever works no matter what position the joystick is in. Cool!

Joystick Mini Push Button Highlighted

Hardware Overview: Breakout

The breakout board has 5 pins broken out to easily connect to the thumb joystick. When mounting and programming with the joystick, make sure to keep track of the orientation of the board to determine what position the joystick is in.

Thumb Joystick Breakout Board Top View

  • VCC - Connect this to your positive supply (usually 5V or 3.3V depending on your logic levels).
  • VERT - This is the vertical output voltage (will be about half of VCC when the joystick is centered).
  • HORIZ - This is the horizontal output voltage (will be about half of VCC when the joystick is centered).
  • SEL - This is the output from the pushbutton, normally open, will connect to GND when the button is pushed.
  • GND - Connect this to your ground line (GND).

Hardware Assembly: Breakout

To easily connect to the joystick, you'll need a "breakout board" (the red printed-circuit board, or PCB). You'll need to solder the breakout board to the joystick. Never soldered before? It's easy, check out our tutorial on how to solder. If this is your first time soldering, practice a bit before working on this board. Read the guide and you'll pick up some good tips that will help your first soldering experience go more smoothly.

How to Solder: Through-Hole Soldering

September 19, 2013

This tutorial covers everything you need to know about through-hole soldering.

Once this is done, it will be much easier to connect the joystick to your project (you won't have to solder wires to all those little pins). To attach the breakout board to the joystick, follow these steps.

Insert Thumb Joystick to Breakout Board

First, test-fit the breakout board to the joystick. If any pins on the joystick are bent, gently straighten them. The joystick goes into the side of the board with the white outline (not the side with the SparkFun logo). Insert the joystick into the board, matching the white outline, and ensure that all the pins go into their holes (if they don't, you may not have the joystick oriented correctly).

Thumb Joystick Inserted Into Breakout Board

Solder

If everything fits OK, carefully solder the pins from the opposite side of the board (the side with the SparkFun logo). Before and during soldering, ensure that the joystick stays tight against the breakout board. There are 14 solder connections to make, including the four posts at the corners of the joystick.

Solder All Pins to the Breakout Board

If you'd like to connect a 5-pin header to the board, or solder bare wires to the output holes, you may do that now.

Solder Headers to Pins Broken Out

Once you're done soldering, you're ready to use your joystick! If you have not already, insert the cap on the joystick.

Soldered Thumb Joystick

Arduino Examples: Breakout

Hardware Hookup

The breakout board provides five labeled connections. You'll connect these lines to your project or microcontroller. In this example, we'll use the RedBoard with ATmega328P. For stability, make sure to have part of the breadboard under the joystick.

Thumb Joystick Circuit Arduino

Hookup Table

RedBoard w/ Atmega328P Thumb Joystick Breakout
5V VCC
A0 VER
A1 HOR
2 SEL
GND GND

Thumb Joystick Breakout Board Example

Note: This example assumes you are using the latest version of the Arduino IDE on your desktop. If this is your first time using Arduino, please review our tutorial on installing the Arduino IDE.

Here's an example Arduino sketch which sets up the microcontroller to read the inputs, and then continuously prints the values to the serial monitor. If you're using a different microcontroller, the steps should be similar; you'll just need to determine how to read analog and digital inputs on your device. Copy the code and paste it in the Arduino IDE. Select Arduino/Genuino Uno as the board, the COM port that it enumerated on, and hit the upload button.

language:c
// Thumb Joystick Breakout Board Example
// Modified by: Ho Yun "Bobby" Chan, SparkFun Electronics, 2/19
// Written by: Mike Grusin, SparkFun Electronics 3/11
// This code is free, baby. Use it however you like.

// This sketch shows the basic operation of the Thumb Joystick (COM-09032) and breakout board (BOB-09110).
// The joystick outputs two analog voltages (VERT and HORIZ), and one digital signal (SEL) for the pushbutton.

// Connections to joystick (change if you use different pins):

const int VERT = 0; // analog
const int HORIZ = 1; // analog
const int SEL = 2; // digital

// Also connect the joystick VCC to Arduino 5V, and joystick GND to Arduino GND.

// This sketch outputs serial data at 9600 baud (open Serial Monitor to view).

//initialize variables for analog and digital values
int vertical, horizontal, select;

void setup(){
  /* old method to turn on the pull-up resistor for the SEL line
     before Arduino IDE v1.01 (see http://arduino.cc/en/Tutorial/DigitalPins)
     make the SEL line an input*/
  //pinMode(SEL, INPUT);
  //digitalWrite(SEL, HIGH);

// make the SEL line an input
  pinMode(SEL, INPUT_PULLUP);

  // set up serial port for output
  Serial.begin(9600);
}

void loop(){

  // read all values from the joystick

  vertical = analogRead(VERT); // will be 0-1023
  horizontal = analogRead(HORIZ); // will be 0-1023
  select = digitalRead(SEL); // will be HIGH (1) if not pressed, and LOW (0) if pressed

  // print out the values

  Serial.print("vertical: ");
  Serial.print(vertical, DEC);
  Serial.print(" horizontal: ");
  Serial.print(horizontal, DEC);
  Serial.print(" select: ");
  if (select == HIGH) {
    Serial.println("not pressed");
  }
  else {
    Serial.println("PRESSED!");
  }
}

What You Should See

Open the serial monitor at 9600 baud to begin seeing the raw output values. With the vertical "↑ V" pointing away from you, start moving the joystick around.

Example Raw Output

In this case, the joystick was sitting around 520 for the vertical and horizontal values when not moving. Moving the joystick up toward the up arrow and in a clockwise motion, the joystick will read a value of about 1023 for the vertical component while the horizontal sits at the same value. Moving it to the right, the vertical component will sit at the resting value of about 520 again while the horizontal component will read a value of about 0. As the joystick moves down toward you, you'll notice the vertical component will drop to 0 and the horizontal will sit at it's resting value again. Moving the joystick to the left, you'll noitice the vertical component sit back to its resting value while the horizontal component jump up to 1023. Finally, you'l receive a the "PRESSED!" message when pressing down on the joystick.

Looking for more examples with the joystick? Check out the examples in the next section for the shield!

Hardware Overview: Shield

Below is a top view of the shield before any component is soldered.

Thumb Joystick Top View

  • Joystick - On the left of the board is the footprint for the thumb joystick. The potentiometers are connected to analog pins A0 and A1. The "select" button for the joystick is connect is connected to pin 2.

  • Prototyping Area - The center includes general plated through holes to prototype and solder additional components like a small OLED screen, XBee Explorer, or sensors. You'll need to wire it up to the respective pins depending on your project.

  • 12mm Buttons - On the right are locations for four 12mm momentary pushbuttons. Up is connected to pin 4, right to pin 3, down to pin 5, and left to pin 6.

  • Edge Pins - The board was designed for the original Arduino Uno footprint so you'll see the standard headers on the edge of the board.

  • Reset Button - Just beside the reset pin is the location for the mini push button to reset an Arduino when stacked on top.

Hardware Assembly: Shield

Before assembling the shield, make sure that you have all the components needed to solder the board together.

Joystick Shield Components

If you ordered a kit, you should have the following components included.

All parts present and accounted for? Great, let's start to put the shield together.

Insert Thumb Joystick and Buttons to Shield

Before I start to solder parts into place, I like to do a "test fit" of the kit components. This allows me to check that everything fits as expected plus it's fun. Just work through the rest of these instructions carefully putting the components into place but don't solder anything. This is entirely optional.

Once you've done a test fit, you can pull the components out with care and then put the shield together for real!

Soldering Tips

If this is your first time soldering you'll probably want to check out our introductory soldering tutorial first. Read the guide and you'll pick up some good tips that will help your first soldering experience go more smoothly.

How to Solder: Through-Hole Soldering

September 19, 2013

This tutorial covers everything you need to know about through-hole soldering.

Below you'll find a suggested order for assembling the shield, your personal preference might give you other ideas on how to proceed and that's fine too. When no order for assembling is provided, soldering the smallest components in first is a good rule to follow. Just make sure all the pieces go in the right place and in the correct orientation.

If you don't have a PCB vise then you might want to put the header pins in before the thumb joystick — that way you can rest the PCB on the headers as you solder the pins. (In fact, you might want to do this even if you do have a vise.)

Another approach to consider is to attach the headers first so you can test each component is working after you add it.

Alright, let's start with...

Mini Push Button Switch

The mini push button resets the main Arduino board — it's present because once the shield is connected to the Arduino, it's difficult to access the normal reset button.

Ensure you're looking at the top of the PCB — the top is where the components sit — it will have the "sparkfun.com" text and logo on it.

Begin by pushing the four legs (or leads) of the button into the correct location on the PCB as shown in the photograph below. It sits just below the word "Reset" on the PCB. The button can be orientated in four different directions with the legs pointing down but only two of them are correct — you shouldn't need to apply much force to seat the push button in the holes. See the next closeup image for a better view of how the button should sit.

Arduino Joystick Shield Mini Button

You can see more clearly below that the legs splay out slightly. There's two pairs of legs on opposite sides of the body — one pair should sit in the set of holes close to the edge of the PCB while the other pair should sit on the opposite short-edge side of the white rectangle marked ("silk screened") on the PCB.

If you bend one of the legs too much gently move it back into place — but don't do this too often or the metal will break from metal fatigue.

With enough room below the PCB for the legs to extend apply pressure to the top of the push button so the plastic bottom sits on the PCB — this allows the PCB to take most of the force when you press the button rather than the thin metal legs.

Mini Button Closeup

Next turn the board over and you should see those cute little legs pointing through the holes in the PCB. If they don't extend as far as shown in this picture check you have the orientation correct and then apply a little more pressure to pop the legs through. The button shouldn't fall out of the holes when you turn the PCB upside down.

Mini Button Closeup Terminals

Now it's time to solder the first leg — it doesn't matter which of the four you start with — but ensure the plastic bottom of the button is still flat against the PCB. Apply heat with the soldering iron simultaneously to the leg of the button and the pad (the circle of track around the hole) on the PCB then carefully feed a little piece of the solder into the joint formed between the soldering iron, pad, and component leg. Then remove the solder wire and then the soldering iron — in that order.

Once you have completed one leg, again check the bottom of the button is touching the PCB and then solder the diagonally opposite leg as well. Soldering the legs in this order ensures the button sits well and you can solder the two remaining legs without needing to double-check if the button is still sitting correctly.

When you have soldered all four legs of the button it should look something like the photo below:

Mini Button Soldered Terminals

If you like, you can flip the board back over and give the mini push button a triumphant press and show it to your friends.

Push Buttons

It is now time to attach the four larger push buttons to the shield. These are the "action" buttons of your joystick shield and you can use them to control the actions of a character on screen, perhaps causing the character to shoot, punch or arrange flowers as the mood strikes. ("Flower Arranger II : This time it's Perennial!")

You'll notice the method we use is very similar to the approach we took with the mini push button — this is because the buttons are almost identical in construction apart from their size.

First, insert the legs of the four buttons into the holes on the PCB — their orientation should mean the edges without legs cover the white silk screen lines above and below the white silk screen circles. For each button ensure all four legs are inside their respective holes before applying pressure to the top of the button to push the legs through to the other side — if you're not careful you can bend one or more of the legs under the button by accident. If you do bend one of the legs under, remove the button and use a small screwdriver or pair of pliers to straighten the bent leg enough that it will again sit in the correct place to fit through the hole.

I suggest putting all four buttons into place before soldering them because the legs will prevent them from falling out when you flip the board over and it's nice to be able to get into the flow of things and solder all the joints at one time. But if you prefer to solder each button in place before adding the next that should work okay too.

12mm Push Buttons

You can now flip the board over and see the push button legs all poking through in a manner resembling the view of the pool during a synchronized swimming competition.

12mm Push Buttons Bottom View

Once again it's time to solder the first of the button legs. My suggestion is to start with the button closest to the middle of the board and work left to right and down from there so you don't have to move the soldering iron over already soldered joints. Again the order isn't critical though.

As before, it doesn't matter which of the four legs of the button you start to solder — but remember to ensure the plastic bottom of the button is still flat against the PCB. You may have to hold the buttons from underneath against the PCB as the legs might be a little loose, be sure to touch only the plastic part as the metal part will heat up. Apply the heat with the soldering iron simultaneously to the leg of the button and the pad then carefully feed a little piece of the solder roll into the joint formed between the soldering iron, pad, and component leg. Then remove the solder wire and then the soldering iron — in that order.

Once you have completed one leg, again check if the bottom of the button is touching the PCB and then solder the diagonally opposite leg as well. Soldering the legs in this order ensures the button sits well and you can solder the two remaining legs without needing to double-check if the button is still sitting correctly.

After you've finished all sixteen legs the board should look like this — I hope those swimmers weren't planning on leaving the pool today:

Soldered

Thumb Joystick

As you may recall from the introduction to this soldering section I suggest you learn from my experience (especially if you don't have a PCB vise) and solder the headers before you solder the thumb joystick. If that's the case, feel free to skip ahead to the headers section and then return to this joystick section.

Ha, I can't believe they fell for that "solder the headers first" trick, can you? Well, joke's on you because it really is easier to solder the headers before the joystick but if you insist, here's how to get the joystick connected. Just remember if you have the headers connected then your board will look a little different to these photos.

You first need to insert the legs of the joystick into the board similar to the breakout board. There's quite a number of legs of different sizes so it pays to be careful pushing the joystick into place.

You'll notice there's a number of sets of legs:

  • Four legs for the small mini push button used for the center button functionality. This sits on an outcrop that juts out from one side of the white plastic base and will look suspiciously similar to our reset mini push button. These are quite thin legs.
  • Four legs which are thicker than the others and are located at the four corners of the main part of the white plastic base. These legs are structural only and aren't intended to connect to any electrical signals.
  • Two sets of three legs each connected to the green/black bodies of the potentiometers used to detect the joystick position in two dimensions.

You might find it easier to remove the black plastic top or "hat" from the joystick first like I have in these photos — just give the hat a gentle tug and it should slide off the center stick. Put the hat to one side so you don't lose it or see if you can wear it as a hat yourself in which case you probably will lose it.

The mini push button legs are the most difficult to get in the correct place so I suggest you line those ones up with the appropriate holes first. Note the whole joystick will only fit in one orientation which has the mini push button facing the center on the PCB. It might help to tilt the base of the joystick slightly so that the two structural legs closest the mini push button fit into their associated holes around the same time as the button legs are in the right place. Then tilt the base level so the remaining legs fit into their proper holes. It's like putting on trousers, there's few things more annoying than getting your leg in the wrong hole — so take your time to make sure everything's where it should be.

If you do bend a leg, first try to see if you can push it gently into position with the head of a small screwdriver, otherwise take the joystick out, straighten the leg and try again — but once again if you do this too often the leg might snap off from metal fatigue.

Thumb Joystick Inserted into Shield

Once you've applied enough pressure to the top of the joystick case all the legs should poke through the bottom of the PCB — the structural legs will protrude further than the others:

Thumb Joystick Inserted Close Up Terminals

You have a couple of options for the order in which you solder the legs but my suggestion is to start with the structural legs:

  • Ensure the base is sitting as close to the PCB as possible — it won't sit entirely flush as there are plastic bumps on the base that prevent this.
  • Then solder the four structural legs starting with any leg. You can use more solder than you might normally use to provide extra support.
  • Check the base is still somewhat flush.
  • Solder the diagonally opposite structural leg into place.
  • Then solder the two remaining structural legs in any order.
  • After the structural legs are in place, I'd suggest soldering the two sets of three potentiometer legs.

Finally, ensure the mini push button legs are through the PCB as far possible and solder the button in place in the same way you've done before.

When you're finished your board should look somewhat like this:

Soldered Terminals

If you've already attached the headers you can now flip the board over and reattach the plastic hat to the white center post of the joystick — take note that it will only fit in two orientations as the center post is rectangular. You can now skip to the Completed Solder Joints section.

If you still need to attach the headers you can move on to the next section.

Feel free to pretend you're using the joystick to dock the Apollo before you move on. ("Psssh" thruster noises aren't optional if you do though.)

Prepping Shield for Headers

Headers

Now it's time to solder the headers. You'll notice in these images and the parts list we use the stackable headers which allow an additional shield to be stacked on top of this one. The alert among you will notice however that a standard shield won't fit on top of this shield due to the position of the joystick and even if it did it would obscure at least one of the push buttons.

So what's the advantage of using the stackable headers in this case? It means you can still insert jumpers into the headers to gain access to the unused pins. If you wanted you could also add a custom mini shield on top if you'd like — perhaps with a couple of extra buttons?

If you don't think you'll need this extra functionality you can use standard breakaway headers instead. If you only populate the used pins with headers you can probably still insert jumpers into the other through the holes in the PCB if you need.

Six Pin Headers

Let's start by soldering the two six pin headers that will supply power and access to the analog pins. First, you can insert one of the headers into the correct location like this:

6 Pin Header Close Up

If you don't have a PCB vise then you will probably want to temporarily put one of the 8 pin headers into its location so that the PCB is level when you solder the headers. The headers won't stay in place when you flip the board over so hold them in place when you turn the PCB over to leave the pins sticking upwards.

If you have a PCB vise you might want to hold the header in place like the following photo:

6 Pin Header Close Up Side View

Next solder one of the pins into place. Ensure the header is aligned as parallel as possible to the edge of the board when you do this:

6 Pin Header 1 Pin Soldered

The reason we start with just one pin is because it makes it easier to obtain the correct alignment and fix any mistakes. Once you've soldered one pin, you might want to test the alignment by inserting the shield into an Arduino. Just be careful when you do so because the header's still only held in place with one solder joint.

If the alignment of the header isn't quite right, carefully reheat the solder joint and move the header slightly. Don't move it after you've removed the heat however, or you'll end up with a poor joint. Here is an example of checking the header alignment:

Testing Header Alignment on Arduino

Once you're happy with the alignment of the header, you can solder another pin into place — my recommendation is to solder the pin at the opposite end of the header to the first pin you soldered. The reason for this is that once the two end pins are in place, the alignment won't change. I recommend double checking the alignment is still okay again by connecting it to your Arduino again.

Once again, if the alignment's not quite right you can reheat the joint and carefully move the pin.

6 Pin Header Soldered to Two Pins

After you've confirmed the alignment you can solder the remaining four pins into place:

6 Pin Header Fully Soldered

At this stage you can repeat these instructions for the second 6 pin header or skip ahead to solder the diagonally opposite 8 pin header. Soldering a 8 pin header now helps to get the alignment right.

Eight Pin Headers

All right class, who can tell me how we're going to solder the 8 pin header..? Yes, you're correct, exactly the same as the 6 pin header except for the last step where we have an extra two pins to solder into place. As before, first we solder a pin at one end and check the alignment:

8 Pin Header Tacked Down

Then we solder the pin at the opposite end of the header and re-check the alignment:

8 Pin Header 2 PinsTacked Down

And finally we solder the remainder of the pins in the middle of the header.

8 Pin Header Soldered

Repeat this for the second 8 pin header and you're done!

Don't forget to go back and solder the last 6 pin header if you skipped ahead. And if you still need to solder the joystick into place you can go back to that section.

Completed Solder Joints

Once you've finished soldering all the components into place your board will look something like this:

All Pins Soldered

Doesn't that red PCB look just spiffy?

Now's the time to double check all your soldering and fix up any problems:

  • Do the joints all look shiny and volcano shaped?
  • Do you have any "shorts" or "bridges" between joints where you've accidentally connected the two joints with solder? Check out the soldering guide for advice to avoid these problems.

Don't be too fussy though because re-heating and moving the joints is to be avoided if possible.

Completed Shield

Once you've completed your shield it should look like this.

Completed Shield

When you are ready, stack the shield on top of the Arduino!

Completed Shield Stacked on Arduino

Now it's time to make your joystick shield control something!

Arduino Examples: Shield

Hardware Hookup

For the scope of this tutorial, we will focus on the first two examples to read the joystick and buttons using the shield.

Fritzing Diagram of Joystick Shield Stacked on Arduino

If you have the joystick breakout, you can still follow along as long as everything is wired like the shield and you use the pin definitions in the code for reference. Also, you can check out the additional examples if you have additional hardware like a piezo buzzer or serial enabled LCD.

Arduino Example Code

The joystick shield provides simple analog inputs along with four separate buttons and one button under the joystick itself. The joystick can be used for controlling outputs such as a melody or pixels on a screen. The buttons can be used for navigation or game control. If you want to jump directly into the example sketches, download and unzip the examples from the GitHub repo to dive in.

  • JoystickArduinoBasicExample.ino - Printing joystick values and button presses to the console.
  • JoystickArduinoIntermediateExample.ino - This code does the same thing as the basic code but includes more positions on the joystick.
  • JoystickArduinoMelodyControl.ino - Controlling a melody and tempo with the joystick and a piezo buzzer.
  • SparkFunJoystickShieldSampleSketch.ino - Example from the demo video to use with the a serial enabled LCD.

Let's check out two out of the three examples from the GitHub repo.

Basic Example

After downloading the examples, open the JoystickArduinoBasicExample.ino sketch, select Arduino/Genuino Uno as the board and the COM port that the board enumerated on, and hit the upload button. Open the serial monitor at 9600 baud and test out the joystick shield to observe the joystick and button behaviors.

Thumb Joystick Shield Raw Output

If you've been following along with the tutorial, the output looks similar to the output from the breakout board example.There are two differences between the breakout and shield. One apparent difference is the output. There are more values for each line due to additional four buttons. If no button is pressed, they will read as a 1. If a button is pressed, they will read as 0.

The second difference is more subtle. The orientation of the joystick is rotated 90°. The "vertical" position is referenced with as the "x-axis" while the "horizontal" is referenced as the "y-axis". The output indicates that the joystick is not moving when the values are around 520. Moving the joystick up toward the "AREF" pin, the joystick will read the same value for the x-axis while y-axis component will jump to 1023. Moving it clockwise to the right, the x-axis will read a value of about 0 while the y-axis component will sit at the resting value of about 520 again. As the joystick moves down toward you, you'll notice the x-axis will sit at it's resting value again while the y-axis component will drop to 0. Moving the joystick to the left, you'll notice the x-axis component jump up to 1023 while the y-axis component sit back to its resting value. Finally, the select button will read as 0 when pressing down on the joystick.

Intermediate Example

Open the JoystickArduinoIntermediateExample.ino sketch, select Arduino/Genuino Uno as the board and the COM port that the board enumerated on, and hit the upload button. Open the serial monitor at 9600 baud and test out the joystick shield to observe the joystick and button behaviors.

Thumb Joystick Shield Raw

Again, you'll notice that the raw output is the same as the basic example. However, there is an additional line indicating the position of the joystick. The code is a little bit more complicated with the nested if statements to check the joystick's position. The code breaks the position up into 9 positions:

  • center
  • up
  • right-up
  • right
  • right-down
  • down
  • left-down
  • left
  • left-up

Code To Note

Once you've got the shield assembled, you can begin to change the example code to make the joystick do your bidding. Here are a few in-depth explanations about the code.

How Do I Find the Current Position of the Joystick?

The position of the joystick is calculated from the two potentiometers in the joystick. The joystick can move in two dimensions which typically would represent X and Y coordinates but could represent any two dimensional quantity. To read the potentiometers we use the analogRead() function which returns a number from 0 to 1023. We need to supply an analog pin number to the function — for the joystick shield the X position is read from analog pin 0 and the Y position is read from analog pin 1:

language:c
Serial.println(analogRead(0)); // Prints current X position
Serial.println(analogRead(1)); // Prints current Y position

It is a good technique — because it clarifies your intent — to use ''constants'' for values that will not change when your sketch runs. With this in mind, the following sketch snippet sets up constants for the analog pins used and prints the current X and Y positions to the serial console:

language:c
const int PIN_ANALOG_X = 0;
const int PIN_ANALOG_Y = 1;

void setup() {
  Serial.begin(9600);
}

void loop() {

  Serial.print("x:");
  Serial.print(analogRead(PIN_ANALOG_X));
  Serial.print(" ");

  Serial.print("y:");
  Serial.print(analogRead(PIN_ANALOG_Y));
  Serial.print(" ");

  Serial.println();
}

How Do I Find the Current Direction of the Joystick?

It can be useful to use the value of the X and Y position to determine if the joystick is centered or moved in one of 8 directions (i.e. up, right-up, right, right-down, down, left-down, left, left-up).

Since we know the value in each dimension will be between 0 and 1023 you might expect the centre value to be around 511 or 512 but because the joysticks are physical devices the actual value is unlikely to be that exact. If we choose the wrong value we'll find that our joystick will be detected as moving in a particular direction even though it is centered.

To work around this issue we specify two "threshold" values and consider that any value within that range should be considered "centered":

language:bash
|----------|----|----------|
0         505  515        1023

The threshold values you choose may be different depending on your joystick. We specify the values as constants in the code:

language:c
const int X_THRESHOLD_LOW = 505;
const int X_THRESHOLD_HIGH = 515;    

const int Y_THRESHOLD_LOW = 500;
const int Y_THRESHOLD_HIGH = 510;

Next, we want to map our value in each dimension from a position range of 0 to 1023 to a direction value in the range -1 to 1. For the X, dimension -1 means moved to the left, 0 means not moved in the X dimension and 1 means moved to the right. For the Y dimension -1 means moved down, 0 means not moved in the Y dimension and 1 means moved up.

We start by setting the direction in each dimension to 0 ("centered") and then we use if/else statements to check if the position value in either dimension is above or below our threshold values:

language:c
x_direction = 0;
y_direction = 0;

x_position = analogRead(PIN_ANALOG_X);
y_position = analogRead(PIN_ANALOG_Y);

if (x_position > X_THRESHOLD_HIGH) {
  x_direction = 1;
} else if (x_position < X_THRESHOLD_LOW) {
  x_direction = -1;
}

if (y_position > Y_THRESHOLD_HIGH) {
  y_direction = 1;
} else if (y_position < Y_THRESHOLD_LOW) {
  y_direction = -1;
}

The Arduino provides a map() function which in theory we could use instead of if/else but the method is complicated by the centering issues so we won't consider that approach here.

As you can see in the next complete example we then use if/else statements to print the direction — you can modify this example to perform whatever action you need:

language:c
const byte PIN_ANALOG_X = 0;
const byte PIN_ANALOG_Y = 1;

const int X_THRESHOLD_LOW = 505;
const int X_THRESHOLD_HIGH = 515;

const int Y_THRESHOLD_LOW = 500;
const int Y_THRESHOLD_HIGH = 510;

int x_position;
int y_position;

int x_direction;
int y_direction;

void setup() {
  Serial.begin(9600);
}

void loop () {
  x_direction = 0;
  y_direction = 0;

  x_position = analogRead(PIN_ANALOG_X);
  y_position = analogRead(PIN_ANALOG_Y);

  if (x_position > X_THRESHOLD_HIGH) {
    x_direction = 1;
  } else if (x_position < X_THRESHOLD_LOW) {
    x_direction = -1;
  }

  if (y_position > Y_THRESHOLD_HIGH) {
    y_direction = 1;
  } else if (y_position < Y_THRESHOLD_LOW) {
    y_direction = -1;
  }


  if (x_direction == -1) {
    if (y_direction == -1) {
      Serial.println("left-down");
    } else if (y_direction == 0) {
      Serial.println("left");
    } else {
      // y_direction == 1
      Serial.println("left-up");
    }
  } else if (x_direction == 0) {
    if (y_direction == -1) {
      Serial.println("down");
    } else if (y_direction == 0) {
      Serial.println("centered");
    } else {
      // y_direction == 1
      Serial.println("up");
    }
  } else {
    // x_direction == 1
    if (y_direction == -1) {
      Serial.println("right-down");
    } else if (y_direction == 0) {
      Serial.println("right");
    } else {
      // y_direction == 1
      Serial.println("right-up");
    }
  }
}

How Do I Set Up the Arduino So I Can Know When a Button has Been Pushed on the Joystick Shield?

Before you can know if a button on the shield has been pushed, you need to set up your Arduino to recognize the buttons. Unsurprisingly, you will perform this setup in the... setup() function!

First, we define constants for the Arduino pin associated with each button:

language:c
// Select button is triggered when joystick is pressed
const byte PIN_BUTTON_SELECT = 2;

const byte PIN_BUTTON_RIGHT = 3;
const byte PIN_BUTTON_UP = 4;
const byte PIN_BUTTON_DOWN = 5;
const byte PIN_BUTTON_LEFT = 6;

If you've used a pushbutton switch before you may have noticed a resistor is normally required in order to detect a known voltage when the button is not pressed. To reduce the number of parts required this shield has been designed not to require resistors on the shield itself. Are you thinking to yourself "if push buttons require resistors and the shield has no resistors how can we get the shield to work?"? If you're not thinking that then you can probably skip reading this bit. (And if you're thinking "I'm really hungry" it might be time to put down the electronics and get some food.)

It turns out your Arduino actually has internal resistors connected to the pins inside the microcontroller. In order to use the internal resistors we need to "enable the internal pull-up resistors". If that sounds to you like "hoist the jib and unfurl the main stay" then I can explain some more:

When a "pull-up" resistor is connected to a push button it means that the voltage level when the button is not pressed will be HIGH because the resistors "pulls the voltage level up" to HIGH when the button is not pressed. On a typical Arduino a pin that is HIGH will be at 5 volts. When the push button is pressed the pin will read as LOW because there is less resistance between the pin and ground than there is between the pin and 5 volts.

To enable a pin's pull-up resistor you first set the pin as an input and then enable the pull-up:

language:c
pinMode(PIN_BUTTON_RIGHT, INPUT_PULLUP);

The actual code to enable the pull-up doesn't really make any sense if you read it literally but that's the way it works.

Other than remembering that an unpressed button will read as HIGH with a pull-up resistor and a pressed button will read as LOW you don't need to remember or understand the other details.

In order to configure each pin to be an input and enable the pull-up resistors we use the following code:

language:c
void setup() {
//.
//.
//.
  pinMode(PIN_BUTTON_RIGHT, INPUT_PULLUP);
  pinMode(PIN_BUTTON_LEFT, INPUT_PULLUP);
  pinMode(PIN_BUTTON_UP, INPUT_PULLUP);
  pinMode(PIN_BUTTON_DOWN, INPUT_PULLUP);
  pinMode(PIN_BUTTON_SELECT, INPUT_PULLUP);
}

See the next section to learn how to read whether a button is pressed or not.

How Do I Know When a Button On the Joystick Shield has Been Pressed?

Once you have set up your Arduino to recognize the buttons (see above) you can tell whether the button is pressed with the digitalRead() function. When the value read is LOW the button is pressed and when the value is HIGH the button is not pressed.

language:c
if (digitalRead(PIN_BUTTON_LEFT) == LOW) {
    // Button is pressed
} else {
   // Button is not pressed
}

The following complete example will print the state of each button and the value of the joystick to the Arduino serial console:

language:c
// Store the Arduino pin associated with each input

// Select button is triggered when joystick is pressed
const byte PIN_BUTTON_SELECT = 2; 

const byte PIN_BUTTON_RIGHT = 3;
const byte PIN_BUTTON_UP = 4;
const byte PIN_BUTTON_DOWN = 5;
const byte PIN_BUTTON_LEFT = 6;

const byte PIN_ANALOG_X = 0;
const byte PIN_ANALOG_Y = 1;

void setup() {
  Serial.begin(9600);

  pinMode(PIN_BUTTON_RIGHT, INPUT);  
  digitalWrite(PIN_BUTTON_RIGHT, HIGH);

  pinMode(PIN_BUTTON_LEFT, INPUT);  
  digitalWrite(PIN_BUTTON_LEFT, HIGH);

  pinMode(PIN_BUTTON_UP, INPUT);  
  digitalWrite(PIN_BUTTON_UP, HIGH);

  pinMode(PIN_BUTTON_DOWN, INPUT);  
  digitalWrite(PIN_BUTTON_DOWN, HIGH);

  pinMode(PIN_BUTTON_SELECT, INPUT);  
  digitalWrite(PIN_BUTTON_SELECT, HIGH);  
}

void loop() {
  Serial.print("l:");
  Serial.print(digitalRead(PIN_BUTTON_LEFT));
  Serial.print(" ");

  Serial.print("r:");
  Serial.print(digitalRead(PIN_BUTTON_RIGHT));
  Serial.print(" ");

  Serial.print("u:");
  Serial.print(digitalRead(PIN_BUTTON_UP));
  Serial.print(" ");

  Serial.print("d:");
  Serial.print(digitalRead(PIN_BUTTON_DOWN));
  Serial.print(" ");

  Serial.print("x:");
  Serial.print(analogRead(PIN_ANALOG_X));
  Serial.print(" ");

  Serial.print("y:");
  Serial.print(analogRead(PIN_ANALOG_Y));
  Serial.print(" ");  

  Serial.print("s:");
  Serial.print(digitalRead(PIN_BUTTON_SELECT));
  Serial.print(" ");

  Serial.println();
}

Processing Library

Note: Processing is a software that enables visual representation of data, among other things. If you've never dealt with Processing before, we recommend you also check out the Arduino to Processing tutorial. Follow the button below to go ahead and download and install Processing IDE v2.2.1. The following examples were intended for Processing IDE v2 so you may have issues getting it running on Processing IDE v3.

Download Processing IDE 2.2.1

To install the Processing Library, you'll need to head over to the Processing-Arduino interface page.

There is a link to receive latest release after it says "Library for Processing v2.0 and v3.0" from its GitHub repository.

Library for Processing v2.0 and v3.0: latest release (Updated 7 Nov. 2016)

Click on the link to download the processing-arduino.zip and unzip to location on your computer. The process to install this library is similar to installing an Arduino library manually. Open a new window and locate the processing libraries folder. It should look similar to "...\Documents\Processing\libraries". Click on the unzipped folder labeled as processing-arduino. Then move the "arduino" folder into the Processing libraries folder.

Standard Firmata

We'll also need to upload the StandardFirmata.ino example code before using the Arduino and Thumb Joystick Shield with Processing. Luckily, this is already in the Arduino IDE. Open the Arduino IDE and head to File > Examples > Firmata > StandardFirmata.ino sketch, and upload it to the Arduino board. Remember to select Arduino/Genuino Uno as the board and COM port on your computer before uploading.

Processing Examples: Shield

If you have not already, download and unzip the examples from the GitHub repo to dive into the Processing examples with the joystick shield.

  • JoystickProcessingBasicExample.pde- Basic processing integration with an Arduino and inputs.
  • JoystickProcessingArtist.pde - Painting on a window.

If you have the joystick breakout, you can still follow along as long as everything is wired like the shield and you use the pins definitions in the code for reference. If not, you will have limited functionality.

Basic Example

We'll assume that your Arduino has the StandardFirmata.ino sketch loaded into the ATmega328P. After downloading the examples, open the JoystickProcessingBasicExample.pde sketch in Processing IDE v2.2.1. You may need to open the file up from the File > Open menu so that the Arduino IDE accidentally open the file. With your joystick shield stacked and the Arduino connected to your computer, hit the run button to execute the processing sketch.

Click on the Run Button for Processing

If you did not adjust the array for the COM port, you'll probably receive an error indicating that the code is unable to run.

Processing Error Due to COM Port Selection

Remember that note earlier when installing the library? Well, you need to adjust the COM port correctly in order to connect to your Arduino. If you remember the COM port when uploading in the Arduino IDE, it should be listed in the console at the bottom of the Processing IDE. In this case, the COM ports listed were:

language:bash
COM4 COM5 COM6 COM7 COM8 COM9 COM10 COM11 COM12

Counting each COM port from 0 (in terms of programming not in mathematical terms) from left to right. In this case, the Arduino enumerated as COM8 when uploading so it should be in the 4th element in the array.

Head back to the code in Processing and adjust the 0 in the array where it says:

language:c
// We assume that the Arduino is the first device in the list,
// if it's not the first device you need to change the '0'.
arduino = new Arduino(this, Arduino.list()[0], 57600);

To the element in the array. In this case, it should be a 4.

// We assume that the Arduino is the first device in the list,
// if it's not the first device you need to change the '0'.
arduino = new Arduino(this, Arduino.list()[4], 57600);

Now that you are ready, hit the run button again. After the Arduino initializes, a blank display window appear. In the code, we did not really draw anything so it should be blank. You'll also notice at the bottom that the output is similar to the output displayed in the Arduino IDE's serial monitor. Moving the joystick and buttons will adjust the values just as we expect.

Basic Example Running on Processing

Artist Example

Again, we'll assume that your Arduino has the StandardFirmata.ino sketch loaded into the ATmega328P. After downloading the examples, open the JoystickProcessingArtistExample.pde sketch in Processing IDE v2.2.1. You may need to open the file up from the File > Open menu so that the Arduino IDE accidentally open the file. Adjust the COM port in the array from 0 to the COM port that the Arduino enumerate on. With your joystick shield stacked and the Arduino connected to your computer, hit the run button to execute the processing sketch.

A display window will pop up and start drawing from the center of the window. Hitting the up button and down buttons will adjust the hue. Hitting the left and right buttons will adjust the brightness. Move the joystick around to begin painting. For thick, bold lines, press down on the joystick. When you are done unleashing your inner artist, click on the left and right buttons simultaneously to save. A *.png file will take screen shot of you artwork and save it in the same folder as the processing sketch!

Example of the Artist Processing Sketch

You might have noticed that the paint brush had a mind of it's own like the image shown above. This is due to the default threshold values set in the code for the "POSITION_METHOD" being 0. Depending on manufacturing tolerances, these values can vary. As explained earlier in the breakout and shield examples, you'll need to observe the readings when the joystick is in the center. Using those values, you'll need to tweak the values in the code before running the code again to prevent the paint brush from drifting. Try exploring methods by adjusting POSITION_METHOD at the top of the code to 1, 2, or 3.

language:c
// There are a number of methods you can choose to use to determine the relationship
// between the position of the joystick and the position of the drawing point on
// the screen. Change POSITION_METHOD to be equal to 0, 1, 2 or 3 to try out the
// different variations.
// See the comments in the code below to find out how each method works.
final int POSITION_METHOD = 0;

Resources and Going Further

Now that you've successfully got your joystick up and running, it's time to incorporate it into your own project!

For more information, check out the resources below:

If you are looking for example code using javascript with the Johnny-Five, check out the examples linked with the Joystick Class.

Need some inspiration for your next project? Check out some of these related tutorials:

BadgerHack: Gaming Add-On Kit

Make a Breakout clone with the BadgerHack Gaming Add-On Kit.

Wireless Joystick Hookup Guide

A hookup guide for the SparkFun Wireless Joystick Kit.

Serial Controlled Motor Driver Hookup Guide

Hookup guide for the Serial Controlled Motor Driver

Qwiic Joystick Hookup Guide

Looking for an easy way to implement a joystick to your next Arduino or Raspberry Pi project? This hookup guide will walk you through using the Qwiic Joystick with the Arduino IDE on a RedBoard Qwiic and in Python on a Raspberry Pi.

If you have no idea what to do with a joystick, checkout the following videos: