iOS Scriba WIKI

Scriba

Scriba is a radical new stylus design for mobile devices that provides an enhanced user experience and greater level of control than most existing stylus products on the market.

iOS

The Scriba iOS SDK supports iOS 8.0 and newer.

Integration

• The Scriba SDK framework [ScribaSDK] is used to connect your application to the Scriba device. This framework enables features including: Scriba detection and pairing, click detection, pressure measurement, battery level, haptic feedback.

Test App

We have also created a test app that illustrates how the various methods described below can be integrated.

https://bitbucket.org/dublindesignstudio/scriba-sdk-test-app-ios.git

Importing the Framework to your own project

1. Download the latest version of the SDK from Bitbucket or clone the repository directly by executing

https://bitbucket.org/dublindesignstudio/scriba-public-framework.git

from the command line.

2. Open your project in the current version of Xcode

3. Also open the Scriba SDK Framework folder, select the SDKs, drag and drop to Embedded Binaries

4. Make sure ‘Copy Items if Needed’ is checked. Then click ‘Add’.

5. The SDK should now appear in the list of ‘Linked Frameworks and Libraries’ and ‘Embedded Binaries’.

6. Be sure to include the SDK’s header files within your application:

import <ScribaSDK/ScribaSDK.h>

Scriba SDK features:

Scanning the Scriba devices

In order to integrate the Scriba SDK feature set, the developer will need to implement the delegate method of ScribaStylusManagerDelegate in the class, by calling the two line codes below:

[ScribaStylusManager sharedManager].delegate = self;

[[ScribaStylusManager sharedManager] startScanning];

The callback method will be called if there is a scriba device discovered:

/*!

 * @discussion Callback method when scriba devices are found

 * @param devices A list of scriba devices are returned.

 */

-(void)didFoundDevices:(NSArray*)devices;

### Connection State

There are two connection states:

typedef NS_ENUM(NSUInteger,ScribaDeviceState)

{

    ScribaDeviceStateDisconnected,

    ScribaDeviceStateConnected

};

Check the state of connection in ScribaStylusDevice class.

Connection notification callbacks

In order to get notified when connecting and disconnecting the Scriba device, the user has to add two optional methods in ScribaStylusManagerDelegate.

The method below will be triggered when connecting to the Scriba device.

/*!
 * @discussion Callback method when scriba device is connected.
 * @param device The scriba device triggers the event
 * @param The CBCentralManager object
 */
-(void)didConnectedDevice:(ScribaStylusDevice*)device manager:(CBCentralManager*)manager;

The method below will be triggered when disconnecting to the Scriba device.

/*!
 * @discussion Callback method when scriba device is disconnected.
 * @param device The scriba device triggers the event
 */
-(void)didDisconnectDevice:(ScribaStylusDevice*)device;

Connection notification UI alert

To show the alert of connecting or disconnecting a scriba device, simply set 'alertUserWhenScribaConnectionChanged' to be YES. By default, the value is NO.

[ScribaStylusManager sharedManager].alertUserWhenScribaConnectionChanged = YES;

Battery Level

To obtain the current battery level, simply use the currentDeviceBatteryState property in the ScribaStylusManager.

This callback method returns a value for the status of the battery charge between 0.0 and 1.0, whereby 1.0 is fully charged and 0.0 is fully discharged.

-(void)didUpdatedBatteryStateForDevice:(ScribaStylusDevice*)device batteryState:(float)batteryState;

Pressure

Scriba measures the applied pressure and this value can be used to determine factors such as line weight or other functionality. The depression value is generated and passes through the callback method, ranging in values from 0.0 to 1.0.

-(void)didChangedDepressionForDevice:(ScribaStylusDevice*)device depression:(float)depression;

Clicks

The Scriba device can generate three click events.

-(void)didSingleClickWithDevice:(ScribaStylusDevice*)device;

-(void)didDoubleClickWithDevice:(ScribaStylusDevice*)device;

-(void)didTrippleClickWithDevice:(ScribaStylusDevice*)device;

Haptics

Haptic feedback provides a discreet and intuitive method of user notification. Scriba is the first stylus to feature this type of feedback and can be configured as an extension of the app UI.

The Scriba framework allows for an instruction to be sent to Scriba over the active BLE connection, causing a short vibration under the user’s fingertips.

One application of this feature, when paired with Smart-Lock, is to physically notify the user that the locking mechanism has been activated.

Taking advantage of the wide range of movement in Scriba, haptic feedback can be configured to vibrate at certain fixed values across this range of movement. In combination with the Squeeze Zone Callback method haptic feedback can be configured to notify the user that they have changed zones, aiding user navigation.

We will expand on the capabilities of this functionality in the future, however at this stage we have included 3 default vibration patterns. For clarity we have called these buzzes.

####1. One buzz [[NSNotificationCenter defaultCenter] postNotificationName:BuzzNotification object:[NSNumber numberWithInteger:1]];

Or

[[NSNotificationCenter defaultCenter] postNotificationName:BuzzNotification object:nil];

####2. Double buzz with interval of 0.2 second [[NSNotificationCenter defaultCenter] postNotificationName:BuzzNotification object:[NSNumber numberWithInteger:2]];

####3. Triple buzz with interval of 0.2 second in between [[NSNotificationCenter defaultCenter] postNotificationName:BuzzNotification object:[NSNumber numberWithInteger:3]];

Note: that any number smaller than 1 or larger than 3 is considered to be one buzz.

Smart Lock

Users will not always require continuous line-weight adjustment. Thus, Scriba features the ability to lock at a particular line-weight. We have called this ‘Smart-Lock’ and this is a feature that can be activated through the Scriba framework.

• Scriba detects when the applied pressure has been held at a constant level for one second or more and automatically locks the line-weight at that pressure. This line-weight is then maintained until the user deactivates Smart Lock.

• Smart Lock is notified through the framework, allowing for on-screen notification and this may also be configured to be accompanied with a haptic response.

• When the Smart Lock is active the user can continually vary the applied pressure up to but not including a full depress and this will not affect the ‘locked’ line-weight.

• Smart lock is deactivated with a full depress and normal pressure mapping returns.

• In alternative configurations, a button may be provided as part of the app UI to allow the user to turn the lock on or off.

• It should be noted that Smart-Lock does not activate at the minimum or maximum line-weights unless manually activated. Brush sizes can be locked at values within, but not equal to the range defined by maximum (1.0) and minimum (0.0).

To check if the smart lock is enabled or disabled:

-(BOOL)isSmartLockEnabled;

To enable the smart lock or disable the smart lock.

-(void)enableSmartLock:(BOOL)enableSmartLock;

To check if the smart lock is activated:

- (BOOL)isSmartLockOn;

Manually disable the smart lock when active:

- (void)removeSmartLock;

Manually set the brush line thickness when the smart lock is active.

-(void)setBrushSizeInLockedMode:(float)brushSize;

Squeeze Zones

To take advantage of the large range of movement of Scriba, we have introduced a feature that sub-divides this range into a number of discrete pressure ranges. We have described these as "Squeeze Zones" and they are included in the Scriba framework.

As an extension of the app UI, these Zones can be used to quickly cycle between commonly used tools or functionality. The selected tool is then activated in combination with a touch event.

The framework includes 5 such zones:

• Zone 0 - This is the default resting value of Scriba without applied pressure. This zone also allows a degree of tolerance for accidental squeezes.

• Zone 1 - A light pressure, this ‘third’ corresponds to depression values of 0.1 to 0.37

• Zone 2 - Medium applied pressure, mid zone, corresponds to depression values of 0.37 to 0.63

• Zone 3 - Heavier pressure, this ‘third’ corresponds to depression values of 0.63 to 1

• Zone 4 - Full depress. This zone also allows a degree of tolerance for incomplete full squeezes.

To detect the squeeze zone changing, the developer must implement the method below, also call enableHapticsBuzz method to YES:

/*!

 * @discussion Callback method when squeeze zone is changed

 * @param device The scriba device triggers the event

 * @param squeezeZone The squeeze zone level (0,1,2,3,4) is returned in integer.

 */

-(void)didChangedSqueezeZoneForDevice:(ScribaStylusDevice*)device squeezeZone:(NSInteger)squeezeZone;

Bluetooth Detection

There are two ways to detect the bluetooth status either ‘on’ or ‘off’.

1. The property ‘isBlueToothEnabled’ which returns the current bluetooth status, and the integrator may find the incorrect status returned in case the app is switched back after toggling bluetooth icon on/off quickly, then the integrator should consider the delegate method.

/*!
 * @brief Check bluetooth state
 */
@property (nonatomic, readonly) BOOL isBlueToothEnabled;

2. The delegate method is called whenever the Bluetooth status is changed.

@protocol ScribaStylusBluetoothDelegate <NSObject>

@optional

-(void)bluetoothStatusChanged:(WDBlueToothState)state;

@end

Test App

We have also created a test app that illustrates how the various methods described below can be integrated.

https://bitbucket.org/dublindesignstudio/scriba-sdk-test-app-ios.git

ScribaDrawingSDK

Adding simple drawing overlays to your apps

Scriba is about more than just drawing and painting, however it may be useful to overlay a drawing canvas to your own app. With the ScribaDrawingSDK, a framework written in Swift 4.2 we have included a number of methods to enable simple drawing or markup capabilities. We have also included the functionality (demonstrated in the Scriba Slides app) that detects when closed shapes have been drawn by the user and automatically dimming the background.

/**
Add a drawing view to the parent view.
 - parameter superView: The view that drawing view being added to
**/
@objc public func addDrawingView(to superView: UIView)

/**
Remove the drawing view from parent view.
 **/
@objc public func removeDrawingView()

/**
Clear all drawings on the drawing view.
**/
@objc public func clearDrawings()

/**
Change the line color to red.
**/
@objc public func changeToRedLine()

/**
Change the line color to yellow.
**/
@objc public func changeToYellowLine()

/**
Change the line color to blue.
**/
@objc public func changeToBlueLine()

Scriba DFU SDK features:

The Scriba DFU SDK framework for iOS 8+ adds Dynamic Firmware Update (DFU) features to the iOS project. It is written in Objective-C, however encapsulates some proprietary code written in Swift 2.1. The Scriba framework integrator can take advantage of this to update the firmware of Scriba device.

Usage:

Enable the ScribaUpdateManager class to initialise the DFU process.

//check firmware version here    

[[ScribaUpdateManagersharedManager]

updateWithCenterManager:manager peripheral:peripheral version:version];

Also there are set/get methods to the update.

- (void)setUpdateAllowed:(BOOL)enabled;

- (BOOL)isUpdateAllowed;

Example

Check out the source code how the Scriba SDK Tester app works at below (Objective-C):

https://leizhang_bitbucket@bitbucket.org/dublindesignstudio/scriba-sdk-test-app-ios.git

Submitting to the App Store

To facilitate development on both iOS devices and emulation within the IDE, the Scriba framework also includes emulator slices for x86_64 and i386. The slices that are not required for the iOS devices will have to be removed before the app is submitted to App Store. The Apple App store will reject any app which contains a framework that has the slices [x86_64,i386] and will return the error below:

[Transporter Error Output]: ERROR ITMS-90087: "Unsupported Architectures. The executable for yourapp.app/Frameworks/ScribaSDK.framework contains unsupported architectures '[x86_64, i386]'."

To cope with this issue, add a Run Script step to your build steps, put it after your step to embed frameworks, set it to use /bin/sh and enter the following script:

APP_PATH="${TARGET_BUILD_DIR}/${WRAPPER_NAME}"

# This script loops through the frameworks embedded in the application and

# removes unused architectures.

find "$APP_PATH" -name '*.framework' -type d | while read -r FRAMEWORK

do

FRAMEWORK_EXECUTABLE_NAME=$(defaults read "$FRAMEWORK/Info.plist" CFBundleExecutable)

FRAMEWORK_EXECUTABLE_PATH="$FRAMEWORK/$FRAMEWORK_EXECUTABLE_NAME"

echo "Executable is $FRAMEWORK_EXECUTABLE_PATH"

EXTRACTED_ARCHS=()

for ARCH in $ARCHS

do

echo "Extracting $ARCH from $FRAMEWORK_EXECUTABLE_NAME"

lipo -extract "$ARCH" "$FRAMEWORK_EXECUTABLE_PATH" -o "$FRAMEWORK_EXECUTABLE_PATH-$ARCH"

EXTRACTED_ARCHS+=("$FRAMEWORK_EXECUTABLE_PATH-$ARCH")

done

echo "Merging extracted architectures: ${ARCHS}"

lipo -o "$FRAMEWORK_EXECUTABLE_PATH-merged" -create "${EXTRACTED_ARCHS[@]}"

rm "${EXTRACTED_ARCHS[@]}"

echo "Replacing original executable with thinned version"

rm "$FRAMEWORK_EXECUTABLE_PATH"

mv "$FRAMEWORK_EXECUTABLE_PATH-merged" "$FRAMEWORK_EXECUTABLE_PATH"

done

Reporting Bugs

If you’ve uncovered a bug or have any feedback please let us know by sending an email to developers@getscriba.com

Get Involved

We're always looking for talented developers to join our team. Email us at developers@dublindesignstudio.com if you're interested in contributing to, or joining our team.