From a7e2d19fe1a7abd60276a66d8c7a7bd47be48c9b Mon Sep 17 00:00:00 2001 From: Werner Lewis Date: Thu, 15 Apr 2021 17:34:51 +0100 Subject: [PATCH] Update examples for Mbed CLI 2 (#367) * cmake: Remove mbed_configure_app_target() calls The CMake function `mbed_configure_app_target()` is now deprecated in Mbed OS and should not be called in the examples. * README: Remove incorrect Known Issues section Issue #40 is closed, #39 is closed as IAR is no longer supported, and the default applications described have been changed since this issue was added. These issues are no longer accurate and should be removed. * README: Fix grammar and markdown style * README: Add CLI 2 instructions --- BLE_Advertising/CMakeLists.txt | 2 - BLE_GAP/CMakeLists.txt | 2 - .../CMakeLists.txt | 2 - .../CMakeLists.txt | 2 - BLE_GattServer_AddService/CMakeLists.txt | 2 - .../CMakeLists.txt | 2 - .../CMakeLists.txt | 2 - .../CMakeLists.txt | 2 - BLE_PeriodicAdvertising/CMakeLists.txt | 2 - BLE_SecurityAndPrivacy/CMakeLists.txt | 2 - BLE_SupportedFeatures/CMakeLists.txt | 2 - README.md | 170 +++++++++++------- 12 files changed, 101 insertions(+), 91 deletions(-) diff --git a/BLE_Advertising/CMakeLists.txt b/BLE_Advertising/CMakeLists.txt index 1368f038..cee62923 100644 --- a/BLE_Advertising/CMakeLists.txt +++ b/BLE_Advertising/CMakeLists.txt @@ -15,8 +15,6 @@ add_subdirectory(mbed-os-ble-utils) add_executable(${APP_TARGET}) -mbed_configure_app_target(${APP_TARGET}) - project(${APP_TARGET}) target_include_directories(${APP_TARGET} diff --git a/BLE_GAP/CMakeLists.txt b/BLE_GAP/CMakeLists.txt index ac92501e..36388c8c 100644 --- a/BLE_GAP/CMakeLists.txt +++ b/BLE_GAP/CMakeLists.txt @@ -15,8 +15,6 @@ add_subdirectory(mbed-os-ble-utils) add_executable(${APP_TARGET}) -mbed_configure_app_target(${APP_TARGET}) - project(${APP_TARGET}) target_include_directories(${APP_TARGET} diff --git a/BLE_GattClient_CharacteristicUpdates/CMakeLists.txt b/BLE_GattClient_CharacteristicUpdates/CMakeLists.txt index dd9d5d4c..bce48861 100644 --- a/BLE_GattClient_CharacteristicUpdates/CMakeLists.txt +++ b/BLE_GattClient_CharacteristicUpdates/CMakeLists.txt @@ -15,8 +15,6 @@ add_subdirectory(mbed-os-ble-utils) add_executable(${APP_TARGET}) -mbed_configure_app_target(${APP_TARGET}) - project(${APP_TARGET}) target_include_directories(${APP_TARGET} diff --git a/BLE_GattClient_CharacteristicWrite/CMakeLists.txt b/BLE_GattClient_CharacteristicWrite/CMakeLists.txt index ab485d3b..78f4bd9f 100644 --- a/BLE_GattClient_CharacteristicWrite/CMakeLists.txt +++ b/BLE_GattClient_CharacteristicWrite/CMakeLists.txt @@ -15,8 +15,6 @@ add_subdirectory(mbed-os-ble-utils) add_executable(${APP_TARGET}) -mbed_configure_app_target(${APP_TARGET}) - project(${APP_TARGET}) target_include_directories(${APP_TARGET} diff --git a/BLE_GattServer_AddService/CMakeLists.txt b/BLE_GattServer_AddService/CMakeLists.txt index fd510afe..f611ea38 100644 --- a/BLE_GattServer_AddService/CMakeLists.txt +++ b/BLE_GattServer_AddService/CMakeLists.txt @@ -15,8 +15,6 @@ add_subdirectory(mbed-os-ble-utils) add_executable(${APP_TARGET}) -mbed_configure_app_target(${APP_TARGET}) - project(${APP_TARGET}) target_include_directories(${APP_TARGET} diff --git a/BLE_GattServer_CharacteristicUpdates/CMakeLists.txt b/BLE_GattServer_CharacteristicUpdates/CMakeLists.txt index 295a1e8b..2eccde25 100644 --- a/BLE_GattServer_CharacteristicUpdates/CMakeLists.txt +++ b/BLE_GattServer_CharacteristicUpdates/CMakeLists.txt @@ -15,8 +15,6 @@ add_subdirectory(mbed-os-ble-utils) add_executable(${APP_TARGET}) -mbed_configure_app_target(${APP_TARGET}) - project(${APP_TARGET}) target_include_directories(${APP_TARGET} diff --git a/BLE_GattServer_CharacteristicWrite/CMakeLists.txt b/BLE_GattServer_CharacteristicWrite/CMakeLists.txt index ecf11d37..7dc33a5b 100644 --- a/BLE_GattServer_CharacteristicWrite/CMakeLists.txt +++ b/BLE_GattServer_CharacteristicWrite/CMakeLists.txt @@ -15,8 +15,6 @@ add_subdirectory(mbed-os-ble-utils) add_executable(${APP_TARGET}) -mbed_configure_app_target(${APP_TARGET}) - project(${APP_TARGET}) target_include_directories(${APP_TARGET} diff --git a/BLE_GattServer_ExperimentalServices/CMakeLists.txt b/BLE_GattServer_ExperimentalServices/CMakeLists.txt index ecabbe6b..e3748628 100644 --- a/BLE_GattServer_ExperimentalServices/CMakeLists.txt +++ b/BLE_GattServer_ExperimentalServices/CMakeLists.txt @@ -17,8 +17,6 @@ add_subdirectory(mbed-os-experimental-ble-services/services/LinkLoss) add_executable(${APP_TARGET}) -mbed_configure_app_target(${APP_TARGET}) - project(${APP_TARGET}) target_sources(${APP_TARGET} diff --git a/BLE_PeriodicAdvertising/CMakeLists.txt b/BLE_PeriodicAdvertising/CMakeLists.txt index ca3328d5..2bb95664 100644 --- a/BLE_PeriodicAdvertising/CMakeLists.txt +++ b/BLE_PeriodicAdvertising/CMakeLists.txt @@ -15,8 +15,6 @@ add_subdirectory(mbed-os-ble-utils) add_executable(${APP_TARGET}) -mbed_configure_app_target(${APP_TARGET}) - project(${APP_TARGET}) target_include_directories(${APP_TARGET} diff --git a/BLE_SecurityAndPrivacy/CMakeLists.txt b/BLE_SecurityAndPrivacy/CMakeLists.txt index af9494d5..0ec36df7 100644 --- a/BLE_SecurityAndPrivacy/CMakeLists.txt +++ b/BLE_SecurityAndPrivacy/CMakeLists.txt @@ -15,8 +15,6 @@ add_subdirectory(mbed-os-ble-utils) add_executable(${APP_TARGET}) -mbed_configure_app_target(${APP_TARGET}) - project(${APP_TARGET}) target_include_directories(${APP_TARGET} diff --git a/BLE_SupportedFeatures/CMakeLists.txt b/BLE_SupportedFeatures/CMakeLists.txt index 2808228c..c4fac418 100644 --- a/BLE_SupportedFeatures/CMakeLists.txt +++ b/BLE_SupportedFeatures/CMakeLists.txt @@ -13,8 +13,6 @@ add_subdirectory(${MBED_PATH}) add_executable(${APP_TARGET}) -mbed_configure_app_target(${APP_TARGET}) - project(${APP_TARGET}) target_include_directories(${APP_TARGET} diff --git a/README.md b/README.md index 8bf958fb..931aee75 100644 --- a/README.md +++ b/README.md @@ -1,60 +1,64 @@ ![](./resources/official_armmbed_example_badge.png) # BLE Examples -This repo contains a collection of BLE example applications based on -mbed OS and built with [mbed-cli](https://github.com/ARMmbed/mbed-cli). -Each example subdirectory contains a separate mbed-cli module meant for building an executable. -Please browse to subdirectories for descriptions of the examples and any additional instructions on running them. +This repo contains a collection of BLE example applications based on Mbed OS. Each example subdirectory contains a separate Mbed OS project, along with a description of the example and additional instructions for running it. -Getting Started -=============== +You can build each project with all supported [Mbed OS build tools](https://os.mbed.com/docs/mbed-os/latest/tools/index.html). However, this file specifically refers to the command-line interface tools, [Arm Mbed CLI 1](https://github.com/ARMmbed/mbed-cli#installing-mbed-cli) and [Mbed CLI 2](https://github.com/ARMmbed/mbed-tools#installation). +The [BLE documentation](https://os.mbed.com/docs/latest/reference/bluetooth.html) describes the BLE APIs on Mbed OS. -Pre-Requisites --------------- +## Mbed OS build tools -To build these examples, you need to have a computer with software installed as described [here](https://os.mbed.com/docs/latest/tools/index.html). +### Mbed CLI 2 +Starting with version 6.5, Mbed OS uses Mbed CLI 2. It uses Ninja as a build system, and CMake to generate the build environment and manage the build process in a compiler-independent manner. If you are working with Mbed OS version prior to 6.5 then check the section [Mbed CLI 1](#mbed-cli-1). -In order to use BLE in mbed OS you need one of the following hardware combinations: +[Install Mbed CLI 2](https://os.mbed.com/docs/mbed-os/latest/build-tools/install-or-upgrade.html). + +### Mbed CLI 1 +[Install Mbed CLI 1](https://os.mbed.com/docs/mbed-os/latest/quick-start/offline-with-mbed-cli.html). + +## Pre-Requisites + + +In order to use BLE in Mbed OS you need one of the following hardware combinations: * A supported target, such as the [NUCLEO-F401RE](https://os.mbed.com/platforms/ST-Nucleo-F401RE/), with a BLE shield or an external BLE peripheral, such as an [X-NUCLEO-BNRG2A1](https://os.mbed.com/components/X-NUCLEO-BNRG2A1/) or an [X-NUCLEO-IDB05A1](https://os.mbed.com/components/X-NUCLEO-IDB05A1/) ST BLE expansion board. * A [DISCO_L475VG_IOT01A (ref B-L475E-IOT01A)](https://os.mbed.com/platforms/ST-Discovery-L475E-IOT01A/) board. * A [DISCO_L562QE (ref STM32L562E-DK)](https://os.mbed.com/platforms/ST-Discovery-L562QE/) board. * A [NUCLEO_WB55RG](https://os.mbed.com/platforms/ST-Nucleo-WB55RG/) board. -* A Nordic nRF52-based board such as [nrf52DK](https://os.mbed.com/platforms/Nordic-nRF52-DK/) -* An Embedded Planet [Agora](https://os.mbed.com/platforms/agora-dev/) board +* A Nordic nRF52-based board such as [nRF52DK](https://os.mbed.com/platforms/Nordic-nRF52-DK/). +* An Embedded Planet [Agora](https://os.mbed.com/platforms/agora-dev/) board. The [BLE documentation](https://os.mbed.com/docs/latest/reference/bluetooth.html) describes the BLE APIs on mbed OS. -Targets for BLE ---------------- +### Targets for BLE The following targets have been tested and work with these examples: * Targets with an ST BLE expansion board plugged in: - * NUCLEO_F401RE - * NUCLEO_L476RG - * NUCLEO_L446RE - * K64F + * NUCLEO_F401RE + * NUCLEO_L476RG + * NUCLEO_L446RE + * K64F * ST boards with embedded SPBTLE-RF module (BlueNRG-MS): - * DISCO_L475VG_IOT01A (ref B-L475E-IOT01A) - * DISCO_L562QE (ref STM32L562E-DK) + * DISCO_L475VG_IOT01A (ref B-L475E-IOT01A) + * DISCO_L562QE (ref STM32L562E-DK) * Board with wireless STM32WB microcontrollers: - * NUCLEO_WB55RG + * NUCLEO_WB55RG * Nordic: - * NRF52_DK - * NRF52840_DK + * NRF52_DK + * NRF52840_DK * Embedded Planet: - * EP_AGORA + * EP_AGORA + +**Important:** If an ST BLE expansion is used with the K64F board, a hardware patch is required. Check out [X-NUCLEO-BNRG2A1](https://github.com/ARMmbed/mbed-os/tree/master/connectivity/drivers/ble/FEATURE_BLE/COMPONENT_BlueNRG_2) or [X-NUCLEO-IDB05A1](https://os.mbed.com/components/X-NUCLEO-IDB05A1/) for more information. - **Important:** If an ST BLE expansion is used with the K64F board, an hardware patch is required. Check out [X-NUCLEO-BNRG2A1](https://github.com/ARMmbed/mbed-os/tree/master/connectivity/drivers/ble/FEATURE_BLE/COMPONENT_BlueNRG_2) or [X-NUCLEO-IDB05A1](https://os.mbed.com/components/X-NUCLEO-IDB05A1/) for more information. - The following board is currently not supported as it doesn't yet support the Cordio stack: - * NRF51_DK + * NRF51_DK ### Using ST BLE expansion board on other targets @@ -63,17 +67,16 @@ It is possible to use the ST BLE expansion on boards not directly supported by t To make the board compatible with the ST BLE expansion three things are required: * Add the BLE feature to your target. * Add the BLE implementation for the ST BLE expansion to the list of modules which have to be compiled. -* Indicate to the BLE implementation that your board use an Arduino connector. +* Indicate to the BLE implementation that your board uses an Arduino connector. All these operations can be done in the file `mbed_app.json` present in every example. -In the section `target_overrides` add a new object named after your target. -In this object two fields are required: +In the section `target_overrides`, add a new object named after your target with the following three fields: * `"target.components_add": ["BlueNRG_2"]` Add the BlueNRG-2 component to the target. * `"target.features_add": ["BLE"]` Add the BLE feature to the target. * `"target.extra_labels_add": ["CORDIO"]`: Add the BLE implementation of the ST BLE expansion to the list of the application modules. -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_F401RE` board. +Below is an example of the JSON to be added in the `target_overrides` section of `mbed_app.json`, with the `NUCLEO_F401RE` board. ```json "NUCLEO_F401RE": { @@ -83,78 +86,107 @@ As an example, this is the JSON bit which has to be added in the `target_overrid }, ``` - **Note:** You can get more information about the configuration system in the [documentation](https://os.mbed.com/docs/latest/reference/configuration.html) +**Note:** Further information about the configuration system is available in the [documentation](https://os.mbed.com/docs/latest/reference/configuration.html). - **Important:** It is required to apply an hardware patch to the ST BLE expansion if it is used on a board with an Arduino connector. Check out [X-NUCLEO-BNRG2A1](https://github.com/ARMmbed/mbed-os/tree/master/connectivity/drivers/ble/FEATURE_BLE/COMPONENT_BlueNRG_2) or [X-NUCLEO-IDB05A1](https://os.mbed.com/components/X-NUCLEO-IDB05A1/) for more information. +**Important:** It is required to apply an hardware patch to the ST BLE expansion if it is used on a board with an Arduino connector. Check out [X-NUCLEO-BNRG2A1](https://github.com/ARMmbed/mbed-os/tree/master/connectivity/drivers/ble/FEATURE_BLE/COMPONENT_BlueNRG_2) or [X-NUCLEO-IDB05A1](https://os.mbed.com/components/X-NUCLEO-IDB05A1/) for more information. -Building and flashing examples ---------------------------------- - -__To build an example:__ +## Building the examples 1. Clone the repository containing the collection of examples: - ``` - $ git clone https://github.com/ARMmbed/mbed-os-example-ble.git - ``` + ```bash + $ git clone https://github.com/ARMmbed/mbed-os-example-ble.git + ``` - **Tip:** If you don't have git installed, you can [download a zip file](https://github.com/ARMmbed/mbed-os-example-ble/archive/master.zip) of the repository. + **Tip:** If you don't have git installed, you can [download a zip file](https://github.com/ARMmbed/mbed-os-example-ble/archive/master.zip) of the repository. -1. Using a command-line tool, navigate to any of the example directories, like BLE_Button: +1. Using a command-line tool, navigate to any of the example directories, like BLE_Advertising: - ``` - $ cd mbed-os-example-ble - $ cd BLE_Advertising - ``` + ```bash + $ cd mbed-os-example-ble + $ cd BLE_Advertising + ``` 1. Update the source tree: - ``` - mbed deploy - ``` + * Mbed CLI 2 + + ```bash + $ mbed-tools deploy + ``` + + * Mbed CLI 1 + + ```bash + $ mbed deploy + ``` + +1. Connect a USB cable between the USB port on the board and the host computer. -1. Run the build: +1. Run the following command: this will build the example project, program the microcontroller flash memory, and then +open a serial terminal to the device. - ```mbed compile -t -m ``` + * Mbed CLI 2 -__To run the application on your board:__ + ```bash + $ mbed-tools compile -m -t --flash --sterm --baudrate 115200 + ``` -1. Connect your mbed board to your computer over USB. It appears as removable storage. + * Mbed CLI 1 -1. When you run the `mbed compile` command above, mbed cli creates a .bin or a .hex file (depending on your target) in ```BUILD//``` under the example's directory. Drag and drop the file to the removable storage. + ```bash + $ mbed compile -m -t --flash --sterm --baudrate 115200 + ``` -Running the examples ---------------------------------- +Your PC may take a few minutes to compile your code. + +The binary will be located in the following directory: +* **Mbed CLI 2** - `./cmake_build////` +* **Mbed CLI 1** - `./BUILD///` + +You can manually copy the binary to the target, which gets mounted on the host computer through USB, rather than using the `--flash` option. + +You can also open a serial terminal separately, as explained below, rather than using the `--sterm` and `--baudrate` options. + +## Running the examples When example application is running, information about activity is printed over the serial connection. The default serial baudrate has been set to 115200 for these examples. -Please have a client open and connected to the board. You may use: -- [Tera Term](https://ttssh2.osdn.jp/index.html.en) for windows +If not using the `--sterm` and `--baudrate` options when flashing, have a client +open and connected to the board. You may use: + +- Mbed CLI 2 + ```bash + $ mbed-tools sterm -b 115200 + ``` -- screen or minicom for Linux (example usage: `screen /dev/serial/ 115200`) +- Mbed CLI 1 + ```bash + $ mbed sterm -b 115200 + ``` + +- [Tera Term](https://ttssh2.osdn.jp/index.html.en) for Windows + +- screen or minicom for Linux + ```bash + screen /dev/serial/ 115200 + ``` To observe and/or interact with example applications please use any BLE scanner on a smartphone. -If you don't have a scanner on your phone, please install : +If you don't have a scanner on your phone, please install: - [nRF Connect for Mobile](https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp) for Android and iOS. - [ST BLE Profile](https://play.google.com/store/apps/details?id=com.stm.bluetoothlevalidation) for Android. -Known issues -============ - -* [NUCLEO_F411RE]: Some BLE examples doesn't work with the ST BLE expansion. See [#40](https://github.com/ARMmbed/mbed-os-example-ble/issues/40) -* [NRF5] Impossible to debug or flash the examples with IAR: See [#39](https://github.com/ARMmbed/mbed-os-example-ble/issues/39) -* [NUCLEO_WB55RG]: some examples are not working with default application described in examples readme. Better use [LightBlue](https://itunes.apple.com/gb/app/lightblue-bluetooth-low-energy/id557428110?mt=8) for iPhone or try out [ST BLE Profile](https://play.google.com/store/apps/details?id=com.stm.bluetoothlevalidation). - ### License and contributions -The software is provided under Apache-2.0 license. Contributions to this project are accepted under the same license. Please see contributing.md for more info. +The software is provided under Apache-2.0 license. Contributions to this project are accepted under the same license. Please see [CONTRIBUTING.md](./CONTRIBUTING.md) for more info. -This project contains code from other projects. The original license text is included in those source files. They must comply with our license guide +This project contains code from other projects. The original license text is included in those source files. They must comply with our license guide. ## Branches