Qwiic Joystick Hookup Guide

Pages
Contributors: santaimpersonator
Favorited Favorite 5

Introduction

Now, you can easily add an HID/controller to your project! The SparkFun Qwiic Joystick combines the convenience of the Qwiic connection system and an analog joystick that feels reminiscent of the thumbstick from a PlayStation 2 controller.

SparkFun Qwiic Joystick

SparkFun Qwiic Joystick

COM-15168
$11.50
3

Thanks to an ATtiny85 on the Qwiic Joystick, all the necessary bits are taken care of and your microcontroller only needs to look for your inputs in the registers of the I2C device.

Required Materials

The Qwiic Joystick does need a few additional items for you to get started. The RedBoard Qwiic is for the Arduino examples and the Qwiic Hat is for the Raspberry Pi example (see note below). You may already have a few of these items, so feel free to modify your cart based on your needs.

SparkFun Qwiic Cable Kit

SparkFun Qwiic Cable Kit

KIT-15081
$8.95
22
SparkFun RedBoard Qwiic

SparkFun RedBoard Qwiic

DEV-15123
$21.50
20
SparkFun Qwiic HAT for Raspberry Pi

SparkFun Qwiic HAT for Raspberry Pi

DEV-14459
$6.50
5
Raspberry Pi Example: If you don't already have them, you will need a Raspberry Pi and standard peripherals. An example setup is listed below.
Raspberry Pi 3 B+

Raspberry Pi 3 B+

DEV-14643
$35.00
40
Multimedia Wireless Keyboard

Multimedia Wireless Keyboard

WIG-14271
$29.95 $19.95
5
pi-topCEED (Green)

pi-topCEED (Green)

KIT-14035
$114.95 $99.95
4

Raspberry Pi™ - 16GB MicroSD NOOBS Card

COM-13945
3 Retired

Suggested Reading

If you're unfamiliar with jumper pads, I2C, or Python be sure to checkout some of these foundational tutorials.

Logic Levels

Learn the difference between 3.3V and 5V devices and logic levels.

I2C

An introduction to I2C, one of the main embedded communications protocols in use today.

How to Work with Jumper Pads and PCB Traces

Handling PCB jumper pads and traces is an essential skill. Learn how to cut a PCB trace, add a solder jumper between pads to reroute connections, and repair a trace with the green wire method if a trace is damaged.

RedBoard Qwiic Hookup Guide

This tutorial covers the basic functionality of the RedBoard Qwiic. This tutorial also covers how to get started blinking an LED and using the Qwiic system.

Raspberry Pi SPI and I2C Tutorial

Learn how to use serial I2C and SPI buses on your Raspberry Pi using the wiringPi I/O library for C/C++ and spidev/smbus for Python.

Qwiic HAT for Raspberry Pi Hookup Guide

Get started interfacing your Qwiic enabled boards with your Raspberry Pi. This Qwiic connects the I2C bus (GND, 3.3V, SDA, and SCL) on your Raspberry Pi to an array of Qwiic connectors.

Python Programming Tutorial: Getting Started with the Raspberry Pi

This guide will show you how to write programs on your Raspberry Pi using Python to control hardware.

Qwiic Connect System

The Qwiic Joystick utilizes the Qwiic connect system. We recommend familiarizing yourself with the Logic Levels and I2C tutorials (above) before using it. Click on the banner above to learn more about our Qwiic products.

Hardware Overview

The Qwiic Joystick will report the thumbstick position over I2C and is designed to be compatible with the Qwiic system so you can add it to your project solder-free!

Power LED

There is a power status LED to help make sure that your Qwiic Joystick is getting power. You can power the board either through the polarized Qwiic connector system or the breakout pins (PWR and GND) provided. The Qwiic system is meant to run on 3.3V, be sure that you are NOT using another voltage when using the Qwiic system.

Power LED on board

Joystick

The joystick is similar to the analog joysticks on PS2 (PlayStation 2) controllers. Directional movements are simply measured with two 10 kΩ potentiometers, one for each axis. This joystick also has a select button that is actuated when the joystick is pressed down.

Thumb Joystick

Thumb Joystick

COM-09032
$4.50
5

The two potentiometers are connected to the analog to digital converter (ADC) of the ATtiny85. The select button operates as a digital input on the ATtiny85. This allows the firmware to read the knob position and any button presses.

Troubleshooting Tip: Due to resistor manufacturing tolerances, the joystick may not read exactly half of VCC when at rest. You may want to make a note of the "zero" reading, and store that value into your program if necessary.

Joystick Orientation

The joystick contains two potentiometers, connected with a gimbal mechanism that separates the horizontal and vertical movements (orientation shown below).

Notated image with joystick axis orientation

The potentiometers are the two blue or 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 will pick up movement on only one axis. Clever, isn't it?

Potentiometers highlighted

Select Button

The joystick also contains a momentary button which activates when you push down on the cap. The button is the small black box on the side of the joystick. If you push down on the cap, you can see a lever pushing down on the head of the button. The lever works no matter what position the joystick is in. That is pretty cool!

button highlighted

ATtiny85

With the pre-installed firmware, the ATtiny85 is acts as an intermediary (microcontroller) for the analog and digital inputs from the joystick. This allows the Qwiic Joystick to report its position over I2C.

ATtiny85 on board

Note: To flash your own firmware, at minimum, you will need an programmer for the ATtiny and a pogo pin adapter. Writing and uploading firmware is not easily done, unless you know what you are doing; this is inadvisable for beginners.

Qwiic & I2C

I2C Address

In the firmware, the Qwiic Joystick’s I2C address is configurable so you can add a bunch of them to the same bus without collision issues.

Factory Default I2C Slave Address: 0x20

I2C Registers

Address Description
0x00 Default I2C Slave Address from EEPROM
0x01 - 0x02 Firmware Version (MSB First)
0x03 - 0x04 Current Horizontal Position (MSB First)
0x05 - 0x06 Current Vertical Position (MSB First)
0x07 Current Button Position
0x08 Button Status: Indicates if button was pressed since last read of button state. Clears after read.
0x09 Configuration or "Locking" Register - Prevents random I2C address changes during I2C scans and register dumps. Must be set to 0x13 before an address change gets saved to the EEPROM.
0x0A Current/Set I2C Slave Address (Write). Stored in EEPROM.


Note: In the registers for the joystick position, the MSB contains the first 8 bits of the 10-bit ADC value and the LSB contains the last two bits. As an example, this is how the library converts the two registers back to a 10-bit value.

uint_16t full10bitvalue = ((MSB << 8) | LSB) >> 6;

You could potentially only look at the MSB and get an 8-bit reading (for 256 positions). The firmware was intentionally written this way in the hopes that it would be useful for customers who didn't need the full resolution of the joystick position.
Troubleshooting Tip:
Please be aware, the first time the joystick position registers are read, it will have a maximum value (all 1's in binary). I am not sure if it is something in the firmware or if has something to do with the ATtiny85, but the initial read will be 1023. Once that is read, everything reading after should be accurate (excluding the manufacturing tolerances mentioned above). If you have a fix for this issue, please feel free to comment on this tutorial or create a pull request on the GitHub repository.

Connections

The board provides four labeled breakout pins. You can connect these lines to the I2C bus of your microcontroller and power pins (3.3V and GND), if it doesn't have a Qwiic connector.

breakout pins on board

However, the simplest way to use the Qwiic Joystick is through the Qwiic connect system. The connectors are polarized for the I2C connection and power. (*They are tied to the breakout pins.)

Qwiic connectors on board

I2C Pull-up Jumpers

Cutting the I2C jumper will remove the 2.2kΩ resistors from the I2C bus. If you have many devices on your I2C bus you may want to remove these jumpers. Not sure how to cut a jumper? Read here!

pullup jumper on board

Hardware Assembly

Arduino Examples

With the Qwiic connector system, assembling the hardware is simple. All you need to do is connect your Qwiic Joystick to the RedBoard Qwiic with a Qwiic cable. Otherwise, you can use the I2C pins of your microcontroller; just be aware of logic levels, that the operating voltage of the ATtiny85 ranges from 1.8 to 5.5V, and the EEPROM needs at least 2V or it will get corrupted .

Hardware assembly with RedBoard Qwiic

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

Troubleshooting Tip:
It is best to power the board at the recommended 3.3V of the Qwiic system. However, if you have a board with firmware version 2.3 and happen to accidentally corrupt the EEPROM and inject a new, random I2C address. There is a way to replace the I2C address and store it in the EEPROM again. Follow the following steps exactly, you will need to use the Arduino Library from below:

  1. Connect the Qwiic Joystick to a RedBoard Qwiic with a Qwiic cable.
  2. Run Example 3 to find the current I2C address.
  3. Modify Example 2 to use the I2C address you just found.
  4. Run Example 2 and change the I2C address back to the default address.
  5. Unplug and the Qwiic Joystick and plug it back in. The EEPROM should be reset to the default I2C address and be ready to use again.

Raspberry Pi Example

With the Qwiic connector system, assembling the hardware is simple. You will need a Qwiic cable, a SparkFun Qwiic HAT for Raspberry Pi, and a Raspberry Pi setup with the Raspbian OS, monitor, and standard peripherals. (*If you are unfamiliar with the Qwiic Hat, you can find the Hookup Guide here.)

Hardware assembly with Raspberry Pi with Qwiic Hat

Note: This tutorial assumes you are familiar with using a Raspberry Pi and you have the latest (full... with recommended software) version of Raspbian OS your Raspberry Pi. You can download the latest version of the Raspbian OS from the Raspberry Pi Foundation website. As of Feb. 13th 2019, we recommend the Raspbian Stretch with desktop and recommended software option.

If this is your first time using a Raspberry Pi, please head over to the Raspberry Pi Foundation website to use their quickstart guides. We have listed a few of them here:

  1. Setting up your Raspberry Pi
  2. Using your Raspberry Pi
  3. Documentation:
  4. Setup Documentation
    Installation Documentation
    Raspbian Documentation
    SD card Documentation

Arduino Library

The easiest way to install the Arduino library is by searching SparkFun Qwiic Joystick inside the Arduino library manager. To manually install, head on over to the GitHub Page or feel free to download the library here!

Library Functions

The Arduino library is commented and the functions should be self-explanatory. However, below is a detailed list of the available library functions.

.begin() or .begin(Wire, deviceAddress)
Creates a connection to an I2C device over the I2C bus using the default or specified I2C address.

Input: uint8_t deviceAddress
Unasssigned 8-bit integer for device address. If not defined, the library will use the default I2C address stored in the I2C library (0x20).
Output: Boolean

True- Connected to I2C device.
False- No device found or connected.

.isConnected()
Tries to connect to the device at the I2C address stored in the library.

Output: Boolean

True- Connected to I2C device.
False- No device found or connected.

.setI2CAddress(newAddress)
Changes the I2C address to newAddress. Once changed, the new I2C address is saved in the EEPROM of the Qwiic Joystick. Reconnects to device using new I2C address. (The new address is printed out in the Serial Monitor.)

Input: uint8_t newAddress

Unasssigned 8-bit integer for device address.

.getHorizontal()
Returns the ADC value of the joystick horizontal position.

Output: uint16_t

Unasssigned 10-bit integer [0 - 1023] for ADC value of the joystick position in the horizontal axis.

.getVertical()
Returns the ADC value of the joystick vertical position.

Output: uint16_t

Unasssigned 10-bit integer [0 - 1023] for ADC value of the joystick position in the vertical axis.

.getButton()
Returns the current button state (clears check button indicator - see below).

Output: byte

0 - Button is currently being pressed.
1 - Button is currently unpressed.

.checkButton()
Indicates if the button was pressed between reads of the button state or calls of this function. The register for this indicator is then cleared.

Output: byte

0 - Button is was NOT pressed.
1 - Button is was pressed.

.getVersion()
Returns a string of the firmware version number.

Output: String AAA.BBB

AAA - Firmware Version (Major)
BBB - Firmware Version (Minor)

Examples

There are four examples in the Qwiic Joystick Arduino Library to get you started with using Qwiic Joystick. These example files are named with self-explanatory titles, but in case you want more information, see the descriptions below.

  • Example1_Basic_Readings

    This example connects to the Qwiic Joystick using the default I2C address saved in the library. The sketch looks at the registers for the current joystick position and button state. The example then prints out those values over the Serial Monitor.

  • Example2_I2C_Address_and_Firmware

    This example connects to the Qwiic Joystick using the default I2C address set in the sketch and then prints out the I2C address and firmware version over the Serial Monitor. The sketch then, takes an input from the Serial Monitor to change the I2C address using a decimal value (DEC). Once the I2C address is changed, it is stored in the EEPROM of the Qwiic Joystick. After, the sketch connects to the joystick using the new I2C address and reads the registers for the firmware version again. The example then prints out those values over the Serial Monitor again.

  • Example3_I2C_Scanner

    This example is from the I2C scanner example from the Arduino Playground webpage. The sketch scans for devices on the I2C bus and reports them on the Serial Monitor. This is useful for users who have forgotten the changed I2C address of their boards.

  • Example4_Joystic_Serial_Output

    This example shows a basic example of how to begin to use the Qwiic Joystick as an HID. The example sketch takes values of the joystick and converts it to directional printouts on the Serial Monitor.

Arduino Examples

Note: This section is an example of using the Qwiic Joystick and the RedBoard Qwiic with the Arduino IDE. It is not intended to be a guide for using I2C devices with the Arduino IDE.

Please use the following links and the internet for a better understanding of I2C and how it works in the Arduino IDE:

Example 1: Basic Readings

This sketch looks at the registers for the current joystick position and button state; the values are sent to the Serial Monitor. Make sure you are using a baudrate of 9600bps.

Serial monitor print out with joystick position and button presses

Example 2: I2C Address Change and Firmware Version Read

This sketch takes an entry from the Serial Monitor, in a decimal value, and changes the I2C address of the device. The firmware version is then read to confirm that the address was changed. Make sure you are using a baudrate of 9600bps.

Serial monitor print out of I<sup>2</sup>C address changes

Example 3: I2C Scanner

This sketch is from the I2C scanner example from the Arduino Playground webpage. The sketch scans for devices on the I2C bus and reports them on the Serial Monitor. Make sure you are using a baudrate of 9600bps.

Example 4: Joystick Serial Output

This sketch takes values of the joystick and converts it to directional printouts on the Serial Monitor. It also reads out if the button was pressed. Make sure you are using a baudrate of 9600bps.

Labeling of Qwiic Joystick for serial monitor print out

Python Examples

Update: We've written a full Python package for the Qwiic Joystick that can be found here:


For installation instructions, please refer to the repository's README file.
Note: This section is an example of using the Qwiic Joystick with the Raspberry Pi in Python. It is not intended to be a guide for using I2C devices with a Raspberry Pi or a tutorial on Python.

Please use the following links and the internet for a better understanding of I2C and how it works in the Arduino IDE:

Enable I2C Interface

If it isn't already enabled, enable I2C interface in Preferences > Raspberry Pi Configuration panel.

Accessing configuration panel from the desktop Enabling the I2C on the configuration panel

Enabling the I2C through the configuration panel.

Check for Device Using Command Line

On the (full) Raspbian OS, i2ctools should be pre-installed (if it is not, follow the instructions here). With the Qwiic Joystick and Qwiick Hat attached to the Raspberry Pi, run the following command in the terminal/commandline.

i2cdetect -y 1

Download and Run Python Examples

Download the Python Examples from the GitHub repository. All you need to do is open an example python file and execute the module. You can do this in Python 3 or another compatible, programming text editor like Geany.

Basic Readings

Below is a screenshot of the python shell from the Basic Readings example file.

screenshot of python shell print out

Snake Game

When you run the Snake Game example code, you only need to click the button to start the game. (*Shout out to Al Sweigart for his Wormy example, which was adapted to work with the Qwiic Joystick.)

screenshot of the snake game example

Troubleshooting Tip: I did run into an error with the python example codes. Unfortunately, I am not an expert in Python and the Raspberry Pi. However, I got around this by having the error print out instead of terminating the script. From what I could deduce based on the available information on the internet, the error [Errno 121] Remote I/O error is an issue with the I2C bus and how SMBUS interacts with the slave device.

You will also get an [Errno 121] Remote I/O error if your I2C address is defined wrong.

Resources and Going Further

For more information, check out the resources below:

Product Information

Example Code and Arduino and Python Libraries

Need help getting started with Arduino and I2C? Check out these resources here:

Need help getting started with your Raspberry Pi? Check out these resources here:

Need help getting started with Python and I2C? Check out these resources here:

Need some inspiration for your next project? Check out some of these other Qwiic product tutorials:

Qwiic pHAT for Raspberry Pi Hookup Guide

Get started interfacing your Qwiic enabled boards with your Raspberry Pi. The Qwiic pHAT connects the I2C bus (GND, 3.3V, SDA, and SCL) on your Raspberry Pi to an array of Qwiic connectors.

Garmin LIDAR-Lite v4 (Qwiic) Hookup Guide

Connecting the Garmin LIDAR-Lite v4 to a microcontroller just got easier! Check out our hookup guide to get started.

Qwiic SHIM for Raspberry Pi Hookup Guide

Ever wanted to prototype I2C components on a Pi? Now you can!

Air Velocity Sensor Breakout - FS3000 Hookup Guide

Get started with the Air Velocity Sensor Breakout - FS3000!