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

BLE GAP 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-GAPButton/

Please read the documentation in this page.

README.md@41:0442d1e1f479, 2017-07-27 (annotated)

Committer:
bcostm
Date:
Thu Jul 27 14:41:19 2017 +0200
Revision:
41:0442d1e1f479
Parent:
7:d4dd083eba53 
Add DISCO_L475VG_IOT01A in mbed_app.json

Who changed what in which revision?

UserRevisionLine numberNew contents of line
mbed_official 3:f0ed4199b362 1 # Button count over GAP
mbed_official 3:f0ed4199b362 2
mbed_official 3:f0ed4199b362 3 This application shows how to use GAP to transmit a simple value to disconnected peer listening for advertisement every time that a value is updated:
mbed_official 3:f0ed4199b362 4
mbed_official 3:f0ed4199b362 5 1. The value is a count of how many times a button on the device was pressed (the code actually monitors the button's releases, not press downs).
mbed_official 3:f0ed4199b362 6
mbed_official 3:f0ed4199b362 7 1. We transmit the value in the SERVICE_DATA field of the advertising payload.
mbed_official 3:f0ed4199b362 8
mbed_official 3:f0ed4199b362 9 # Running the application
mbed_official 3:f0ed4199b362 10
mbed_official 3:f0ed4199b362 11 ## Requirements
mbed_official 3:f0ed4199b362 12
mbed_official 3:f0ed4199b362 13 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:f0ed4199b362 14
mbed_official 3:f0ed4199b362 15 - [nRF Master Control Panel](https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp) for Android.
mbed_official 3:f0ed4199b362 16
mbed_official 3:f0ed4199b362 17 - [LightBlue](https://itunes.apple.com/gb/app/lightblue-bluetooth-low-energy/id557428110?mt=8) for iPhone.
mbed_official 3:f0ed4199b362 18
mbed_official 3:f0ed4199b362 19 Hardware requirements are in the [main readme](https://github.com/ARMmbed/mbed-os-example-ble/blob/master/README.md).
mbed_official 3:f0ed4199b362 20
mbed_official 7:d4dd083eba53 21 ### Porting this example on new boards
mbed_official 7:d4dd083eba53 22
mbed_official 7:d4dd083eba53 23 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:d4dd083eba53 24
mbed_official 7:d4dd083eba53 25 It is easy to add the button configuration for your board:
mbed_official 7:d4dd083eba53 26 * Open the file named `mbed_app.json` at the root of this example.
mbed_official 7:d4dd083eba53 27 * 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:d4dd083eba53 28 * 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:d4dd083eba53 29
mbed_official 7:d4dd083eba53 30 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:d4dd083eba53 31
mbed_official 7:d4dd083eba53 32 ```json
mbed_official 7:d4dd083eba53 33 "NUCLEO_F411RE": {
mbed_official 7:d4dd083eba53 34 "ble_button_pin_name": "USER_BUTTON"
mbed_official 7:d4dd083eba53 35 }
mbed_official 7:d4dd083eba53 36 ```
mbed_official 7:d4dd083eba53 37
mbed_official 7:d4dd083eba53 38 <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:d4dd083eba53 39
mbed_official 7:d4dd083eba53 40 <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:d4dd083eba53 41
mbed_official 7:d4dd083eba53 42
mbed_official 3:f0ed4199b362 43 ## Building instructions
mbed_official 3:f0ed4199b362 44
mbed_official 3:f0ed4199b362 45 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:f0ed4199b362 46
mbed_official 3:f0ed4199b362 47 ## Checking for success
mbed_official 3:f0ed4199b362 48
mbed_official 3:f0ed4199b362 49 **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:f0ed4199b362 50
mbed_official 3:f0ed4199b362 51 1. Build the application and install it on your board as explained in the building instructions.
mbed_official 3:f0ed4199b362 52
mbed_official 3:f0ed4199b362 53 1. Open the BLE scanner on your phone.
mbed_official 3:f0ed4199b362 54
mbed_official 3:f0ed4199b362 55 1. Start a scan.
mbed_official 3:f0ed4199b362 56
mbed_official 3:f0ed4199b362 57 ![](img/start_scan.png)
mbed_official 3:f0ed4199b362 58
mbed_official 3:f0ed4199b362 59 **figure 1** How to start scan using nRF Master Control Panel 4.0.5.
mbed_official 3:f0ed4199b362 60
mbed_official 3:f0ed4199b362 61 1. Find your device; it should be named `GAPButton`; and look at the advertisement broadcasted by your device (there is no need to connect to your device).
mbed_official 3:f0ed4199b362 62
mbed_official 3:f0ed4199b362 63 ![](img/discovery.png)
mbed_official 3:f0ed4199b362 64
mbed_official 3:f0ed4199b362 65 **figure 2** Scan results using nRF Master Control Panel 4.0.5.
mbed_official 3:f0ed4199b362 66
mbed_official 3:f0ed4199b362 67 1. The Service Data field of the advertisement packet broadcasted by your device reflects the button press count. The starting value is 0.
mbed_official 3:f0ed4199b362 68
mbed_official 3:f0ed4199b362 69 ![](img/initial_state.png)
mbed_official 3:f0ed4199b362 70
mbed_official 3:f0ed4199b362 71 **figure 3** Initial state of the button using nRF Master Control Panel 4.0.5.
mbed_official 3:f0ed4199b362 72
mbed_official 3:f0ed4199b362 73 1. Press the button on the device.
mbed_official 3:f0ed4199b362 74
mbed_official 3:f0ed4199b362 75 ![](img/first_press.png)
mbed_official 3:f0ed4199b362 76
mbed_official 3:f0ed4199b362 77 **figure 3** State after 1 button press using nRF Master Control Panel 4.0.5.
mbed_official 3:f0ed4199b362 78
mbed_official 3:f0ed4199b362 79 1. The Service Data field value of the advertisement packet should change every time you press the button.
mbed_official 3:f0ed4199b362 80
mbed_official 3:f0ed4199b362 81 ![](img/result.png)
mbed_official 3:f0ed4199b362 82
mbed_official 3:f0ed4199b362 83 **figure 3** State after 6 button press using nRF Master Control Panel 4.0.5.
mbed_official 3:f0ed4199b362 84
mbed_official 3:f0ed4199b362 85 ## Note
mbed_official 3:f0ed4199b362 86
mbed_official 3:f0ed4199b362 87 Since broadcasting is not reliable and your phone may scan intermittently, it is possible that your phone will miss button updates.