BLE Advertising sample application

Dependents:   X_NUCLEO_IDB0XA1

This example shows how to advertise a value of battery service data. The battery value is simulated. The battery level is a percentage, with 100% being a fully charged battery and 0% being a fully drained battery. The level starts at 50% and drains every second second, until it hits 10% when it jumps to 100% and continues draining.

Files at this revision

API Documentation at this revision

Comitter:
apalmieri
Date:
Thu Jan 14 11:25:30 2021 +0000
Commit message:
Initial commit of BLE Advertising example for X-NUCLEO-IDB05A1

Changed in this revision

.gitignore Show annotated file Show diff for this revision Revisions of this file
CONTRIBUTING.md Show annotated file Show diff for this revision Revisions of this file
README.md Show annotated file Show diff for this revision Revisions of this file
img/scan_result.png Show annotated file Show diff for this revision Revisions of this file
img/start_scan.png Show annotated file Show diff for this revision Revisions of this file
mbed-os-ble-utils.lib Show annotated file Show diff for this revision Revisions of this file
mbed-os.lib Show annotated file Show diff for this revision Revisions of this file
mbed_app.json Show annotated file Show diff for this revision Revisions of this file
resources/official_armmbed_example_badge.png Show annotated file Show diff for this revision Revisions of this file
source/main.cpp Show annotated file Show diff for this revision Revisions of this file
diff -r 000000000000 -r 7373a1c9d5b4 .gitignore
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/.gitignore	Thu Jan 14 11:25:30 2021 +0000
@@ -0,0 +1,4 @@
+.build
+.mbed
+projectfiles
+*.py*
diff -r 000000000000 -r 7373a1c9d5b4 CONTRIBUTING.md
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/CONTRIBUTING.md	Thu Jan 14 11:25:30 2021 +0000
@@ -0,0 +1,5 @@
+# Contributing to Mbed OS
+
+Mbed OS is an open-source, device software platform for the Internet of Things. Contributions are an important part of the platform, and our goal is to make it as simple as possible to become a contributor.
+
+To encourage productive collaboration, as well as robust, consistent and maintainable code, we have a set of guidelines for [contributing to Mbed OS](https://os.mbed.com/docs/mbed-os/latest/contributing/index.html).
diff -r 000000000000 -r 7373a1c9d5b4 README.md
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/README.md	Thu Jan 14 11:25:30 2021 +0000
@@ -0,0 +1,37 @@
+This example shows how to advertise a value of battery service data. The battery value is simulated.
+The battery level is a percentage, with 100% being a fully charged battery and 0% being a fully drained battery.
+The level starts at 50% and drains every second second, until it hits 10% when it jumps to 100% and continues draining.
+
+# Running the application
+
+## Requirements
+
+Hardware requirements are in the [main readme](https://github.com/ARMmbed/mbed-os-example-ble/blob/master/README.md).
+
+## Building instructions
+
+Building instructions for all samples are in the [main readme](https://github.com/ARMmbed/mbed-os-example-ble/blob/master/README.md).
+
+## Checking for success
+
+**Note:** Screens captures depicted below show what is expected from this example if the scanner used is *nRF Connect for Mobile* version 4.0.5. If you encounter any difficulties consider trying another scanner or another version of nRF Connect for Mobile. Alternative scanners may require reference to their manuals.
+
+1. Build the application and install it on your board as explained in the building instructions.
+1. Open the BLE scanner on your phone.
+1. Start a scan.
+
+    ![](img/start_scan.png)
+
+    **figure 1** How to start scan using nRF Connect for Mobile 4.0.5
+
+1. Find your device; it should be named `BATTERY`.
+
+    ![](img/scan_result.png)
+
+    **figure 2** Scan results using nRF Connect for Mobile 4.0.5
+
+1. Click on the entry to see the payload details
+
+   
+If you can see the battery level, and if its value is changing, the application is working properly.
+
diff -r 000000000000 -r 7373a1c9d5b4 img/scan_result.png
Binary file img/scan_result.png has changed
diff -r 000000000000 -r 7373a1c9d5b4 img/start_scan.png
Binary file img/start_scan.png has changed
diff -r 000000000000 -r 7373a1c9d5b4 mbed-os-ble-utils.lib
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mbed-os-ble-utils.lib	Thu Jan 14 11:25:30 2021 +0000
@@ -0,0 +1,1 @@
+https://github.com/ARMmbed/mbed-os-ble-utils/#5a87e640383b2a1465e19ea6c052f80459314670
diff -r 000000000000 -r 7373a1c9d5b4 mbed-os.lib
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mbed-os.lib	Thu Jan 14 11:25:30 2021 +0000
@@ -0,0 +1,1 @@
+https://github.com/ARMmbed/mbed-os/#84d991342a41011fc417aab62c0f5a8832f1d18f
diff -r 000000000000 -r 7373a1c9d5b4 mbed_app.json
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/mbed_app.json	Thu Jan 14 11:25:30 2021 +0000
@@ -0,0 +1,23 @@
+{
+    "target_overrides": {
+        "*": {
+            "platform.stdio-baud-rate": 115200
+        },
+        "K64F": {
+            "target.components_add": ["BlueNRG_MS"],
+            "target.features_add": ["BLE"],
+            "target.extra_labels_add": ["CORDIO"]
+        },
+        "NUCLEO_F401RE": {
+            "target.components_add": ["BlueNRG_MS"],
+            "target.features_add": ["BLE"],
+            "target.extra_labels_add": ["CORDIO"]
+        },
+        "NRF52840_DK": {
+            "target.features_add": ["BLE"]
+        },
+        "NRF52_DK": {
+            "target.features_add": ["BLE"]
+        }
+    }
+}
diff -r 000000000000 -r 7373a1c9d5b4 resources/official_armmbed_example_badge.png
Binary file resources/official_armmbed_example_badge.png has changed
diff -r 000000000000 -r 7373a1c9d5b4 source/main.cpp
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/source/main.cpp	Thu Jan 14 11:25:30 2021 +0000
@@ -0,0 +1,181 @@
+/* mbed Microcontroller Library
+ * Copyright (c) 2006-2019 ARM Limited
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ */
+
+#include <events/mbed_events.h>
+#include "ble/BLE.h"
+#include "ble/Gap.h"
+#include "pretty_printer.h"
+
+const static char DEVICE_NAME[] = "BATTERY";
+
+using namespace std::literals::chrono_literals;
+
+static events::EventQueue event_queue(/* event count */ 16 * EVENTS_EVENT_SIZE);
+
+class BatteryDemo : ble::Gap::EventHandler {
+public:
+    BatteryDemo(BLE &ble, events::EventQueue &event_queue) :
+        _ble(ble),
+        _event_queue(event_queue),
+        _battery_level(50),
+        _adv_data_builder(_adv_buffer)
+    {
+    }
+
+    void start()
+    {
+        /* mbed will call on_init_complete when when ble is ready */
+        _ble.init(this, &BatteryDemo::on_init_complete);
+
+        /* this will never return */
+        _event_queue.dispatch_forever();
+    }
+
+private:
+    /** Callback triggered when the ble initialization process has finished */
+    void on_init_complete(BLE::InitializationCompleteCallbackContext *params)
+    {
+        if (params->error != BLE_ERROR_NONE) {
+            print_error(params->error, "Ble initialization failed.");
+            return;
+        }
+
+        print_mac_address();
+
+        start_advertising();
+    }
+
+    void start_advertising()
+    {
+        /* create advertising parameters and payload */
+
+        ble::AdvertisingParameters adv_parameters(
+            /* you cannot connect to this device, you can only read its advertising data,
+             * scannable means that the device has extra advertising data that the peer can receive if it
+             * "scans" it which means it is using active scanning (it sends a scan request) */
+            ble::advertising_type_t::SCANNABLE_UNDIRECTED,
+            ble::adv_interval_t(ble::millisecond_t(1000))
+        );
+
+        _adv_data_builder.setFlags();
+        _adv_data_builder.setName(DEVICE_NAME);
+
+        /* we add the battery level as part of the payload so it's visible to any device that scans */
+        _adv_data_builder.setServiceData(GattService::UUID_BATTERY_SERVICE, {&_battery_level, 1});
+
+        /* setup advertising */
+
+        ble_error_t error = _ble.gap().setAdvertisingParameters(
+            ble::LEGACY_ADVERTISING_HANDLE,
+            adv_parameters
+        );
+
+        if (error) {
+            print_error(error, "_ble.gap().setAdvertisingParameters() failed");
+            return;
+        }
+
+        error = _ble.gap().setAdvertisingPayload(
+            ble::LEGACY_ADVERTISING_HANDLE,
+            _adv_data_builder.getAdvertisingData()
+        );
+
+        if (error) {
+            print_error(error, "_ble.gap().setAdvertisingPayload() failed");
+            return;
+        }
+
+        /* when advertising you can optionally add extra data that is only sent
+         * if the central requests it by doing active scanning */
+        _adv_data_builder.clear();
+        const uint8_t _vendor_specific_data[4] = { 0xAD, 0xDE, 0xBE, 0xEF };
+        _adv_data_builder.setManufacturerSpecificData(_vendor_specific_data);
+
+        _ble.gap().setAdvertisingScanResponse(
+            ble::LEGACY_ADVERTISING_HANDLE,
+            _adv_data_builder.getAdvertisingData()
+        );
+
+        /* start advertising */
+
+        error = _ble.gap().startAdvertising(ble::LEGACY_ADVERTISING_HANDLE);
+
+        if (error) {
+            print_error(error, "_ble.gap().startAdvertising() failed");
+            return;
+        }
+
+        /* we simulate battery discharging by updating it every second */
+        _event_queue.call_every(
+            1000ms,
+            [this]() {
+                update_battery_level();
+            }
+        );
+    }
+
+    void update_battery_level()
+    {
+        if (_battery_level-- == 10) {
+            _battery_level = 100;
+        }
+
+        /* update the payload with the new value */
+        ble_error_t error = _adv_data_builder.setServiceData(GattService::UUID_BATTERY_SERVICE, make_Span(&_battery_level, 1));
+
+        if (error) {
+            print_error(error, "_adv_data_builder.setServiceData() failed");
+            return;
+        }
+
+        /* set the new payload, we don't need to stop advertising */
+        error = _ble.gap().setAdvertisingPayload(
+            ble::LEGACY_ADVERTISING_HANDLE,
+            _adv_data_builder.getAdvertisingData()
+        );
+
+        if (error) {
+            print_error(error, "_ble.gap().setAdvertisingPayload() failed");
+            return;
+        }
+    }
+
+private:
+    BLE &_ble;
+    events::EventQueue &_event_queue;
+
+    uint8_t _battery_level;
+
+    uint8_t _adv_buffer[ble::LEGACY_ADVERTISING_MAX_SIZE];
+    ble::AdvertisingDataBuilder _adv_data_builder;
+};
+
+/* Schedule processing of events from the BLE middleware in the event queue. */
+void schedule_ble_events(BLE::OnEventsToProcessCallbackContext *context)
+{
+    event_queue.call(Callback<void()>(&context->ble, &BLE::processEvents));
+}
+
+int main()
+{
+    BLE &ble = BLE::Instance();
+    ble.onEventsToProcess(schedule_ble_events);
+
+    BatteryDemo demo(ble, event_queue);
+    demo.start();
+
+    return 0;
+}