Common Issues and Questions

Bluetooth problems? Check our micro:bit Bluetooth troubleshooting guide!

When you're writing code, you'll soon find there are certain things you have to deal with again and again in many different applications. So it makes sense to describe common concepts, issues and tasks in one place rather than repeat them in every tutorial and that's precisely what this page is about!

common issues

  1. My Bitty Software application is not working!
  2. How to create a hex file which does not need pairing
  3. How to build and install your code
  4. micro:bit events
  5. How to track the state of Bluetooth connections to the micro:bit
  6. Responding to the micro:bit buttons
  7. Bluetooth pairing
  8. micro:bit Blue is not working
  9. micro:bit Blue says the Bluetooth services it needs are not present

1. My Bitty Software application is not working!

Welcome to the black art of software problems and troubleshooting. In every problem lies an opportunity or so the saying has it. So if your smartphone application is not responding to your micro:bit the way it's supposed to, here are some things to try.

(a) Check your micro:bit code

If you developed the micro:bit code yourself, maybe it has a bug. It's possible and all part of developing software. All developers create bugs in their code all the time. The thing to do when this happens to you is just roll up your sleeves and be systematic in figuring out where the problem lies.

The easiest way to determine whether or not the problem is with your micro:bit code is to copy the standard hex file which you can download from the downloads page onto your micro:bit and test again. If it still doesn't work then the issue is not with your micro:bit code.

(b) Do you need to pair? Have you paired?

If you installed a hex file which requires pairing then you *must* pair your phone or tablet with the micro:bit before things will work. Watch one of the how to pair videos and make sure you follow the steps carefully. We also talk about pairing elsewhere on this page.

Whether or not your hex file requires you to pair is *entirely* controlled by code. Both PXT and C/C++ let you choose whether or not pairing is required. For example, here's how to switch pairing off using C/C++.

We also supply hex files which do not need you to pair and again, these are on the downloads page. If you need to pair again or decide to use a hex file which does not require pairing, go into Settings on your phone and remove the existing pairing record. On Android this involves selecting the entry for your micro:bit and selecting "Forget" for example.

(c) Perhaps you don't need to pair but your phone thinks you have?

Whether or not you need to pair depends entirely on the hex file (i.e. the code) you install on your micro:bit. Critically however, if you install a hex file that does not require pairing then your phone must not think it is paired with the micro:bit, typically due to you having paired with the same micro:bit on a previous occasion. So if you install a "no pairing required" hex file, you should also check Settings / Bluetooth on your phone and if your micro:bit is listed there as Paired, use the Forget function to clear it. The golden rule is that both phone and micro:bit must have the same status regarding pairing

(d) Pairing is about two devices and both must agree on their state

If you installed a hex file which requires pairing then *both* micro:bit and phone need to be in the same, paired state. So there are two situations where things can go wrong in this respect:

1. if you pair successfully, then flash new code (which will destroy the pairing data on your micro:bit), your phone will think it's paired, but your micro:bit will not.

2. if you pair successfully, then "Forget" the pairing on your phone, your micro:bit will think it's paired, but your phone will not.

In either case, applications will then not work properly.

To resolve such problems, flash your hex file again and "Forget" the pairing on your phone so that both micro:bit and phone consider themselves to be "unpaired" and then pair again.

(e) Has your micro:bit got the right services on it?

Bluetooth services are part of your micro:bit's code. A "service" lets some aspect of your micro:bit be used over Bluetooth. For example, the Button Service lets a smartphone receive messages whenever a button is pressed or released. The Accelerometer Service allows motion data to be transmitted from the micro:bit to the smartphone. And so on. If you need certain Bluetooth capabilities, then the appropriate Bluetooth service must have been included in the micro:bit code. If not.... it won't work.

Some applications will display an error message if it seems as though the micro:bit does not have a hex file on it which includes the Bluetooth services which the application needs. If this happens then the first and obvious thing to do is to check you have the right hex file installed. Copy your hex file again or download a hex file you know to be the right one and install that. Don't forget that installing a hex file will wipe your pairing details so if you did pair and this hex file requires pairing, you'll have to forget the pairing on the phone and pair again.

If you're certain that the hex file contains the required services but are still seeing an error that indicates the phone disagrees, there's one other possibility.

Sometimes a smartphone will ask the micro:bit what services it has, the first time they connect to each other and the smartphone will store these details so that the next time they connect, it doesn't have to ask again. This is called Service Caching. If you change the services on your micro:bit by installing a new hex file, this can confuse some phones. It shouldn't. The Bluetooth specification does define how this should work, but some phones don't handle this correctly. So your phone can think you have one set of services when in fact you have another. Here's how to solve this:

On Android, install the nRF Connect smartphone application from Google Play. Scan and find your micro:bit. Connect to it. Select Refresh Services from the menu. Disconnect and try your Bitty Software application again.

On iOS: There's no way to Refresh Services using nRF Connect on iOS. Instead, Forget the pairing. Switch off Bluetooth. Switch it on again. Pair again. Test again.

(f) Has your phone gone wonky?

Despite the monumental effort that goes into ensuring Bluetooth 'just works' on every device it's used on (and fyi over 3 billion new devices had Bluetooth on them in 2015. That's a lot!), sometimes there are problems with the way it is implemented by the manufacturer of the device. So if all else fails, try switching Bluetooth off, wait 5 seconds and then switch it on again. If that does not help, reboot your phone and try again.

(g) Twitter

We're on Twitter so follow us and tweet us a message and we'll see if we can help! Do try to solve the problem yourself first though. It really is the best way to learn.

(h) Email

Email details of your problem, including what type of device you are using (and in particular whether it runs iOS or Android) and a step by step description of how to recreate the problem you're having and we'll try to assist. Send the hex file you're using on the micro:bit as well. Screenshots can really help. Better still, create a short video showing your problem and send a link to it (don't send the video file itself). Here's the support email address:

Working through a tutorial? Resume now by clicking your browser's Back button


2. create a hex file which does not need pairing

Most of our applications involve Bluetooth. Depending on how you build your micro:bit code, you may or may not need to pair your micro:bit with your phone or tablet before using it. Every time you change your micro:bit code and install it on your micro:bit, you'll need to pair again. This is clearly not very convenient when you're developing. So our recommendation is to build your hex file in such a way that pairing will not be necessary. When you've finished developing, if you think pairing is beneficial (for example this will stop someone else from connecting to your micro:bit) then you can do one final build, this time with pairing enabled.

Here's how to build a hex file which does not need pairing:

Download this config.json file and save it in your microbit-samples folder. Rename it to config.json.

Open config.json in a text editor. There are two properties which are related to pairing: 'pairing_mode' and 'open'. The 'open' property needs to have a value of 1 to ensure pairing is not needed. Strictly speaking, that's all we need to do. But 'pairing_mode' controls whether or not you can switch your micro:bit into pairing mode and since we will not need this, we set its value to 0 so that pairing mode is not available.

Working through a tutorial? Resume now by clicking your browser's Back button


3. build and install

C/C++ code must be converted into a binary 'hex file' before it can be copied onto a micro:bit. We build C/C++ code using the Yotta command line tools.

yt clean
yt build

Your Yotta window should look something like this:

The result of the build process is a 'hex file' called microbit-samples-combined.hex which will be in the build\bbc-microbit-classic-gcc\source folder. Plug your micro:bit into your computer using a USB cable and make a note of the drive letter assigned to it when the file system window pops up. On Windows it will look like this but the drive letter may vary:

Copy your hex file to the micro:bit like this (remember to use whatever drive letter your computer assigned to the micro:bit)

copy build\bbc-microbit-classic-gcc\source\microbit-samples-combined.hex g:

The yellow LED on the underside of your micro:bit will flash while code is being copied to it. When the yellow LED stops flashing, your code has been installed.

Working through a tutorial? Resume now by clicking your browser's Back button


4. micro:bit events

In the world of computer programming, an 'event' is a piece of data which indicates and describes *something* which has happened and which some part of the software might want to know about. For example, pressing a button on the micro:bit could (and does!) generate an event which means "Button A was pressed and held down". Releasing the same button would generate an event meaning "Button A is no longer being pressed".

Our code can say what kinds of events it is interested in being told about by the micro:bit and it can also generate events of its own. This last point is particularly exciting because it means we can create code which communicates with other parts of the micro:bit simply by generating the right events with the right values inside them.

But better still, micro:bit has a Bluetooth 'service' called the Event Service which means that events can flow out of the micro:bit to another, connected device or in the other direction, from the connected device to the micro:bit.

Working through a tutorial? Resume now by clicking your browser's Back button


5. keeping track of bluetooth connections

Many of our apps use Bluetooth for communication between the micro:bit and the mobile app. Before any communication can take place, the mobile device must connect to the micro:bit. micro:bit code often needs to keep track of whether or not something is connected by Bluetooth to it and then use this information in some of its main logic. Let's look at the kind of code which is needed to accomplish Bluetooth connection tracking.

First we need to indicate that we want our code to be told whenever a Bluetooth connection is created or lost (disconnection). The following code in the main() function right near the beginning, perhaps after displaying a start-up message, will do just that:

uBit.messageBus.listen(MICROBIT_ID_BLE, MICROBIT_BLE_EVT_CONNECTED, onConnected);
uBit.messageBus.listen(MICROBIT_ID_BLE, MICROBIT_BLE_EVT_DISCONNECTED, onDisconnected);

In short, we have simply said:

  1. Run the code function 'onConnected' if something connects to the micro:bit using Bluetooth
  2. Run the code function 'onDisconnected' if a device which was connected to the micro:bit using Bluetooth disconnects

Let's take a moment though, to fully understand those two lines of code.

micro:bit (or uBit as it's referred to here in this code) has a thing called a message bus. It's what events travel along to get from the place where the event occurred (e.g. the button which was pressed) to those places where there's a need to know that the event occurred (e.g. your code because you've said you want to know about this type of event).

Each of these lines of code says "Please tell me if a Bluetooth event occurs" because 'MICROBIT_ID_BLE' is an event ID which all Bluetooth related events will have.

The first line is more specific though and goes on to say "but only tell me if the specific type of Bluetooth event is one meaning that micro:bit was just connected to by something else over Bluetooth".

The second line is very similar but says the interest is in events meaning that something has disconnected from the micro:bit.

So as you have probably realised, the second of the three parameters (the things inside the brackets) is an event value and you can see that MICROBIT_BLE_EVT_CONNECTED means "a Bluetooth connection was established" and MICROBIT_BLE_EVT_DISCONNECTED means "the other device disconnected from the micro:bit".

This just leaves the third parameter. We have to indicate what code to execute should one of these events actually happen. In the first case we're saying "please run the code function called onConnected" and in the second line we're saying "please run the code function called onDisconnected".

Now the functions 'onConnected' and 'onDisconnected' don't automatically exist. We have to create them. Let's see how we might approach that.

Adding this code above the line containing 'int main()' is how you might proceed:

int connected = 0;

void onConnected(MicroBitEvent)
{
    uBit.display.print("C");
    connected = 1;
}

void onDisconnected(MicroBitEvent)
{
    uBit.display.print("D");
    connected = 0;
}

The onConnected and onDisconnected functions are called 'event handlers' because they get sent events and... handle them!

Now, if a device connects to our micro:bit using Bluetooth, the micro:bit display will show a letter "C" and if it then disconnects it will show a letter "D". This allows us to know at a glance whether or not something is connected to the micro:bit and this can be really useful, especially when we're testing. Note that we also set a variable called 'connected' to 1 when we have a connection and 0 when disconnected. We can use that variable in other logic of course.

Working through a tutorial? Resume now by clicking your browser's Back button


6. responding to the micro:bit buttons

micro:bit has two incredibly useful buttons on its front panel called Button A and Button B. Many of your micro:bit applications will use these buttons. Let's take a look at the basics of button use.

Pressing or releasing buttons generates 'events'. Read all about events above. We can program the micro:bit to listen for and respond to button events. Here's an example:

// this code goes in the main() function near the beginning
uBit.messageBus.listen(MICROBIT_ID_BUTTON_A, MICROBIT_BUTTON_EVT_CLICK, onButton);
uBit.messageBus.listen(MICROBIT_ID_BUTTON_B, MICROBIT_BUTTON_EVT_CLICK, onButton);
uBit.messageBus.listen(MICROBIT_ID_BUTTON_AB, MICROBIT_BUTTON_EVT_CLICK, onButton);

Notice we're using one event handler called onButton for all three types of button event. We can check what sort of button event happened in the event handler code because it gets passed the event itself as a parameter.

// this code goes above and outside of the main() function
void onButton(MicroBitEvent e)
{
    if (e.source == MICROBIT_ID_BUTTON_A) {
        uBit.display.print("A");
    }

    if (e.source == MICROBIT_ID_BUTTON_B) {
        uBit.display.print("B");
    }

    if (e.source == MICROBIT_ID_BUTTON_AB) {
        uBit.display.print("AB");
    }
}

All we do in the onButton event handler in this example is use an 'if' statement to check the type of event we have (i.e. where the event came from) and use that to decide to display "A" for Button A, "B" for Button B or "AB" if both buttons were pressed.

For more information on ways to work with micro:bit buttons, take a look at the documentation page for the message bus.

Working through a tutorial? Resume now by clicking your browser's Back button


7. Bluetooth pairing

Bluetooth has a feature called 'pairing'. It causes two devices to trust and know about each other. For example, you might pair your micro:bit with an Android phone. Whether you need to pair or not depends on the hex file your micro:bit has installed on it. Usually you will need to pair. We provided versions of all hex files on our downloads page in both forms i.e. one which requires pairing and one which does not. If you do need to pair, check out our videos page for demonstrations of how to go about pairing your device. Note that every time you copy new code to your micro:bit you will need to pair your micro:bit and device again.

8. micro:bit Blue is not working

Your microbit needs to have the right software installed on it for it to work with the micro:bit Blue application.

Go to this web page and download the hex file named "For micro:bit Blue - Main Bluetooth services, pairing not required". Plug your micro:bit into your computer with a USB cable. A Window should open with what looks like a drive named "D:" or "E:" or similar. Copy the hex file onto this drive. The yellow light on the micro:bit next to the reset button should flash. The indicates that the hex file is being copied onto your micro:bit.

On your phone, go into Settings, then Bluetooth and if your micro:bit is listed there, select "Forget" to clear the micro:bit from the list.

Now launch micro:bit Blue and on the first screen with the "Find..." button, go into the menu and select Settings. Where it says "Filter unpaired micro:bits...." clear the check box. We have not paired your micro:bit so we do not want to filter it from the list.

Select Save.

Now select the FIND... button. You should see your micro:bit listed. Select it.

At the next screen with all the icons, go into the menu and select Bluetooth Services. All services should be listed in green except for DFU Control Service, Event Service and UART Service. If that's not what you see, read the next item in this FAQ. Otherwise, select Back.

Now test the various icons. Some of them require special hex files and will not work. You'll see a message indicating that the Event Service or the UART Service is not present. This is expected. See http://bluetooth-mdw.blogspot.co.uk/p/bbc-microbit.html if you want to try those functions.

9. micro:bit Blue says it does not have the right Bluetooth services

micro:bit Blue requires your micro:bit to be running software that includes certain "services". For most functions, the micro:bit Blue download file listed in the downloads page here on the bittysoftware.com site is all you need. For some, such as the Animal, Vegetable, Mineral guessing game, you need different code. See here for alternative hex files.

If the Bluetooth Services screen indicates that services other than those listed in the previous FAQ item are missing, then there are only two possibilities:

1. You've installed the wrong hex file on your micro:bit. Check and double check this.

2. You've installed the right hex file but your phone doesn't realise the Bluetooth services your micro:bit has have changed since the last time the two devices were connected. Phones will cache details of Bluetooth services so that they don't have to discover them each time they connect to a particular device. For most devices this makes perfect sense since their services will never change. For a programmable device like a micro:bit however, this isn't the case. So you may need to hint to your phone that it needs to retrieve up to date details of the Bluetooth services on the micro:bit for it to have correct information. To do this, first try the Refresh Services function which is in the menu on the micro:bit Blue screen which has all the demo icons listed. If this does not work for you, download and install the free application 'nRF Connect'. Run it, scan and find your micro:bit, connect to it and then select Refresh Services from the menu. This should work.

If you still have the same problem with micro:bit Blue, try 'desperate measures' like switching Bluetooth off and then on again or even rebooting your phone. If you still find that micro:bit Blue insists that your micro:bit does not have the right Bluetooth services, then go back to item (8) in this FAQ. It's not mistaken. You really don't have the right hex file on your micro:bit.