S Pen Remote SDK

Overview

S Pen Remote SDK allows you to develop applications that use S Pen Remote generated events. S Pen includes buttons and motion sensor, and events from these units can be delivered to the application via the S Pen Framework. Simple gestures such as Button Click or 4-directional Swipe can be easily recognized via the S Pen Framework. But to implement a more powerful application using the raw data of units, you must use the S Pen Remote SDK.

Supported Platform

The package uses a static Java library that depends on internal Android framework modules. It means that this package only runs on devices that support those modules. Some Samsung Smart Devices do not support S Pen Remote as it requires devices of the Note series.

Supported Features

The S Pen Remote SDK provides functions to identify motion coordinates and verifying if the side button is pressed for your application.

S Pen Remote SDK supports the following detailed features:

  • Checking if the side button is pressed or released.

  • Identifying motion coordinates

    • two-dimensional device movement
    • relative values of the current position from the previous position
    • a positive value for the x-coordinates means to move right
    • a positive value for the y-coordinates means to move up
    • value range : -1.0 ~ 1.0

Components

  • Components

    • spenremote-v1.0.X.jar
    • sdk-v1.0.0.jar

  • Imported package:

    • com.samsung.android.sdk.penremote

Installing the SDK in Android Studio

To install SpenRemote in Android Studio:

a) Add the spenremote-v1.0.X.jar and sdk-v1.0.0.jar files to the libs folder in Android Studio.

b) Add dependencies for the SDK library folder in build.gradle

    dependencies{
        compile fileTree(include: '*.jar', dir: 'libs') 
        … 
    }

Using SpenRemote

SpenRemote is a representative class and provides the following methods:

  • getInstance() gets the object of the SpenRemote. This class is singleton.

  • getVersionCode() gets the S Pen Remote version number as an integer.

  • getVersionName() gets the S Pen Remote version name as a string.

  • isFeatureEnabled(int type) checks if an S Pen Remote feature is available on the device.

  • connect() is used to connect to the S Pen Framework. You need to connect to the S Pen Framework to use S Pen Remote Features.

  • disconnect() is used to disconnect from the S Pen Framework.

The SpenRemote can run only on Samsung smart devices. Some Samsung smart device models do not support some of the features.

Check the Availability of SpenRemote Features

You can check if an SpenRemote feature is supported on the device using the isFeatureEnabled() method. The feature types are defined in the SpenRemote class. The feature type is passed as a parameter when calling the isFeatureEnabled() method. The method returns a boolean value that indicates the support for the feature on the device.

    public boolean isFeatureEnabled(int type)

The following types are defined as constants in the SpenRemote class:

  • FEATURE_TYPE_BUTTON

  • FEATURE_TYPE_AIR_MOTION

Connecting to the S Pen Framework

Connect to the S Pen Framework to access the supported features in SpenRemote. To connect to The S Pen Framework, create a ConnectResultCallback and call the connect() method. If connection is already established, connect() method will not respond. Therefore, check the connection state with isConnected() method before attempting to connect.

    SpenUnitManager mSpenUnitManager = null;
    ...
                    
    SpenRemote spenRemote = SpenRemote.getInstance();
                    
    if (!spenRemote.isConnected()) {
        spenRemote.connect(getContext(), 
            new SpenRemote.ConnectionResultCallback() {
            @Override
            public void onSuccess(SpenUnitManager manager) {
                mSpenUnitManager = manager;
                ...
            }
                    
            @Override
            public void onFailure(int error) {
                    
            }
        });
    }

If the connection is successful, ConnectResultCallback.onSucces() is called and a SpenUnitManager instance is passed. SpenUnitManager provides a method to set the Event Listener to monitor the events of embedded units in the S Pen.

If the connection fails, an error code is passed to ConnectResultCallback.onFailure(). The error codes that can be passed are as follows:

  • UNSUPPORTED_DEVICE: The device is not a Samsung device or S Pen Remote is not supported.

  • CONNECTION_FAILED: The S Pen Framework refuses the connection.

  • UNKNOWN: Unknown error.

Disconnecting

If your application is stopped or is no longer able to handle the S Pen Event, call disconnect() to terminate an established connection.

SpenRemote spenRemote = SpenRemote.getInstance();
spenRemote.disconnect(getContext());

Using SpenUnitManager

The SpenUnitManager provides a method to set the Event Listener to monitor the events of embedded units in the S Pen.

Related Classes and Interfaces

SpenUnit

This class manages instances of specific S Pen embedded unit.

SpenEvent

S Pen Framework will send this class to your application with S Pen event information.

SpenEventListener

You can use this interface to create a Callback method that can receive SpenEvent when an event occurs on an S Pen embedded unit.

Monitoring S Pen Events

To monitor S Pen events the following procedure is required

  1. Get instance of SpenUnitManager

    As introduced previously, the instance of SpenUnitManager can be obtained when a connection to the S Pen Framework is successful.

  2. Request an instance of the embedded unit (SpenUnit) you want to monitor

    To obtain instance of specific embedded unit, use getUnit method.

    The getUnit method accepts a constant, TYPE_BUTTON or TYPE_AIR_MOTION, defined in the SpenUnit class as constants. If you try to obtain instance of unsupported unit in the device, it returns null.

        // get Instance of Button Unit
    SpenUnit button = mSpenUnitManager.getUnit(SpenUnit.TYPE_BUTTON);
            
    // get Instance of AirMotion Unit
    SpenUnit airMotion = mSpenUnitManager.getUnit(SpenUnit.TYPE_AIR_MOTION);

  3. Register Event Listener

    Register Event Listener to SpenUnit using registerSpenEventListener method of SPenUnitManager instance.

    The data of SpenEvent passed to the SpenEventListener is hidden. You can refer to the data by casting it as a ButtonEvent or AirMotionEvent class, depending on the device you are monitoring.

    Button Event :

        SpenUnit button = mSpenUnitManager.getUnit(SpenUnit.TYPE_BUTTON);
    mSpenUnitManager.registerSpenEventListener(mButtonEventListener, button);
    ...
    //EventListener for Button Unit
    private SpenEventListener mButtonEventListener = new SpenEventListener() {
        @Override
        public void onEventChanged(SpenEvent ev) {
            ButtonEvent buttonEvent = new ButtonEvent(ev)
            
            switch (buttonEvent.getAction()) {
                case ButtonEvent.ACTION_DOWN:
                    Log.d(TAG, "Spen Button Pressed");
                    break;
                case ButtonEvent.ACTION_UP:
                    Log.d(TAG, "Spen Button Released");
                    break;
            }
        }
    };

    AirMotion Event:

        SpenUnit airMotion = mSpenUnitManager.getUnit(SpenUnit.TYPE_AIR_MOTION);
    mSpenUnitManager.registerSpenEventListener(mAirMotionEventListener, airMotion);
    ...
    //EventListener for AirMotion Unit
    private SpenEventListener mAirMotionEventListener = new SpenEventListener() {
        @Override
        public void onEventChanged(SpenEvent ev) {
            AirMotionEvent airMotionEvent = new AirMotionEvent(ev)
                        
            float deltaX = airMotion.getDeltaX();
            float deltaY = airMotion.getDeltaY();
                
            Log.d(TAG, "Air Motion = " + deltaX + ", " + deltaY);
        }
    };

  4. Unregister Event Listener

    Unregister Event Listener using unregisterSpenEventListener method of the SPenUnitManager instance, if your application is terminated or is no longer processing S Pen events. In particular, AirMotion consumes a large amount of S Pen battery power, so you should unregister the Event Listener when not handling Air Motion events.

        SpenUnit airMotion = mSpenUnitManager.getUnit(SpenUnit.TYPE_AIR_MOTION);
    mSpenUnitManager.unregisterSpenEventListener(airMotion);