Working with Conspicuous Devices (My One Obligatory IoT Article)

IoT! The new, hip word meaning “Internet of Things” – unlike many other trends that come and go, this one is here to stay. Oh, and grow! But enough of the hyped marketing talk; I’m not good at that anyways. What I want to offer to you, developers, in this short blog post, is a small part of Windows 10 offering for IoT related app development, specifically for Bluetooth LE (BLE) beacons.

What is a BLE beacon you ask? It’s a small piece of hardware, typically run by a small battery of which lifetime varies from months to many years. It does but one thing: Transmits a signal with a small payload over and over again (hence the name beacon). Beacons can be attached in many places, both stationary and mobile. Who knows – you could have one in your pants right now!

So, a beacon alone does not do anything useful, but think of what devices receiving the signals can do! Like the whole field of IoT, it’s hard to foresee all the use cases random tech enthusiasts devise with beacons and similar devices. I already worked with one of the visionaries in the field, a company called Sensorberg, and it’s hard not to get excited by their enthusiasm alone.

But, let’s cut to the chase (I promised this would be a short article)!

Windows 10 and its new converged Bluetooth stack

Windows 8.1 did not have enablers for developers to work with beacons, but this unfortunate shortcoming is spectacularly fixed in the spanking new Windows 10. Not only that, but the whole Bluetooth stack is now converged i.e. it’s the same on all devices running Windows 10. However, you should note that some of the features have hardware dependencies, which you have to take into consideration when developing universal apps. The good news is that the same code works everywhere; you just have to catch the possible exceptions in the case of missing hardware support.

The new namespaces for working with beacons are Windows.Devices.Bluetooth.Advertisement and Windows.Devices.Bluetooth.Background. The aforementioned is the one I’ll be focusing in this article. The latter provides the means to work with beacons using a background task.

Implementing a tricorder

What does it take to make your Windows 10 device to scan for beacons. Not much. You simply construct a BLE advertisement watcher instance, give it some filters, start it and wait for beacons to come in range. Then, simply catch the event and do something with the data you received.

DataTricorder“Look Geordi! I received a coupon code!”

In code setting the watcher up and starting it is done like this (based on the snippet taken from the official Microsoft sample):

BluetoothLEAdvertisementWatcher watcher =
    new BluetoothLEAdvertisementWatcher();

var manufacturerData = new BluetoothLEManufacturerData();

// Then, set the company ID for the manufacturer data.
// Here we picked an unused value: 0xFFFE
manufacturerData.CompanyId = 0xFFFE;

// Finally set the data payload within the manufacturer-specific section
// Here, use a 16-bit UUID: 0x1234 -> {0x34, 0x12} (little-endian)
var writer = new DataWriter();
writer.WriteUInt16(0x1234);

// Make sure that the buffer length can fit within an advertisement payload.
// Otherwise you will get an exception.
manufacturerData.Data = writer.DetachBuffer();

// Add the manufacturer data to the advertisement filter on the watcher:
watcher.AdvertisementFilter.Advertisement.ManufacturerData.Add(manufacturerData);

watcher.Start();

To catch the received beacon data you must hook to BluetoothLEAdvertisementWatcher.Received event, where you get the data encapsulated in BluetoothLEAdvertisementReceivedEventArgs. You will find all the data transmitted there as raw byte array and some of the data is provided as properties for convenience. You can check out the format of the beacon data here.

If at this point you are too eager to jump right into code, I don’t mind. You can check out the official Microsoft sample code here or take a look at my awesome sample here.

Your device can be a beacon too

Windows 10 also allows you to make your device function as a beacon (and remember that Windows 10 runs on all kinds of devices including even the smallest ones). This is handy for a number of reasons, probably many use cases exist that I can’t even imagine yet, but of course, the obvious one is testing your app – unlike a standard, physical beacon, the beacon ID, used to identify a certain beacon, can be changed dynamically and you can easily start or stop broadcasting with a push of a button.

For turning your device into beacon there’s a class called BluetoothLEAdvertisementPublisher. The use of it is just as simple as that of the watcher; construct the instance, give it a payload and hit start! Here’s an example (based on the snippet taken from the official Microsoft sample):

// Create and initialize a new publisher instance.
BluetoothLEAdvertisementPublisher publisher =
    new BluetoothLEAdvertisementPublisher();

// We need to add some payload to the advertisement. A publisher without any payload
// or with invalid ones cannot be started. We only need to configure the payload once
// for any publisher.

// Add a manufacturer-specific section:
// First, let create a manufacturer data section
var manufacturerData = new BluetoothLEManufacturerData();

// Then, set the company ID for the manufacturer data. Here we picked an unused value: 0xFFFE
manufacturerData.CompanyId = 0xFFFE;

// Finally set the data payload within the manufacturer-specific section
// Here, use a 16-bit UUID: 0x1234 -> {0x34, 0x12} (little-endian)
var writer = new DataWriter();
UInt16 uuidData = 0x1234;
writer.WriteUInt16(uuidData);

// Make sure that the buffer length can fit within an advertisement payload. Otherwise you will get an exception.
manufacturerData.Data = writer.DetachBuffer();

// Add the manufacturer data to the advertisement publisher:
publisher.Advertisement.ManufacturerData.Add(manufacturerData);

publisher.Start();

Note that the advertising feature is a limited hardware resource, which can be used by multiple apps. So, unless your app is the only one using it on your device, be prepared for having to wait for the resource to be available. Luckily, you can hook to BluetoothLEAdvertisementPublisher.StatusChanged event. One of the statuses is “Waiting”.

 

Please, have my code

Screenshot of BLE Beacon Sample

You can check out my BLE beacon sample, which does both scanning (using the watcher) and advertising (using the publisher). It allows you to enter the desired beacon IDs. I tried to keep the code as simple as I could by adding two utility classes: Beacon and BeaconFactory. The sample is hosted in GitHub here.

Wait, there’s more…

You might have noticed that I did not cover beacon scanning scenario where the application is in the background. That’s because my dear colleague, Juhana Koski, has already covered that in his article, and it also comes with a code sample.

Do also check out this great session on BLE advertisement APIs from the 2015 //build/ conference.

Finally, for a proper developer, which I’m sure you are, code speaks more than… umm… 1000 words which are not code. Thus, check these samples to get a quick dive-in to the world of BLE beacons on Windows 10 universal platform: