Friday, 29 July 2016

Sending 'commands' from a micro:bit over Bluetooth

I got asked how you might use Bluetooth to send 'commands' from a micro:bit to another Bluetooth enabled device.

First read my blog on what kind of Bluetooth device can 'talk' to what kind of other device.

micro:bit has the concept of "events" which are things we can use as though they are numeric commands. An event has an ID and a value. Each are 16 bits in length so an event is a total of 32 bits long.

The micro:bit has something called the Event Service and this allows events to flow in either direction between the micro:bit and something else like a smartphone.

The Microsoft PXT tool lets you create your own event values and trigger them from anything you like in your code.

So these are our basic ingredients.

Let's walk through an example.

First, check out this application I created in PXT


You can fork the code itself here: https://makecode.microbit.org/_PUaidt6ub1Rm

You can see I create an event ID of 9010 and two associated event values of 1 and 2. I also keep track of whether or not we have a Bluetooth connection in a variable called 'connected'

Then, if the user presses button A we create an event with ID 9010 and event value 01. If the user presses button B we create an event with ID 9010 and event value 02.

That's all we need to do on the micro:bit side of things.

On the other device we have to send the micro:bit the event ID and values we're interested in being notified about if they occur.

Here's what the micro:bit Bluetooth Event Service looks like. It will help when we look at how to test this code from a smartphone next.


The blobs are called "characteristics" and they're like data items or variables that have particular purposes. Client Requirements contains a list of one or more event IDs and event values that the client (i.e. the other device) has said it's interested in. MicroBit Event contains the event ID and value of the most recent event that has happened on the micro:bit.

There's a great smartphone app for Android and iOS that lets you explore and test Bluetooth communication called nRF Connect. I'll walk through how I tested my PXT code using screenshots to illustrate:


Note: I've paired my micro:bit and phone. This is essential as at the time of writing both PXT and the microbit.co.uk tools produce code which requires your micro:bit to be paired if you're going to use Bluetooth. Here's how to pair with an iOS device and here's how to pair with Android.

There's nRF Connect on my Android phone. I launch it and it automatically scans for advertising Bluetooth devices and finds my micro:bit.


I click CONNECT to have the phone connect to the micro:bit.This gives me the next screen which shows the Bluetooth services on the micro:bit. Most were custom designed for the micro:bit so nRF Connect does not know their names.


The UUIDs are unique identifiers. The highlighted one is the event service. You can see the UUID shown here is the same as the one in the Event Service graphic above. Selecting the service causes it to expand so we can see its characteristics:


The two we're interested in are highlighted in green. 9775 is the MicroBit Event characteristic. 23C4 is the Client Requirements characteristic. The next job is to write to the Client Requirements characteristic using nRF Connect. This will transmit the value we enter to the micro:bit, effectively saying "Hey, if one of these events happens, please tell me". You start a Write operation by selecting the upwards pointing arrow icon next to the characteristic and this causes a dialogue to appear:


The second field is a drop down data type selector. I have it set to BYTE ARRAY. The value is in hex and needs some explanation. The first two bytes are the event ID of 9010. The second is the event value but 0000 means "any event values with the specified event ID". 9010 is not 0x3223 in hex though, it's 0x2332! micro:bit, in common with many other devices likes its data to arrive or be sent over comms links in 'little endian format'. So the least significant bytes come first as we read left to right and this is why we're sending 0x3223.

Now that the micro:bit knows what we're interested in, we also have to switch on "notifications" relating to the MicroBit Event characteristic. This just tells Bluetooth on the micro:bit to send the phone a message if its value changes. And it will change if one of the events we just said we were interested in happens.


Notifications are enabled by selecting the icon with multiple downward pointing arrows next to the MicroBit Event characteristic as shown.

All that's left now is to test! Pressing first button A and then button B causes the value of the MicroBit Event characteristic to change as the data is received over Bluetooth from the micro:bit. Your own code on a phone or other Central mode Bluetooth device could respond to these events anyway you choose.


That's the result of pressing Button A. Event ID 0x3234 (9010) and Event Value 0x0100 which of course is ID 9010 and value 01 in little endian format.

And button B produces....


the same result but this time the value is 02.

Simples!

Code it. Connect it. Bitty Software.

micro:bit and Bluetooth 'roles'

Bluetooth devices will play one of 4 possible Bluetooth roles as defined by that masterpiece, the Bluetooth core specification. The four roles are called
  1. Peripheral
  2. Central
  3. Broadcaster
  4. Observer
These terms are part of "GAP", the Generic Access Profile, which is a part of the Bluetooth architecture.

A Peripheral advertises, inviting and (perhaps) accepting connections from Central devices. 'Advertising' means transmitting small amounts of data, quite frequently, which other Bluetooth devices can receive and act upon if they think the advertising device is of interest.

A Central device scans, looking for advertising packets and based on their content, may decide to connect to a device it thinks is suitable.

A Broadcaster is like a peripheral in that it advertises but it does not accept connections. It's sole purpose is to advertise.

An Observer scans and processes advertising packets but never tries to connect to another device.

Examples:

The BBC micro:bit is a Peripheral.

A smartphone is typically a Central but some newer devices can also act as Peripherals with the right application software running.

A Bluetooth beacon (iBeacon, AltBeacon, EddyStone and so on) is a Broadcaster.

A beacon application on a smartphone which alerts you to special offers broadcast by beacons for example, is an Observer.

A Peripheral cannot create connections, only accept them. Therefore a Peripheral cannot connect to another Peripheral. A Peripheral cannot scan for advertising packets from other devices, only transmit them. Therefore two Peripherals cannot interact using advertising data only.

The outcome of this is that one micro:bit cannot talk to another micro:bit *directly* using Bluetooth. You'd need a Central mode device acting as a hub and relaying messages between micro:bits.  My Heart Rate Monitor video shows a smartphone acting as a Central hub which is connected to two Peripherals, a BBC micro:bit and a heart rate monitor.

Technically, a device like the BBC micro:bit could have the ability to be either (or both) a Peripheral and a Central but there's just not enough memory available on the micro:bit to squeeze the larger Bluetooth stack that would be required to support both GAP roles. Maybe as and when there's a 32K micro:bit (complete conjecture / wishful thinking!) this will happen.

That's it. An introduction to Bluetooth GAP roles and their relevance to BBC micro:bit. Amaze your friends at your next dinner party ;-)

Code it. Connect it. Bitty Software.

Implementing a Buggy controller using Microsoft's PXT tool

Ages ago I wrote the code needed to control a Kitronix buggy with a micro:bit which is itself being sent commands over Bluetooth from my microbit Blue Android application. You can see it and the C/C++ code here.

Microsoft released their amazing PXT tool fairly recently. It's fantastically flexible and you can fully exploit Bluetooth very easily. I reimplemented by buggy controller code using PXT and the results are here.

In fact I also published the project so if you want to fork it and have play, here's the URL:

https://codethemicrobit.com/rurfubdeav