BLE_Button is a BLE service template. It handles a read-only characteristic with a simple input (boolean values). The input's source is the button on the board itself - the characteristic's value changes when the button is pressed or released. The canonical source for this example lives at https://github.com/ARMmbed/mbed-os-example-ble/tree/master/BLE_Button

BLE_Button is a BLE service template. It handles a read-only characteristic with a simple input (boolean values). The input's source is the button on the board itself - the characteristic's value changes when the button is pressed or released.

The template covers:

  • Setting up advertising and connection modes.
  • Creating an input characteristic: read-only, boolean, with notifications.
  • Constructing a service class and adding it to the BLE stack.
  • Assigning UUIDs to the service and its characteristic.
  • Pushing notifications when the characteristic's value changes.

Running the application

Requirements

The sample application can be seen on any BLE scanner on a smartphone. If you don't have a scanner on your phone, please install :

- nRF Master Control Panel for Android.

- LightBlue for iPhone.

Hardware requirements are in the main readme.

Building instructions

Building with mbed CLI

If you'd like to use mbed CLI to build this, then you should refer to the main readme. The instructions here relate to using the developer.mbed.org Online Compiler

In order to build this example in the mbed Online Compiler, first import the example using the ‘Import’ button on the right hand side.

Next, select a platform to build for. This must either be a platform that supports BLE, for example the NRF51-DK, or one of the following:

List of platforms supporting Bluetooth Low Energy

Or you must also add a piece of hardware and the supporting library that includes a Bluetooth Low Energy driver for that hardware, for example the K64F or NUCLEO_F401RE with the X-NUCLEO-IDB05A1

List of components supporting Bluetooth Low Energy.

Once you have selected your platform, compile the example and drag and drop the resulting binary onto your board.

For general instructions on using the mbed Online Compiler, please see the mbed Handbook

Checking for success

Note: Screens captures depicted below show what is expected from this example if the scanner used is nRF Master Control Panel version 4.0.5. If you encounter any difficulties consider trying another scanner or another version of nRF Master Control Panel. Alternative scanners may require reference to their manuals.

  • Build the application and install it on your board as explained in the building instructions.
  • Open the BLE scanner on your phone.
  • Start a scan.

https://developer.mbed.org/teams/mbed-os-examples/code/mbed-os-example-ble-Button/raw-file/3fe9d5124576/img/start_scan.png

figure 1 How to start scan using nRF Master Control Panel 4.0.5

  • Find your device; it should appear with the name `Button` in the scanner.

https://developer.mbed.org/teams/mbed-os-examples/code/mbed-os-example-ble-Button/raw-file/3fe9d5124576/img/scan_results.png

figure 2 Scan results using nRF Master Control Panel 4.0.5

  • Establish a connection with the device.

https://developer.mbed.org/teams/mbed-os-examples/code/mbed-os-example-ble-Button/raw-file/3fe9d5124576/img/connection.png

figure 3 How to establish a connection using Master Control Panel 4.0.5

  • Discover the services and the characteristics on the device. The Button service has the UUID `0xA000` and includes the Button state characteristic which has the UUID `0xA001`. Depending on your scanner, non standard 16-bit UUID's can be displayed as 128-bit UUID's. If it is the case the following format will be used: `0000XXXX-0000-1000-8000-00805F9B34FB` where `XXXX` is the hexadecimal representation of the 16-bit UUID value.

https://developer.mbed.org/teams/mbed-os-examples/code/mbed-os-example-ble-Button/raw-file/3fe9d5124576/img/discovery.png

figure 4 Representation of the Button service using Master Control Panel 4.0.5

  • Register for the notifications sent by the button state characteristic then the scanner will automatically receive a notification containing the new state of the button every time the state of the button changes.

https://developer.mbed.org/teams/mbed-os-examples/code/mbed-os-example-ble-Button/raw-file/3fe9d5124576/img/register_to_notifications.png

figure 5 How to register to notifications using Master Control Panel 4.0.5

  • Pressing Button 1 on your board updates the state of the button and sends a notification to the scanner. The new state of the button characteristic value should be equal to 0x01.

https://developer.mbed.org/teams/mbed-os-examples/code/mbed-os-example-ble-Button/raw-file/3fe9d5124576/img/button_pressed.png

figure 6 Notification of button pressed using Master Control Panel 4.0.5

  • Releasing Button 1 on your board updates the state of the button and sends a notification to the scanner. The new state of the button characteristic value should be equal to 0x00.

https://developer.mbed.org/teams/mbed-os-examples/code/mbed-os-example-ble-Button/raw-file/3fe9d5124576/img/button_depressed.png

figure 7 Notification of button depressed using Master Control Panel 4.0.5

Committer:
mbed_official
Date:
Thu Aug 04 15:47:44 2016 +0100
Revision:
7:fc1d7b518af4
Parent:
3:6f18b8269d65
Merge pull request #22 from ARMmbed/button_configuration_documentation

Document how to add button configuration on new targets.

Commit copied from https://github.com/ARMmbed/mbed-os-example-ble

Who changed what in which revision?

UserRevisionLine numberNew contents of line
mbed_official 3:6f18b8269d65 1 BLE_Button is a BLE service template. It handles a read-only characteristic with a simple input (boolean values). The input's source is the button on the board itself - the characteristic's value changes when the button is pressed or released.
mbed_official 3:6f18b8269d65 2
mbed_official 3:6f18b8269d65 3 The template covers:
mbed_official 3:6f18b8269d65 4
mbed_official 3:6f18b8269d65 5 1. Setting up advertising and connection modes.
mbed_official 3:6f18b8269d65 6
mbed_official 3:6f18b8269d65 7 1. Creating an input characteristic: read-only, boolean, with notifications.
mbed_official 3:6f18b8269d65 8
mbed_official 3:6f18b8269d65 9 1. Constructing a service class and adding it to the BLE stack.
mbed_official 3:6f18b8269d65 10
mbed_official 3:6f18b8269d65 11 1. Assigning UUIDs to the service and its characteristic.
mbed_official 3:6f18b8269d65 12
mbed_official 3:6f18b8269d65 13 1. Pushing notifications when the characteristic's value changes.
mbed_official 3:6f18b8269d65 14
mbed_official 3:6f18b8269d65 15 # Running the application
mbed_official 3:6f18b8269d65 16
mbed_official 3:6f18b8269d65 17 ## Requirements
mbed_official 3:6f18b8269d65 18
mbed_official 3:6f18b8269d65 19 The sample application can be seen on any BLE scanner on a smartphone. If you don't have a scanner on your phone, please install :
mbed_official 3:6f18b8269d65 20
mbed_official 3:6f18b8269d65 21 - [nRF Master Control Panel](https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp) for Android.
mbed_official 3:6f18b8269d65 22
mbed_official 3:6f18b8269d65 23 - [LightBlue](https://itunes.apple.com/gb/app/lightblue-bluetooth-low-energy/id557428110?mt=8) for iPhone.
mbed_official 3:6f18b8269d65 24
mbed_official 3:6f18b8269d65 25 Hardware requirements are in the [main readme](https://github.com/ARMmbed/mbed-os-example-ble/blob/master/README.md).
mbed_official 3:6f18b8269d65 26
mbed_official 7:fc1d7b518af4 27 ### Porting this example on new boards
mbed_official 7:fc1d7b518af4 28
mbed_official 7:fc1d7b518af4 29 This example requires a board with at least a button to work. While the pin name of the button is defined for the `NRF51_DK`, `NRF52_DK`, `K64F` and `NUCLEO_F401RE`, it is not specified for other boards.
mbed_official 7:fc1d7b518af4 30
mbed_official 7:fc1d7b518af4 31 It is easy to add the button configuration for your board:
mbed_official 7:fc1d7b518af4 32 * Open the file named `mbed_app.json` at the root of this example.
mbed_official 7:fc1d7b518af4 33 * In the section `target_overides` add a new object named after your target if it doesn't exist. This object contain overridden parameters for your target.
mbed_official 7:fc1d7b518af4 34 * Override the property `ble_button_pin_name` in your target object. The value of the property should be equal to the pin name to use as a button.
mbed_official 7:fc1d7b518af4 35
mbed_official 7:fc1d7b518af4 36 As an example, this is the JSON bit which has to be added in the `target_overrides` section of `mbed_app.json` for a `NUCLEO_F411RE` board.
mbed_official 7:fc1d7b518af4 37
mbed_official 7:fc1d7b518af4 38 ```json
mbed_official 7:fc1d7b518af4 39 "NUCLEO_F411RE": {
mbed_official 7:fc1d7b518af4 40 "ble_button_pin_name": "USER_BUTTON"
mbed_official 7:fc1d7b518af4 41 }
mbed_official 7:fc1d7b518af4 42 ```
mbed_official 7:fc1d7b518af4 43
mbed_official 7:fc1d7b518af4 44 <span> **Note:** You can get more informations about the configuration system in the [documentation](https://github.com/ARMmbed/mbed-os/blob/master/docs/config_system.md)</span>
mbed_official 7:fc1d7b518af4 45
mbed_official 7:fc1d7b518af4 46 <span> **Important:** If your target use an ST BLE shield, other parameters have to be overridden for your target. More information are available in the global [README](https://github.com/ARMmbed/mbed-os-example-ble/blob/master/README.md#targets-for-ble)</span>
mbed_official 7:fc1d7b518af4 47
mbed_official 3:6f18b8269d65 48 ## Building instructions
mbed_official 3:6f18b8269d65 49
mbed_official 3:6f18b8269d65 50 Building instructions for all samples are in the [main readme](https://github.com/ARMmbed/mbed-os-example-ble/blob/master/README.md).
mbed_official 3:6f18b8269d65 51
mbed_official 3:6f18b8269d65 52 ## Checking for success
mbed_official 3:6f18b8269d65 53
mbed_official 3:6f18b8269d65 54 **Note:** Screens captures depicted below show what is expected from this example if the scanner used is *nRF Master Control Panel* version 4.0.5. If you encounter any difficulties consider trying another scanner or another version of nRF Master Control Panel. Alternative scanners may require reference to their manuals.
mbed_official 3:6f18b8269d65 55
mbed_official 3:6f18b8269d65 56 1. Build the application and install it on your board as explained in the building instructions.
mbed_official 3:6f18b8269d65 57 1. Open the BLE scanner on your phone.
mbed_official 3:6f18b8269d65 58 1. Start a scan.
mbed_official 3:6f18b8269d65 59
mbed_official 3:6f18b8269d65 60 ![](img/start_scan.png)
mbed_official 3:6f18b8269d65 61
mbed_official 3:6f18b8269d65 62 **figure 1** How to start scan using nRF Master Control Panel 4.0.5
mbed_official 3:6f18b8269d65 63
mbed_official 3:6f18b8269d65 64 1. Find your device; it should appear with the name `Button` in the scanner.
mbed_official 3:6f18b8269d65 65
mbed_official 3:6f18b8269d65 66 ![](img/scan_results.png)
mbed_official 3:6f18b8269d65 67
mbed_official 3:6f18b8269d65 68 **figure 2** Scan results using nRF Master Control Panel 4.0.5
mbed_official 3:6f18b8269d65 69
mbed_official 3:6f18b8269d65 70 1. Establish a connection with the device.
mbed_official 3:6f18b8269d65 71
mbed_official 3:6f18b8269d65 72 ![](img/connection.png)
mbed_official 3:6f18b8269d65 73
mbed_official 3:6f18b8269d65 74 **figure 3** How to establish a connection using Master Control Panel 4.0.5
mbed_official 3:6f18b8269d65 75
mbed_official 3:6f18b8269d65 76 1. Discover the services and the characteristics on the device. The *Button service* has the UUID `0xA000` and includes the *Button state characteristic* which has the UUID `0xA001`. Depending on your scanner, non standard 16-bit UUID's can be displayed as 128-bit UUID's. If it is the case the following format will be used: `0000XXXX-0000-1000-8000-00805F9B34FB` where `XXXX` is the hexadecimal representation of the 16-bit UUID value.
mbed_official 3:6f18b8269d65 77
mbed_official 3:6f18b8269d65 78 ![](img/discovery.png)
mbed_official 3:6f18b8269d65 79
mbed_official 3:6f18b8269d65 80 **figure 4** Representation of the Button service using Master Control Panel 4.0.5
mbed_official 3:6f18b8269d65 81
mbed_official 3:6f18b8269d65 82 1. Register for the notifications sent by the button state characteristic then the scanner will automatically receive a notification containing the new state of the button every time the state of the button changes.
mbed_official 3:6f18b8269d65 83
mbed_official 3:6f18b8269d65 84 ![](img/register_to_notifications.png)
mbed_official 3:6f18b8269d65 85
mbed_official 3:6f18b8269d65 86 **figure 5** How to register to notifications using Master Control Panel 4.0.5
mbed_official 3:6f18b8269d65 87
mbed_official 3:6f18b8269d65 88
mbed_official 3:6f18b8269d65 89 1. Pressing Button 1 on your board updates the state of the button and sends a notification to the scanner. The new state of the button characteristic value should be equal to 0x01.
mbed_official 3:6f18b8269d65 90
mbed_official 3:6f18b8269d65 91 ![](img/button_pressed.png)
mbed_official 3:6f18b8269d65 92
mbed_official 3:6f18b8269d65 93 **figure 6** Notification of button pressed using Master Control Panel 4.0.5
mbed_official 3:6f18b8269d65 94
mbed_official 3:6f18b8269d65 95 1. Releasing Button 1 on your board updates the state of the button and sends a notification to the scanner. The new state of the button characteristic value should be equal to 0x00.
mbed_official 3:6f18b8269d65 96
mbed_official 3:6f18b8269d65 97 ![](img/button_depressed.png)
mbed_official 3:6f18b8269d65 98
mbed_official 3:6f18b8269d65 99 **figure 7** Notification of button depressed using Master Control Panel 4.0.5