Adding haptic effects to your Android application

baroohspottyMobile - Wireless

Jul 19, 2012 (4 years and 11 months ago)

708 views

Adding haptic effects to your
Android application

Version 1, June 24th, 2011

























Immersion Corporation
www.immersion.com



Table of contents

© 2011 Immersion Corporation. All rights reserved.

Adding haptic effects to your Android application

Table of contents

Why Immersion?

What you will learn in this course

Who should be taking this course

What you should have installed before starting the class

What will be provided to you in class

The science of haptics

The benefits of haptics

Examples of haptic effects and implementations

Immersion’s haptic technologies

Exploring prebuilt effects using the Haptic Effect Preview application

Exercise 1: Exploring prebuilt effects in an Android application

Understanding the Universal Haptic Layer (UHL)

Exercise 2: Adding the UHL package to the Bouncing Ball application

Set up an Eclipse project

Add the Universal Haptic Layer (UHL) package

Add the jar file

Right-click on the BouncingBall project in the Eclipse Package Explorer and

choose Build Path > Configure Build Path.

Add the Javadocs for the UHL

Expand the UHL.jar directory and select Javadoc location.

Add the native library file

Adjusting an application’s manifest file

Exercise 3: Adjust the Bouncing Ball application’s manifest file

Disabling automatic haptic feedback

Adding prebuilt haptic effects to an application

Playing a haptic effect

Stopping a haptic effect

Exercise 4: Adding prebuilt haptic effects to the Bouncing Ball application

Importing the Launcher class

Playing the haptic effect

Stopping the haptic effect

Running an application to test haptic effects

Exercise 5: Test the haptic effect applied to the Bouncing Ball application

Haptic power modes

Exercise 6: Add different power variants of the Bounce effect to the Bouncing Ball

application

Appendix A: Configure ProGuard

Appendix B: Android NDK

Additional Resources





Who is Immersion?

About Immersion Corporation: Immersion has been a leader in the research, development
and delivery of haptics since our formation in 1994. Immersion technology has shipped in
hundreds of millions of devices worldwide, including gaming peripherals, mobile phones, tablets,
medical devices, touchscreen kiosks, casino games, digital cameras, and automotive
applications. Our extensive technology and expertise allows us to offer the most comprehensive
series of solutions available.

Problem Statement: Research has shown that consumers find a mobile experience with
haptics more intuitive, engaging and informative than simple touch interfaces. The key to
delivering on the promise of a superior haptics mobile experience is twofold: 1) Integrating high-
resolution haptics technology to communicate meaningful & nuanced information 2) Ensuring
that the technology is well implemented at both the OS and the application level to create a
consistent but context-sensitive experience.

Hundreds of millions of phones and tablets have shipped with haptics, and advancements in
haptics technology have improved resolution and enabled advanced effects, but the haptics
mobile experience has been hampered by underutilization in the user interface (UI) and
applications. This is primarily due to the complexity of integrating haptics in the UI and the lack
of API access for mobile application developers.

The Immersion Solution: With the continued success of Android as the dominant OS in the
smart phone marketplace, Immersion now has access to a development platform that is capable
of addressing the complexities of haptics for the mobile ecosystem. Immersion is announcing a
revolutionary new tool for the Android platform, the Immersion MOTIV™ Development Platform.
MOTIV provides a set of software development tools that allows Mobile OEMs, Carriers and
Application Developers to easily deliver a HD haptics experience through automated integration
tools and effects libraries that simplify customization at the UI and the application levels.

The Immersion MOTIV Development Platform for Android is an innovative software solution for
OEMs, Carriers and Application Developers that enables a HD haptics experience through
tighter integration of haptics into the Android UI and applications. The MOTIV Development
Platform is comprised of two key elements, the MOTIV Integrator for OEMs and the MOTIV
SDK for application developers. For this course, we will only address MOTIV SDK for
application developers.

MOTIV SDK: Our SDK makes it simple for application developers to implement haptics by
providing simple code samples that developers can use to insert haptics into their applications.
The MOTIV SDK enables haptic effects on ALL Android handsets in the market, allowing the
developers to have a single code base and avoid fragmentation. The SDK comes with a number
of valuable features, including:

● developer.immersion.com: Our new developer site filled with resources to provide
developers with the latest releases of our SDK, as well as helpful tools like: sample
code, best practices, handset compatibility, the latest applications using MOTIV and a
forum developer’s can access to help get their questions answered. Also included on
the developer’s site:

● Universal Haptic Layer (UHL): Automatically optimizes haptics effects based
on the handset the consumer is using and includes effects libraries:
Immersion has developed over 100 individual effects that developers can
select to incorporate into their applications. Categories of effects include:
textures, explosions, engines, weapons, alerts, clicks, bounces, and even
impacts made on different materials, like wood, rubber and metal.

● MOTIV Studio: For more advanced developers, the MOTIV Studio program
offers the ability to edit existing haptic effects or create entirely new effects
from scratch.

● UHL Effect Preview: An Android Application that is used by developers to
preview effects on their handset. Effect Preview doesn’t require any PC
tethering, making it easy for Android developers to quickly test how effects will
feel on different handsets.






 
Developer Values:
The MOTIV Development Platform delivers a superior user experience
Customizing applications to include haptics creates a more fun and exciting user experience
∙ Differentiation: Games with haptics are a way to differentiate your application in a crowded marketplace, as users look for
applications that take advantage of their haptics technology
∙ Realism: Haptics brings an element of realism to applications that are not available through normal vibrations or non-haptics
environments
∙ Stickiness: A superior user experience makes for a sticky application, users are more engaged.
∙ Control: The MOTIV Development Platform provides an opportunity for application developers to have greater control over the
user experience
With Immersion’s MOTIV Development Platform, you will be the first to market with next-gen
technology
Hundreds of millions of users have haptics technology in them, but users have never been able to download
applications with this level of customization before
∙ Differentiate your application in the market
∙ Bringing an arcade experience to a handset/high performance – console gaming. Bring rumble to the handset.
∙ Attract the early adopters and garner attention as a technology leader

Immersion’s MOTIV Development Platform is straightforward and easy to use
Immersion’s tools are comprised of pre-designed haptic effects, customization tools, and simple code samples that can
be inserted into your application, making it simple to add a custom haptic experience
∙ Tools are easily accessible through the MOTIV Development Platform developer’s portal
∙ Today, mobile developers have simple turn on/turn off features for haptics. With the MOTIV Development Platform, they will
have many more colors in the palette to paint from
∙ Immersion as already done the hard work and prebuilt hundreds of effects, from a simple button press to explosions to
textures
∙ Immersion provides sample code, reference effects, reference games and more to mobile developers
 












What you will learn in this course

In this course, you will learn about haptic effects and how to include them in your Android
applications. Topics include:

● The science of haptics
● Why use haptics?
● Examples of haptic effects and implementations
● Immersion’s haptic technologies
● Adding haptics to an application
● Understanding the Universal Haptic Layer (UHL)
● Exploring prebuilt effects using the Haptic Effect Preview application
● Adjusting an application’s manifest file
● Disabling automatic haptic feedback
● Adding prebuilt haptic effects to an application
● Running an application to test haptic effects

Who should be taking this course

This course targets experienced Android developers who have practical experience with:

● Android architecture
● The life cycle of components
● Event handling
● Debugging an application
● Deploying an application to a device
What you should have installed before starting the
class

As an experienced Android developer, you should attend class with these items installed on
your computer:

● Java SE
○ http://java.sun.com/javase/downloads/index.jsp

● Eclipse
○ http://www.eclipse.org/downloads

● Android SDK
○ http://developer.android.com/sdk/1.5_r1/index.html

● Android Developer Tools
○ From within Eclipse’s “Install new Software” option, point to http://dl-
ssl.google.com/android/eclipse/

● UHL Package
○ http://www2.immersion.com/developers/index.php?option=com_content&view=ca
tegory&layout=blog&id=119&Itemid=592


For detailed instructions on installing the Android SDK and Android developer tools, see:
http://developer.android.com/sdk/installing.html
.

What will be provided to you in class

This course focuses on integrating haptics into an existing Android application: Bouncing Ball
(http://www2.immersion.com/developers/index.php?option=com_content&view=article&id=544&
Itemid=659
). The following files will be provided to you in class:

● BouncingBall_Starter.zip (Eclipse project file)
● BouncingBall_Starter.apk
● BouncingBall_Solution.zip (Eclipse project file)
● BouncingBall_Solution.apk

The science of haptics

In this context, haptics is the science concerned with how people explore the environment
through touch, or tactile feedback. The role of touch, as a sense, is often underestimated. We
rely extensively on touch input to control the movement of our bodies and to perceive the world
around us—have you ever tried to walk when your foot was asleep?

Haptic interaction with the physical environment relies on mechanical signals such as contact
forces, torques, movement of objects and limbs, mass, geometry and weight of objects, stiffness
and texture of materials, etc. Haptic perception in virtual environments relies on sensory signals
simulated by haptic interfaces.

Haptic interfaces use actuators to create haptic sensations. For example, by delivering a
perfectly timed and tuned set of vibrations, a user is able to perceive the edges of a button while
running their finger across a screen what is actually a two-dimensional display. Haptic interfaces
use the sense of touch to provide environmental cues.


Figure 1: A carefully timed and tuned vibration can simulate the pressure felt when running a
finger over a change in surface.

You’ve probably experienced haptics in many of the consumer devices that you use every day.
The rumble effect in your console game controller and the reassuring touch vibration you
receive on your smart-phone dial-pad are both examples of haptic effects. In the world of mobile
devices, computers, consumer electronics, and digital devices and controls, meaningful haptic
information is frequently limited or missing. For example, when dialing a number or entering text
on a conventional touchscreen without haptics, users have no sense of whether they’ve
successfully completed a task.

With haptic technology, users feel the vibrating force or resistance as they push a virtual button,
scroll through a list or encounter the end of a menu. In a video or mobile game with haptics,
users can feel the gun recoil, the engine rev, or the crack of the bat meeting the ball. When
simulating the placement of cardiac pacing leads, a user can feel the forces that would be
encountered when navigating the leads through a beating heart, providing a more realistic
experience of performing this procedure.

Haptics can enhance the user experience through:

Improved Usability: By restoring the sense of touch to otherwise flat, cold surfaces,
haptics creates fulfilling multi-modal experiences that improve usability by engaging
touch, sight and sound. From the confidence a user receives through touch confirmation
when selecting a virtual button to the contextual awareness they receive through haptics
in a first person shooter game, haptics improves usability by more fully engaging the
user’s senses.

Enhanced Realism: Haptics inject a sense of realism into user experiences by exciting
the senses and allowing the user to feel the action and nuance of the application. This is
particularly relevant in applications like games or simulations that rely on only visual and
audio inputs. The inclusion of tactile feedback provides additional context that translates
into a sense of realism for the user.

Restoration of Mechanical Feel: Today’s touchscreen-driven devices lack the physical
feedback that humans frequently need to fully understand the context of their
interactions. By providing users with intuitive and unmistakable tactile confirmation,
haptics can create a more confident user experience and can also improve safety by
overcoming distractions. This is especially important when audio or visual confirmation is
insufficient, such as industrial applications, or applications that involve distractions, such
as automotive navigation.

The potential for haptics in computer interface design goes beyond using touch to simulate
forces found in nature. Haptics can be used to develop a tactile language that consistently
delivers touch cues to reinforce typical interactions. A simple example of this, in wide use today,
is the delivery of different vibrations to signal incoming calls, incoming text messages, etc., on a
mobile device. In this course we will explore a sample application, Bouncing Ball, that uses
tactile feedback to provide dimension to a library of visual objects.

Learn more about haptics:

International Society for Haptics

Haptics-e

Haptics Laboratory



The benefits of haptics

Here are some ways that haptics can improve your applications:

● Haptics-enabled content, such as navigational cues, ringers, or games enhance the
user's experience, making it more engaging, intuitive, and personal.

● Touch sensations make navigating software user interfaces easier by assisting with
hand-eye coordination and confirming completed tasks.

● Sensations, such as unique vibrating effects, assist in identifying callers without the use
of sound.

● Touch sensations can replace or complement graphical cues to diminish problems with
screen glare or when looking at the screen is inconvenient, such as receiving an alert
during a call.

Surveys show a clear and measurable preference for haptic-enabled applications:

● 90% of respondents indicated a preference for haptics in their next phone.

● 95% of users surveyed perceived next-generation, haptic-enabled applications to be of
high value.


Examples of haptic effects and implementations

Immersion provides developers with a library of more than 100 prebuilt haptic effects—each
available in three different amplitudes (strengths). You can view a complete list in the Immersion
Developer Center
(http://www2.immersion.com/developers/index.php?option=com_content&view=article&id=496&
Itemid=814
). You can also sample these effects on your Android device by downloading and
installing the Immersion Developer Effects Preview from the Android Marketplace.

If you own a modern touch-screen device, you have likely experienced haptic effects. The
Android OS for example, uses haptics (when enabled) to provide a sense of touch to the action
of unlocking your phone or dialing using the keypad. Figure 2 shows other examples of haptics-
enabled experiences (Figure 2).



Figure 2: These are three examples of applications that use haptics to enhance the user
experience.

Immersion’s haptic technologies

Immersion makes haptic player technology (TouchSense) for device manufacturers as well as
resources and tools for application developers. When you combine Immersion-based player and
development technologies, you can create unique, high fidelity haptic experiences.

While Immersion player technology is being adopted by an increasing number of manufacturers,
your application will need to talk to devices that don’t have it. Immersion provides developers
with a software emulator that controls the existing vibrator on an Android device (Figure 3).



Figure 3: Haptic effects can be delivered to devices with or without Immersion TouchSense
technology on board.

While the Android SDK allows access to device vibrators, the fine control necessary to deliver a
meaningful, consistent haptic-experience requires either a haptic player or emulation software. It
is Immersion’s emulator that facilitates realistic haptic experiences on devices that do not
incorporate Immersion TouchSense or other player technology.






Adding haptics to an application

Immersion provides Android developers with a Universal Haptic Layer (UHL) that includes a
library of more than 100 prebuilt haptic effects. You can also use Immersion’s MOTIV Studio to
easily create your own custom haptic effects. MOTIV Studio works in tandem with MOTIV
Bridge to allow you to test effects on an Android device (Figure 4).



Figure 4: The Universal Haptic Layer, MOTIV Studio, and MOTIV Bridge are the three core
components of the Immersion developer technologies.

In the first half of this course you will learn how to add haptic effects to an existing application
using the UHL. In the second half of this course you will learn how to develop custom effects
using MOTIV Studio and MOTIV Bridge.


Exploring prebuilt effects using the Haptic Effect
Preview application

You will select prebuilt haptics from a list maintained here:
http://www2.immersion.com/developers/index.php?option=com_content&view=article&id=496&It
emid=814


You can experience these prebuilt effects using Immersion’s UHL Effect Preview application
available in the Android Marketplace (Figure 8).



Figure 5: These are screen captures from Immersion’s UHL Effect Preview application.


In the preview application, effects are organized by type (Table 1). Many effects are available in
different powers and each variant is identified by a unique ID number. Power is typically
expressed as High (100%), Mid (66%) or Low (33%).

ID range Effect Type

0-11 Single
12-20 Double
21-30 Triple
31-32 Buzz
33-38 Ramp up
39-44 Ramp down
46-58 Pulse
59-66 Buzz-Bump
67-70 Alert
71-82 Explosion
83-89 Weapon
90-106 Collision
107-120 Texture
121-123 Engine

Table 1: UHL Effect categories representing 123 total prebuilt effects as of this writing.

Note: In Exercise 4 you will be using the prebuilt haptic effect: ID 9, Bounce-High. In Exercise
6, you will adjust the power of the Bounce-High effect based on input. You will do this by
implementing ID 10, Bounce-Mid and ID 11, Bounce-Low.

Exercise 1: Exploring prebuilt effects in an Android
application

In this exercise, you will use your Android device to:

● Install and explore a version of the sample application (Bouncing Ball) that does not
include haptic effects.
● Download and explore Immersion’s UHL Effect Preview application.
● Install and explore a version of the sample application that does employ haptic effects.


Install the Bouncing Ball starter file

1. Install BouncingBall_Starter.apk (provided in class) using the command line tool adb
(Android Debug Bridge).

Note: The Android Debug Bridge is installed on your computer as part of the Android
SDK. Use the command: adb install <path_to_apk>

2. Launch the Bouncing Ball application on your device.

3. Manipulate the device to move the ball and notice that it bounces off of the display
edges.

Explore the UHL Effect Preview application

4. Download and install Immersion UHL Effect Preview from the Android Marketplace.

5. Launch the application.

6. Navigate through the various categories to try out different effects.


Install the Bouncing Ball solution file

7. Install BouncingBall_Solution.apk using the command line tool adb.

Note: When switching between the starter and solution applications on your device, you must
delete one before installing the other.



8. Launch the application on your device.

9. Manipulate the device and notice the haptic effects that are delivered when the ball
contacts an edge.



Understanding the Universal Haptic Layer (UHL)

You can download the Universal Haptic Layer (UHL) package in the Immersion developer
center
(http://www2.immersion.com/developers/index.php?option=com_content&view=category&layout
=blog&id=119&Itemid=592
).

The UHL package consists of three files:

● UHL.jar: Java library containing the UHL implementation. Java applications using the
UHL must link with this library.

● libEmmulatorJ.so: Native library for ARM, containing the emulator (TouchSense 3000)
implementation. Applications using the UHL must link with this library.

● UHLdoc.zip: Documentation in javadoc format. This provides context-sensitive help for
UHL classes in Eclipse.

You will need these three files in the following exercise and will use them throughout the course.

Exercise 2: Adding the UHL package to the Bouncing
Ball application


In this exercise you will set up an Eclipse project using the starter file provided to you and then
add the UHL package to the project.
Set up an Eclipse project

The first step is to create a new Eclipse project and then import the Bouncing Ball
source code (See: What will be provided to you in class).

1. In Eclipse, select File > Import > General > Existing Projects into Workspace.

2. Select Next and choose the radio button for Select archive file.

3. Enter the path to the file BouncingBall_Starter.zip that you downloaded earlier.

4. Click Finish.

You now have the Bouncing Ball source code in the Eclipse environment.
Add the Universal Haptic Layer (UHL) package

5. Unzip the UHL package that you downloaded earlier. You will see three files:

■UHL.jar
■libEmmulatorJ.so
■UHLdoc.zip

Add the jar file
6. Right-click on the BouncingBall_Starter project in the Eclipse Package Explorer
and choose Build Path > Configure Build Path.

7. Select the Libraries tab and click on Add External JARs.

8. Browse to where you unzipped the UHL package and select the UHL.jar file.
Notice the UHL.jar file added to the project.



Figure 6. Add the UHL.jar file to the BouncingBall project in the project’s build path.

Add the Javadocs for the UHL
9. Expand the UHL.jar directory and select Javadoc location.

10. Click Edit.



Figure 7. Click to edit the Javadoc location.

11. In the Javadoc For ‘UHL.jar’ window, click Javadoc in archive.

12. To set the Archive path, browse to your unzipped UHL package and select
UHLdoc.zip.


Figure 8. Browse to select the UHLdoc.zip for the Archive path.

13. Click OK.

Add the native library file

14. Create a new folder armeabi, inside the libs folder in your project directory.

15. Copy the libImmEmulatorJ.so file from the UHL package and paste it into the
new armeabi folder.

Note: If you are using NDK, reference Appendix B for details on how to configure your
environment for the UHL native library.





Adjusting an application’s manifest file

All of the prebuilt haptic effects require Android SDK version 7 (Eclair) and above. You must
make this declaration in the application’s manifest file. You must also set the VIBRATE
permission.





Exercise 3: Adjust the Bouncing Ball application’s
manifest file

In this exercise, you will make changes in the manifest file for the BouncingBall project to add
the VIBRATE permission and to specify the Android SDK version.

1. In Eclipse, within the BouncingBall_Starter project, open AndroidManifest.xml in the
root directory.

2. Locate the tag <uses-sdk android:minSdkVersion=”3”/> and change the value of the
minSdkVersion to 7. Your code should look like this:


<uses-sdk android:minSdkVersion=”7”/>


3. After the application tag block, add the following code for the VIBRATE permission:


<uses-permission android:name="android.permission.VIBRATE" />


4. Save the file.


Disabling automatic haptic feedback

The Android user interface automatically applies haptic feedback (when enabled) to certain
interface components depending on configuration. Since you will be providing haptic feedback
through the UHL, and since you don’t know how the device has been configured, you must
disable automatic feedback on a per-instance basis. You can do this in two ways:

● In the layout’s XML file, add the property for the specific component:


<Button
android:layout_weight="0"
android:layout_width="fill_parent"
android:layout_height="wrap_content"
android:layout_marginTop="10px"
android:text="@string/btnPlayMag"
android:hapticFeedbackEnabled="false"
android:onClick="btnPlayMagsweepClicked"
/>



● In Java code, you can set a boolean value for the property setHapticFeedbackEnabled
on a UI component:


mBtnPer.setHapticFeedbackEnabled(false);



Adding prebuilt haptic effects to an application

When adding a prebuilt haptic to your application, you must import the Launcher class in the
UHL API. You must then instantiate the Launcher object in order to play the chosen effect.

Importing the Launcher class

The Launcher class is used to start and stop playing built-in effects. You must import this class
for use.

import com.immersion.uhl.Launcher;

The UHL provides many classes to aid you in adding haptics to your application. Refer to this
documentation for more information:
http://www2.immersion.com/developers/index.php?option=com_wrapper&view=wrapper&Itemid
=765


Note: You will deal with other classes when adding custom effects (covered later).

Instantiating a Launcher object

You must instantiate the Launcher object before you can use it in the code. This is typically
done in the onCreate() method of your Android Activity. You create a Launcher object by
calling the Launcher constructor and passing in the context of the Activity:


/** Called when the Activity is first created. */
@Override
public void onCreate(Bundle savedInstanceState)
{
super.onCreate(savedInstanceState);
setContentView(R.layout.main);

try
{
mLauncher = new Launcher(this);
}
catch (Exception e)
{
Log.e("My App", "Exception!: " + e.getMessage());
}
}

You can learn more about the Launcher object here:
http://www2.immersion.com/developers/index.php?option=com_wrapper&view=wrapper&Itemid
=783

Playing a haptic effect

After you have created and instantiated a Launcher object, you can use it at any point in your
application to provide haptic feedback. For example, you might play a short double click effect
on a button click:

public void btnPlayEffectClicked(View view)
{
try
{
mLauncher.play(Launcher.DOUBLE_STRONG_CLICK_100);
}
catch (Exception e)
{
Log.e("My App", "Exception!: " + e.getMessage());
}
}

Stopping a haptic effect

If a haptic effect is playing, you must stop it once you exit from the activity. This is typically done
in the onPause() event of the Android lifecycle.

protected void onPause()
{
super.onPause();

// stop vibration effect on application pause
try
{
m_launcher.stop();
}
catch (RuntimeException re)
{
Log.e("My App", "Exception!: " + re.getMessage());
}
}

Exercise 4: Adding prebuilt haptic effects to the
Bouncing Ball application


In this exercise, you will add code to the Bouncing Ball application to:

● Import the Launcher class
● Create an instance of Launcher class for an Activity
● Play a haptic effect when the ball bounces off the edge of the screen

The effect that you are adding is Bounce - High Power, with an ID of 9.

Importing the Launcher class

1. In Eclipse, within the BouncingBall_Starter project, open BouncingBallActivity.java.

2. Add an import statement for the Launcher class to the list of imports:


import com.immersion.uhl.Launcher;



Instantiating a Launcher object for an Activity

3. Create a private variable for the Launcher object in the BouncingBallActivity class:


private Launcher m_launcher;


4. Within the onCreate() method, add code to create an instance of the Launcher object as
shown here:

protected void onCreate(Bundle savedInstanceState)
{
super.onCreate(savedInstanceState);
setContentView(R.layout.main);
m_view = (BouncingBallView)findViewById(R.id.bouncingballview);
PowerManager pm = (PowerManager)
getSystemService(Context.POWER_SERVICE);
m_wakelock = pm.newWakeLock(PowerManager.FULL_WAKE_LOCK,
"DoNotDimScreen");

// initialize UHL vibration object
try
{
m_launcher = new Launcher(this);
}
catch (RuntimeException re) {}

m_nextCollision = 0;
m_view.getPhysicsWorld().setContactListener(m_contactListener);
}

Playing the haptic effect

5. Within the same class, locate the ContactListener event handler for the moving ball.

Note: The ContactListener class is a gaming class that lets you control how an object
will react to a collision. This class is available as part of the org.jbox2d.dynamics
package and is open source. Please refer to this link to learn more about this class.
http://www.java2s.com/Open-Source/Java-Document/Game/JBox2D-
2.0.1/org/jbox2d/dynamics/ContactListener.java.htm


6. Add code for playing the haptic as shown here:

private ContactListener m_contactListener = new ContactListener()
{
public void add(ContactPoint contactPoint) {}
public void persist(ContactPoint contactPoint){}
public void remove(ContactPoint contactPoint) {}
public void result(ContactResult contactResult)
{
if (contactResult.normalImpulse >= MIN_COLLISION_IMPULSE)
{
long time = System.currentTimeMillis();

// effects played too fast blur together
if (time >= m_nextCollision)
{
// choose a suitably strong collision effect
try
{
m_launcher.play(Launcher.BOUNCE_100);
}
catch (RuntimeException re) {}
m_nextCollision = time + MIN_COLLISION_TIME;
}
}
}
};

Stopping the haptic effect

7. Within the same class, locate the onPause() method.

8. Add code for stopping the haptic effect as shown here:

protected void onPause()
{
super.onPause();
m_wakelock.release();
m_view.pause();

// stop vibration effect on application pause
try
{
m_launcher.stop();
}
catch (RuntimeException re) {}
}

9. Save this file.

Running an application to test haptic effects

You will test the haptic effects in your application by installing it on your device and running it.
Connect your android device to your machine using a USB cable and simply Run the
application within Eclipse. This automatically downloads and launches the application.




Exercise 5: Test the haptic effect applied to the
Bouncing Ball application

In this exercise, you will run the application on an Android device to test the haptic effect that is
launched when the ball strikes and edge.

1. Connect your device to your desktop using a USB cable.

2. In Eclipse, select the BouncingBall_Starter project and click Run > Run from the main
menu.

Note: When switching between the starter and solution applications on your device, you
must delete one before installing the other.

3. On the device, notice the Bouncing Ball application being installed and launched.

4. Manipulate the device to move the ball and test the haptic effect.



Haptic power modes

As discussed previously, many effects are available in different power modes. You can use
different versions of the same effect to control the intensity of a haptic effect. You might want a
subtle haptic reaction in some instances and a more pronounced effect in others.

Here is an example of a haptic effect available in three different powers:

ID Name Description
0 Sharp Single Click - High Power Click Effect, Narrow Pulse, 100% Power
1 Sharp Single Click - Mid Power Click Effect, Narrow Pulse, 66% Power
2 Sharp Single Click - Low Power Click Effect, Narrow Pulse, 33% Power
Table 2: Example of an effect available in three different power settings.

Note: The Launcher Class has all of the constants defined for all of the effects but the names
vary slightly for example, Sharp Single Click -High Power is SHARP_CLICK_100

Based on design requirements, you can add code to your application to make it play different
power variants of a haptic effect for different events.






Exercise 6: Add different power variants of the
Bounce effect to the Bouncing Ball application

In this exercise, you will add code to play a different haptic effect based on the intensity of the
collision. If the ball collides with the edge at a high intensity, you will play ID 9: Bounce-High
(Bounce_100)). If the ball collides at a medium intensity, you will play ID 10: Bounce-Mid
(Bounce_66). If the ball collides at low intensity, you will play ID 11: Bounce-Low (Bounce_33).

1. In Eclipse, within the BouncingBall_Starter project, open BouncingBallActivity.java.

2. Within the same class, locate the ContactListener event handler for the moving ball.

3. Within the try loop, add code to determine collision strength:

private ContactListener m_contactListener = new ContactListener()
{
public void add(ContactPoint contactPoint) {}
public void persist(ContactPoint contactPoint){}
public void remove(ContactPoint contactPoint) {}
public void result(ContactResult contactResult)
{
if (contactResult.normalImpulse >= MIN_COLLISION_IMPULSE)
{
long time = System.currentTimeMillis();

// effects played too fast blur together
if (time >= m_nextCollision)
{
// choose a suitably strong collision effect
try
{
float strength =
(contactResult.normalImpulse -
MIN_COLLISION_IMPULSE) / (MAX_COLLISION_IMPULSE -
MIN_COLLISION_IMPULSE);
if (strength < 0.34f)
m_launcher.play(Launcher.BOUNCE_33);
else if (strength < 0.67f)
m_launcher.play(Launcher.BOUNCE_66);
else
m_launcher.play(Launcher.BOUNCE_100);
}
catch (RuntimeException re) {}

m_nextCollision = time + MIN_COLLISION_TIME;
}
}
}
};

4. Save this file.

5. Run the application and notice the different haptic effects based on collision intensity.



















Appendix A: Configure ProGuard

ProGuard is a tool built in to the Android build that optimizes and obfuscates application code.
When using ProGuard, developers must configure it to work with the Universal Haptic Layer.

To configure ProGuard, open the proguard.cfg file and add these lines to the end of the file:

-dontwarn com.immersion.**
-dontnote com.immersion.**


























Appendix B: Android NDK

If your application is using NDK and needs to include haptics, you may add the UHL native
library as a prebuilt library (requires NDK r5b or later). Since build systems vary, please refer to
the Android NDK Dev Guide for complete details on using prebuilt libraries with the NDK.

Using the UHL native library instead of the complete UHL java interface has some tradeoffs.
Several features of the UHL will be bypassed if you choose to use the native library directly.
These include:
● Built-in effect support (Launcher class)
● TouchSense Emulator (the application will only play effects on devices containing the
TouchSense Player)
● Version compatibility (the application will only play effects on devices containing the
TouchSense Player that matches the version number of the UHL native library being
used. For example, you app will run on devices that have TouchSense 3.4.*, but not on
devices with TouchSense 3.3 or 2.0)

Note: NDK users will have to implement a C-to-Java interface for accessing UHL since UHL is a
Java library.

The instructions below represent a typical build configuration. You must follow these to add the
UHL native library to your project.

1. In most cases, your native source will be located in the jni subdirectory of your project
folder. In the jni directory, create a new subdirectory called libImmEmulatorJ.

2. Place libImmEmulatorJ.so in the newly created jni/libImmEmulatorJ directory.

3. Add a new Android.mk file to this folder that contains this code:

LOCAL_PATH := $(call my-dir)
include $(CLEAR_VARS)
LOCAL_MODULE := ImmEmulatorJ-prebuilt
LOCAL_SRC_FILES := libImmEmulatorJ.so
include $(PREBUILT_SHARED_LIBRARY)

4. Now you must explicitly call this new Android.mk file located in the libImmEmulatorJ
folder from the Android.mk located in the jni folder. To do this, add the following to the
end of your Android.mk file:

include $(call all-makefiles-under,$(LOCAL_PATH))

5. Launch your NDK build. In addition to compiling your own native libraries, the NDK will
copy libImmEmulatorJ.so into your project’s libs/armeabi directory.

6. In Eclipse, right-click on the application project and choose Refresh. You should see
libImmEmulatorJ.so under armeabi.































Additional Resources

● Android Developer website: http://developer.android.com/index.html



LEGAL DISCLAIMERS
General Disclaimer.
Although Immersion has attempted to provide accurate information in this document, Immersion assumes no
responsibility for the accuracy of the information. Mention of non-Immersion products or services is for information
purposes only and constitutes neither an endorsement nor a recommendation.
THIS DOCUMENT, INCLUDING ALL CONTENT AND INFORMATION CONTAINED HEREIN ARE PROVIDED ON
AN "AS IS" BASIS. IMMERSION EXPRESSLY DISCLAIMS ALL WARRANTIES OF ANY KIND, WHETHER
EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE, NON-INFRINGEMENT AND WARRANTIES
ARISING FROM A COURSE OF DEALING, USAGE OR TRADE PRACTICE.

Intellectual Property.
The trademarks, logos and service marks ("Marks") displayed in this document are the property of Immersion or other
third parties. You are not permitted to use these Marks without the prior written consent of Immersion or such
appropriate third party.
All information in this document is (and shall continue to be) owned exclusively by Immersion or other third parties,
and is protected under applicable copyrights, patents, trademarks, trade dress, and/or other proprietary rights, and
the copying, redistribution, use or publication by you of any such information or any part of this document is
prohibited. Under no circumstances will you acquire any ownership rights or other interest in any information
contained herein by or through your use of this document.
©2011 Immersion Corporation. All rights reserved. Complying with all applicable copyright laws is the responsibility
of the reader. Without limiting the rights under copyright, no part of this document may be reproduced without the
express written permission of Immersion Corporation.
Immersion, the Immersion logo, MOTIV and TouchSense are trademarks of Immersion Corporation in the United
States and other countries. All other trademarks are the property of their respective owners.














immersion.com | 408.467.1900
801 Fox Lane | San Jose, California 95131