Introduction

This article arose out of a real-life project I (@jcmrim) had been working on which involved connecting medical devices to BlackBerry 10 handsets using Bluetooth Serial Port Profile (SPP). What made it particularly interesting is that the BlackBerry 10 application was a WebWorks / Cordova application.

I’ve written quite extensively about using Bluetooth from both Cascades and Headless applications, but had never had to interface to Bluetooth from WebWorks. The approach I took was to write a WebWorks Plugin in native code that exposed a suitable JavaScript API to the WebWorks application itself.

This model was very successful, so obviously I wanted to share this with the developer community. However, the plugin itself was matched closely to the medical devices it needed to communicate with, and it was unlikely that the ordinary developer would have access to a blood pressure and oximeter monitoring device. So I crafted a simpler version of the plugin that was device-agnostic, that would simply send and receive data over an SPP connection.

Using this as a base, and inspired by an existing Cascades application on GitHub, I wrote a simple WebWorks “chat” application that used the plugin to communicate, using Bluetooth SPP, between two BlackBerry 10 devices to demonstrate the basic architecture and model of the application and plugin. If you have another Bluetooth use-case, it should be easy to follow this pattern to develop your application.

Before delving into the plugin itself, let’s just look at how the “chat” application behaves.

The “Chat” Application and How It Behaves

I recorded a short video that demonstrates the main elements of this simple application:

Listening for an inbound Bluetooth connection

Scanning for nearby devices

Connecting to a selected Bluetooth device

Bi-directional exchange of simple messages

Disconnection of the two devices

OK, I’m not by any means an expert at designing user interfaces, particularly HTML5 ones, so forgive me if it seems a little Spartan. It is, however, completely functional.

Let me just summarize what you’ve just seen: Two BlackBerry 10 devices running a simple WebWorks application are able to establish a Bluetooth SPP connection between themselves and exchange simple messages over this connection. It’s Bluetooth “chat.”

A key point to note is that all of the operations – connection, two-way messaging, disconnection – take place asynchronously. This requirement influenced the way the Bluetooth SPP JavaScript API was designed.

Let’s look at that next and work our way down from the application, through the javascript API and into the plugin itself.

The Bluetooth SPP JavaScript API

Both the sample “chat” application and the plugin are available as a project on GitHub here:

I’m not going to go through the details of each element of the JavaScript API since it’s been documented in the link above, and you can read all the details there. Rather, I just want to point out one or two features of how it works and how it was designed.

There are three types of elements in the API:

Properties

Synchronous functions

Asynchronous functions

Properties

I use these to set and get values that should be persisted in the plugin. The best example of this is the Bluetooth Address of the device to which to connect. You’d use it like this:

Synchronous Functions

I use this form when some operation, such as sending a message, needs to be performed. I’ll know whether this has been successful by the returned value from the call.

So, the returned value from “sendMessage” would be one of these:

The first thing I want to note is that all return values are of this general pattern: JSON format with common interpretation of attributes such as “status” and “desc”! I’ve chosen to use JSON preferentially since it’s easy to parse both in WebWorks and the plugin itself using the “Json::FastWriter” class and its relatives.

Asynchronous Functions

I use this type of function when some operation needs to be initiated. I’ll be able to tell whether the operation has been successfully started by the return value from the call to the function; and, as the operation itself is completed, I’ll receive information back from the plugin using a callback. A good example of this pattern would be the call “listenForConnection()” that starts the plugin listening for inbound connection events. I’d use it something like this:

I can test the variable “foo” to check that the listen request has been initiated correctly and then when an inbound connection is detected by the plugin, the callback “inboundConnectionCallback()” is called by the plugin. The data that is passed back as an argument to the callback function might look something like this:

I can check this and figure out that I’m now connected to a device at the address: “34:BB:1F:3E:77:BC”. Also notice that I supply a description field “desc” in all status messages that you can use in any error messages you need to provide.

There’s just one other point I’d like to note before moving on, and that’s got to do with what actual data the “chat” application will pass to the plugin when it issues a “sendMessage()” request to send data to the other device.

I took the view that I wanted to be able to send arbitrary byte streams across the underlying SPP connection to the peer device and conversely receive arbitrary byte streams. The reason might be that I’d want to use this API to communicate with a device that “speaks” a protocol that is byte-oriented rather than character-oriented. Most medical devices that use SPP communicate like this.

So, the plugin will accept messages of the following format:

And this will be sent over the SPP connection as the byte stream: 02,74,02,05,05,03. This isn’t a random stream of bytes, by the way, but is in fact a request to a particular type of medical device to report its serial number. The 0x02 is “STX” and the 0x03 is “ETX”, which, if any of you remember your basic serial communications, are mnemonics for framing symbols around a message. The reason for this is that many medical devices were designed to work with real serial cable connections to monitoring equipment, and with the advent of Bluetooth the same protocol is simple transported over SPP. This is the reason for the word “Serial” in Serial Port Protocol.

Conversely, data returned from the remote device might be encoded the same way, something like:

So, I can use this to send, unambiguously, the text of messages entered into the input field on the “chat” application. The text of the message entered in this way will be in UTF-16 format; so, for example, string “hello” in the images at the start of this article would actually be passed to the plugin as:

{"command":[104,0,101,0,108,0,108,0,111,0]}

Where, for example, the character “h” – which is 0x0068 in UTF-16 – is passed as the two bytes (104, 0) (shown here in decimal), remember that this is in little-endian format. In essence, what I’ve done here is select an “on-the-(virtual)-wire” encoding for text encountered in JavaScript.

If you’re interested, here’s how I did this in the code of the “chat” application itself:

Using an “ArrayBuffer()” mapped with two views “Uint16Array()” and “Uint8Array()”, I could encode an arbitrary string encoded as UTF-16 unambiguously as a byte array before sending it to the plugin as a JSON string.

Now let’s look in more detail at the plugin itself.

The Plugin Itself

In a sense, I’ve cheated – I have to admit that I didn’t write this plugin from scratch myself. I had help. What I did was to use the excellent Cordova Plugin Template for BlackBerry 10 that you can find on GitHub here:

It comes with an Ant script that you can use to customize various aspects of your plugin, including its name. What you get, after you’ve done this, is a project that you can import into Momentics and a matching sample WebWorks/Cordova application that you can build. You should take a look at this in GitHub since it comes with a great explanation of how a plugin is architected and organized.

I’m going to assume that you’ve done this and now have a grasp of how a plugin works. What I’m going to explain now is how I’ve overlaid this model on top of the BlackBerry 10 Bluetooth SPP APIs.

It’s probably sufficient to look at how one single operation is implemented since the others follow the same pattern. I’ll look at “startDeviceScan()” operation, which looks like this:

I’ll get some immediate status as to the initialization of the scan operation in the variable “foo,” and subsequently, the “data” argument of the callback function will contain the result of the scan.

You have to provide some JavaScript “glue” first for any function or property that you implement.

Much of this is boilerplate code, setting up the “success” and “fail” callbacks, and the plumbing to handle the synchronous and asynchronous aspects of the function call. The “exec()” call makes a call to the next level of the “glue” layer, which is shown in the image below.

The actual call into native code is made in the fragment above – again, pretty much boilerplate code, where a “PluginResult()” object is obtained and a reference to it is saved for later when the asynchronous operation returns. The actual call to native code is made using the object returned from “simpleBtSppPlugin.getInstance()”.

Once you drop into native code, you have to call the appropriate method based on the name of the function you’re calling represented as a character string – something like what is shown in the image below, which calls the appropriate method on an instance of a class the template has provided for us.

In essence, this method is quite simple – all it does is start a pthread() that will perform the actual scan, since it can be a lengthy operation, and return the appropriate JSON to the caller, indicating whether the operation was initiated correctly or not. In the snippet below, “writer” is an instance of “Json::FastWriter”.

Once the pthread() has started, it scans for Bluetooth devices in the same way I’ve done in many other examples.

The key difference is this call made by the thread when it’s just about to exit:

This is where the JSON response containing all the devices that have been scanned is passed back up through the JavaScript layers as an asynchronous event to the correct callback that the user of the API has specified.

If everything has worked correctly, the user of the plugin’s API will see a response on the callback they have provided with data similar to this:

You can see that, along with a couple of BlackBerry 10 devices, there are also a couple of Estimote beacons in the vicinity . If no devices are found, the response would be like this:

It’s not an error to find no devices, so the “status” field is “OK,” but the “devices” array attribute is an empty array.

That’s about it!

If you follow the path of one operation all the way from the JavaScript API layer in the WebWorks application, you can discern the basic pattern; all the other operations work in basically the same way.

Summary

I’ve released V1.0.0 of the SimpleBtSppPlugin plugin containing the features described in this article, so you can download, review, and reuse the full source code. You can find the URL in the “Resources” section below. I hope this has been interesting and will help set you on your way to developing real-world Bluetooth applications for BlackBerry 10.

Please feel free to contact me on Twitter (@jcmrim) if you need help on anything Bluetooth SPP or Smart-related.

Introduction

“Not another blog post about Bluetooth Low Energy GATT!” I hear you say.

Ok, it’s true that there are quite a number of posts on this topic for BlackBerry 10 now. You can find a list here: Bluetooth Low Energy Resource Index, including the “Swiss Army Knife” of Bluetooth Low Energy GATT applications: “BlackBerry Bluetooth Explorer” which featured as the Bluetooth SIG application of the month earlier this year.

GATT is fundamental to how a BlackBerry 10 device communicates with Bluetooth Low Energy peripherals such as Heart Rate Monitors, Cycling Speed and Cadence monitors and even iBeacons™. In these use-cases, the BlackBerry device acts as a GATT client to the GATT server running in a peripheral.

However, BlackBerry 10 is also capable of hosting a GATT server, and this opens up a whole range of new use-cases. What classes of use-case am I thinking about? Well, let’s have a look.

An Example Use-Case for BlackBerry 10 Acting as a GATT Server

Let’s imagine we have a “smart watch” that acts as a Bluetooth Low Energy GATT server and that it exposes a number of services to which a BlackBerry 10 handset can connect. These services might include:

Acceleration – so the watch can recognize when you’re walking or running;

Heart Rate – the back of the watch may have sensors that connect to your skin and detect your heart rate;

Temperature – the watch may be able to detect your body temperature;

The list could go on.

The idea is that these data can be captured by the BlackBerry 10 handset and perhaps even saved and analyzed in the “cloud.” However, suppose that you also wanted the watch to be able to notify you, by perhaps vibrating, when a new email arrived; or have it be able to access the Location Services on the handset; or even have access to a custom GATT service running on the smartphone.

To do this sort of thing, the BlackBerry 10 handset has to be able to host one or more GATT services and allow the smart watch to connect back to the handset. That is, the watch acts both as a GATT server to the BlackBerry 10 handset’s client and as a GATT client to the BlackBerry 10 handset’s GATT server.

It’s important not to mix the quite distinct concepts of GATT Server and Client roles with the separate roles of Central and Peripheral Bluetooth LE devices. Because the two concepts are distinct, it’s quite legitimate to have a GATT Server run on either a central or peripheral device. The same applies to a GATT client.

I hope you can now begin to see why being able to host GATT services on a BlackBerry 10 handset is such a powerful capability.

I had a problem with demonstrating this: I didn’t have a smart watch, but what I did have was more than one BlackBerry 10 device! So here’s the model I used for this sample application:

There is a BlackBerry 10 application running on the first device acting as a GATT server, and

There is another BlackBerry 10 application, running on the second device, acting, in place of the “smart watch,” as a GATT client.

The GATT server application is called “GattServerRandom” and the GATT client application is called “SimpleRnsClient.” If you haven’t already guessed, the service offered by the GATT server application will generate a stream of random numbers that will be subscribed to by the GATT client application and displayed. Having the GATT server act as a random number server is a simple way to demonstrate this capability. I’m sure you can think of other more “real-world” applications based on this same pattern.

Here’s what the pair of applications looks like when random numbers are served from one device to the other. The Server is running on a Q10 on the left and the Client on a Z10 on the right. The client searches for the server and connects to it.

Once the client has connected to the server, it tells the server to start sending out a stream of random numbers, in the range 1 to 256. The server then starts using the Bluetooth Low Energy GATT Notify mechanism to send the stream of numbers. It will continue to do so until told to stop or the GATT connection is terminated.

So you can see that the principle is quite simple, but also incredibly powerful in terms of how you can use this capability.

How was this done? What code is needed to achieve this? First, let’s look at the server application.

How the GattServerRandom Application Works

This application initializes itself in the same way as all the other Bluetooth LE BlackBerry applications we’ve already talked about except that, additionally, it initializes itself as a GATT server as shown below:

The next thing it has to do is describe the GATT services and attributes that the application will host. You need to specify this information in a data structure like this:

Oh my goodness! That looks extremely intimidating doesn’t it? Let’s go through it slowly and use this as a key:

All that we’re doing here is defining an array with four entries that describe different elements of the GATT service we want to create. The BlackBerry 10 GATT Service will use this array to add your definitions to its list of services, provided the array is syntactically correct and self-consistent.

The first entry ( _myService[0] ) describes the overall service identified by a UUID ( “0x3759E92B-4E2C-4EFD-97B5-AABBCCDDEEAA” ). Notice that each entry is given a handle. This one has a handle of “0”.

The next entry ( _myService[1] ) describes a characteristic of this service identified by another UUID ( “0x3759E92B-4E2C-4EFD-97B5-000000000000″ ). The handle of this entry is “1”. It states that this value can be sent using Notifications to a client that asks. It also notes that the value of this attribute is to be found at handle “2”. Notice there is no explicit definition of handle “2” since the GATT server supplies that when it is started.

The next entry ( _myService[2] ) describes a characteristic of this service identified by a well-known, and predefined by architecture, UUID ( “0x2902” ). Its handle is “3” (notice that we’ve skipped “2”). It’s writeable, and if a client writes 0x0001 to this attribute, the server will start notifying the value associated with the characteristic – the random number in this case. The sending of Notifications can be stopped if a client writes the value 0x0000 to this attribute.

The final entry ( _myService[3] ) describes a characteristic of this service identified by a well-known, and predefined by architecture, UUID ( “0x2901” ). Its handle is “4” and its value is just a human readable string identifying the attribute – namely, the “Random Number” attribute.

There is certainly scope for making a mistake in defining such a service definition. The next step is to verify the self-consistency of the definition and, if it passes the check, then to register the definition with the GATT service.

The final step is to tell the GATT Service to start running. The code below shows how this is done by instructing the GATT Service to “Start Advertising.”

Now all we need to do is wait for a GATT client to connect to the GATT service and start reading and writing attributes. The application gets called via a call-back when one of these events occurs. Let’s take a look at what happens when the client asks for Notifications of random numbers to be started by writing a value of 0x0001 into the attribute at handle “3”.

Some defensive work is needed, like checking that the client is attempting to write to the correct handle (“3”) and that the value is either 0x0000, or 0x0001. If it all checks out, we respond with a positive response to the write operation, if it’s required, and allow it to proceed or bounce it with an error. Then we start the random number generator and every second, until stopped, the code below gets executed where a new random number is generated and written into the handle “2” of the GATT service.

It’s as simple as that. Just to put the whole server side into context, let’s see what the GATT service actually looks like using the Texas Instruments “BTool” utility, which is a standard item in my toolset now. Here’s the description of the GATT service as it appears to BTool.

The highlighted column on the left shows the handles of the attributes. There are five of them in our service. We defined them as numbered “0” through “4”, but when the GATT service integrated the definitions, they were offset to handles 0x00BA through 0x00BE. You should compare this with the original GATT service definition that was defined for our service.

If you’ve been paying attention, you’ll probably have a question. If our service has been shifted up to handle 0x00BA, then what additional services is BlackBerry 10 providing that are also in the GATT? Well, let’s take a look.

We find something very interesting. When our GATT service application is running, BlackBerry 10 offers, and advertises, the following well-known services as defined by the Bluetooth SIG specifications:

0x1811 – Alert Notification Service

0x1804 – Transmit Power Service

0x180F – Battery Service

0x180A – Device information Service

0x1819 - Location and Navigation Service

0x1807 – Next DST Change Service

0x1805 – Current Time Service

0x1803 – Link Loss Service

Let’s take a look at the “Device Information Service”:

This shows that my device running the GATT service is a Q10 running 10.3.0.698. This is the same information you’d find on the device “About” page in “Settings.”

Another one is the “Location and Navigation” service:

So, a GATT client, like the “smart watch” I mentioned earlier in this article, could determine location and speed-based data on demand from the BlackBerry 10 device.

It’s important to note that these services are available only when an application is running a GATT service and that the BlackBerry 10 handset user is prompted with an Alert when a GATT client attempts to connect so that it’s not possible to read this data without the express consent of the handset’s owner.

I think you now see why I said that the potential use-cases expand enormously when you start to run GATT services on your device.

I haven’t said much about the GATT client application. Let’s take a look at it now.

How the SimpleRnsClient Application Works

In fact, there’s not much that is different in this client application compared to other GATT client applications I’ve already written about in prior blog posts, so I’ll not dwell on this one. All of the code is available on GitHub for you to examine anyway.

There is one interesting point in this GATT client application, though, that’s worth pointing out.
How does the SimpleRnsClient work out how to connect to the BlackBerry 10 device in the first place? The custom GATT random number service I’ve written about isn’t mentioned in any Bluetooth LE advertisements; only the standard ones like 0x1819, etc. that I mentioned earlier.

Also, every time the GATT server application is restarted, the BlackBerry 10 device advertises using a different random Bluetooth LE device address. This is because it uses a privacy feature that thwarts attempts to track a device through Bluetooth LE advertisements via the MAC address. The real private MAC address is only available to devices that have performed a secure key exchange and bonded.

I could have added a text field to the client’s screen where the user could have entered the current MAC address or the “name” of the device, such as “BLACKBERRY-16EE,” or “John’s Q10,” but I wanted this client to work without tedious entering of data in the application.

So what the client actually does is enumerate the various standard services that BlackBerry 10 advertises when a custom GATT service is being run in an application – the ones mentioned earlier. The client will attempt a GATT connection to the first device it finds that matches all of these services. It’s a little more user-friendly for a sample application, but maybe not viable in the real world.

In a real-world scenario, when the BlackBerry 10 handset connects to the “smart watch,” it could be designed to pass sufficient information to the watch to allow it to connect back to the handset without any need for user intervention. This would, of course, be a function of the GATT services offered by the watch.

Summary

I’ve released V1.0.0 of the GattServerRandom and SimpleRnsClient applications containing the features described in this article, so you can download, review and reuse the full source code. You can find the URL in the “Resources” section below. I hope this has been interesting and will help set you on your way to developing real-world GATT Server based applications for Blackberry 10.

Please feel free to contact me @jcmrim via Twitter if you need help on anything related to Bluetooth Low Energy.

Resources

]]>http://devblog.blackberry.com/2014/08/gatt-server/feed/0Gatt1jcmurray2012Image: “Counting Maths Means Background Design and Numbers" courtesy of “Stuart Miles” / FreeDigitalPhotos.net Gatt2Gatt3Gatt4Gatt5Gatt6Gatt7Gatt8Gatt9Gatt10Gatt11Gatt12Gatt13If You Thought You Were Good at Air Hockey, Try Playing Against a BlackBerry Z30http://devblog.blackberry.com/2014/07/air-hockey/
http://devblog.blackberry.com/2014/07/air-hockey/#commentsMon, 14 Jul 2014 20:01:47 +0000http://devblog.blackberry.com/?p=18574/ Read More]]>When BlackBerry announced our Spring 2014 Hackathon for employees, I knew that I wanted to make something unique. Ideally, I wanted to build something that used a BlackBerry Z30 to control external components. We had an old air hockey table lying around the office that nobody used anymore, so I decided that with BlackBerry 10, we could breathe some new life into it. (Relocating it to my office would be a benefit of course!)…

This post is by Stephen Lau, Systems Software Developer at BlackBerry Sweden (TAT)

One of the best aspects of working for BlackBerry at the Malmö, Sweden office is that our leadership team is always enabling us to take on new and exciting projects. With their assistance, I got my hands on the old Rack2000 demo, a windshield wiper motor scrounged from a BMW and a few other scrap parts. With the parts on hand, I was ready for a weekend of hacking.

I had several goals for the project:

Create a goalie for the air hockey table.

Have everything run from a BlackBerry Z30.

Build it in two full days.

Have it beat my boss at air hockey.

The physical setup for the project was fairly simple. I found a microphone stand from our music room upstairs and mounted the device above the table. From this vantage point, the BlackBerry Z30’s front facing camera has a view of about 85% of the air hockey table. Another engineer from Malmö and I repurposed the BMW’s windshield motor to be the “goalie.” The windshield motor is hooked to an Arduino with a Bluetooth shield and a relay shield. To ensure that the BlackBerry Z30 was doing all the work, the Arduino is simply programmed to turn each relay on or off via Bluetooth. The device does the actual H bridge logic and the position control. Physical limit switches ensure a little bit of safety, by ensuring the goalie’s power is disconnected before it is able to break itself or swing wildly.

The code itself is quite simple. Since I cheated and made the puck green, I was able to greatly simplify my image processing code. Between each frame, the BlackBerry Z30 locates the puck, calculates the puck’s trajectory and then moves the goalie to try and block it.

I think the best part about working on this project was seeing all of the sample code in the Community GitHub. Since I only had two days to complete the project, and this was my second ever Cascades application, I really needed to find code I could use instead of writing it all from scratch. After exploring the samples section, I found two samples that would do about 80% of what I needed to do: the Råck2000 demo and the BestCam sample. From the Råck2000 code I borrowed the Bluetooth code and the Arduino code. The next step was to start modifying the BestCam code, and after finishing the project I only ended up adding about 250 lines of code!

I really enjoyed building this demo for the Hackathon and showing how the BlackBerry 10 OS can interface with hardware in a way that people don’t expect. Too bad I couldn’t accomplish the last goal… I ended up having to buy my boss a coffee when she won.

Editor’s Note: In this post, Stephen shows how Cascades was used to develop a unique twist on an air hockey game. But even as BlackBerry aligns our developer strategy with our enterprise-focused corporate strategy, the tactics Stephen used to bring his idea to life – implementing a standardized technology such as Bluetooth, utilizing sample code from GitHub and taking advantage of BlackBerry’s wireless debugging support – are just as relevant for enterprise devs.

This is the third in a series of Bluetooth™ beacon related posts by me (@jcmrim), and my colleague Martin Woolley (@mdwrim). You can find the two previous posts here and here if you haven’t already read them and the subject of beacons is new to you.

In this article, I want to move the story on and talk about how a beacon-aware BlackBerry 10 application ought to behave in the real world. The original WheresMyBeacon application, which was the subject of the two earlier posts in this series, demonstrated the mechanics of how beacons worked but suffered from one key drawback, namely: the application had to be running to detect beacons. Whilst this is useful whilst exploring the technology it’s not very useful in the real-world.
This post shows how to develop a beacon-aware application that is able to detect beacons even when the GUI part of the application is not running using features that have been introduced in BlackBerry 10 version 10.3 GOLD.

The Use-Case

Let’s just remind ourselves of the use-case that we’re supporting and build on the example of the fictional supermarket chain, “Exco”, which I introduced in the first post in this series. Exco have deployed beacons in all their retail outlets and designed a beacon infrastructure to allow them to deliver special deals to customers as they walk around any of their stores.

Key to this use-case is that customers would have installed the “Exco Loyalty App” on their smart-phone; without this application installed the handset is unable to recognise a beacon as an “Exco” beacon rather than their rival’s beacons. This application will notify the user of any special deals as they wander around a store and also, potentially, provide statistics to Exco as to customer behaviour in the store.

Now, it’s not acceptable that a user would manually have to open the “Exco Loyalty App” every time they entered a store. What is required is that the application should be capable of recognising Exco’s beacons even if the application itself is not running.

Let’s see how this can be achieved on BlackBerry 10.

The Technology

The key BlackBerry 10 technology for supporting this use-case is called “Headless Application” support. There are many explanations of how Headless Applications are structured and I’m not going to describe in detail how Headless applications work. I’ve provided links to some of these at the foot of this article. If you’re not familiar with the Headless Application architecture then this is a good time to go and learn about it.

At a very high level here’s what you need to know. A BlackBerry 10 Headless Application consists of two components:

A GUI component which is identical to an ordinary BlackBerry 10 application capable of interacting directly with the user, and;

A background service component which does not interact with the user and which has a more restricted application lifecycle when compared to the GUI component.

These two components are packaged into a single application BAR file and share the same sandbox so they can share data on the file system. The background service can be started when the device is started so it’s always running in the background but with certain constraints in terms of how much CPU cycles it can consume.

So, the key task to converting the WheresMyBeacon application into a Headless one is to move all of the Bluetooth™ interactions into the Headless component and utilise capabilities, such as the BlackBerry 10 Hub, to notify a user when a beacon detection event occurred in the Headless component.

The BlackBerry 10 Application: WakeMeByBeacon

This Headless application was built using the standard Headless Application template in Momentics which creates two interrelated projects which have been called “WakeMeByBeacon” and “WakeMeByBeaconService”. Let’s have a look, first, at the bar-descriptor.xml file in the GUI component project.

You can see that there are two permissions specified: one identifies the permission needed to allow this application to run a headless component, and the other identifies the permission needed to allow the application to add notifications to the BlackBerry 10 Hub.

Secondly notice that the invocation action “bb.action.system.STARTED” has been registered for the headless component. This ensures that the headless component will be started at device start time.

Initialisation of Bluetooth™ is identical to the “WheresMyBeacon” except that this now takes place in the headless service (in Service.cpp) rather than in the GUI.

The headless service also registers for a couple of SIGNAL()s: one from InvokeManager() so that it can handle Invocation Requests, and one from Application() which tracks the service’s process state.

So, now the headless component will start at device start time, be registered for Bluetooth™ advertisement events, be able to react to invoke requests and be aware of its processing state.

Now, let’s look at the GUI. It’s a simple interface with two basic actions:

Start or Stop the headless service component.

Enable or Disable scanning for Bluetooth™ beacons.

The ability to start and stop the headless service is a useful feature rather than having to re-install the application or restart the device. Similarly the ability to Enable or Disable scanning in the headless service for Bluetooth™ beacons is useful.

The buttons reflect the state of scanning and the headless service and there is a log section which is used to log certain events in the service.

Now, if you’ve been paying close attention you may have a question! How is it that the GUI component can possibly know about the status of the headless service, whether it’s running or not, and whether or not the headless service is currently scanning for Bluetooth™ devices?

The GUI isn’t cheating or guessing the headless service state; it actually knows the status of the headless service. How is it doing this?

Let’s go back for a minute to the headless service again to see how this is done. If you look at the code for the headless service you’ll find a class called SocketListener(). An instance of this class is instantiated in the headless service and provides a QLocalSocket() server running in the headless service. When the GUI starts it tries to connect to this local socket() and establish a two-way communication channel between the headless service and the GUI.

SocketListener() also exposes some SIGNAL()s which can be used to determine when the GUI connects and disconnects and a SLOT() to allow the headless service to send data over the socket() to the GUI.
So, what does the headless service send over this connection? If you look in the application’s console log when you run it from Momentics you’ll see examples like this:

Periodically, it sends a JSON encoded message indicating the current status of the headless service to the GUI so that it can use this information to reflect the state of the headless service. The GUI is also aware of the state of the socket() to the headless service so it knows whether it’s running or not.

So, it’s not magic; just a simple socket() between the two components. This is a useful pattern to re-use. In fact I re-used it from this more generic headless sample application that we have written and blogged about here.

Similarly, sending instructions to the headless service through invoke requests is quite simple as well. Here’s the action that’s hooked up to the button that instructs the headless service to start scanning for beacon advertisements:

In fact here’s the code fragment in the headless service that handles starting and stopping of scanning for Bluetooth™ beacon advertisements:

Now, this is the point at which we begin to differ from the previous application, “WheresMyBeacon”. The functions bt_le_enable_scan_invoke() and bt_le_disable_scan_invoke() are new in BlackBerry 10 version 10.3 GOLD. They enable you to request that an application be invoked when a Bluetooth™ event occurs, which means that the headless component of your application can stop running and be restarted when a suitable Bluetooth™ event occurs. This is exactly what we do in this application.

Lets’ have a look at how the headless service deals with such an event.

The “bb.action.bluetooth.SCANRESULT” invocation action is the one we have to handle and then decode the advertisement data in the request payload using the utility function bt_le_invoke_decode_scan_result().

So, if we now stand back a bit we can see that the headless service will receive Bluetooth™ advertisement events from two sources:

If the headless service is running they will be received through the standard call-back scheme that we demonstrated in the WheresMyBeacon application.

If the headless service is not running when a Bluetooth™ advertising event occurs it will be delivered through the Invoke mechanism.

These two sources of beacon advertisements will converge when the headless service needs to decide what to do with these events – does it tell the GUI? And, if it does, how does it tell the GUI?

First of all, all new beacons that are detected are added to a data model with a time-stamp to show when they were last seen. If a beacon has gone out of range it will be removed from the data model after a certain period of time – I compromised with a time of 5 minutes in this application, feel free to experiment.

This means that the headless service can generate events for the GUI when a new beacon is detected and also when a beacon has gone out of range. Let’s take a look at the case of a new beacon having been detected – the process is identical for one moving out of range. Here’s the code that notifies the GUI:

If the headless service knows that the GUI is running (remember the socket() connected to the GUI?) it sends a message over the socket() for the GUI to deal with.

If the GUI is not running then the headless service constructs a Notification() to be placed in the BlackBerry 10 Hub that will launch the GUI and with a payload that contains the same data that would have been sent across the socket(). Here’s an example of the message that gets sent to the GUI from the headless service when a new beacon is detected, and the same data as it’s rendered in the GUI.

Apart from some bits and pieces of housekeeping that’s pretty much it for the headless component. If the GUI is not running when the headless service detects a beacon event the notification it sends to the hub appears something like this.

It can be used to launch the GUI component application which then can take action on the beacon that’s been discovered. Here’s how that’s done:

Summary

I’ve released V1.0.0 of the WakeMeByBeacon application containing the features described in this article and so you can download, review and reuse the full source code – you can find the URL in the “Resources” section below. I hope this has been interesting and will help set you on your way developing real-world beacon applications for Blackberry 10.

Please feel free to contact myself @jcmrim via Twitter if you need any help on anything Bluetooth Low Energy related.

A few weeks ago, John Murray (@jcmrim) published a blog post entitled “Where’s My Beacon?” This was the first of several we plan to share, relating to work we’ve been doing together on the subject of Bluetooth™ beacons. You can find that post here and if you’re new to beacons and haven’t read it yet, you should check it out before diving into this article. John did a great job of introducing the topic and explaining the key technicalities.

In this article, I want to continue where John left off and talk about the practicalities of developing beacon applications, share information about the tools I’ve been using to assist me, the issues I’ve encountered, and other important points.

Testing Beacon Applications

One of the key issues for beacon application developers is testing. Imagine your application is targeted to the customers of a retailer with hundreds of large stores up and down the country. Each store is to have a number of beacons deployed in it, and your application will need to respond to the proximity of each distinct beacon in a unique way. For example, it could notify the user of special offers relating to products in that department of that particular store. So ideally, you need to test your application with a wide range of relevant beacon UUID, major and minor attribute value combinations.

This raises the question: how exactly can you set the values of these attributes?

Setting Beacon Attribute Values

There does not appear to be a standard defining the way in which a beacon might expose configuration settings and allow them to be updated.

So you may ask, “how is it done with the Estimote beacons which John talked about in the first article of the series?”

Estimote beacons include a form of authentication to prevent unauthorized attempts to change attribute values, an important measure in the context of real world applications. They’ve not yet published details of how to work directly with this aspect of their product however, and the only way to use it right now is via their SDK. The SDK is not currently available for BlackBerry but, we are working with the Estimote team regarding the possibility of a BlackBerry version becoming available in the future.

Texas Instruments SensorTag

In support of my work, I’ve also been making extensive use of a great Bluetooth developer tool from Texas Instruments (TI): the SensorTag. There’s a lot that could be written about this flexible bit of kit, but first of all: SensorTag is not a beacon! In fact, it’s a small hardware device that has a whole range of sensors dotted about its surface, various IO pins and a Bluetooth Low Energy (BLE) “system on a chip”. The sensors include an infra-red temperature sensor, a barometric pressure sensor, a humidity sensor, an accelerometer, a magnetometer, a gyroscope and just for good measure an ambient temperature sensor. BLE GATT services make this data available to your application. One of the cool things about SensorTag is that in the most recent firmware update, it is now able to switch into “beacon mode”, where those other services are disabled and instead the device starts to emit advertising packets containing the beacon data that John previously explained, including a UUID, major and minor attribute through which to identify a specific beacon.

Figure 1 – My 2 SensorTags side by side and out of their plastic case

Furthermore, a new GATT service was added, the iBeacon service, and this exposes the beacon attributes as writable GATT characteristics[1].

I’ve made some changes to the WheresMyBeacon application that John introduced in the last article, and this includes a feature that lets me modify the beacon attributes that SensorTag includes in advertising packets and a couple of other attributes concerned with beacon operation.

Naming Beacons

Before I get to the good stuff, let me mention one change I implemented in WheresMyBeacon V2.0.0 that made life easier but, is not quite in line with this article’s main point. I made it possible to associate a human readable name with a beacon, keyed on its MAC address. This simple idea made it so much easier to know which beacon was which as they popped up on the UI of WheresMyBeacon. To use it, just select any beacon listed in the main screen showing iBeacon advertising and a new screen will open up, allowing you to name and indicate the type of beacon. Check the code and you’ll see I used the QSettings class to persist this data.

Figure 2 – Naming your beacons in WheresMyBeacon V2.0.0

Managing SensorTag Beacon Attributes

As mentioned, the TI SensorTag can be in one of two modes; either it’s exposing a variety of GATT services or it’s in “beacon mode” and advertising with iBeacon packets. To toggle between the two modes, you hold down the side button on the SensorTag for a couple of seconds.

I pointed another of my TI tools, “BLE Device Monitor” at the SensorTag whilst it was in “non-beacon mode” and here are the GATT services that are evident:

Figure 3 – SensorTag GATT services and characteristics

As you can see, there’s an “iBeacon Service” with UUID 0xF000BCC0-0451-4000-B000-000000000000. This service exposes six writable characteristics, four of which contain attributes whose value will appear in advertising packets when in “beacon mode”. These are the Beacon UUID, Beacon Major, Beacon Minor and Beacon Power attributes. The other two are the Beacon Interval, which control how often advertising packets are sent (and this can be important as it impacts battery life) and Beacon PIN, which according to the TI documentation is “not currently used” but, which I assume will be used for authentication purposes in the future.

Updating these values is easy and no different to the way you’d write to any GATT characteristics for which write access is permitted.

The device must first be paired via the BlackBerry 10 Bluetooth Settings page. After this has been done, your application will find it by scanning, and then connect to its iBeacon Service. Having done so you need to establish the handle values of those attributes you wish to update and use these values when updating them via an API call[2].

Using bt_gatt_write_value to update a beacon attribute (code simplified for blog)

Using WheresMyBeacon to Modify SensorTag Beacon Attributes

WheresMyBeacon 2.0.0 includes a new pull-down menu. Selecting the Configure action takes you to the “Configurable Beacons” screen. Selecting “Scan” will cause all previously paired SensorTag devices to be listed. Note that they need to be in “non-beacon mode” to be configurable. Select a beacon by touching the item in the list and you’ll be presented with a screen where you can modify and save beacon attribute values back to the selected SensorTag. Figure 4 shows this:

Figure 4 – Changing Beacon Attribute Values with WheresMyBeacon 2.0.0

Useful BLE Tools for Developers

During any development project, you’re bound to hit a problem or two and need to investigate. Aside from standard debugging techniques that might be used for any application, I often use additional BLE tools to help troubleshoot problems. These are useful for any BLE application, not just those relating to beacons.

I’ve already mentioned one of these tools, the TI BLE Device Monitor. This is a user-friendly tool, used in conjunction with a BLE dongle that plugs into my laptop and allows me to query and explore the GATT services and characteristics. Figure 3 shows a screen shot taken from this tool. Note that if you need more control (e.g. you want to send specific Attribute Protocol commands), TI have another tool called “btool” that I also use quite a lot.

Sometimes you really need to see what’s being transmitted and received “over the air”. This can be particularly true with beacons where being able to see the content of advertising packets can be a big help sometimes. To that end, I use the same TI dongle, loaded with alternative firmware which turns it into a “sniffer” plus a TI PC tool called Smart RF Packet Sniffer. Figure 5 shows three iBeacon advertising packets broadcast by one of my SensorTag devices. I’ve highlighted the four iBeacon fields which are (in order from left to right), the UUID, major, minor and “calibrated power” values.

We’ve released V2.0.0 of the WheresMyBeacon application containing the features described in this article and, so you can download, review and reuse the full source code, you can find the URL in the “Resources” section below. I hope this has been interesting and will help set you on your way developing beacon applications for Blackberry 10.

Watch out for more from myself and John Murray on this topic right here in the BlackBerry Developer Blog.

Please feel free to contact either myself (@mdwrim) or John (@jcmrim) via Twitter if you need any help on anything Bluetooth Low Energy related.

Lighthouses, or beacons, have always played a key role in ocean navigation and safety at sea. They are built at key locations so that they – or their light – can be seen by distant ships. They can identify safe havens or dangerous shoals by different sequences of flashing lights as well as sounds, and seafarers can use them to triangulate the position of their vessel.

It’s not surprising that a parallel digital technology has evolved to help users of mobile devices navigate through the world of streets, buildings and a host of other locations.

Apple introduced iBeacon™ technology that operates over Bluetooth Low Energy as a vehicle for extending location services. It’s caught the imagination of people as a real, tangible example of the “Internet of Things,” and there are now many manufacturers of such iBeacon technology.

Martin (@mdwrim) and I managed to acquire several such beacons from the kind people at Estimote. My first thought was, how can I write a BlackBerry 10 application to interact with these Estimote beacons?

Never one to turn down a challenge, I developed a simple BlackBerry 10 application to do just that – this is the story.

Background on iBeacon

Figure 1: An Estimote Beacon (courtesy Estimote)

Estimote beacons are just a few centimetres in size and can be adhered to almost any surface. A battery that powers a Bluetooth Low Energy device is the key to how beacons work. For an ordinary individual using a mobile smartphone, interacting with a beacon is a passive experience. Just like a lighthouse, the beacon periodically advertises its presence using a Bluetooth Low Energy Advertisement. Lighthouses “flash” every few seconds; iBeacon devices advertise about every 100 milliseconds. For a beacon to be useful, mobile applications need to be aware of the various beacons around it, just in the same way a ship at sea would be aware of the lighthouses around it.

So, what does an iBeacon advertisement contain? Bluetooth Low Energy advertisements are defined by the Bluetooth Low Energy Specification from the Bluetooth Special Interest Group. There’s not a lot of room in an advertisement packet but it’s possible to shoe-horn some information into the Manufacturer field. The original intent of the Manufacturer field is to allow the manufacturer of a Bluetooth Low Energy device to add additional identification information about their device. In defining iBeacon, Apple used this field to add additional information to the advertisement without compromising the Bluetooth Specification. Apple has not made the content of this field public, although the specification is now available through a program that requires signing an NDA with Apple. However, the Web is replete with details from people who have reverse-engineered the field’s content (for example here: Estimote Advertising Packet). It looks like this:

A 128-bit UUID field (such as B9407F30-F5F8-466E-AFF9-2555-6B57FE6D)

A 16-bit unsigned integer field called Major Number (such as 12654)

A 16-bit unsigned integer field called Minor Number (such as 32456)

An 8-bit signed integer field called Calibrated Signal Strength (such as -74)

You may ask how these values get programmed into a beacon in the first place. In practical terms, each manufacturer adds additional Bluetooth Low Energy services to their beacons to allow the management of these values – but we’re not interested in that here. In fact, Martin will write about this in our next blog post on beacons.

So what do these numbers mean? Do they conform to any set of standards for their assignment? The short answer is no. It’s entirely up to a beacon infrastructure implementation to assign meaning to these values. However, just as an example, here’s how a supermarket chain (let’s call it Exco for sake of argument) might make use of such beacons:

Exco decides to use a single unique UUID for their beacons across all its stores. This allows them to easily determine if their mobile application on a smartphone when the device is in beacon-range of one of their stores.

They decide to assign different Major numbers to each of their stores. This allows the mobile application to know in which store the smartphone is currently located.

They decide to assign Minor numbers to each department so that the smartphone application now knows which department within the store it’s located.

The concept is elegant in its simplicity. There is no need to use GPS to figure out where the smartphone is located. Once the application knows that it’s close to the bakery department, it can offer special deals to the user. How it does this is application dependent. It could periodically download offers and store them locally, or fetch them each time.

The Calibrated Signal Strength field represents the strength of the signal from the beacon in dBm as measured and calibrated at a distance of 1 meter from the device and is a constant value that was set when the beacon was configured. The value allows you to compare this value with the actual power, the Received Signal Strength Indication (RSSI), detected at the smartphone to figure out a “path loss,” in dB, between the beacon and the handset. A large path loss means the beacon is further away or obstructed by walls that may absorb the radiated power. All other things being equal, you will be closest to the beacon that has the smallest path loss. If the beacon calibration is accurate, you should see a path loss of 0 dB when the handset and beacon are 1 meter apart.

The BlackBerry 10 Application

This is just a simple application that demonstrates how to detect and parse iBeacon data, including the Bluetooth MAC address, UUID, Major, Minor and Calibrated Signal Strength values, and also calculates the path loss. Figure 2 shows how to initialize Bluetooth and enable the call-back, btLeAdvertisements(), that will be called whenever any Bluetooth Low Energy device advertises. I’ve also set the Bluetooth Low Energy scan parameters (using le_set_scan_params()) so the call-back won’t be swamped by advertisement events every 100 milliseconds; rather, it should trigger every second or so.

The BT_LE_ADVERT_SCAN_PASSIVE option indicates that we’ll simply listen for advertisements rather than actively scan for them. The “interval” value of 1000 indicates that we’ll start listening every 1000 milliseconds (1 second) and the “window” value of 100 indicates that when we start listening, we’ll listen for 100 milliseconds. The value of 100 milliseconds is chosen because that’s the value of the default iBeacon advertisement interval.

Figure 2: Initialize Callback for Advertisements

Every time an advertisement is detected, it gets parsed as shown in Figure 3. What this is doing is running through the advertisement data looking for a Manufacturer field (0xff) and for an Apple specific field in particular (0x4c, 0x00) which itself contains iBeacon data (0x02) which is of a fixed length (0x15).

Once we’ve located the iBeacon data the UUID, Major, Minor and Calibrated Strength fields can easily be extracted, taking care with integers for the sake of endian-ness.

Figure 3: How to parse the Advertisement Field

Here’s a screenshot of the application running having detected three Estimote beacons, each with a distinct Bluetooth MAC address. Estimote beacons are all configured to have exactly the same UUID, so this is a way to identify them as I’ve done in Figure 4. You can see the Major and Minor numbers for each beacon, as well as the Calibrated Signal Strength for each, which is -74 dBm. The calculated path loss is also shown for each beacon. If the BlackBerry 10 device is moved around, this value will change depending on the proximity of the handset to each of the beacons. In this case, you can see that my device is closest to the second beacon with a path loss of 3 dB.

Just click the “Start” button to have the application collect advertisements from all beacons in the vicinity and “Stop” to stop it. It’s a simple application and you can probably see the opportunities for expansion. Perhaps add a GUI element to show visually the distances of the various beacons?

If you like this application, then use the “About” page to share it with others on social media.

Figure 4: Three Estimote beacons detected

The source code for this application is on GitHub. Watch out for follow-up articles from me and my colleague Martin Woolley on this subject. We will look at related products and how to take this simple BlackBerry 10 application and turn it into a robust, “real world” Internet of Things application.

Feel free to contact me or Martin via Twitter if you need any help on anything Bluetooth Low Energy related.

If you’re in the business of creating physical products that integrate with mobile devices, we’ve got the specs you need to add BlackBerry to your portfolio. Whether you integrate via Bluetooth, USB, WiFi, HDMI, or audio jack, we’ve got you covered. Case maker? Yeah, we can help you too – not only in getting device specs, but also in promoting your products.

Today I’m pleased to announce the availability of developer.blackberry.com/accessories, your one stop shop for all the device specs you need to integrate with BlackBerry 10 smartphones. Check it out and let us know what you think!

If you have been following my earlier blog posts, you know that I tend to explore areas like NFC and Bluetooth Low Energy from a BlackBerry 10 developer’s perspective, usually in conjunction with my colleague Martin Woolley.

So you may be wondering what this Unity 3D thing is all about, and why I’m rooting around gaming. Well, Unity 3D is a phenomenal framework that allows you to develop amazing games on multiple platforms, including BlackBerry 10. And what’s more, it contains a very flexible plugin framework to allow you to extend your game’s capabilities down into native capabilities of BlackBerry 10!

Because of this framework, I saw an opportunity to add the capability to a Unity 3D game to interact with a Bluetooth Smart device. Imagine influencing gameplay through data streamed from a heart rate monitor worn by the player; perhaps zombies could become more frenetic as your heart rate increases! This capability goes by the name of “haptics.” Hold that thought for a while!

I’ve already touched on this in a previous post but to I’m going to explain in a lot more detail how I implemented a Bluetooth Plugin for Unity to allow game objects to access live heart rate monitor (HRM) data worn by a player.

If you’ve never encountered Bluetooth Low Energy technology before, you’ve got a little bit of homework to do. Take a look at these documents:

Now that you’ve read about how a Bluetooth LE Heart Rate Monitor can be integrated into a standard native BlackBerry 10 application, it should be clear how we can do this in Unity 3D. It’s just a case of embedding the Bluetooth functionality in a native shared library and plumbing it into the Unity 3D framework. I’ll skip over the Bluetooth specific details in this article since these are already well documented in the links above; I’ll focus instead on the Unity 3D bits.

The Plugin Shared Library

Let’s start with a little background. Unity 3D plugins are basically shared libraries, such as libBtHrmPlugin.so (this is the name of my Bluetooth Low Energy Heart Rate Monitor Plugin) that expose a set of “C” functions something like this:

The first thing to notice is that the plugin shared library should expose functions using “C” linkages. If you expose these using “C++” linkage conventions then external names get “mangled” to allow accommodation of “C++” class qualifiers and other annotations. I’ve exposed five functions:

initialiseBtLeImpl(): This function would be called by the Unity application to initialize the Bluetooth Low Energy environment. Essentially doing things like ensuring Bluetooth is on, establishing callbacks for Bluetooth events and other housekeeping.

scanForHrmDevices(): Before we can use a particular HRM device, we perform a scan for candidate Bluetooth LE devices. There may be many devices that offer the HRM service so we need to enumerate them and pass the list of the ones that have been found back to the Unity application – more on how we actually do this later. Scanning for devices could be a time consuming activity so this task is handled by a separate thread that is started as part of this functions execution. When we return from this function back to the calling Unity application, the thread will still be running in the background searching for devices.

startMonitoringImpl(const char *address): Once the Unity application has determined the number, names and addresses of the available Bluetooth HRM devices, it needs to select one to connect to and monitor. That’s what this function does. After successfully returning to the Unity application, Heart Rate Monitor events will be delivered to it. We’ll talk about the mechanics of how this happens later.

terminateBtLeImpl(): This is the reverse of the initialize step where we tidy things up after the Unity application using the services of this library has finished.

These functions allow the Unity application to instruct the plugin to perform specific tasks, and they all pass back an integer return code to indicate whether they were called successfully or not. Functions such as initialiseBtLeImpl and terminateBtLeImpl are quite simple and a return code is all they need to return. However, you’re probably wondering how the plugin communicates information other than simple return codes back to the Unity application. If you take another look at the code snippet above, you’ll see a declaration of a function called UnitySendMessage(); this should give you a clue.

UnitySendMessage() is a function that is exposed by the Unity 3D framework itself. This is the way that data is passed back asynchronously to Unity from our shared library plugin. Let’s examine the parameters that this function takes:

const char *obj: This a pointer to a NULL terminated string that identifies a “Game Object” within the Unity application.

const char *method: This is a pointer to a NULL terminated string that identifies a method on the “Game Object” that we want to call.

const char *msg: This is a pointer to a NULL terminated string that represents the data that will be passed to the above method on the aforesaid “Game Object.”

You can see that we can only pass a single string back into the Unity application. This means that if we want to pass back a complex object, such as a list of discovered Heart Rate Monitor devices with their names and addresses, we’d better find some way of encoding that information in a single string. Sounds like a job for JSON, which is exactly the approach taken in the plugin. Let’s solidify that with a concrete example.

The code fragment above comes from the plugin itself. You can see that it covers two cases:

The plugin has successfully scanned and detected a number of HRM devices. It’s encoded these into a JSON string ( json_for_unity ) and passes that as the single parameter to a function called RequestScanForHrmDevicesSucceeded on the Game Object called “BtHrmPlugin” .

In the case that there has been an error in the plugin while scanning for HRM devices, an error message is constructed as a JSON object with an error ID and an error text string. This is passed as the single string parameter to a function called RequestScanForHrmDevicesFailed on the same Game Object, “BtHrmPlugin”.

Some of you may have noticed that UnitySendMessage returns pointers to the Unity 3D framework. Isn’t that unsafe? In the above fragment it returns a pointer to a char array containing the JSON string and this becomes invalid after exiting the block after returning from UnitySendMessage. This is a good question and what seems to happen is that Unity copies the data rather than pass around pointers, so it’s safe to do it this way.

In essence, that’s all there is to the plugin. The key to constructing a Unity application and plugin as a functioning pair is to identify these functions, which represent events that can be emitted from the plugin asynchronously. Let’s just have a look at the ones that I’ve used:

RequestScanForHrmDevicesSucceeded: This indicates that the plugin has successfully completed a scan for Bluetooth HRM devices and these are returned encoded in a JSON string.

RequestScanForHrmDevicesFailed: This indicates that the plugin has failed in some way during its scan for Bluetooth HRM devices. An error ID and a description of the error are returned encoded in a JSON string.

RequestServiceDisconnected: This indicates that the plugin has been notified that the HRM device has been disconnected from the plugin. This normally occurs as the result of a request from the Unity Application but the reason is returned as a JSON encoded string.

BtHrmNotification: This indicates that the HRM device has notified the plugin of a heart rate measurement. The measurement data can contain many data points and is described in detail in the Bluetooth Special Interest Group (SIG) Heart Rate Profile specification. In essence, it contains the current measured heart rate in beats per minute, with optional details on energy expended, skin contact indication and other data points dependent on the device’s implementation.

BtHrmMessage: This indicates that the plugin is sending a message to the Unity application. It’s simply a text string, but the application can chose to display it in a suitable way. I typically use it to show progress of the plugin’s processing and also simple debugging information.

Let’s now just a have a quick look at the structure of the project in Momentics.

This project was created using the standard BlackBerry shared library template.

I use “.c” and “.h” file types so that the compiler recognizes these as “C” files and not “C++” ones. Do you recall the discussion above on “C” versus “C++”?

The shared library itself is created in the standard locations and called libBtHrmPlugin.so.

I’ve also added a Scripts folder. The reason for this is that the shared library needs to be copied onto the Unity 3D framework project where I build my Unity application, and having to do this manually became tedious, so I added some scripts to make the process a little easier.

The Unity 3D Application

Now that we understand the way the plugin is architected, and the API that has been designed to interact with it in terms of functions it exposes and events that it communicates back to the Unity 3D framework, let’s look at other side of the API: how to interact with this plugin from a Unity 3D game.

Unity 3D applications typically use C# (using the cross-platform Mono Framework) or JavaScript to express game logic. I used C# in this example rather than JavaScript for no other reason than I quite like C#. C# has a very nice ability to represent events. It allows applications to subscribe to these events and be notified when they occur, and it sits nicely with the model of a Unity 3D application which is driven by external events such as button clicks, timers, network events,or even events that percolate up from our Bluetooth LE HRM plugin!

This means that we need to implement a “layer” beneath the Unity application which can map both calls made by the application onto the plugin and asynchronous events from the plugin onto C# events that can be subscribed to by the application. We do that in a C# class called BtHrmPlugin. Here are the relevant elements of the definition of this class focusing on the one method used to enable the application to initialise the plugin’s Bluetooth environment:

This class needs to link to the external functions in the plugin that we described in the previous section. C# uses the statement DllImport to achieve this. It has this peculiar name since C# originated on Windows and a DLL is a Dynamic Link Library, which is the Windows analogue to a shared library on BlackBerry 10. Notice that the name of the library to import is “BtHrmPlugin” rather than “libBtHrmPlugin.so”. Mono will try a variety of permutations of names as it tries to locate the underlying library and this gives an element of platform independence to naming of the plugin libraries.

In this case the function that is exposed to the Unity 3D game application is called InitialiseBtLe() and this results in a call to the corresponding function in the plugin library called initialiseBtLeImpl(). Notice the #if … #else … #endif construct. This ensures that the call to the plugin is made only if the application is running on a BlackBerry 10 device and we’re not running the application inside the Unity editor. If we are running in the Unity editor we just return a good return code.

Now, how do we deal with C# events? When the plugin makes an asynchronous call to UnitySendMessage this needs to be mapped onto a C# event that the application can subscribe to. Here’s how it’s done; I’ve highlighted the key points to help you see what’s going on.

A successful scan for Bluetooth LE devices will result in the plugin calling the C# method in our class called RequestScanForHrmDevicesSucceeded. First we check to see if there are any subscriptions in place for this type of event, and if so, we parse the JSON string provided by the plugin and create a new instance of the class ScanForHrmDevicesEventArgs which is used as a container for the list of devices discovered and their attributes. Then we raise the ScanForHrmDevicesSuccessfulEvent event we’ve defined and it’s sent to the subscribers.

Here’s how part of the Unity game logic would register for this event in C#:

The successful scan resulting in a list of Bluetooth LE heart rate monitor devices end up being processed asynchronously in this function (ScanSuccessful) in the game logic. All the other functions and events supported by this plugin work in exactly the same way, the pattern is identical.

It’s worth looking at how these elements are arranged in a simple Unity 3D project. In order to test it, I wrote a simple Unity 3D sample application. I’m only a newbie when it comes to being able to design sophisticated and elegant user interfaces, so the application is a very functional one using OnGUI() to demonstrate how the plugin is functions. Here’s the layout of the project:

This is where you must place the shared library plugin libBtHrmPlugin.so. It won’t work if it is placed anywhere else. Now you can see why I had some useful scripts in my Momentics plugin project to be able to copy a new version of the plugin to this location whenever I’d re-built it.

I placed the C# BtHrmPlugin.cs file containing the C# class BtHrmPlugin in the folder above outlined in RED. There are no constraints on where you can place this. You’ll notice that there is also, outlined in GREEN, a Game Object also called “BtHrmPlugin”. This is important. In order to attach the C# plugin script to the game play scene you need to attach the script to a Game Object. Here we’re closing the loop on a point I made earlier. Do you recall that I noted that the first parameter on the UnitySendMessage() function identified a Game Object that the message should be sent to? Well, here’s confirmation of that! The plugin send its messages to a Game Object called “BtHrmPlugin”.

So, we’ve come full circle regarding the plugin and how it works. My simple test application is in the file BtHrmGuiHandler.cs as shown below.

Below is a snapshot of the application running using a real heart rate monitor! The large number is my instantaneous heart rate while testing this application. You can see that I happened to be using a “Zephyr” Heart Monitor, which I had already paired to my Z30, although any others that support the Bluetooth SIG Heart Rate Profile will also work.

The buttons at the top of the screen control the ability to start and stop monitoring through the plugin, and the area at the bottom of the screen represents a log showing the operation of the plugin and the data that it’s receiving from the heart rate monitor.

Summary

I hope that you’ve found this description of my journey through this simple Unity 3D plugin useful. The plugin itself and the associated simple Unity application are available on GitHub.

It would be nice to see a real game exploiting Bluetooth Low Energy accessories. Watch this space!

]]>http://devblog.blackberry.com/2014/02/diary-of-a-unity-3d-newbie-bluetooth-low-energy-plugins/feed/0Diary of a 3D Newbie_2_12_featurejcmurray2012Diary of a 3D Newbie_2_1Diary of a 3D Newbie_2_2Diary of a 3D Newbie_2_3Diary of a 3D Newbie_2_4Diary of a 3D Newbie_2_5Diary of a 3D Newbie_2_6Diary of a 3D Newbie_2_7Diary of a 3D Newbie_2_8Diary of a 3D Newbie_2_9Diary of a 3D Newbie_2_10Diary of a 3D Newbie_2_11Diary of a 3D Newbie_2_12Diary of a Unity 3D Newbie – Solving DllImportException Errorshttp://devblog.blackberry.com/2014/01/diary-of-a-unity-3d-newbie-solving-dllimportexception-errors/
http://devblog.blackberry.com/2014/01/diary-of-a-unity-3d-newbie-solving-dllimportexception-errors/#commentsTue, 21 Jan 2014 16:45:47 +0000http://devblog.blackberry.com/?p=17312/ Read More]]>If you’ve followed any of my earlier blog posts, you know that I tend to explore areas like NFC and Bluetooth Low Energy from a BlackBerry 10 developer’s perspective – usually in conjunction with my colleague Martin Woolley.

So you may be wondering why I’m writing about Unity 3D today. Well, if you weren’t already aware, Unity 3D is a phenomenal framework that allows you to develop amazing games on multiple platforms, including BlackBerry 10. What’s more, it contains a very flexible plugin framework that allows you to extend your game’s capabilities down into native capabilities of BlackBerry 10!

So naturally, I wondered if I could add the capability to a Unity 3D game to interact with, say, a Bluetooth Smart device. Imagine influencing gameplay through data streamed from a Heart Rate Monitor worn by the player. (Hold that thought for a bit!)

Because I already know how to interact with Bluetooth Smart devices, it’s just a case of embedding the Bluetooth functionality in a native shared library and plugging it into the Unity 3D framework. I’ll share how to do just that in future blog post.

However, today I’d like to share with you what, as a Unity 3D newbie, I had to do to get to the root-cause of a particularly opaque error I encountered when testing my plugin in and application on a BlackBerry 10 device. I kept on seeing “DllImportException” errors, which suggested that my plugin couldn’t be found by the running application.

Background on Unity 3D Plugins

Unity 3D applications typically use C# (using the cross-platform Mono Framework) or JavaScript to express game logic, and to link these external function references into your Unity 3D script you would typically, in the case of C#, use the statements like the ones below. The directive DllImport has a peculiar name because C# originated on Windows and a DLL is a Dynamic Link Library (the Windows analogue to a shared library on BlackBerry 10). Notice that the name of the library to import is “BtHrmPlugin” rather than “libBtHrmPlugin.so”. Mono will try a variety of permutations of names as it tries to locate the underlying library and this gives an element of platform independence to naming of the plugin libraries.

So, all is looking good and we run the application on the BlackBerry 10 device:

Whoops! Bang! Something went wrong and we see a DllImportException when we look at the log file:

How annoying! So, how do you deal with this issue? Here’s what I’ve found to be a logical set of steps that I’ll outline below:

Ensure that the plugin is added to the correct path in the Unity 3D project.

Switch on Mono debugging via the bar-descriptor.xml file to understand what actual file names Mono is attempting to use to locate the shared library.

Switch on QNX dynamic library logging to understand how the underlying dlopen() service is searching for the shared library.

Ensure that the plugin is in the correct path in the Unity 3D project

This may seem obvious but it caught me out. Your plugin (libBtHrmPlugin.so in my case) needs to go here in your Unity 3D project’s Assets folder. It won’t be included in the project’s “.bar” file as an asset unless it goes here:

As a sanity check, you can check the “.bar” file, which you can find here:

Open the “.bar” file with a tool like “7-zip” and there it is in the “native\lib” folder. So, we verified that the plugin has been included in the “.bar” file as an asset and it will be installed onto the device as party of the application.

Check to see where Mono is looking for the file on the device

When Unity 3D builds a project for BlackBerry 10, it assembles all the project assets in a “StagingArea” folder. Here is where it’s located:

We’re interested in the “bar-descriptor.xml” file that is created by Unity 3D. The part of this file that is of interest to us is the following:

Here, the environment variable LD_LIBRARY_PATH, which determines the search location for shared libraries at run-time for BlackBerry 10 applications, is correctly set to include the “native/lib” path. If we add the following line to the “bar-descriptor.xml”, this will switch on additional logging when Mono tries to locate the shared library at run-time:

Then we need to rebuild the “.bar” file using the command line something like this, using “BlackBerry-nativepackager.bat”, since Unity 3D would just re-create the “bar-descriptor.xml” file if you used the Unity 3D IDE to rebuild the project. Notice we were careful to delete the old “.bar” file since we didn’t want it included in the new one.

If we install this on the device, again using, say, the “blackberry-deploy.bat” command line tool, we can look at the log once again. This time we see something like the following:

What we see now is that Mono is reporting on the various permutations of names that it is attempting to use from the base name of “BtHrmPlugin” to locate the underlying shared library file. Perhaps this is able to shed some light on why we’re seeing a problem? If not, then maybe the next step will help.

Switch on QNX dynamic library logging to see what QNX thinks is happening

We follow exactly the same process as in the previous section but add two additional statements, which are described in the QNX documentation for “dlopen()”, to the “bar-descriptor.xml” file, thus:

When we look at the log file this time, we see a lot of information regarding how the search for the unresolved external references is taking place. We see that the “libBtHrmPlugin.so” shared library is being located correctly in the “native/lib” folder in the application.

If we were to look in more detail, we’d see that the issue was not that the shared library was not found, but rather, there were unresolved external references in the shared library itself, which give rise to the “DllImportException” being reported. The real problem was back in the plugin NDK project itself:

The reference to the external library “libbtapi.so” (Bluetooth API library) was missing from the project’s link step! Remember that we’re building a shared library, and missing external references are quite legitimate at build-time since they would be resolved at run-time, but we still need to identify the external library to the linker when the project is built.

Adding this fixed the problem:

Summary

I hope that my own experience has given you some insight into how to logically track down this sort of issue in any Unity 3D plugin you may write, and how it could be used in a more general context to find the root cause of unresolved references in your application.

I’ll be following up this post with one on the Unity 3D Bluetooth Low Energy Heart Rate Monitor plugin I’m currently writing, so watch this space!

Additional Resources

If you want to know more about Bluetooth Low Energy, then look here at the index of material produced by John Murray and Martin Woolley.

]]>http://devblog.blackberry.com/2014/01/diary-of-a-unity-3d-newbie-solving-dllimportexception-errors/feed/0Diary of a 3D Newbie_5jcmurray2012Diary of a 3D Newbie_1Diary of a 3D Newbie_2Diary of a 3D Newbie_3Diary of a 3D Newbie_4Diary of a 3D Newbie_5Diary of a 3D Newbie_6Diary of a 3D Newbie_7Diary of a 3D Newbie_8Diary of a 3D Newbie_9Diary of a 3D Newbie_10Diary of a 3D Newbie_11Diary of a 3D Newbie_12Diary of a 3D Newbie_13Diary of a 3D Newbie_14Diary of a 3D Newbie_15Diary of a 3D Newbie_16BlackBerryBleExplorer: Bluetooth SIG App of the Monthhttp://devblog.blackberry.com/2014/01/blackberrybleexplorer-bluetooth-sig-app-of-the-month/
http://devblog.blackberry.com/2014/01/blackberrybleexplorer-bluetooth-sig-app-of-the-month/#commentsFri, 03 Jan 2014 20:00:03 +0000http://devblog.blackberry.com/?p=17166/ Read More]]>

Earlier this year, John Murray and I became involved with the Bluetooth Special Interest Group (AKA “Bluetooth SIG”). We’d been working with Bluetooth Smart, or “Low Energy” as it’s also known, for some time. You may have seen some of our work with Heart Rate Monitors, Cycling Speed and Cadence sensors, Key Finders, Proximity sensors and so on (links for more information on these projects are provided below). Our work came to the attention of Steve Hegenderfer, Director Developer Programs at the Bluetooth SIG, and we got talking about how we might collaborate. BlackBerry 10 has excellent support for both the older Bluetooth BR (Basic Rate) and the newer Bluetooth Low Energy, so this seemed like a great opportunity for both parties.

Bluetooth Developer Training Day, London

In September John and I presented at a Bluetooth Developer Training Day in London. We talked to a packed room of developers about the BlackBerry APIs, explaining how they map to the primary use cases of device discovery, reading characteristics, receiving notifications, writing to a characteristic and monitoring RSSI (Received Signal Strength Indicator). We even performed a live demo of an application that used a small family of cartoon chickens to illustrate the Bluetooth Proximity Profile, and how an application using our APIs could monitor the distance from the BlackBerry smart phone of a “precious item,” or something you don’t want to lose. A little eccentric? Maybe! But it made the point well, and it got a laugh out of our audience. :-)

The Bluetooth SIG Application Accelerator ProgramAfter our participation in the Bluetooth SIG’s successful developer training day and the evident high degree of interest in BlackBerry 10 that Bluetooth developers had shown, we were invited to contribute a reference application for inclusion in the Bluetooth SIG’s “Application Accelerator Program.” The functional specification for the application was provided by the Bluetooth SIG and was for a Bluetooth GATT explorer application, which can discover Bluetooth Low Energy devices and let you drill down through their GATT services and characteristics.

John and I set to work on the application and created BlackBerryBleExplorer, which you can download along with full source code from our GitHub repository (link provided below). In addition to demonstrating the use of BlackBerry 10 Bluetooth Low Energy APIs, we made good use of Cascades for the user interface and created a carousel-like, animated UI for browsing through and selecting devices and GATT services.

The Bluetooth SIG App of the Month

Today we learned that BlackBerryBleExplorer will be showcased as “App of the Month” on the Bluetooth SIG web site. John and I are pretty excited about this and appreciate the support and interest from Steve Hegenderfer and his colleagues at Bluetooth SIG.

Over to you
Bluetooth is a pervasive technology and its presence in devices is on the rise. From sports equipment to household appliances, Bluetooth is there. BlackBerry 10 has the APIs and you have the talent. So what are you waiting for? Grab our sample applications and create something amazing with BlackBerry 10 and Bluetooth Low Energy!

Just in time for the holidays, I now have a BlackBerry powered model railway in my living room!

I recently helped Tim Neil with Bluetooth control for parts of the BatBerry – which left me with the Arduino code and Cascades application I needed for this project.

On Father’s Day, my daughter declared the perfect gift for me would be a model train set. She gave me my first HO rolling stock train, and later in the year I bought a starter kit with an engine and some track. My family wanted to set up the train for the holidays, but we don’t have enough space for a loop track, so I bought hardware to make the train go up and down the same track.

I used a pine board as a base and covered it with white “snow” felt. I also used some spare LED lights to illuminate some of the houses and bought some micro-switches to use as limit switches (buffers) at either end of the line (yellow heat shrink visible in the photo above).Then I installed a pair of relays to cut and reverse power to the line and plugged them into an Arduino. I also updated the Cascades control application to be four-year-old friendly.

Using the BlackBerry app, my family can now send the train either direction or stop it completely. The train also automatically reverses after a gentle delay when it hits the limit switches.

I also built in controls for the lights in the four houses, with the choice between steady or a pretty flickering setting, plus a brightness setting.

The model functions without being connected to my BlackBerry as well; however, when I do connect, I have dynamic instant control over my train from anywhere in the room. It’s a lot of fun for the family and it will definitely be a new annual holiday tradition! Check out the video below for a demo:

Feel free to post your questions in the comments section below, and have a great New Year!

It is the year of “Sense, Understand, Adapt” here at BlackBerry. The capabilities of the BlackBerry 10 OS and APIs, together with its hardware, have propelled BlackBerry 10 and app developers into a world of IoT (Internet of Things). Built-in sensors and technologies like Bluetooth Low Energy (AKA Bluetooth Smart) give apps the ability to sense aspects of the physical environment, interpret environmental data and take action – adapting the application’s behavior and UI as things of interest change in that environment.

I teamed up with my BlackBerry Developer Relations colleague John Murray earlier this year to explore some of the BlackBerry 10 capabilities that make “Sense, Understand, Adapt” possible, in particular Bluetooth Low Energy and Near Field Communications (NFC).

In this blog post, we will discuss a specific environmental attribute that makes it possible to program your application to “sense” the world around it. That attribute is called proximity.

About Proximity

Proximity can mean different things in different contexts. Only last year, I was using the term “proximity gaming” to refer to games that leveraged NFC in game play by allowing physical interactions between players and their devices.

To some, “proximity” immediately conjures up the proximity sensor, which uses infrared light to detect objects that are near to the BlackBerry 10 device. It’s often used for face detection for example.

In this blog post however, we will focus on the Bluetooth Low Energy Proximity Profile.

The Bluetooth Low Energy Proximity Profile

The Proximity Profile enables us to monitor objects which we would hate to lose, and specifically to:

Be notified when the object has become too far away from us for comfort

Be notified when we’re so far away from our object that we’ve completely lost “sight” of it

Gain assistance when we have lost our object when we think it is still relatively close by

There are Bluetooth Low Energy devices on the market that use the Bluetooth Proximity Profile concerned with these use cases. For example, John and I obtained and worked with the Philips AEA1000 “smart leash,” a small rectangular device that you can either place inside a bag or attach to something via the rubber band it comes with.

Figure 1 – The Philips AEA1000 Smart Leash

The Proximity Profile – Roles

The Bluetooth SIG defines two roles with respect to the Proximity Profile.

Figure 2 – Proximity Roles

A Proximity Reporter like the Philips AEA1000 is a GATT server. A Proximity Monitor, on the other hand, is a device that works with the Proximity Reporter, keeping an eye on the status of the Proximity Reporter device. In our case, the Proximity Monitor is a BlackBerry 10 application. So we have a partnership here: with a Proximity Reporter device in your bag or attached to your keys, and a Proximity Monitor application running on your BlackBerry 10smartphone, you will never lose your precious things again!

In case you’re new to Bluetooth Low Energy, be aware that a “profile” is essentially a specification that defines things like the services (things a device can do) and characteristics (data) that a device has implemented and available. Read our Bluetooth Low Energy Primer if you want to know more about Bluetooth Low Energy and its key technical components such as “GATT.”

Figure 2 lists the services defined for the Proximity Profile reporter role. The dotted lines indicate an optional service. The only mandatory service in this profile is the Link Loss Service, but let’s briefly examine each of the three services in turn:

Link Loss Service: This service triggers an audible “alert” whenever the Bluetooth link to the monitor device is lost.

Immediate Alert Service: This service will trigger an audible alert whenever it is instructed to do so by the monitor device. In other words, it can respond to “Where are you?” queries with a beep or similar audio signal.

TX Power Service: This service exposes the reporter device’s current transmit power level when it’s in a connection.

The Philips AEA1000 implements all three of these services.

Exploiting the Proximity Profile

A Proximity Reporter like the Philips AEA1000 does the “sensing” for us, but it’s up to your BlackBerry 10 application to implement the “understand” and “adapt” behaviors. John and I set about developing an application that would do just that. The functional requirements were clear enough, but we wanted a UI that would stand out and convey the feeling of safe-guarding precious items. We brainstormed. We did everything possible to get the creative juices flowing like never before. John even stood on his head whilst holding a wet fish at one point [John: Yes, I can confirm that this is true!]. And yet despite all of our efforts and use of leading-edge creativity-enhancing techniques, *this* was the best we could come up with: chickens. Yes, CHICKENS!

A colleague had quite seriously asked if he could attach a proximity reporter to his children. We followed that thought through to its logical conclusion and substituted a brightly colored, cartoon metaphor. The Bluetooth Chicken Guardian was born!

Figure 3 – The BtChickenGuardian application

We’d successfully utilized chickens before; you may remember NFC Chicken. If not, check out this video (specifically around 20:05) and then come back and read on!

BtChickenGuardian implements all three use cases described above. It monitors your distance from the Proximity Reporter device with which it has been paired and gives a visual representation of distance falling into three bands: Near, Middle Distance and Far. In this case, “Far” is deemed “too far,” so the application indicates this with a distinct visual appearance and suitable sound effect. Now what noise would you expect a momma chicken to make when alarmed that one of her chicks has strayed too far away? Yes, the app makes that very noise. This is the very essence of “Understand” and “Adapt” in action!

Figure 4 – The BtChickenGuardian application

The Panic button exploits the Immediate Alert Service. When selected, we send a command over Bluetooth Low Energy which causes the Philips Proximity Reported to emit a loud tone which we can hear and thereby locate the lost item, be it a baby chick or otherwise. We’ve talked about the Immediate Alert Service in this blog post and this video in the past.

So how do we monitor distance? When we first connect to the Proximity Reporter, we query the TX Power Service. This returns a value which indicates, as a digital quantity, the power with which the Reporter device asserts that it is transmitting. We can then use this as a baseline to compare with the locally “experienced” signal strength that we receive.

However, we found that the TX Power Service didn’t work properly on the Philips device, no matter what third party tools we used to test it. So instead we gave our application a Settings page where the user can define signal strength thresholds, which are linked to our three distance bands of near, middle distance and far. It’s a simple approach which works in practice and which can be tuned by the user as they see fit.

So what does the code look like? Much of what we do in this application you’ve seen before, and of course the full BtChickenGuardian app has been released as open source in our GitHub repository. But one aspect of this application that is new is the monitoring of signal strength. Technically this is called the RSSI (Received Signal Strength Indicator) and monitoring its value is very easy as shown here.

As you can see, all we do is to kick off a background thread, and in that thread we periodically (once per second) read the RSSI value using API function bt_rdev_get_current_rssi. We communicate the current value to the UI by emitting a Qt signal, and if the signal indicates the distance has changed significantly, say from “middle distance” to “far,” we emit another signal so that the UI can change its appearance accordingly.

One last word on the technique used here. RSSI as a means of estimating distance is not particularly accurate because all sorts of environmental factors can affect RSSI. It’s good enough as a guide, and therefore fine for this type of application, but we wouldn’t recommend using it when pinpoint accuracy is needed.

Bluetooth Low Energy and BlackBerry 10: Sense. Understand. Adapt.

Bluetooth Low Energy and BlackBerry 10 partner well together. Your applications can exhibit smart behaviors by sensing what’s going on in the outside world, interpreting and understanding that data and adapting to it. All in all, your applications can significantly enhance the user’s experience and add real value by breaking out of the confines of the device they run on and connecting to the outside world.

As mobile computing drives forward, so does the potential to create a compelling experience by connecting with end-users in more meaningful ways; be it via heart rate monitor, finding lost items, or one of today’s most common accessories: gamepads.

The catalog of supported gamepads on the BlackBerry 10 platform is ever growing as our teams aim to support a wide variety of devices for the benefit of both developers and end-users.

However, the Bluetooth landscape can resemble the Wild West at times with proprietary implementations being chosen in favor of industry standards. This is why when developers ask us “Can you implement support for Gamepad XYZ?” sometimes the answer has to be “No.” It isn’t that it can’t be done, but targeting non-standard implementations requires resources for integration and maintenance, and leads to uncertainty whether that gamepad will work with specific OS builds and, if broken, when the implementation will be fixed.

What BlackBerry Looks For In a Gamepad

We wanted to share our criteria with developers so you can focus on those gamepads that will provide an A+ experience on our platform, helping to achieve both Built For BlackBerry and Gamepad Enabled status. This information will also be useful for end-users who are looking to purchase gamepads to complement their BlackBerry 10 devices.

There are two supported ways to connect a gamepad to a BlackBerry 10 device. The first is over Bluetooth using the Bluetooth Human Interface Device (HID) profile. Gamepads that leverage this profile can be paired to a BlackBerry 10 device running BlackBerry 10 OS version 10.1 or later, including:

BlackBerry Z30 smartphone

BlackBerry Z10 smartphone

BlackBerry Q10 smartphone

BlackBerry Q5 smartphone

The second connection method is using a direct USB connection that follows the USB On-The-Go (OTG) specification. In most cases this will require a Micro USB OTG to USB 2.0 adapter, in addition to a BlackBerry 10 device running BlackBerry 10 OS version 10.2 or later, including:

BlackBerry Z30 smartphone

For consistency, we are also focusing our efforts on gamepads that have analog Joystick controls. Gamepads that have only a Directional Pad (D-pad) may be supported, however for the full BlackBerry 10 experience analog joystick integration is the recommendation.

Supported Gamepads

Based on the criteria above, there are a number of gamepads today that enable the full BlackBerry 10 experience out-of-the-box.

The Android Runtime team has been hard at work this year, bringing many new improvements to the runtime, such as support for Jelly Bean 4.2.2, hardware acceleration and performance updates. The team is continuing the quest to improve the overall compatibility of the runtime and add support for many highly requested features and APIs.

Beginning in BlackBerry 10.2.1, increased compatibility improvements will now include:

Android Native Support: Android apps that use shared libraries written in native-code, such as C and C++, will now be supported on BlackBerry 10. Support is limited to the recommended system headers and APIs as documented by Google. Headers and APIs outside this scope may not function correctly.

Bluetooth: Android applications using Android Bluetooth APIs will now work on BlackBerry 10. Bluetooth Low Energy for Android is planned to be supported in a future OS release. As a reminder, Bluetooth LE is supported in the BlackBerry 10 Native/Cascades SDK.

MapView v1: Applications that use MapView from Google Maps v1 API are now supported using OpenStreetMaps. Support for MapView v2 API is being planned for a future release.

Share Framework: Android applications that register with the share framework in Android will now also appear as share targets on the BlackBerry 10 share menu.

Spellcheck: Applications that use text input can now leverage support for spell checking and correction, and the ability to add words to the BlackBerry 10 dictionary.

With the addition of all these new APIs, support for a greater range of ported Android applications will be possible. If you’ve been waiting for some of these features for your application, the wait is almost over! A BlackBerry 10.2.1 SDK OS will be arriving soon and you’ll be able to start testing and submitting your application to BlackBerry World!

In addition to all these new features and APIs, a new Beta release of the BlackBerry Tools for Android development will also be coming soon. This release will not only include support for these new features (no more warnings for features now supported) but will also include any bug fixes from the previous beta.

Did you know that you can connect your gamepad to a BlackBerry 10 smartphone connected to a large screen TV to give your mobile app a game console experience? Attendees at recent game developer conferences have experienced this functionality first hand and they were blown away by the quality of the gaming.

“Shadowgun for BlackBerry 10 is a perfect example of how gamepad support can elevate the mobile game experience. Simple gamepad integration, a gamepad and HDMI connection turns your BlackBerry 10 smartphone into a console gaming system and as we’ve witnessed with Shadowgun—people are loving it!” – Marek Rabas of Madfinger Games

Just add gamepad support

Our latest promotion gives you the opportunity to earn two free gamepads and increased visibility in BlackBerry World. All you need to do is enable gamepad-support for your game. Simply submit your gamepad-enabled game in draft mode to BlackBerry World and you will qualify to receive a free Gamepad Package, consisting of a MOGA Pro controller and a SteelSeries controller. As a bonus, when you complete your game and it’s approved, we will add it to our gamepad-enabled feature in BlackBerry World, making it easier to discover your app.

How to add gamepad support

It’s very easy to add gamepad support because the BlackBerry 10.2 Native SDK adds a hardware abstraction layer. No need to worry which gamepad controller the end user prefers, BlackBerry takes care of that.

Identify your app as gamepad enabled. Add the <permission>use_gamepad</permission> into your bar-descriptor to ensure BlackBerry World finds your application as gamepad enabled. If you’re using Unity, be sure to add “Gamepad” into the submission keywords for BlackBerry World.

Use the new gamepad functionality using screen library for new gamepad events and for polling analog joystick and button state values.

Ensure your gamepad support works right out of the gate with default button configuration in place on all menus and within gameplay

Click here for a full description on how to add gamepad support to your app.

Important Note: You must use the BlackBerry Native SDK 10.2 and target BlackBerry OS 10.1 and above.

This program runs from September 24, 2013 until December 24, 2013. In order to receive the free Gamepad Package, you need to be one of the first 250 to submit your draft game to BlackBerry World. Check out all of the Terms and Conditions to get the whole scoop.

]]>http://devblog.blackberry.com/2013/09/gamepad-support-rewards/feed/0lgazzolaTITLE_IMAGEBlackBerry Jam Unplugged: Connectivityhttp://devblog.blackberry.com/2013/05/blackberry-jam-unplugged-connectivity/
http://devblog.blackberry.com/2013/05/blackberry-jam-unplugged-connectivity/#commentsThu, 09 May 2013 01:25:34 +0000http://devblog.blackberry.com/?p=14873/ Read More]]>We’ve now posted the final episode of the BlackBerry Jam Unplugged series where we learn a little more about connecting to the world around you with BlackBerry 10.

I hope you’ve enjoyed the series and we look forward to seeing you all at BlackBerry Jam Americas in Orlando. Please let us know what you thought of the videos to ensure that we can bring information to you in a way that’s educational, but entertaining as well.

This particular video will give you some information about the current opportunities and upcoming roadmap items that we’re looking at for extending connectivity for developers. In this video we’re joined by Rob Williams who talks about how you can connect BlackBerry 10 to the world around you to incorporate context into your apps.

]]>http://devblog.blackberry.com/2013/05/blackberry-jam-unplugged-connectivity/feed/0timneil1BlackBerry Jam Unplugged: Gaminghttp://devblog.blackberry.com/2013/05/blackberry-jam-unplugged-gaming/
http://devblog.blackberry.com/2013/05/blackberry-jam-unplugged-gaming/#commentsTue, 07 May 2013 08:00:13 +0000http://devblog.blackberry.com/?p=14877/ Read More]]>After a bit of a struggle, no thanks to our interviewee Dale, we now have the latest episode of the BlackBerry Jam Unplugged series ready where we learn more about gaming on BlackBerry 10.

We’ll be posting videos as part of this series leading up to BlackBerry Jam Americas in Orlando in order to give some more background surrounding the topics that we’ll be discussing in detail during the conference.

In this video we’re joined by Dale Ducharme (against his will) to talk about the cool features available for gaming developers on BlackBerry 10.

So, we thought we’d try a little bit of BlackBerry 10 Bluetooth Low Energy (LE) magic to help us. This follows on nicely from my previous Blog post on the Internet of Things and the model is more widely applicable than just finding lost keys. In fact, if you haven’t already done so, this is probably a good time to have a read of that blog post and article since it covers the basic concepts needed in this blog post.

Go on … I’ll wait and have a cup of tea.

Ah, ok, you’re back … right, let’s continue.

The first thing we did was to do a little bit of research to see if the Bluetooth SIG had set any standards in this area; no point in re-inventing the wheel and the existence of a standard would mean that a vendor may have already implemented the technology in a product.

Browsing through the GATT Profiles we came upon this one: Find Me … this sounded promising!

To quote the Abstract for the Find Me profile, “The Find Me profile defines the behavior when a button is pressed on one device to cause an alerting signal on a peer device”. An image formed in our minds immediately!

A closer look shows that this profile implemented a GATT Service called Immediate Alert which used a GATT Characteristic called Alert Level … this looked a perfect match.

Here’s the description of the Alert Level Characteristic.

Alert Level Characteristic

It’s an 8-bit unsigned integer that can take on three values signifying:

No Alert

Mild Alert

High Alert

The interpretation of these Alert Levels is the responsibility of the device that implements this characteristic.

Having found the Bluetooth LE Profile that matched our requirements the next step was to find a simple device that implemented it.

We found this one (see Figure 2) from Texas Instruments[1]. As well as supporting the Find Me profile it also allows re-programming with other Bluetooth services.

Texas Instruments CC2540/41 Mini Development Kit

Out of interest, I used one of the tools ( BTool ) that came with the key-fob to examine the GATT services that this device supported. Here’s a screen shot:

GATT Services present on the key-fob

So, you can see the highlighted red box clearly shows the Immediate Alert Service which has UUID 0x1802 (integers are represented in little-endian order so 0x1802 is represented as 02:18) and the Alert Level Characteristic which has UUID 0x2A06. Notice that the value field of the Alert Level characteristic has been assigned a handle of 0x0028 – handles are discovered by and used by applications to access fields in the GATT Service list and they’ve been covered in a previous blog post and article.

The application that we developed based on this is actually very similar in structure to the Heart Rate Monitor application that was described in a previous blog and article. The basic logic is the same:

Pair the Bluetooth LE device with the BlackBerry 10 handset before using the application.

Launch the application which:

Discovers devices that support the Immediate Alert Service

Connects to a discovered device selected by the user

Offers the user the choice of Alert Levels ( Off, Mild and High) to be sent to the device

Here are some screenshots showing what the application looks like:

Screens from the application

You can see that the buttons at the top of the screen become enabled only once the application has connected to the Immediate Alert Service on the key-fob. If you select the “High” option this device will emit a loud buzzing sound and flash a green LED.

Application Sending an Alert to key-fob

This is the application in action. If you use your imagination you can hear the buzzing and I can find my keys!

The key part of the application is where the Alert Level is sent to the device. Here’s the section of code that does this:

You can see that we’ve already connected to the Immediate Alert Service and have a reference to this in the variable _serviceInstance; we also have a handle to the Alert Level characteristic value _alertLevelValueHandle. The API used is bt_gatt_write_value_noresp()which means that the Alert Level (level) is written to the device and no acknowledgement is expected in return.

Wait, I hear you say! How did you know that you had to use a Write without Response to write the Alert Level value to the device? Well, it’s part of the definition of the Immediate Alert Service. Here (Figure 6) is the definition of the Alert Level characteristic from the definition of the Immediate Alert Service. It says that this characteristic can be accessed only though the Write without Response request.

Immediate Alert Service Alert Level Characteristic Properties

And, just to confirm that the device understands and enforces this as well, Figure 7 shows this value in the GATT‘s entry for the Alert Level characteristic – the value 0x04 in the green box is the encoding of this property.

Characteristic Properties of the Alert Level

We made a video which has Martin (@mdwrim) showing the application in action and explaining the code. Here it is:

I hope you’ve enjoyed this short note and hope it has piqued your interest to find out more about Bluetooth Low Energy and how it can be integrated into your BlackBerry 10 applications.

[1] This should not be regarded as an endorsement by BlackBerry, explicit or implied.

]]>http://devblog.blackberry.com/2013/04/dude-wheres-my-car-keys-bluetooth-le-and-blackberry-10-how-to/feed/0jcmurray2012dudeTITLE_IMAGEdude3dude4dude5Application Sending an Alert to key-fobdude7Characteristic Properties of the Alert LevelBluetooth Low Energy and the Internet of Thingshttp://devblog.blackberry.com/2013/04/bluetooth-low-energy-and-the-internet-of-things/
http://devblog.blackberry.com/2013/04/bluetooth-low-energy-and-the-internet-of-things/#commentsMon, 08 Apr 2013 14:50:27 +0000http://devblog.blackberry.com/?p=14532/ Read More]]>Having spent some time looking at Near Field Communication (NFC), my colleague Martin Woolley (@mdwrim) and I (@jcmrim) became really excited when we came across the new Bluetooth Low Energy APIs in BlackBerry 10.

“Bluetooth Low Energy”, I hear you say. ”I know all about Bluetooth since that’s been around for many years. It’s what I use to connect my headset to my BlackBerry device and play music though my sound system. What’s this ‘Low Energy’ thing?”

Well, the Bluetooth specification went through a number of changes a couple of years ago when Bluetooth 4.0 was released. Bluetooth Low Energy (LE) is an addition to the classic specification that allows ultra low power devices to participate in Bluetooth Networks.

What does “Ultra low power” mean? Well, Bluetooth LE is designed to support devices that would typically be powered by battery cells like the one in this picture.

That means that such devices can have incredibly small footprints yet can be full participants in a Bluetooth network alongside larger devices like tablets or smart phones such as BlackBerry 10 smartphones.

It also means that this awesome technology is an enabler for the “Internet of things” where such devices can participate in an Internet populated with all sorts and sizes of devices ranging from large servers to intelligent thermometers; from tablets to intelligent sensors in your running shoes; from mobile phones to intelligent light switches in your home.

Imagine being able to use your BlackBerry 10 smartphone to tailor your environment to your preferences as you move around. It’s already capable of knowing where you are and Bluetooth LE gives it the capability of communicating with smart devices in your home or car. Imagine returning home and having your BlackBerry 10 smartphone communicate with your lighting to set it appropriately; your home entertainment system to play your favourite playlist; and your house’s environmental controls to set just the right temperature!

The diversity of potential applications is quite staggering. Sports, wearable devices, home automation, automotive and healthcare, are just a few of the sectors recognising the potential of Bluetooth LE.

And … BlackBerry 10 is a perfect fit here! So, we got to thinking how we could demonstrate how easy it is to integrate Bluetooth LE technology into your BlackBerry 10 application!

In order to provide some focus for this activity we acquired some Bluetooth LE technology and tools including a Wahoo Blue HR device to see what we could do with it. There are a number of similar devices on the market but this seemed like a good starting point. It’s a small, lightweight electronic device, encased in plastic. It has an adjustable strap to allow you to strap it around your chest and the strap has two conductive pads which need to be in contact with the skin.

The nice thing about Bluetooth LE is that there are standards for devices like this that support what’s called the Heart Rate Profile and we managed to develop a nice, even though I say it myself, self contained BlackBerry 10 application that interacted with the heart rate monitor and displayed it’s data.

Take a look at the images below! The image on the left shows a typical trace for a healthy person like Martin who went on a long, exhausting bike ride to gather this data.

The middle one is probably from a small, hyperactive animal like this hamster; whilst the one on the right probably comes from a hibernating hedgehog I came across in my garden.

Rest assured that no small timid animals were involved in our testing other than in our imaginations!

If you want to know more then check out the following resources:

A much more detailed article describing the theory and practice behind this application