Getting Started with Microsoft Band SDK

On October 2014, Microsoft released the “Microsoft Band” — a smartwatch/fitness band. The reception to it surprised even Microsoft who, after preparing a limited amount of devices, found that the demand far exceeded supply. Not long after, they released the Band SDK, allowing developers to target the Band and provide applications to accompany the Band or extend its experience. A year after its initial release, the Band 2 was released improving several aspects of the device and brandishing a new sleeker, curved design.

Microsoft Band 2

The Microsoft Band 2 (Image Credit: Microsoft)

The Band is filled with sensors that focus on usage in fitness and sporting activities — but it can also be used as a sleep tracker and a smartwatch that displays notifications from a paired phone and/or from social networks such as Facebook and Twitter.

Band SDK Features

Before we dive into the features of the SDK, it is vital to understand that any user/SDK code will not be running on the Band itself (it is similar to the model used by the Apple Watch) but on a device paired with the Band.

The device can run any platform supported by the Band SDK — iOS, Android and Windows (including both Windows 10 and Windows 8.1 applications).

However, when you harness the SDK it will provide you with rich functionality including accessing its sensor data, providing custom UI shown on the Band (known as “tiles” and “tiles content”), and sending notifications to the Band.

The features offered by the Microsoft Band SDK are as follows:

  • Multi-platform support
  • Sensor data subscriptions
  • Tile creation and management
  • Tile notifications
  • Custom layouts
  • Haptic notifications
  • Band theme personalization

Band Sensors

As we mentioned earlier, the Band is packed with sensors. Here is the complete sensor list provided by either the Band/Band 2:

  • Accelerometer — Measures accelerations on the X, Y, Z axes.
  • Gyroscope — Measures angular velocity.
  • <li Distance — Measures distance in centimetres, and also provide current speed.

  • Heart Rate — Measures the wearer’s beats per minute.
  • Pedometer — Measures steps since the Band last factory reset.
  • Skin Temperature — Measures the skin temperature of the wearer in degrees Celsius.
  • UV — Measures the current ultraviolet radiation exposure intensity.
  • Calories — Measures the total number of calories the wearer has burned.
  • Galvanic Skin Response* — Provides the wearer’s skin resistance.
  • RR Interval* — Provides the interval between the last two continuous heart beats.
  • Ambient Light* — Provides the current room light intensity.
  • Barometer* — Provides the current raw air pressure.
  • Altimeter* — Provides the current elevation.

* Microsoft Band 2 only.

More information can be found on the Microsoft Band Sensors page.

In this article, we will look at how we can read sensor data using all three major platforms — iOS, Android and Windows. First, we need to setup our applications to use the SDK.

Download the SDK relevant to the platform of choice at the Microsoft Band platform page. If you aim to create a UWP (Universal Windows Platform) application, you may use Nuget to download and install the SDK into our application via the Microsoft Band nuget package.

Let’s start with iOS.

iOS – Setting up the Band SDK Environment

Currently, the Band SDK is supported on iOS 7 and above. Support for the iOS Simulator is not available, so we will need to test out our application on a real device paired with the Band.

If we would like our application to keep communication with the Band while it is on in the background, we need to enable “Use Bluetooth LE accessories” in background mode. For the sake of this tutorial, it won’t be necessary.

  • Launch Xcode (version 6.0 and above) and create a new single page iPhone application. This article will be using Objective-C, but it is fairly simple to translate the example code into Swift.
  • First things first, we need to add the Band SDK into our project. In the project navigator, right click on our project name and select “Add Files…”.
  • Locate and select the MicrosoftBandKit framework file (from where you’ve downloaded and extracted the SDK file) and select the option to “Copy items if needed”.
  • Select “Build Phases” under the project target. And add CoreBluetooth.framework under “Linking Binary with Libraries”.

Now, we are ready to start coding.

iOS — Connecting to a Band Device

Navigate to the ViewController.m file. Add an import statement in order to have access to the Micorsoft Band SDK.

#import <MicrosoftBandKit_iOS/MicrosoftBandKit_iOS.h>

Let us add a delegate to the ViewController definition. Via this delegate, we will get callbacks when we manage to successfully connect or disconnect from the device.

Add the following callbacks inside the implementation section of the ViewController:

@interface ViewController () <MSBClientManagerDelegate>
....
@implementation ViewController

-(void)clientManager:(MSBClientManager *)cm
  clientDidConnect:(MSBClient *)client {
  // handle connected event
}
-(void)clientManager:(MSBClientManager *)cm
clientDidDisconnect:(MSBClient *)client {
  // handle disconnected event
}
-(void)clientManager:(MSBClientManager *)cm client:(MSBClient *)client
didFailToConnectWithError:(NSError *)error {
  // handle failure event
}  

Later on, we will try to connect with a Band device, we will store this instance in a property so we will be able to access it from various methods.

@interface ViewController () <MSBClientManagerDelegate>
@property (nonatomic, weak) MSBClient *client;
@end

This tutorial assumes that you, the reader, is fluent enough with iOS development and creating a simple UI with buttons and labels is well within your grasp. To keep this tutorial as simple as possible, we will not get into details on how to create the user interface and hook it up with instances and actions on the ViewController side. Now add a button and hook it to an action named init.

MSBClientManager is a singleton which will provide us access to the SDK functionality. Later on, we will use an instance of a device client to access sensors, tiles and the rest of the SDK features. In this method, we will try to gain that instance.

As promised, we are setting up our ViewController for notifications via the delegate when calling setDelegate.

Then we are accessing the attachedClients collection. This will provide us with a list of all Band devices paired with the device running this app. (Yes, there can be multiple Bands connected to a single device!). Your code can have heuristics/UI to decide which Band to connect to, in this tutorial we will just grab the first one.

Lastly, we are initiating a call to try and connect to this device by calling connectClient and passing the Band’s client instance.

- (IBAction)init:(id)sender {
  [[MSBClientManager sharedManager] setDelegate:self];
  NSArray *attachedClients = [[MSBClientManager sharedManager]
                              attachedClients];
  self.client = [attachedClients firstObject];
  if (self.client) {
      [[MSBClientManager sharedManager] connectClient:self.client];
  }
}

iOS – Accessing a Sensor

Assuming all went well, and we’ve managed to connect to a Band, we can now proceed to gain access to a sensor’s data feed. However, some sensors require explicit user consent. Currently, only the heart rate and RR Interval sensors require consent, but this could be changed without warning. It is best practice to check for consent whenever you require access to a sensor.

Once again, I assume you have another button in your View to be able to call the following method.

First, we are checking whether we have user consent for the sensor in question. As we have mentioned above, since that in this specific example, we are asking for access to the Heart Rate sensor, we will most likely receive MSBUserConsentNotSpecified. We will need to call requestHRUserConsentWithCompletion. A dialog will popup out on the device where the user will be able to approve our app’s access to their heart rate.

Heart rate consent on iOS

The consent dialog on iOS

Consecutive call to this method should now give us a MSBUserConsentGranted or MSBUserConsentDeclined. For the sake of this tutorial, let’s assume that the optimistic scenario has happened and the user has agreed. We can now call the method startHeartRateUpdates which we will describe soon.

- (IBAction)getSensor:(id)sender {
  MSBUserConsent consent = [self.client.sensorManager
                            heartRateUserConsent];
  switch (consent) {
    case MSBUserConsentGranted:
      // user has granted access
      [self startHeartRateUpdates];
      break;
    case MSBUserConsentNotSpecified:
      // request user consent
      [self.client.sensorManager
          requestHRUserConsentWithCompletion:
               ^(BOOL userConsent, NSError *error) {
          if (userConsent) {
              // user granted access
          }
          else {
              // user declined access
          }
      }];
      break;
    case MSBUserConsentDeclined:
      // user has declined access
      break;
    default:
      break;
  }
}

Continue reading %Getting Started with Microsoft Band SDK%


Source: Sitepoint