Pmod JSTK2 Reference Manual

The Digilent Pmod JSTK2 (Revision C) is a versatile user input device that can be easily incorporated into a wide variety of projects. With a two-axis joystick on a center button, a trigger button, and a programmable RGB LED capable of 24-bit color.

Download This Reference Manual
Download 3D Print Files

Features

  • Factory Calibrated Two Axis Resistive Joystick
  • Center Joystick Button
  • Trigger Style Push Button
  • 24-bit RGB LED
  • 6-pin Pmod connector with SPI interface
  • Library and example code available in resource center

Functional Description

The Pmod JSTK2 utilizes two potentiometers oriented orthogonally to one another and are manipulated by moving the joystick in the X and Y directions. As the joystick moves, the voltage output at the sweep pin of each potentiometer changes and is measured by the 10-bit ADC present on the embedded PIC16F1618 microcontroller. The raw measured data is stored at a rate of 100 Hz as a 16-bit right-justified variable in RAM with the upper 6 bits masked with zeros.

Additionally, each successive measurement also produces two 8-bit values representative of the joysticks physical location with respect to each axis. Note that if inversion of either of the 8-bit position axis are set, the values will not change until the data has been re-collected by the PIC16 at the 100 Hz rate.


Specifications

Parameter Min Typical¹ Max Units
Recommended Operating Voltage 3.1 3.3 3.5 V
Maximum Supply Voltage - - 5.5 V
Power Supply Current² - 4.85 - mA
Power Supply Current³ - 17.6 - mA
Parameter Value Units
Maximum Joystick Angle 25 Degrees
Communication Protocol SPI

Note¹ - Data in the Typical Column uses VCC at 3.3V unless otherwise noted
Note² - Normal operation with the RGB LED Off and no buttons pressed
Note³ - Normal operation with the RGB LED set to white and both buttons pressed


Interfacing with the Pmod

The Pmod JSTK2 communicates with the host board via the SPI protocol with SPI Mode 0, CS active low, a 1 MHz clock, and each data byte organized MSb first. With the Pmod JSTK2, there are two types of data packet protocols: the standard data packet of 5 bytes and an extended data packet with 6 or 7 bytes in total. With the standard 5 byte protocol, users may use the old code from the Pmod JSTK without any syntax errors. The 5 byte packet structure is provided in the image below:

Standard 5 Byte Packet Structure

As noted in the standard data packet structure, users may either send a zero and a series of 4 dummy bytes to receive the standard 5 bytes of data or they may send a single command byte with up to 4 parameters in the four following bytes to set the internal values such as the joystick calibration or on-board RGB LED. The two bytes of data for each axis represent the 10-bit value for that axis. For the x-axis, a 0 value corresponds to the axis being tilted fully to the left and a value of 1023 corresponds fully to the right. Similarly, the y-axis has a value of 0 when it is tilted all the way down and a value of 1023 when it is tilted all the way up.

The extended data protocol allows for additional data to be obtained from the device during a communication session after the standard 5 bytes of information such as normalized 8-bit positional data for each axis. Users may also obtain the current calibration values and the status of the module through this method.

Extended Byte Packet Structure

SPI Timing Requirements

The embedded PIC16F1618 requires certain SPI timing requirements in order for successful communication to occur. When the Chip Select line is brought low, users must wait at least 15 μS before sending the first byte of data. An interbyte delay of at least 10 μS is required when transferring multiple bytes. When the Chip Select line is brought high after the last byte has been transferred, at least 25 μS is required before users may bring the Chip Select line low again to initiate another communication session.

Calibrating the Module

The Pmod JSTK2 has a set of factory loaded calibration values that are used to calculate the 8-bit position values for each axis. Users may enter calibration mode to recalculate all of those values by rotating the joystick around so the embedded PIC16 can record all of the maximum and minimum samples for the two axes. The on-board blue LED will be flashing to indicate that the calibration sequence is taking place. When the embedded microcontroller detects that the joystick has not changed for an entire second, allowing the microcontroller to presume that the most recent set of measurements correspond to the joystick's center position, the blue LED will stop flashing and the green LED will flash twice to indicate that the calibration procedure was successful. However, if 10 seconds pass without the PIC16 detecting the center position, the blue LED will stop flashing and the red LED will flash twice indicating that the calibration procedure was not successful.

Once the Chip Select pin goes high after the calibration command has been processed, the Pmod JSTK2 will not accept any new commands during the calibration procedure. Users may still poll the status register to determine the current status of the device during this time.

Using the High Endurance Flash

The calibration constants that the module uses are loaded into RAM from the High Endurance Flash (HEF) during the firmware initialization which occurs shortly after power is supplied. If a calibration sequence is performed, new calibration constants are loaded into RAM. In general, it is not necessary to then write the new calibration constants in RAM to the HEF unless the user wishes to have those new calibration constants available after a power cycle. The factory loaded calibration constants are available in the header file for the Pmod JSTK2 in the Example Code.

If the user does want to store the calibration constants in a more permanent fashion, they may issue a command to write the constants from RAM to Flash, but it is recommended to wait at least 5 milliseconds once the Chip Select goes high after the data transfer is complete because the device is unable to respond to traffic on the SPI bus.

Users may also choose to reload the constants from HEF back into RAM which will take up to 95 microseconds to complete, so it is recommend to wait at least 100 microseconds after the Chip Select is pulled high after the data transfer. Much like the RAM to Flash command, the module will not be able to respond to SPI commands during this time.


Command Summary

A list of commands supported by the Pmod JSTK2 library code is provided below.

Get Commands


Set Commands


Other Commands


Pinout Description Table

A pinout table of the Pmod JSTK2 is provided below.

Header J1
Pin Signal Description
1 CS Chip Select
2 MOSI Master-Out-Slave-In
3 MISO Master-In-Slave-Out
4 SCK Serial Clock
5 GND Power Supply Ground
6 VCC Power Supply (3.3V)

Although users are welcome to create their own interface code for the Pmod JSTK2 if they so desire, although pre-constructed libraries that provide functions for initializing the module, reading in values, and adjusting calibration values exist. They are available on the Pmod JSTK2 Example Code section.

Any external power applied to the Pmod JSTK2 must be within 2.95V and 5.5V; however, it is recommended that Pmod is operated at 3.3V.


Physical Dimensions

The pins on the pin header are spaced 100 mil apart. The PCB is 1.875 inches long on the sides parallel to the pins on the pin header, 0.9375 inch long on the sides perpendicular to the pin header, and 1.75 inches tall. With the 3-D printed housing the module is 1.875 inches long on the sides parallel to the pins on the pin header, 1.125 inches long on the sides perpendicular to the pin header, and 1.75 inches tall.


Additional Information

The schematics of the Pmod JSTK2 are available here. Additional information about the PIC16F1618 including communication modes and specific timings of the chip can be found by checking out its datasheet here.

Example code demonstrating how to get information from the Pmod JSTK2 can be found here.

If you have any questions or comments about the Pmod JSTK2, feel free to post them under the appropriate section (“Add-on Boards”) of the Digilent Forum.