Basics

Important Note

This series of Wacom products is now discontinued and support for them is no longer offered.

Introduction

Overview

This page will give the developer a basic overview of the Wacom Bluetooth Stylus framework, the programming model, and details on including the Framework in your application.

Supported iPhones and iPads

The iPhones and iPads that are currently supported by the latest released versions of iOS and iPadOS.

• iPad Pro 11 (2nd gen)
• iPad Pro 12.9 (4th gen)
• iPad Air (4th gen)
• iPad (8th gen)
• iPhone 12
• iPhone 12 Pro
• iPhone 12 Pro Max
• iPad 10.2
• iPad Pro 9.7
• iPad Pro 10.5
• iPad Pro 11
• iPad Pro 12.9”
• iPad Pro 12.9 (2nd gen)
• iPad Pro 12.9 (3nd gen)
• iPad mini 4
• iPad mini 3
• iPad Air 2
• iPad Air
• iPad mini 2
• iPad (4th gen)
• iPad mini
• iPad (3rd gen)
• iPad (6th gen.)
• iPad Air (3rd gen)
• iPad Mini (5th gen)
• iPhone 6/Plus
• iPhone 7
• iPhone 8/Plus
• iPhone X
• iPhone XS
• iPhone XS Max
• iPhone R
• iPhone 11
• iPhone 11 Pro
• iPhone 11 Pro Max

Where to Start

Download the current version of the BluetoothStylus_SDK. Add the following to your app’s Xcode project:

• WacomDevice.xcframework
• The WacomStylusFrameworkResources.bundle
• When adding the WacomDevice.xcframework to your target, make sure the target > 'General' settings for the framework is set to 'Embed & Sign'.

You can find them in the sdk folder included in the BluetoothStylus_SDK download. All supported languages are included in the bundle.

Programing Basics

There are three main components of the SDK: pairing, stylus events, and tracked touches. The following code examples are in Objective-C.

Pairing

Discover Styli and pair them by Bluetooth

Start discovery so that your iPad sends out a Bluetooth signal to find stylus products that are nearby and pair with them.

[[WacomManager getManager] startDeviceDiscovery];

- (void) deviceDiscovered:(WacomDevice *)device
{
NSLog(@"Discovered a device");

//If you want to select and pair with the first device that is discovered, use this:

[[WacomManager getManager] selectDevice:(WacomDevice *) device];

//Otherwise, use the kiss-to-pair method.
}

Stop Styli discovery

Stop discovery once the stylus is paired.

[[WacomManager getManager] stopDeviceDiscovery];

Disconnect the stylus from your app

Background-foreground transitions are automatically handled by the SDK. The SDK disconnects the stylus from your app when your app loses focus and automatically re-pairs the stylus when your app gains focus again. If you don’t want this to happen, you can disconnect the stylus from your app.

[[WacomManager getManager] deselectDevice:(WacomDevice *) device];

Stylus Events

Enable callbacks

Enable callbacks so that you can receive information about stylus events and devices.

@interface MyUIView : UIView <WacomDiscoveryCallback,WacomStylusEventCallback>
- (void) stylusEvent:(WacomStylusEvent *)stylusEvent;
- (void) deviceDiscovered:(WacomDevice *)device;
- (void) discoveryStatePoweredOff;

@end

Get pressure and stylus button data

Get information about the type of event that is occurring to the stylus, such as when the pressure on the stylus tip changes or when a stylus button is pressed.

You can see how pressure changes might affect your app by experimenting with the WacomStylusDemoApp. The harder you press with the stylus, the thicker your lines and the denser the color.

-(void)stylusEvent:(WacomStylusEvent *)stylusEvent

{

     switch ([stylusEvent getType])
     {
          case eStylusEventType_PressureChange:
                //Pressure data received.
                break;

          case eStylusEventType_ButtonReleased:
                switch ([stylusEvent getButton])
                {
                   case 2:
                   {
                      //Stylus button 2 clicked.
                      break;
                   }

                  case 1:
                  {
                     //Stylus button 1 clicked.
                     break;
                  }

                default:
                    break;
            }
            break;

     default:
          break;
    }
}

Tracked Touches

Register the UIView

Register the UIView so that the SDK automatically handles touch information.

[[TouchManager GetTouchManager] registerView:self];

Set the User’s Hand Position

Let your users select a hand position and then set it in your app for improved stylus accuracy.

[[TouchManager GetTouchManager] setHandedness:eh_Left //or eh_Right, eh_RightUpward, eh_RightDownward, eh_LeftUpward, eh_LeftDownward];

Enable multi-touch

Enable multi-touch so your app can receive touch input from multiple points of contact on the iPad at the same time. You can enable it via the Xcode Interface Builder or by using this code.

[self setMultipleTouchEnabled:YES];

Get Current Touch Information

Pass information about touch from your UIView into the TouchManager so that you can access the current TrackedTouches.

A TrackedTouch contains a pointer to a UITouch.

Important: The UITouch information will be different depending on if you have touch rejection enabled or not.

- (void)touchesBegan:(NSSet *)touches withEvent:(UIEvent *)event
{
   [[TouchManager GetTouchManager] addTouches:touches view:self event:event];
}



[[TouchManager GetTouchManager] moveTouches:touches view:self event:event];
NSArray *theTrackedTouches = [[TouchManager GetTouchManager] getTrackedTouches];



- (void)touchesMoved:(NSSet *)touches withEvent:(UIEvent *)event
{
   CGRect     bounds = [self bounds];
   @try
   {
      [[TouchManager GetTouchManager] moveTouches:touches view:self event:event];
      NSArray *theTrackedTouches = [[TouchManager GetTouchManager] getTrackedTouches];

      for (UITouch * theTouch in theTrackedTouches)
      {
         //Do work here. For example:
         current = touch.currentLocation;
         current.y = self.bounds.size.height - touch.currentLocation.y;
         previous = touch.previousLocation;
         previous.y = self.bounds.size.height - touch.previousLocation.y;
         // Update the pressure value:

         if (mPressure != mCurrentPressure)
         {
            mCurrentPressure = mPressure;
         }

         [self renderLineFromPoint:previous toPoint:current];
         mPreviousPressure = mCurrentPressure;
         mCurrentPressure = mPressure;
      }
   }
   @catch (NSException *exception)
   {
      NSLog(@"uh oh");
   }
}

[[TouchManager GetTouchManager] moveTouches:touches view:self event:event];

NSArray *theTrackedTouches = [[TouchManager GetTouchManager] getTrackedTouches];

// Do work here.

[[TouchManager GetTouchManager] removeTouches:touches view:self event:event];

- (void) touchesEnded:(NSSet *)touches withEvent:(UIEvent *)event
{
   CGPoint current, previous;
   [[TouchManager GetTouchManager] moveTouches:touches view:self event:event];
   NSArray *theTrackedTouches = [[TouchManager GetTouchManager] getTouches];

   for(UITouch *touch in theTrackedTouches)
   {
      //Do work here.
   }
   [[TouchManager GetTouchManager] removeTouches:touches view:self event:event];

}

Best Practices

Register the UIView so the SDK automatically handles touch information

Register the UIView so that the SDK handles calls to addTouches, moveTouches, and removeTouches automatically.

You can view an example of this in the WacomStylusDemoApp in the drawingView.m file.

Note: If you are experiencing issues with TrackedTouches with the view registered, remove this code from your app and refer to the documentation about handling touch information.

Create a stylus icon that opens a menu of stylus-related settings

• Let your users know that they can use a Wacom stylus with your app by creating a stylus icon that, when clicked, opens a menu of stylus-related settings.
• Include stylus settings, such as touch rejection, hand position, and stylus button functions. Also, include a battery status icon or other indicator that shows the percentage of battery charge remaining for the stylus.
• Program your stylus icon to change color when the stylus is paired to the iPad by a Bluetooth connection so that it is obvious to your users that the stylus is paired.

Disable the iPad multitasking gestures

iPad multitasking gestures can intermittently interfere with your app when a palm or finger touches the screen. Give your app users the option to disable iPad multitasking gestures directly from your app.

• One option is to create a button on a tool bar in your app that allows your users to turn gestures on and off when they want.
• You can also accomplish this by programming the stylus button to toggle multitasking gestures on and off. Make sure your app turns gestures back on automatically if the stylus is disconnected.
• Another option is for you to create a notification asking your users to turn off the iPad multitasking gestures themselves. Multitasking gestures can be turned on and off in the iPad Settings menu.

Let your users choose their preferred hand position

Display the hand position options in your app so that your users can choose the one that most closely matches the way they hold the stylus. You can open the WacomStylusDemoApp on an iPad and click on Hand positions for an example of this in the WacomStylusDemoApp files; setHandedness is called in the HandPositionTableViewController.m file.

Hand Positions

Left Upward	Right Upward	Left	Right	Left Down	Right Down

The hand position images are available to you as part of the SDK download in the WacomStylusDemoApp folder.

Use the Kiss-to-Pair method

Use the Kiss-to-Pair method to pair the stylus that is currently touching the surface of the iPad to your app.

Display a notification with a guided tour for first-time users

When the app detects a new stylus, display a pop-up notification that includes a visual guided tour of pairing and using your app for first-time users.

Use the full name of the stylus

Use the full name of stylus products in the UI so that your users will know what stylus products are supported. If space is limited, use the short name Wacom Stylus.

Find out when the stylus unique ID is available

The unique ID for a stylus is the MAC address, and the MAC address is not immediately available when the stylus is paired. Use - (WacomStylusEventType) getType; to return eStylusEventType_MACAddressAvaiable = 4 to find out if a MAC address is available yet or not.

Use TrackedTouch for improved accuracy

It is best practice to use TrackedTouch instead of UITouch for apps that include drawing on the screen.

• TrackedTouch uses currentLocation and previousLocation coordinates, which have been modified to improve stylus accuracy.
  • This includes improvements around stair casing, tilt and angle offset, dropped touches, and points near the edges.
  • It also helps to support touch rejection.
• UITouch uses currentTouchLocation and previousTouchLocation coordinates, which have not been modified to improve stylus accuracy.

Use coalesced touches to improve stylus accuracy

Coalesced tracked touches augment touch information with intermediate touches to "fill in" strokes and improve stylus accuracy. Coalesced touches are also UITouches, and coalesced tracked touches are also TrackedTouches.

You can see an example of how to use coalesced tracked touch in the WacomStylusDemoApp in the drawingView.m file. Look for the plotCoalescedTrackedLines method.

Enable touch rejection to automatically remove palm touches

You can enable touch rejection so that the SDK figures out if touch information is coming from a palm or from a stylus touching the surface of the iPad. The touch rejection in the SDK then removes the palm touches, only returning the stylus touches.

If you do not enable touch rejection, all touches on the surface of the iPad are returned, including touches from a palm or fingers.

Adjust the RSSI settings to make pairing easier

To adjust which iPads are detected during pairing, you can increase or decrease the value of the Received Signal Strength Indicator (RSSI) using [[WacomManager getManager] setMinimumSignalStrength:(int)value].

The default is -85, and the range is 0 to -100. If you set the value to -100, all stylus products that are closer than approximately 28 inches (71 centimeters) from your iPad are detected.

Test Plan for your App

Pairing test

• Pair a stylus with your app.
• Verify that the application is reporting the pairing.
• Verify that the stylus remains paired while you perform the following:
  • Put the tablet to sleep.
  • Minimize your app.
  • Switch between apps.

Stylus pressure test

Draw lines using a variety of pressures. The harder you press with the stylus, the thicker your lines should be and the denser the color should be.

Stylus battery level test

If you included an indicator in your app that displays the battery level, verify that the more you use the stylus, the lower the battery level in the indicator.

Button function test

If you programmed the stylus button or buttons to perform a specific function when pressed while using your app, make sure they perform that function when they are pressed.

Important: Perform the tests listed below using all six hand positions and all four iPad orientations.

iPad orientations

Drawing test

Draw the following quickly and then again slowly to verify that the drawings show minimal distortion:

• Straight, diagonal lines drawn at approximately 30, 45, and 60 degree angles
• Small circles and big circles
• Horizontal lines
• Vertical lines

Stylus offset test

Draw a dot in your app, and then attempt to touch the same spot again with the stylus. Verify that the offset is minimal.

Touch rejection test

If your app includes touch rejection, write the following items out in print form (not cursive):

• The quick brown fox jumps over the lazy dog
  • The sentence has approximately 43 strokes.
• The numbers 1 to 30 with five numbers on each line, for a total of six lines
  • The numbers have approximately 67 strokes.

Then, count the number of visible strokes in each item and compare it to the number of strokes specified above. Perform this test at least three times.

Wacom Stylus iOS demo app

Download the Wacom Stylus Demo App sample code to view an example of working code using the Bluetooth Stylus Framework. To build and run the Demo app:

1. After unzipping the WacomStylusDemo, open the WacomStylusDemoApp folder.

2. Build the demo app.

3. Open the demo app on your iPad.

4. Hold your stylus slightly above the iPad and press the stylus button.

   • A window opens displaying the name of your stylus. When your stylus has paired to your iPad, you see a checkmark next to the stylus name in that window.
   • Tap Done.

5. With your stylus, tap Hand Position and select the option that most closely matches how you hold your stylus.

6. Tap if you want to turn touch rejection on. Tap it again to turn it off.

7. Using your stylus, start drawing in the blank space in the demo app to see how using the Wacom Stylus iOS SDK can be applied in your app.

8. Tap Clear to clear the page. (Rotating your iPad also clears the page.)

Download the Bluetooth Stylus SDK for iOS

1. Go to the Wacom for Developers Downloads page.

   Note: To access the Downloads page, you will need to login with or create your Wacom ID.

2. At the top of the Downloads page, select Wacom Device Kit.

3. At the bottom of the Wacom Device Kit page, click Download Bluetooth Stylus SDK for iOS.

Also See

Overview

Reference

FAQs