Quick Start

Prerequisites

To develop applications that use the SensorCore SDK, you will need Visual Studio 2013 with Windows Phone 8.1 SDK installed.

The SDK supports the emulator by using the simulator classes, but with greatly reduced functionality. In practice, you will also need a developer unlocked device that supports the SensorCore SDK.

Lumia devices previous to Windows Phone 8.1 and Cyan SW update do not support SensorCore.

Getting started

For our first project, we will be creating a simple application that displays the current Step Counter values.

Create a new project

Start by opening Visual Studio and creating a new Visual C# Windows Phone 8.1 project.

1. Select File > New > Project...
2. Select Installed > Templates > Visual C# > Store Apps > Windows Phone Apps > Blank App (Windows Phone) and name the project "HelloSensorCore"

Add SensorCore SDK to the project

In the next step, add the SensorCore SDK to the project. The packages are in the NuGet format.

Now, we can add the actual NuGet package to the project.

1. Select Tools > NuGet Package Manager > Manage NuGet Packages for Solution...
2. Locate Lumia SensorCore SDK and click Install.
3. When prompted to select projects, make sure that our project is checked and click OK.
4. Read the license terms and click OK.
5. You can now close the package manager window.
6. If prompted to reload project files, click Reload All.

About to install SensorCore SDK to our project

Installing the SDK adds Lumia.Sense and Microsoft Visual C++ 2013 Runtime Package for Windows Phone references to the project.

In order for an application to access the APIs, it needs to declare the SensorCore HID device and Location capability in its manifest. Installing the SDK automatically adds capabilities to Package.appxmanifest:

<DeviceCapability Name="location" />
<m2:DeviceCapability Name="humaninterfacedevice">
    <m2:Device Id="vidpid:0421 0716">
      <m2:Function Type="usage:ffaa 0001" />
      <m2:Function Type="usage:ffee 0001" />
      <m2:Function Type="usage:ffee 0002" />
      <m2:Function Type="usage:ffee 0003" />
      <m2:Function Type="usage:ffee 0004" />
    </m2:Device>
</m2:DeviceCapability>

Using the SensorCore SDK in code

In this example code, we will show how to implement a simple application that shows walking and running steps as well as time used to collect these steps.

First, we will define a UI element to display our information on the screen. Open MainPage.xaml and inside the element add a ListBox:

<Grid>
    <ListBox x:Name="SensorcoreList"/>
</Grid>

Now, we are ready for some coding! Add the following " using" statement to MainPage.xaml.cs to enable the SensorCore SDK:

using Windows.UI.Popups;
using Lumia.Sense;

Add the following member variable to the MainPage class:

private StepCounter _stepCounter;

Check whether the device supports SensorCore functionality using the following code:

if (!(await StepCounter.IsSupportedAsync()))
{
    MessageDialog dlg = new MessageDialog("Unfortunately this device does 
                                           not support SensorCore features");
    await dlg.ShowAsync();
    Application.Current.Exit();
}

Please note that many people will have either Location services or motion data collection disabled by default, so we are providing an easy way for the users to enable them without having to find the correct settings. When enabling the motion data setting, a developer must handle two different types of motion data settings. Devices with old motion data settings:

And devices with updated motion data settings:

Motion data settings version can be queried by using the following API.

MotionDataSettings settings = await SenseHelper.GetSettingsAsync(); 
uint settingsVersion = settings.Version;

Version	Motion data settings
1	Motion data settings 1.x
2	Motion data settings 2.x

Note that with Motion data settings 2.0, Steps and Activities data is always available. The following table explains how Steps and activities work with Motion data settings 1.0 and 2.0.

SensorCore Features	Motion data settings 1.0	Motion data settings 2.0
Steps	Location and motion data on	No location and motion data required
Activities	Location and motion data on	Only Bicycle activity requires location on, motion data settings places visited on, and detailed data. Other activities do not require location or motion data enabled. In-vehicle detection is more accurate if these settings are on.
Places	Location and motion data on	Location and places visited on. Detailed data gives more accurate data.
Tracks	Location and motion data on	Location and places visited on. Detailed data gives more detailed and accurate data.

Example code to enable motion data and location settings in both motion data settings 1.0 and 2.0 is included in SimpleActivities . For more information, see the How apps should deal with motion data settings chapter.

Next, we define a helper method that will allow us to call the SensorCore SDK functionality safely, ensuring that the device supports the API and the necessary services are enabled.

private async Task<bool> CallSensorcoreApiAsync( Func<Task> action )
{
    Exception failure = null;

    try
    {
        await action();
    }
    catch( Exception e )
    {
        failure = e;
    }

    if( failure != null )
    {
        MessageDialog dialog;

        switch( SenseHelper.GetSenseError( failure.HResult ) )
        {
            case SenseError.LocationDisabled:
                dialog = new MessageDialog( "Location has been disabled. Do you want to
                    open Location settings now?", "Information" );
                dialog.Commands.Add( new UICommand( "Yes", async cmd => await
                    SenseHelper.LaunchLocationSettingsAsync() ) );
                dialog.Commands.Add( new UICommand( "No" ) );
                await dialog.ShowAsync();
                new System.Threading.ManualResetEvent( false ).WaitOne( 500 );
                return false;

            case SenseError.SenseDisabled:
            {
                var settings = await SenseHelper.GetSettingsAsync();
             
                 if( settings.Version < 2 )
                 {
                     dialog = new MessageDialog( "Motion data has been disabled. Do you
                                 want to open motion data settings now?", "Information" );
                 }
                 else
                 {
                     dialog = new MessageDialog( "Places visited has been disabled. Do you
                                    want to open motion data settings now?", "Information" );
                 }
             
                 dialog.Commands.Add( new UICommand( "Yes", new
                            UICommandInvokedHandler( async ( cmd ) => await
                            SenseHelper.LaunchSenseSettingsAsync() ) ) );
                 
                 dialog.Commands.Add( new UICommand( "No" ) );                 
                 await dialog.ShowAsync();
                 new System.Threading.ManualResetEvent( false ).WaitOne( 500 );
                 return false;
            }

            default:
                dialog = new MessageDialog( "Failure: " + SenseHelper.GetSenseError(
                                  failure.HResult ), "" );
                await dialog.ShowAsync();
                return false;
        }
    }
    
    return true;
}

Next, add code to MainPage constructor to initialize the step counter and handle the activation/deactivation of the sensor according to the visibility of the app.

Window.Current.VisibilityChanged += async ( oo, ee ) =>
{
    if( ee.Visible )
    {
        if( await CallSensorcoreApiAsync( async () =>
        {
            if( _stepCounter == null )
            {
                _stepCounter = await StepCounter.GetDefaultAsync();
            }
            else
            {
                await _stepCounter.ActivateAsync();
            }
        } ) )
        {
          await ShowCurrentReading();
        }
    }
    else
    {
        if( _stepCounter != null ) await CallSensorcoreApiAsync( async () =>
            await _stepCounter.DeactivateAsync() );
    }
};

Next, we are ready to add the code to access the step counter. We get the current reading from the sensor and display it in the list box defined in the first step.

private async Task ShowCurrentReading()
{
    await CallSensorcoreApiAsync( async () =>
    {
        var reading = await _stepCounter.GetCurrentReadingAsync();
        SensorcoreList.Items.Add( "Current step counter reading" );
        
        if( reading != null )
        {
            SensorcoreList.Items.Add( reading.Timestamp.ToString() );
            SensorcoreList.Items.Add( "Walk steps = " + reading.WalkingStepCount );
            SensorcoreList.Items.Add( "Walk time = " + reading.WalkTime.ToString() );
            SensorcoreList.Items.Add( "Run steps = " + reading.RunningStepCount );
            SensorcoreList.Items.Add( "Run time = " + reading.RunTime.ToString() );
        }
        else
        {
            SensorcoreList.Items.Add( "Data not available" );
        }
    } );
}

Deploy your app

Now, make sure that your phone is connected to your PC and Device build target and ARM architecture are selected from the Visual Studio toolbar.

Deploy your application by selecting Build > Deploy HelloSensorCore.

Our application running on device

Congratulations! You have now successfully built your first SensorCore SDK application.

Downloads

Quickstart project

v1.1.0.3

HelloSensorCore.1.1.0.3.zip