ST / Mbed OS mbed-os-example-ble-Button

BLE Button example

This example is a fork of the following mbed-os example:

https://developer.mbed.org/teams/mbed-os-examples/code/mbed-os-example-ble-Button/

Please read the documentation in this page.

readme.md@2:2be0a2820d3d, 2016-07-28 (annotated)

Committer:
Vincent Coubard
Date:
Thu Jul 28 23:30:40 2016 +0100
Revision:
2:2be0a2820d3d
Parent:
1:cd85f873e10d
Child:
3:6f18b8269d65
Sync with mbed-os-5.1.0-rc3

Who changed what in which revision?

UserRevisionLine numberNew contents of line
Vincent Coubard 2:2be0a2820d3d 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.
Vincent Coubard 2:2be0a2820d3d 2
Vincent Coubard 2:2be0a2820d3d 3 The template covers:
Vincent Coubard 2:2be0a2820d3d 4
Vincent Coubard 2:2be0a2820d3d 5 1. Setting up advertising and connection modes.
Vincent Coubard 2:2be0a2820d3d 6
Vincent Coubard 2:2be0a2820d3d 7 1. Creating an input characteristic: read-only, boolean, with notifications.
Vincent Coubard 2:2be0a2820d3d 8
Vincent Coubard 2:2be0a2820d3d 9 1. Constructing a service class and adding it to the BLE stack.
Vincent Coubard 2:2be0a2820d3d 10
Vincent Coubard 2:2be0a2820d3d 11 1. Assigning UUIDs to the service and its characteristic.
Vincent Coubard 2:2be0a2820d3d 12
Vincent Coubard 2:2be0a2820d3d 13 1. Pushing notifications when the characteristic's value changes.
Vincent Coubard 2:2be0a2820d3d 14
Vincent Coubard 2:2be0a2820d3d 15 # Running the application
Vincent Coubard 2:2be0a2820d3d 16
Vincent Coubard 2:2be0a2820d3d 17 ## Requirements
Vincent Coubard 2:2be0a2820d3d 18
Vincent Coubard 2:2be0a2820d3d 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 :
Vincent Coubard 2:2be0a2820d3d 20
Vincent Coubard 2:2be0a2820d3d 21 - [nRF Master Control Panel](https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp) for Android.
Vincent Coubard 2:2be0a2820d3d 22
Vincent Coubard 2:2be0a2820d3d 23 - [LightBlue](https://itunes.apple.com/gb/app/lightblue-bluetooth-low-energy/id557428110?mt=8) for iPhone.
Vincent Coubard 2:2be0a2820d3d 24
Vincent Coubard 2:2be0a2820d3d 25 Hardware requirements are in the [main readme](https://github.com/ARMmbed/mbed-os-example-ble/blob/master/README.md).
Vincent Coubard 2:2be0a2820d3d 26
Vincent Coubard 2:2be0a2820d3d 27 ## Building instructions
Vincent Coubard 2:2be0a2820d3d 28
Vincent Coubard 2:2be0a2820d3d 29 Building instructions for all samples are in the [main readme](https://github.com/ARMmbed/mbed-os-example-ble/blob/master/README.md).
Vincent Coubard 2:2be0a2820d3d 30
Vincent Coubard 2:2be0a2820d3d 31 ## Checking for success
Vincent Coubard 2:2be0a2820d3d 32
Vincent Coubard 2:2be0a2820d3d 33 **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.
Vincent Coubard 2:2be0a2820d3d 34
Vincent Coubard 2:2be0a2820d3d 35 1. Build the application and install it on your board as explained in the building instructions.
Vincent Coubard 2:2be0a2820d3d 36 1. Open the BLE scanner on your phone.
Vincent Coubard 2:2be0a2820d3d 37 1. Start a scan.
Vincent Coubard 2:2be0a2820d3d 38
Vincent Coubard 2:2be0a2820d3d 39 ![](img/start_scan.png)
Vincent Coubard 2:2be0a2820d3d 40
Vincent Coubard 2:2be0a2820d3d 41 **figure 1** How to start scan using nRF Master Control Panel 4.0.5
Vincent Coubard 2:2be0a2820d3d 42
Vincent Coubard 2:2be0a2820d3d 43 1. Find your device; it should appear with the name `Button` in the scanner.
Vincent Coubard 2:2be0a2820d3d 44
Vincent Coubard 2:2be0a2820d3d 45 ![](img/scan_results.png)
Vincent Coubard 2:2be0a2820d3d 46
Vincent Coubard 2:2be0a2820d3d 47 **figure 2** Scan results using nRF Master Control Panel 4.0.5
Vincent Coubard 2:2be0a2820d3d 48
Vincent Coubard 2:2be0a2820d3d 49 1. Establish a connection with the device.
Vincent Coubard 2:2be0a2820d3d 50
Vincent Coubard 2:2be0a2820d3d 51 ![](img/connection.png)
Vincent Coubard 2:2be0a2820d3d 52
Vincent Coubard 2:2be0a2820d3d 53 **figure 3** How to establish a connection using Master Control Panel 4.0.5
Vincent Coubard 2:2be0a2820d3d 54
Vincent Coubard 2:2be0a2820d3d 55 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.
Vincent Coubard 2:2be0a2820d3d 56
Vincent Coubard 2:2be0a2820d3d 57 ![](img/discovery.png)
Vincent Coubard 2:2be0a2820d3d 58
Vincent Coubard 2:2be0a2820d3d 59 **figure 4** Representation of the Button service using Master Control Panel 4.0.5
Vincent Coubard 2:2be0a2820d3d 60
Vincent Coubard 2:2be0a2820d3d 61 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.
Vincent Coubard 2:2be0a2820d3d 62
Vincent Coubard 2:2be0a2820d3d 63 ![](img/register_to_notifications.png)
Vincent Coubard 2:2be0a2820d3d 64
Vincent Coubard 2:2be0a2820d3d 65 **figure 5** How to register to notifications using Master Control Panel 4.0.5
Vincent Coubard 2:2be0a2820d3d 66
Vincent Coubard 2:2be0a2820d3d 67
Vincent Coubard 2:2be0a2820d3d 68 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.
Vincent Coubard 2:2be0a2820d3d 69
Vincent Coubard 2:2be0a2820d3d 70 ![](img/button_pressed.png)
Vincent Coubard 2:2be0a2820d3d 71
Vincent Coubard 2:2be0a2820d3d 72 **figure 6** Notification of button pressed using Master Control Panel 4.0.5
Vincent Coubard 2:2be0a2820d3d 73
Vincent Coubard 2:2be0a2820d3d 74 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.
Vincent Coubard 2:2be0a2820d3d 75
Vincent Coubard 2:2be0a2820d3d 76 ![](img/button_depressed.png)
Vincent Coubard 2:2be0a2820d3d 77
Vincent Coubard 2:2be0a2820d3d 78 **figure 7** Notification of button depressed using Master Control Panel 4.0.5
Vincent Coubard 2:2be0a2820d3d 79