{"id":29013905,"url":"https://github.com/armmbed/mbed-os-example-ble","last_synced_at":"2025-06-25T20:12:22.685Z","repository":{"id":10222298,"uuid":"60862142","full_name":"ARMmbed/mbed-os-example-ble","owner":"ARMmbed","description":"BLE demos using mbed OS and mbed cli","archived":false,"fork":false,"pushed_at":"2023-02-28T15:20:49.000Z","size":5583,"stargazers_count":134,"open_issues_count":6,"forks_count":118,"subscribers_count":20,"default_branch":"development","last_synced_at":"2024-12-06T22:13:23.380Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"apache-2.0","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ARMmbed.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2016-06-10T16:30:51.000Z","updated_at":"2024-07-17T00:44:27.000Z","dependencies_parsed_at":"2023-10-20T17:38:39.848Z","dependency_job_id":null,"html_url":"https://github.com/ARMmbed/mbed-os-example-ble","commit_stats":null,"previous_names":[],"tags_count":129,"template":false,"template_full_name":null,"purl":"pkg:github/ARMmbed/mbed-os-example-ble","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARMmbed%2Fmbed-os-example-ble","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARMmbed%2Fmbed-os-example-ble/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARMmbed%2Fmbed-os-example-ble/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARMmbed%2Fmbed-os-example-ble/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ARMmbed","download_url":"https://codeload.github.com/ARMmbed/mbed-os-example-ble/tar.gz/refs/heads/development","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ARMmbed%2Fmbed-os-example-ble/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":261945404,"owners_count":23234243,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-06-25T20:12:21.336Z","updated_at":"2025-06-25T20:12:22.673Z","avatar_url":"https://github.com/ARMmbed.png","language":"C++","funding_links":[],"categories":[],"sub_categories":[],"readme":"![](./resources/official_armmbed_example_badge.png)\n# BLE Examples\n\nThis 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.\n\nYou 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).\n\nThe [BLE documentation](https://os.mbed.com/docs/latest/reference/bluetooth.html) describes the BLE APIs on Mbed OS.\n\n## Mbed OS build tools\n\n### Mbed CLI 2\nStarting 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).\n\n[Install Mbed CLI 2](https://os.mbed.com/docs/mbed-os/latest/build-tools/install-or-upgrade.html).\n\n### Mbed CLI 1\n[Install Mbed CLI 1](https://os.mbed.com/docs/mbed-os/latest/quick-start/offline-with-mbed-cli.html).\n\n## Pre-Requisites\n\n\nIn order to use BLE in Mbed OS you need one of the following hardware combinations:\n\n* 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.\n* A [DISCO_L475VG_IOT01A (ref B-L475E-IOT01A)](https://os.mbed.com/platforms/ST-Discovery-L475E-IOT01A/) board.\n* A [DISCO_L562QE (ref STM32L562E-DK)](https://os.mbed.com/platforms/ST-Discovery-L562QE/) board.\n* A [NUCLEO_WB55RG](https://os.mbed.com/platforms/ST-Nucleo-WB55RG/) board.\n* A Nordic nRF52-based board such as [nRF52DK](https://os.mbed.com/platforms/Nordic-nRF52-DK/).\n* An Embedded Planet [Agora](https://os.mbed.com/platforms/agora-dev/) board.\n\nThe [BLE documentation](https://os.mbed.com/docs/latest/reference/bluetooth.html) describes the BLE APIs on mbed OS.\n\n### Targets for BLE\n\nThe following targets have been tested and work with these examples:\n\n* Targets with an ST BLE expansion board plugged in:\n    * NUCLEO_F401RE\n    * NUCLEO_L476RG\n    * NUCLEO_L446RE\n    * K64F\n\n* ST boards with embedded SPBTLE-RF module (BlueNRG-MS):\n    * DISCO_L475VG_IOT01A (ref B-L475E-IOT01A)\n    * DISCO_L562QE (ref STM32L562E-DK)\n\n* Board with wireless STM32WB microcontrollers:\n    * NUCLEO_WB55RG\n\n* Nordic:\n    * NRF52_DK\n    * NRF52840_DK\n\n* Embedded Planet:\n    * EP_AGORA\n\n**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.\n\nThe following board is currently not supported as it doesn't yet support the Cordio stack:\n    * NRF51_DK\n\n### Using ST BLE expansion board on other targets\n\nIt is possible to use the ST BLE expansion on boards not directly supported by these examples as long as the board has an Arduino UNO R3 connector.\n\nTo make the board compatible with the ST BLE expansion three things are required:\n* Add the BLE feature to your target.\n* Add the BLE implementation for the ST BLE expansion to the list of modules which have to be compiled.\n* Indicate to the BLE implementation that your board uses an Arduino connector.\n\nAll these operations can be done in the file `mbed_app.json` present in every example.\n\nIn the section `target_overrides`, add a new object named after your target with the following three fields:\n* `\"target.components_add\": [\"BlueNRG_2\"]` Add the BlueNRG-2 component to the target.\n* `\"target.features_add\": [\"BLE\"]` Add the BLE feature to the target.\n* `\"target.extra_labels_add\": [\"CORDIO\"]`: Add the BLE implementation of the ST BLE expansion to the list of the application modules.\n\nBelow is an example of the JSON to be added in the `target_overrides` section of `mbed_app.json`, with the `NUCLEO_F401RE` board.\n\n```json\n        \"NUCLEO_F401RE\": {\n            \"target.components_add\": [\"BlueNRG_2\"],\n            \"target.features_add\": [\"BLE\"],\n            \"target.extra_labels_add\": [\"CORDIO\"]\n        },\n```\n\n**Note:** Further information about the configuration system is available in the [documentation](https://os.mbed.com/docs/latest/reference/configuration.html).\n\n**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.\n\n\n## Building the examples\n\n1. Clone the repository containing the collection of examples:\n\n    ```bash\n    $ git clone https://github.com/ARMmbed/mbed-os-example-ble.git\n    ```\n\n\n    **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.\n\n1. Using a command-line tool, navigate to any of the example directories, like BLE_Advertising:\n\n    ```bash\n    $ cd mbed-os-example-ble\n    $ cd BLE_Advertising\n    ```\n\n1. Update the source tree:\n\n    * Mbed CLI 2\n\n    ```bash\n    $ mbed-tools deploy\n    ```\n    \n    * Mbed CLI 1\n\n    ```bash\n    $ mbed deploy\n    ```\n\n1. Connect a USB cable between the USB port on the board and the host computer.\n\n1. Run the following command: this will build the example project, program the microcontroller flash memory, and then\nopen a serial terminal to the device.\n\n    * Mbed CLI 2\n\n    ```bash\n    $ mbed-tools compile -m \u003cTARGET\u003e -t \u003cTOOLCHAIN\u003e --flash --sterm --baudrate 115200\n    ```\n\n    * Mbed CLI 1\n\n    ```bash\n    $ mbed compile -m \u003cTARGET\u003e -t \u003cTOOLCHAIN\u003e --flash --sterm --baudrate 115200\n    ```\n\nYour PC may take a few minutes to compile your code.\n\nThe binary will be located in the following directory:\n* **Mbed CLI 2** - `./cmake_build/\u003cTARGET\u003e/\u003cPROFILE\u003e/\u003cTOOLCHAIN\u003e/`\n* **Mbed CLI 1** - `./BUILD/\u003cTARGET\u003e/\u003cTOOLCHAIN\u003e/`\n\nYou can manually copy the binary to the target, which gets mounted on the host computer through USB, rather than using the `--flash` option.\n\nYou can also open a serial terminal separately, as explained below, rather than using the `--sterm` and `--baudrate` options.\n\n## Running the examples\n\nWhen example application is running, information about activity is printed over the serial connection.\nThe default serial baudrate has been set to 115200 for these examples.\n\nIf not using the `--sterm` and `--baudrate` options when flashing, have a client \nopen and connected to the board. You may use:\n\n- Mbed CLI 2 \n    ```bash\n    $ mbed-tools sterm -b 115200\n    ```\n\n- Mbed CLI 1\n    ```bash\n    $ mbed sterm -b 115200\n    ```\n\n- [Tera Term](https://ttssh2.osdn.jp/index.html.en) for Windows\n\n- screen or minicom for Linux\n    ```bash\n    screen /dev/serial/\u003cyour board\u003e 115200\n    ```\n\nTo observe and/or interact with example applications please use any BLE scanner on a smartphone.\nIf you don't have a scanner on your phone, please install:\n\n- [nRF Connect for Mobile](https://play.google.com/store/apps/details?id=no.nordicsemi.android.mcp) for Android and iOS.\n\n- [ST BLE Profile](https://play.google.com/store/apps/details?id=com.stm.bluetoothlevalidation) for Android.\n\n\n## Using bare metal profile\n\nMBED BLE can support bare metal profile: https://os.mbed.com/docs/mbed-os/v6.10/bare-metal/using-the-bare-metal-profile.html\n\n\nHere is an example with NUCLEO_WB55RG, update your local mbed_app.json:\n```\n{\n    \"requires\": [\"bare-metal\", \"events\", \"cordio-stm32wb\"],\n```\n\n## How to reduce application size\n\nHere are few tips to reduce further application size (this could be in addition of baremetal)\n\nUpdate in mbed_app.json:\n\n```\n{\n    \"target_overrides\": {\n        \"*\": {\n            \"target.c_lib\": \"small\",\n            \"target.printf_lib\": \"minimal-printf\",\n            \"platform.minimal-printf-enable-floating-point\": false,\n            \"platform.stdio-minimal-console-only\": true,\n...\n```\n\n\n## Troubleshooting\n\nIf you encounter problems with running the example, first try to update to the `development` branch of the example and\nsee if the problem persists. Make sure to run `mbed update` after you checkout the `development` branch to update the\nlibraries to the versions in that branch.\n\nIf the problem persists, try turning on traces in the example. This is done by changing the config in `mbed_app.json`:\n\n```\n\t\t\"mbed-trace.enable\": true,\n\t\t\"mbed-trace.max-level\": \"TRACE_LEVEL_DEBUG\",\n\t\t\"cordio.trace-hci-packets\": true,\n\t\t\"cordio.trace-cordio-wsf-traces\": true,\n\t\t\"ble.trace-human-readable-enums\": true\n```\n\nCompile with `--profile debug` and run with the serial connected to your PC.\n\nThis will enable all the traces in BLE. If the number of traces is too big for the serial to handle or the image\ndoesn't fit try turning off all except the first one (`mbed-trace.enable`) and/or lowering the `max-level` to\n`\"TRACE_LEVEL_WARNING\"`.\n\nSave the output of the serial to a file. Please open an issue in this repo, describe the problem and attach the file\ncontaining the trace output.\n\n## License and contributions\n\nThe 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.\n\n## Branches\n\n`Master` branch is for releases only. Please target the `development` branch for all your PRs.\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farmmbed%2Fmbed-os-example-ble","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Farmmbed%2Fmbed-os-example-ble","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Farmmbed%2Fmbed-os-example-ble/lists"}