The information supplied in this manual is believed to be reliable and accurate at the time of its publication. Grayhill,
Inc. assumes no responsibility for any errors, omissions, or suitability of its products for a particular application.
Multi-Touch Ring Encoder Software Development Kit User’s Guide v3.0
What’s in this Guide?
Welcome to the Grayhill Multi-Touch Ring Encoder (MTRE) Software
Development Kit User’s Guide. We’ll first get your encoder up and
running with a demo so you can quickly begin to appreciate the MTRE’s
many features and capabilities. Next we’ll dive in deeper into the MTRE
operation. Lastly, we’ll introduce Grayhill’s Instinct Gesture Recognition Library that makes product development a snap. Let’s get started!
What’s in the Kit?
The Multi-Touch Ring Encoder Software Development Kit contains a Quick
Start Guide, and (1) Grayhill Multi-Touch Ring Encoder (Part
number:T101-5C3-111-M0) mounted in a case, with a USB cable ready to
plug into your type “A” USB host connector on your hub or PC.
Multi-Touch Ring Encoder Features
The Grayhill Multi-Touch Ring Encoder has the following features:
•A 50mm round projected capacitive touchpad, that can track up to
5 touch positions
•A rotating knob - detented with three different torque options, and
encoded for 32 or 48 positions
• Integral pushbutton
• Proximity sensor
• Overlay, with custom logo capabilities, backlit with 256 level
adjustable brightness settings
• Highlight ring, backlit with 256 level adjustable brightness settings
The Medical Demo is a Windows XP, Windows 7, or Windows 8 application
that will introduce you to some of the basic features of the MTRE. The
Demo is a simulation of some of the functions that may be required in a
typical imaging application. To load and run the demo, follow these steps:
Plug in the USB cable into any convenient USB port on your PC. Your
computer should automatically recognize the device without any special
drivers.
Multi-Touch Ring Encoder Software Development Kit User’s Guide v3.0
Next find the Grayhill Instinct Demo application at
http://www.grayhill.com/instinct
For users of Google’s Chrome Browser
Click on the link “Grayhill Instinct Demo (zip)”
When the download is complete, click on the file “Grayhill Instinct
Demo.zip” that appears in the download area at the bottom of the screen.
Follow the instructions of your zip file extraction tool to ex tract and locate
the files on your PC where it can be easily found.
For users of Mozilla’s Firefox Browser
Click on the link “Grayhill Instinct Demo (zip)”
The browser should open a popup box. Under “What should Firef o x do wi th
this file?” select your zip file extraction tool under “Open with.”
Follow the instructions of your zip file extraction tool to ex tract and locate
the files on your PC where it can be easily found.
For users of Microsoft Internet Explorer
Click on the link “Grayhill Instinct Demo (zip)”
The browser should open a pop up box. Under “Do you want to open or
save this file?” select “Open.” Under certain settings this step may be
skipped.
Follow the instructions of your zip file extraction tool to ex tract and locate
the files on your PC where it can be easily found.
Installing the Demo
To install the demo, navigate to the directory on your system where the
application files were extracted and run “setup.exe.” Follow the on screen
instructions to install the application. An internet connection is required.
Multi-Touch Ring Encoder Software Development Kit User’s Guide v3.0
Running the Demo
To run the demo, click on the application icon on your desktop. The connect
screen should appear as below:
Make sure the USB connector from the MTRE SDK is plugged into the PC’s
USB port. After the MTRE is found, the type (MTRE) and serial number
will be listed in the connection list next to a check box under the
“CONNECT?” heading. Click on the check box to connect the MTRE. If
multiple devices are connected to the PC, they will also appear in the list.
Click on the check box for all the devices you wish to connect, or alternately
click on the “CONNECT?” header to connect to all Grayhill devices
currently connected to the PC. When the application connects to any type of
device, the picture of the device will be highlighted on the following page:
Multi-Touch Ring Encoder Software Development Kit User’s Guide v3.0
2D Demo
The 2D demo screen is an example application that illustrates how easy it is
to position and size an image for viewing using the MTRE. Use a single
finger (or two fingers) on the touchpad to pan the image in the X or Y
direction. Use two fingers in a pinching or un-pinching motion to control the
zoom level. Spin two fingers about each other to rotate the image.
In this example application, any of these gestures can be performed
simultaneously to quickly and efficiently position the image. If the fingers
are released from the touchscreen during a gesture, the object will continue
the gesture’s movement with virtual momentum. This is a more efficient
method of positioning especially when lar ge images are used.
Also in this example, a different picture can be selected by flipping a single
finger to the left or right as if turning a page.
All of the gestures shown on the 2D screen application example can be
easily configured and recognized using the Instinct Gesture Recognition
Library. The gestures implemented and corresponding actions are only an
example of a typical 2D image application. The library is very flexible and
allows many different configurations for many different applications. The
Instinct Gesture Recognition Library is available license-free for Grayhill
customers. For further information about Instinct, please refer to
“Grayhill’s Instinct Gesture Recognition Library” section at the end of
this document.
Multi-Touch Ring Encoder Software Development Kit User’s Guide v3.0
3D Demo
The 3D demo screen is an example application that illustrates how easy it is
to position and size an object for viewing using the MTRE. Use a single
finger on the touchpad to pan the object in either the X or Y direction. Drop
a second finger to rotate the object about the opposite axis. Use two fingers
in a pinching or un-pinching motion to move the object in the Z axis (toward
or away from the screen.) Spin two fingers about each other to rotate the
image in the z plane. In fact, using these simple gestures, all six degrees of
freedom of movement can be resolved.
Gestures that use the same number of fingers can be performed
simultaneously to quickly and efficiently position the object where it is
desired. Again, as in the 2D example, if the fingers are released from the
touchscreen during a gesture, the object will continue t he gesture’s
movement with virtual momentum.
All of the gestures shown on the 2D screen application example can be
easily configured and recognized using the Instinct Gesture Recognition
Library. The gestures implemented and corresponding actions are only an
example of a typical 2D image application. The library is very flexible and
allows many different configurations for a variety of applications. The
Instinct Gesture Recognition Library is available license-free for Grayhill
customers. For further information about Instinct, please refer to
“Grayhill’s Instinct Gesture Recognition Library” section at the end of
this document.
Multi-Touch Ring Encoder Software Development Kit User’s Guide v3.0
Instinct Demo
The Instinct Page demonstrates the Instinct Gesture Recognition process by
allowing the user to change some of the settings that control how gestures
are recognized - and then allowing the user to observe how these changes
affect the output. After changing one of the settings, hit the “Apply
Changes” button to try out the new settings. Default settings can easily be
recovered by hitting the “Reset Defaults” button. The current settings are
retained for use with any of the other demo screens.
You can enable or disable any of the Event Gestures in Instinct through a
simple bit mask. Setting the check boxes next to the Event Gestures
assembles the bit mask and sets up Instinct to recognize only the checked
gestures. For more information on Event Gestures see the “Instinct
Introduction” section at the end of this document.
The Instinct page lists some of the Instinct parameters that can be used to
optimize the Gesture recognition process for a particular application. Not all
the settings are listed here, but they are a good example of some of the
settings available.
•The Down Delay is the time in 20mS intervals before the specific
number of current touches are declared down. This delay helps
eliminate "false positives" during transitional periods, i.e. when the
desired number of fingers is not yet in contact with the touch pad.
•The Max Tap Duration is the maximum number of 20mS intervals
that a given number of fingers can be "down" in order for the
"TAP" event to be re ported.
Multi-Touch Ring Encoder Software Development Kit User’s Guide v3.0
The MTRE page allows interaction with the features exclusive to the MTRE.
If a finger or fingers are placed on the touchscreen, while in touch mode, its
movements will be tracked in the circular area on the left hand side of the
screen.
To demonstrate the push button function, the indicator under the heading
“PUSH BUTTON” illuminates when the MTRE push button is activated.
To demonstrate the encoder function, turning the MTRE knob clockwise
causes the counter under the heading “ENCODER COUNTS” to increment,
while turning it counter-clockwise causes it to decrement.
To demonstrate the brightness control function, the slider bars under the
headings “Backlight Intensity” and “Highlight Intensity” can be used to
control the brightness of the backlight an d hi g hl ight ri n gs respect i vely .
The MTRE can be placed in proximity mode by selecting the “PROXIMITY
MODE” option button. To demonstrate the proximity mode function, the
circular area where the touch movements are tracked will turn green when
proximity is detected. To return to touch tracking, select the “TOUCH
MODE” option button.
Multi-Touch Ring Encoder Overview
We’ve demonstrated some of the functions of the MTRE with a simple demo
application - but we’ve only scratched the surface of its possibilities. While
the demo can show some examples of the ways the MTRE can be used, it
cannot match your imagination of how it might be used. In this section we’ll
cover the technical details of the MTRE so that you can appreciate its
flexibility.
Multi-Touch Ring Encoder Software Development Kit User’s Guide v3.0
Mechanical Drawing
The mechanical layout of the MTRE is shown below. The knob is
removable but the number of times it can be engaged is limited. For this
reason, the knob should not be removed by users in the field but sho uld be
installed one time during manufacturing.
Multi-Touch Ring Encoder Software Development Kit User’s Guide v3.0
For the discussion of the components of the MTRE see the block diagram of
the MTRE shown below:
Knob Section
Touchscreen
Encoder Section
Base Section
Powe r
Touchscreen
Controller
LED
Controller
Switching
Power Supply
Stem
Emitter
Emitter
Detector
Push-button
Proximity
Sensor
Quadrature
Push-button
USB
Microcontroller
USB – I/O Interface
The MTRE has a full speed USB device interface. Data that is transmitted
from the MTRE to the host includes the following: the raw touch positions,
proximity status, encoder (outer ring) changes, and pushbutton status. Data
can be sent to the MTRE to set the current touchpad/proximity mode, or
change the backlight or highlight on - off or control the brightness.
In addition to the USB connector, a redundant output is provided that
contains the quadrature output I/O from the encoder and the pushbutton
status.
Multi-Touch Ring Encoder Software Development Kit User’s Guide v3.0
Touchpad
The touchpad built into the MTRE uses the mutual projected capacitive
method to track up to 5 touch positions simultaneously with a 20mS sample
rate. Some features of the touchpad are listed below:
•As each individual touch is sensed, the touch is assigned the lowest
number available from 0 to 4 for reporting.
• The touch is tracked under this number until it has been released.
• The screen has an overall resolution of 1280 x 1280, although because
of the round shape, not all of these positions are utilized.
•No gesture recognition is provided in the MTRE, but “Instinct” -
Grayhill’s gesture recognition library, is available to our customers and
will be introduced later in this guide.
• Two-touch differentiation can be sensed down to about 3mm.
• Touch sensing will work with latex gloves.
• The MTRE can be set to either Touch or Proximity mode, but they
cannot be used simultaneously.
Ring Encoder
An encoder is connected to the outer ring, which in turn dr ives the I/O
outputs and also is connected to the internal controller for assembly into
USB packets. The encoder provides relative (not absolute) position of the
outer ring. The USB packet contains the number of counts (up or down)
since the last time the MTRE was polled (20ms sample rate.) The I/O
connector provides the output directly from the encoder in quadrature format
as shown below:
The ring encoder is available in 32 or 48 positions wi t h 3 dif ferent torque
options. The ring encoder functions in either the touch or proximity mode.
Pushbutton
The pushbutton make and break information is available on the USB and as
a redundant I/O. The I/O is “low” whenever the pushbutton is active and
Multi-Touch Ring Encoder Software Development Kit User’s Guide v3.0
“high” when inactive. The pushbutton functions in either the touch or
proximity mode.
Proximity
The device has two modes of operation: touchpad, and proximity. The
device is set to proximity mode by command over the USB. In Proximity
Mode the device sends make and break codes over the USB corresponding to
the current status of the proximity sensor. Proximity is detected using the
mutual projected capacitance method.
Backlight
There are four lighting elements that make up the backlight. Each element
can be individually set to on or off. Additionally the four elements together
(with a single setting) may be set to one of 256 different brightness levels.
In the sample unit provided with the SDK, the backlight has a Grayhill logo,
but the standard device has a solid white backlight. Custom logo printing is
available for the MTRE.
Highlight Ring
There are 12 lighting elements that make up the highlight ring. Each element
can be individually set to on or off. Additionally the twelve elements
together (with a single setting) may be set to one of 256 different brightness
levels. The highlight ring comes in four different colors: white, blue, red, or
green. Custom colors are also available.
Additional Information
Please visit http://www.grayhill.com/instinct for updates to this document,
updates and releases of demos, updates to unit firmware and settings files,
Errata, and other application notes.
Documentation for the USB data input and output format is available to our
customers with a signed Non-Disclosure Agreement. To request a form
please email Grayhill at instinct@grayhill.com.
Grayhill’s Instinct Gesture Recognition
Library
What is Instinct?
Welcome to the Grayhill Instinct Software Developer’s Guide. Instinct is
Grayhill’s Gesture Recognition Software Library for Grayhill Touch Devices
that makes developing applications using touch gestures a snap. Instinct
uses proven and tested recognition algorithms to accurately track and detect
single and multi-touch gestures. The Grayhill Instinct Gesture Recognition
Multi-Touch Ring Encoder Software Development Kit User’s Guide v3.0
Software Library is a C source code library – which is intended to be
included and built into your application. Simple initialization calls allow the
flexible setup of parameters to fine-tune the recognition process for your
application. During normal operation, data from the Grayhill touch device is
passed directly to the library. The data is quickly processed and the results
are passed back to your application.
What makes the Grayhill Instinct
Gesture Recognition Library unique?
When we looked at Human/Machine interface we found two basic, but
powerful types of gestures useful for machine control – we call them Event Gestures and Tracking Gestures.
Multi-Touch Ring Encoder Software Development Kit User’s Guide v3.0
Event Gestures
An Event Gesture is defined as any gesture that is performed and recognized
as a singular event and that might be used to initiate immediate state changes
in the host. The following are examples of event gestures: Tap, Double-Tap,
Touch&Hold, Tap,Touch&Hold, Swipe etc. Note that these events don’t
require any magnitude information - they are simply recognized as the user
performs them as single events. These types of events have a long hi st o ry in
user interface. A mouse click or a key press, for example, can both can be
thought of as an event.
However, since a touch panel has many more dimensions than a simple
pushbutton, these event gestures can be far more complex and powerful. For
example, Instinct has the ability to detect event gestures involving from one
to five touch points. Instinct can also recognize single-finger gesture events
in certain user-configurable circular areas, called “Icons”.
If the user taps within the area of Icon1, for example, a Tap event and an
Icon1 event is generated. By default, Icon1 through Icon4 are located in the
top, bottom, left and right corners of the screen. All other Icons are
undefined by default but can be enabled easily by using GestureConfigure.
The Tap,Touch&Hold event gesture is a combination of the Double-Tap and
Touch&Hold gestures. During a Tap,Touch&Hold, the second contact with
the screen is held longer than during a Double-Tap. One way a
Tap,Touch&Hold gesture event might be used is to in itiate an object drag
across the screen.
The Swipe gesture event is recognized when any given number of touches
leaves the touch screen with a specified velocity . The direct i onal gest u re
events Up, Down, Left, Right are used in combination with Swipe to indicate
in which direction the Swipe was performed. One way a Swipe gesture
event might be used is to initiate an advance to the next screen (Swipe Left)
or a return to the previous screen (Swipe Right).
The following Event Gestures are recognized by Instinct:
• Tap (1-5 fingers)
• Double-Tap (1-5 fingers)
• Touch&Hold (1-5 fingers)
• Tap,Touch&Hold (1-5 fingers)
• Swipe Up (1-5 fingers)
• Swipe Down (1-5 fingers)
• Swipe Left (1-5 fingers)
• Swipe Right (1-5 fingers)
• Icon1 through Icon16* (1 finger only)
*(These events can only be recognized in combination with a single-finger
Tap, Double-Tap, Touch&Hold or Tap,Touch&Hold event.)
Multi-Touch Ring Encoder Software Development Kit User’s Guide v3.0
Tracking Gestures
A Tracking Gesture is not recognized as a single event, but rather, is
reported as a continuous stream of control data for as long as the user
performs the gesture. Tracking Gestures are very useful fo r vi ewi n g an d
positioning 2-D and 3-D objects or images, or positioning the view in a field
of text. Pan, Zoom, Rotate and Scroll are examples of Tracking Gestures.
Note that these gestures need not be exclusive (they can all occur
simultaneously) and magnitude and direction information is very important
in providing the most intuitive experience.
The Instinct library can be set to provide tracking data optimized for
controlling/ positioning either 2-D or 3-D objects. Additionally, the 2-D or
3-D tracking data can be reported either in “relative” mode or in “threshold”
mode. The relative mode reports the changes in normalized tracking data
since the last report received from the device. In threshold mode, Instinct
keeps an internal cumulative value of the relative data, but then reports the
number of times this cumulative value is evenly divisible by the specified
threshold value. The internal cumulative value then gets reduced by the
reported multiple of the threshold value.
In the 2-D modes (relative and threshold), Instinct provides the following
tracking data:
•X - average movement of one to five touch positions along the
x-axis
•Y - average movement of one to five touch positions along the
y-axis
•Scale - average change of scale indicated by the relative
expansion (un-pinch) or contraction (pinch) of one to three
touch positions
•Angle - average rotation angle of one to three touch positions
about a point determined by the number of touches
In order to provide the maximum flexibility, Instinct provides full tracking
data for up to three touches. For example; using only the X and Y data:
•A mouse cursor could be moved when only one touch is
present
• An underlying picture could be panned if two touches are used
• The entire picture album could be re-positioned, or a different
one selected, if three touches are used
In this case, the developer simply qualifies the X and Y position data, with
the number of touches, and sends the data to the proper function. Although
some gesture / number of touch combinations are well known, (such as two-
finger “pinch” to control zoom) Instinct gives the flexibility to add many
more dimensions.
In the 3-D modes (relative and threshold), Instinct provides six parameters
corresponding to the six degrees of freedom of movement of any object in
space.
Multi-Touch Ring Encoder Software Development Kit User’s Guide v3.0
•X - average movement of one to five touch positions along the
x-axis
•Y - average movement of one to five touch positions along the
y-axis
•Z - corresponding movement in the z-axis (toward or away
from the user) by relative expansion (un-pinch) or contraction
(pinch) of from one to three touch positions
•X Angle - rotation angle around the x-axis that would
correspond to an average movement of one to five touch
positions along the y-axis
•Y Angle - rotation angle around the y-axis that would
correspond to an average movement of one to five touch
positions along the x-axis
•Z Angle - rotation angle about the z-axis of one to three touch
positions, about a point determined by the nu mber of touches
In 3-D modes, as in 2-D modes, the developer has flexibility to qualify the
tracking data with the number of touches desired for a particular gesture.
For example; moving fingers along the x-axis produces both X data,
(panning along the x-axis) and Y Angle data (rolling an object about the yaxis.) The developer may decide that two fingers should be used to
perform a pan along the x-axis and three fingers will be used to rotate about
the y axis. It is then only a matter of applying the X data when two touch
positions are indicated and Y Angle data when three occur.
Additional Information
The Grayhill Instinct Gesture Recognition Library is available to our
customers with a signed Non-Disclosure Agreement. To request a form
please contact Grayhill at instinct@grayhill.com.