diff --git a/.editorconfig b/.editorconfig new file mode 100644 index 00000000..47433680 --- /dev/null +++ b/.editorconfig @@ -0,0 +1,26 @@ +[*] +end_of_line = lf +insert_final_newline = true +indent_style = space +indent_size = 2 +trim_trailing_whitespace = true + +[*.patch] +insert_final_newline = unset +indent_style = unset +indent_size = unset +trim_trailing_whitespace = unset + +[*.md] +trim_trailing_whitespace = false + +[*.sh] +# like -i=2 +indent_style = space +indent_size = 2 + +#shell_variant = posix # like -ln=posix +#binary_next_line = true # like -bn +switch_case_indent = true # like -ci +space_redirects = true # like -sr +#keep_padding = true # like -kp diff --git a/.gitattributes b/.gitattributes new file mode 100644 index 00000000..422ae6f5 --- /dev/null +++ b/.gitattributes @@ -0,0 +1,42 @@ +# Set the default behavior, in case people don't have core.autocrlf set. +* text=auto + +# Explicitly declare text files you want to always be normalized and converted +# to native line endings on checkout. +.editorconfig text eol=lf +.flake8 text eol=lf +.gitattributes text eol=lf +.gitignore text eol=lf + +*.adoc text eol=lf +*.c text eol=lf +*.cmake text eol=lf +*.cpp text eol=lf +*.css text eol=lf +*.dtsi text eol=lf +*.gv text eol=lf +*.h text eol=lf +*.html text eol=lf +*.in text eol=lf +*.ino text eol=lf +*.json text eol=lf +*.ld text eol=lf +*.md text eol=lf +*.MD text eol=lf +*.old text eol=lf +*.patch text eol=lf +*.pde text eol=lf +*.properties text eol=lf +*.py text eol=lf +*.s text eol=lf +*.S text eol=lf +*.sh text eol=lf +*.spec text eol=lf +*.txt text eol=lf +*.yml text eol=lf + +# Denote all files that are truly binary and should not be modified. +*.jpg binary +*.pdf binary +*.png binary + diff --git a/.github/dependabot.yml b/.github/dependabot.yml deleted file mode 100644 index f2bfa724..00000000 --- a/.github/dependabot.yml +++ /dev/null @@ -1,13 +0,0 @@ -# See: https://docs.github.com/en/code-security/supply-chain-security/configuration-options-for-dependency-updates#about-the-dependabotyml-file -version: 2 - -updates: - # Configure check for outdated GitHub Actions actions in workflows. - # Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/dependabot/README.md - # See: https://docs.github.com/en/code-security/supply-chain-security/keeping-your-actions-up-to-date-with-dependabot - - package-ecosystem: github-actions - directory: / # Check the repository's workflows under /.github/workflows/ - schedule: - interval: daily - labels: - - "topic: infrastructure" diff --git a/.github/workflows/compile-examples.yml b/.github/workflows/compile-examples.yml index 706ccb4c..903abc44 100644 --- a/.github/workflows/compile-examples.yml +++ b/.github/workflows/compile-examples.yml @@ -12,88 +12,20 @@ on: - ".github/workflows/compile-examples.yml" - "examples/**" - "src/**" - schedule: - # Run every Tuesday at 8 AM UTC to catch breakage caused by changes to external resources (libraries, platforms). - - cron: "0 8 * * TUE" workflow_dispatch: - repository_dispatch: jobs: - build: - name: ${{ matrix.board.fqbn }} + build-for-stm32: runs-on: ubuntu-latest - env: - SKETCHES_REPORTS_PATH: sketches-reports - - strategy: - fail-fast: false - - matrix: - board: - - fqbn: arduino:samd:mkrwifi1010 - platforms: | - - name: arduino:samd - artifact-name-suffix: arduino-samd-mkrwifi1010 - - fqbn: arduino:samd:nano_33_iot - platforms: | - - name: arduino:samd - artifact-name-suffix: arduino-samd-nano_33_iot - - fqbn: arduino:megaavr:uno2018:mode=on - platforms: | - - name: arduino:megaavr - artifact-name-suffix: arduino-megaavr-uno2018 - - fqbn: arduino:mbed_nano:nano33ble - platforms: | - - name: arduino:mbed_nano - artifact-name-suffix: arduino-mbed_nano-nano33ble - - fqbn: arduino:mbed_nano:nanorp2040connect - platforms: | - - name: arduino:mbed_nano - artifact-name-suffix: arduino-mbed_nano-nanorp2040connect - - fqbn: arduino:renesas_uno:unor4wifi - platforms: | - - name: arduino:renesas_uno - artifact-name-suffix: arduino-renesas_uno-unor4wifi - - steps: - - name: Checkout repository - uses: actions/checkout@v4 - - - name: Compile examples - uses: arduino/compile-sketches@v1 - with: - github-token: ${{ secrets.GITHUB_TOKEN }} - fqbn: ${{ matrix.board.fqbn }} - platforms: ${{ matrix.board.platforms }} - libraries: | - # Install the library from the local path. - - source-path: ./ - sketch-paths: | - - examples - enable-deltas-report: true - sketches-report-path: ${{ env.SKETCHES_REPORTS_PATH }} - - - name: Save sketches report as workflow artifact - uses: actions/upload-artifact@v4 - with: - if-no-files-found: error - path: ${{ env.SKETCHES_REPORTS_PATH }} - name: sketches-report-${{ matrix.board.artifact-name-suffix }} - - build-for-esp32: - runs-on: ubuntu-latest - strategy: matrix: fqbn: - - esp32:esp32:esp32 - - esp32:esp32:esp32s3 - - esp32:esp32:esp32c3 - # future bluetooth chips - #- esp32:esp32:esp32c2 - #- esp32:esp32:esp32c6 - #- esp32:esp32:esp32h2 + - STMicroelectronics:stm32:Eval:pnum=STEVAL_MKSBOX1V1,usb=CDCgen + - STMicroelectronics:stm32:Nucleo_64:pnum=NUCLEO_L476RG + - STMicroelectronics:stm32:Disco:pnum=B_L475E_IOT01A + - STMicroelectronics:stm32:Nucleo_64:pnum=P_NUCLEO_WB55RG + - STMicroelectronics:stm32:Nucleo_64:pnum=P_NUCLEO_WB55_USB_DONGLE steps: - uses: actions/checkout@v4 @@ -102,14 +34,11 @@ jobs: github-token: ${{ secrets.GITHUB_TOKEN }} fqbn: ${{ matrix.fqbn }} platforms: | - - name: esp32:esp32 - source-url: https://raw.githubusercontent.com/espressif/arduino-esp32/gh-pages/package_esp32_index.json + - name: STMicroelectronics:stm32 + source-url: https://github.com/stm32duino/BoardManagerFiles/raw/main/package_stmicroelectronics_index.json sketch-paths: | - - examples/Central/Scan - - examples/Central/PeripheralExplorer - - examples/Central/ScanCallback - - examples/Central/SensorTagButton - - examples/Peripheral/Advertising/EnhancedAdvertising - - examples/Peripheral/Advertising/RawDataAdvertising + - examples cli-compile-flags: | - - --warnings="none" + - --build-property + - build.extra_flags=-DIDB05A2_SPI_CLOCK_D3 + diff --git a/.github/workflows/report-size-deltas.yml b/.github/workflows/report-size-deltas.yml deleted file mode 100644 index 39e2a0ad..00000000 --- a/.github/workflows/report-size-deltas.yml +++ /dev/null @@ -1,24 +0,0 @@ -name: Report Size Deltas - -# See: https://docs.github.com/en/free-pro-team@latest/actions/reference/events-that-trigger-workflows -on: - push: - paths: - - ".github/workflows/report-size-deltas.yml" - schedule: - # Run at the minimum interval allowed by GitHub Actions. - # Note: GitHub Actions periodically has outages which result in workflow failures. - # In this event, the workflows will start passing again once the service recovers. - - cron: "*/5 * * * *" - workflow_dispatch: - repository_dispatch: - -jobs: - report: - runs-on: ubuntu-latest - steps: - - name: Comment size deltas reports to PRs - uses: arduino/report-size-deltas@v1 - with: - # Regex matching the names of the workflow artifacts created by the "Compile Examples" workflow - sketches-reports-source: ^sketches-report-.+ diff --git a/.github/workflows/spell-check.yml b/.github/workflows/spell-check.yml index 6faf09c8..61af09cd 100644 --- a/.github/workflows/spell-check.yml +++ b/.github/workflows/spell-check.yml @@ -23,3 +23,10 @@ jobs: - name: Spell check uses: codespell-project/actions-codespell@v2 + with: + check_filenames: true + check_hidden: true + # In the event of a false positive, add the word in all lower case to this file: + # ignore_words_file: ./extras/codespell-ignore-words-list.txt + skip: src/utility/STM32_WPAN + path: src diff --git a/.github/workflows/sync-labels.yml b/.github/workflows/sync-labels.yml deleted file mode 100644 index 53a9f54f..00000000 --- a/.github/workflows/sync-labels.yml +++ /dev/null @@ -1,138 +0,0 @@ -# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/sync-labels.md -name: Sync Labels - -# See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows -on: - push: - paths: - - ".github/workflows/sync-labels.ya?ml" - - ".github/label-configuration-files/*.ya?ml" - pull_request: - paths: - - ".github/workflows/sync-labels.ya?ml" - - ".github/label-configuration-files/*.ya?ml" - schedule: - # Run daily at 8 AM UTC to sync with changes to shared label configurations. - - cron: "0 8 * * *" - workflow_dispatch: - repository_dispatch: - -env: - CONFIGURATIONS_FOLDER: .github/label-configuration-files - CONFIGURATIONS_ARTIFACT: label-configuration-files - -jobs: - check: - runs-on: ubuntu-latest - - steps: - - name: Checkout repository - uses: actions/checkout@v4 - - - name: Download JSON schema for labels configuration file - id: download-schema - uses: carlosperate/download-file-action@v2 - with: - file-url: https://raw.githubusercontent.com/arduino/tooling-project-assets/main/workflow-templates/assets/sync-labels/arduino-tooling-gh-label-configuration-schema.json - location: ${{ runner.temp }}/label-configuration-schema - - - name: Install JSON schema validator - run: | - sudo npm install \ - --global \ - ajv-cli \ - ajv-formats - - - name: Validate local labels configuration - run: | - # See: https://github.com/ajv-validator/ajv-cli#readme - ajv validate \ - --all-errors \ - -c ajv-formats \ - -s "${{ steps.download-schema.outputs.file-path }}" \ - -d "${{ env.CONFIGURATIONS_FOLDER }}/*.{yml,yaml}" - - download: - needs: check - runs-on: ubuntu-latest - - strategy: - matrix: - filename: - # Filenames of the shared configurations to apply to the repository in addition to the local configuration. - # https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/sync-labels - - universal.yml - - steps: - - name: Download - uses: carlosperate/download-file-action@v2 - with: - file-url: https://raw.githubusercontent.com/arduino/tooling-project-assets/main/workflow-templates/assets/sync-labels/${{ matrix.filename }} - - - name: Pass configuration files to next job via workflow artifact - uses: actions/upload-artifact@v4 - with: - path: | - *.yaml - *.yml - if-no-files-found: error - name: ${{ env.CONFIGURATIONS_ARTIFACT }} - - sync: - needs: download - runs-on: ubuntu-latest - - steps: - - name: Set environment variables - run: | - # See: https://docs.github.com/en/actions/reference/workflow-commands-for-github-actions#setting-an-environment-variable - echo "MERGED_CONFIGURATION_PATH=${{ runner.temp }}/labels.yml" >> "$GITHUB_ENV" - - - name: Determine whether to dry run - id: dry-run - if: > - github.event_name == 'pull_request' || - ( - ( - github.event_name == 'push' || - github.event_name == 'workflow_dispatch' - ) && - github.ref != format('refs/heads/{0}', github.event.repository.default_branch) - ) - run: | - # Use of this flag in the github-label-sync command will cause it to only check the validity of the - # configuration. - echo "::set-output name=flag::--dry-run" - - - name: Checkout repository - uses: actions/checkout@v4 - - - name: Download configuration files artifact - uses: actions/download-artifact@v4 - with: - name: ${{ env.CONFIGURATIONS_ARTIFACT }} - path: ${{ env.CONFIGURATIONS_FOLDER }} - - - name: Remove unneeded artifact - uses: geekyeggo/delete-artifact@v5 - with: - name: ${{ env.CONFIGURATIONS_ARTIFACT }} - - - name: Merge label configuration files - run: | - # Merge all configuration files - shopt -s extglob - cat "${{ env.CONFIGURATIONS_FOLDER }}"/*.@(yml|yaml) > "${{ env.MERGED_CONFIGURATION_PATH }}" - - - name: Install github-label-sync - run: sudo npm install --global github-label-sync - - - name: Sync labels - env: - GITHUB_ACCESS_TOKEN: ${{ secrets.GITHUB_TOKEN }} - run: | - # See: https://github.com/Financial-Times/github-label-sync - github-label-sync \ - --labels "${{ env.MERGED_CONFIGURATION_PATH }}" \ - ${{ steps.dry-run.outputs.flag }} \ - ${{ github.repository }} diff --git a/README.md b/README.md index b0027583..660c78fd 100644 --- a/README.md +++ b/README.md @@ -1,22 +1,102 @@ -# ArduinoBLE +# STM32duinoBLE -[![Compile Examples Status](https://github.com/arduino-libraries/ArduinoBLE/workflows/Compile%20Examples/badge.svg)](https://github.com/arduino-libraries/ArduinoBLE/actions?workflow=Compile+Examples) [![Spell Check Status](https://github.com/arduino-libraries/ArduinoBLE/workflows/Spell%20Check/badge.svg)](https://github.com/arduino-libraries/ArduinoBLE/actions?workflow=Spell+Check) +This library is a fork of ArduinoBLE library to add the support of STM32WB, SPBTLE-RF, SPBTLE-1S, BLUENRG-M2SP, BLUENRG-LP and BLUENRG-M0 BLE modules. -Enables Bluetooth® Low Energy connectivity on the Arduino MKR WiFi 1010, Arduino UNO WiFi Rev2, Arduino Nano 33 IoT, Arduino Nano 33 BLE, Arduino Portenta H7, Arduino Giga R1 and Arduino UNO R4 WiFi. +It was successfully tested with the NUCLEO-WB15CC, P-NUCELO_WB55RG, STM32WB5MM-DK, X-NUCLEO-IDB05A2 or +X-NUCLEO-IDB05A1 or X-NUCLEO-BNRG2A1 expansion board and a NUCLEO-F401RE or NUCLEO-L476RG or NUCLEO-L053R8, +with B-L475E-IOT01A and with STEVAL-MKSBOX1V1. -This library supports creating a Bluetooth® Low Energy peripheral & central mode. + - In order to use this library with SM32WBxx series, you need to update the STM32WB Copro Wireless Binaries with stm32wbxx_BLE_HCILayer_fw.bin depending of your mcu: -For the Arduino MKR WiFi 1010, Arduino UNO WiFi Rev2, and Arduino Nano 33 IoT boards, it requires the NINA module to be running [Arduino NINA-W102 firmware](https://github.com/arduino/nina-fw) v1.2.0 or later. +https://github.com/STMicroelectronics/STM32CubeWB/tree/master/Projects/STM32WB_Copro_Wireless_Binaries -For the Arduino UNO R4 WiFi, it requires the ESP32-S3 module to be running [firmware](https://github.com/arduino/uno-r4-wifi-usb-bridge) v0.2.0 or later. + Each subdirectories contains binaries and Release_Notes.html which explain how to update it. + - In order to use this library with STEVAL-MKSBOX1V1, you need to update the firmware of the SPBTLE-1S BLE module mounted on that board as described in the following wiki page: + +https://github.com/stm32duino/Arduino_Core_STM32/wiki/STM32duinoBLE#stm32duinoble-with-steval_mksbox1v1 + +- In order to use this library with X-NUCLEO-BNRG2A1, you need to update the firmware of the BLUENRG-M2SP BLE module mounted on that expansion board as described in the following wiki page: + +https://github.com/stm32duino/Arduino_Core_STM32/wiki/STM32duinoBLE#stm32duinoble-with-x-nucleo-bnrg2a1 + +For more information about ArduinoBLE library please visit the official web page at: -For more information about this library please visit us at: https://www.arduino.cc/en/Reference/ArduinoBLE +# Configuration + +### STM32WB + +STM32Cube_WPAN has several configuration options, which are set in the `app_conf.h`. +This package has a default configuration named `app_conf_default.h`. +The user can include the file `app_conf_custom.h` to customize the BLE application. +Options wrapped in `#ifndef`, `#endif` in `app_conf_default.h` can be overwritten. +Additional options can be added. + +### Shield + +The user can include the file `ble_spi_conf.h` to define which shield and configuration to use from the following list: + + * [X-NUCLEO-IDB05A2](https://www.st.com/en/ecosystems/x-nucleo-idb05a2.html) + * `IDB05A2_SPI_CLOCK_D3`: SPI clock on D3 + * `IDB05A2_SPI_CLOCK_D13` SPI clock on D13 + * [X-NUCLEO-IDB05A1](https://www.st.com/en/ecosystems/x-nucleo-idb05a1.html) + * `IDB05A1_SPI_CLOCK_D3`: SPI clock on D3 + * `IDB05A1_SPI_CLOCK_D13`: SPI clock on D13 + * [X-NUCLEO-BNRG2A1](https://www.st.com/en/ecosystems/x-nucleo-bnrg2a1.html) + * `BNRG2A1_CLOCK_D3`: SPI clock on D3 + * `BNRG2A1_CLOCK_D13`: SPI clock on D13 + * `CUSTOM_BLE_SPI`: define a custom configuration, it requires below definition: + * `BLE_SPI_MISO`: SPI MISO pin + * `BLE_SPI_MOSI`: SPI MOSI pin + * `BLE_SPI_CLK`: SPI CLocK pin + * `BLE_SPI_CS`: SPI Chip Select pin + * `BLE_SPI_IRQ`: SPI IRQ pin + * `BLE_SPI_FREQ`: SPI bus frequency + * `BLE_SPI_MODE`: can be one of the below `SPIMode`: + * `SPI_MODE0` + * `SPI_MODE1` + * `SPI_MODE2` + * `SPI_MODE0` + * `BLE_CHIP_TYPE`: can be one of the below `BLEChip_t`: + * `SPBTLE_RF` + * `SPBTLE_1S` + * `BLUENRG_M2SP` + * `BLUENRG_M0` + * `BLUENRG_LP` + * `BLE_RESET`: BLE reset pin + +#### Examples + +To use the [X-NUCLEO-IDB05A2](https://www.st.com/en/ecosystems/x-nucleo-idb05a2.html) with SPI clock on D3, define in `ble_spi_conf.h`: +```C +#define IDB05A2_SPI_CLOCK_D3 +``` +This is equivalent to the below configuration using the `CUSTOM_BLE_SPI`: +```C +#define CUSTOM_BLE_SPI +#define BLE_SPI_MISO D12 +#define BLE_SPI_MOSI D11 +#define BLE_SPI_CLK D3 +#define BLE_SPI_CS A1 +#define BLE_SPI_IRQ A0 +#define BLE_SPI_FREQ 8000000 +#define BLE_SPI_MODE SPI_MODE0 +#define BLE_CHIP_TYPE BLUENRG_M0 +#define BLE_RESET D7 +``` + +#### Using a SPI BLE module on STM32WB + +If required, user can use a compatible BLE module over SPI. + +In the `ble_spi_conf.h`, define `USE_BLE_SPI`. + ## License ``` +Copyright (c) 2019 STMicroelectronics. All rights reserved. Copyright (c) 2019 Arduino SA. All rights reserved. This library is free software; you can redistribute it and/or diff --git a/docs/api.md b/docs/api.md deleted file mode 100644 index c9f41840..00000000 --- a/docs/api.md +++ /dev/null @@ -1,3818 +0,0 @@ -# ArduinoBLE library - -## BLE class - -Used to enable the Bluetooth® Low Energy module. - -### `BLE.begin()` - -Initializes the Bluetooth® Low Energy device. - -#### Syntax - -``` -BLE.begin() - -``` - -#### Parameters - -None - -#### Returns -- 1 on success -- 0 on failure - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - -``` - -### `BLE.end()` - -Stops the Bluetooth® Low Energy device. - -#### Syntax - -``` -BLE.end() - -``` - -#### Parameters - -None - -#### Returns -Nothing - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - // .... - - BLE.end(); - - -``` - -### `BLE.poll()` - -Poll for Bluetooth® Low Energy radio events and handle them. - -#### Syntax - -``` -BLE.poll() -BLE.poll(timeout) - -``` - -#### Parameters - -**timeout**: optional timeout in ms, to wait for event. If not specified defaults to 0 ms. - -#### Returns -Nothing - -#### Example - -```arduino - - // assign event handlers for connected, disconnected to peripheral - BLE.setEventHandler(BLEConnected, blePeripheralConnectHandler); - BLE.setEventHandler(BLEDisconnected, blePeripheralDisconnectHandler); - - - BLE.poll(); - - -``` - -### `BLE.setEventHandler()` - -Set the event handler (callback) function that will be called when the specified event occurs. - -#### Syntax - -``` -BLE.setEventHandler(eventType, callback) - -``` - -#### Parameters - -- **eventType**: event type (BLEConnected, BLEDisconnected) -- **callback**: function to call when event occurs -#### Returns -Nothing. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - // ... - - // assign event handlers for connected, disconnected to peripheral - BLE.setEventHandler(BLEConnected, blePeripheralConnectHandler); - BLE.setEventHandler(BLEDisconnected, blePeripheralDisconnectHandler); - - - -void blePeripheralConnectHandler(BLEDevice central) { - // central connected event handler - Serial.print("Connected event, central: "); - Serial.println(central.address()); -} - -void blePeripheralDisconnectHandler(BLEDevice central) { - // central disconnected event handler - Serial.print("Disconnected event, central: "); - Serial.println(central.address()); -} - - -``` - -### `BLE.connected()` - -Query if another Bluetooth® Low Energy device is connected - -#### Syntax - -``` -BLE.connected() - -``` - -#### Parameters - -None - -#### Returns -- **true** if another Bluetooth® Low Energy device is connected, -- otherwise **false**. - -#### Example - -```arduino - - // while the central is still connected to peripheral: - while (BLE.connected()) { - - // ... - } - - -``` - -### `BLE.disconnect()` - -Disconnect any Bluetooth® Low Energy devices that are connected - -#### Syntax - -``` -BLE.disconnect() - -``` - -#### Parameters - -None - -#### Returns -- **true** if any Bluetooth® Low Energy device that was previously connected was disconnected, -- otherwise **false**. - -#### Example - -```arduino - - if (BLE.connected()) { - BLE.disconnect(); - } - - -``` - -### `BLE.address()` - -Query the Bluetooth® address of the Bluetooth® Low Energy device. - -#### Syntax - -``` -BLE.address() - -``` - -#### Parameters - -None - -#### Returns -- The **Bluetooth® address** of the Bluetooth® Low Energy device (as a String). - -#### Example - -```arduino - - String address = BLE.address(); - - Serial.print("Local address is: "); - Serial.println(address); - - -``` - -### `BLE.rssi()` - -Query the RSSI (Received signal strength indication) of the connected Bluetooth® Low Energy device. - -#### Syntax - -``` -BLE.rssi() - -``` - -#### Parameters - -None - -#### Returns -- The **RSSI** of the connected Bluetooth® Low Energy device, 127 if no Bluetooth® Low Energy device is connected. - -#### Example - -```arduino - - if (BLE.connected()) { - Serial.print("RSSI = "); - Serial.println(BLE.rssi()); - } - - -``` - -### `BLE.setAdvertisedServiceUuid()` - -Set the advertised service UUID used when advertising. - -#### Syntax - -``` -BLE.setAdvertisedServiceUuid(uuid) - -``` - -#### Parameters - -- **uuid:** 16-bit or 128-bit Bluetooth® Low Energy UUID in **String** format - -#### Returns -Nothing - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - BLE.setAdvertisedServiceUuid("19B10000-E8F2-537E-4F6C-D104768A1214"); - - // ... - - // start advertising - BLE.advertise(); - - -``` - -### `BLE.setAdvertisedService()` - -Set the advertised service UUID used when advertising to the value of the BLEService provided. - -#### Syntax - -``` -BLE.setAdvertisedService(bleService) - -``` - -#### Parameters - -- **bleService:** BLEService to use UUID from - -#### Returns -Nothing - -#### Example - -```arduino - -BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // Bluetooth® Low Energy LED Service - -// ... - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - BLE.setAdvertisedService(ledService); - - // ... - - // start advertising - BLE.advertise(); - - -``` - -### `BLE.setManufacturerData()` - -Set the manufacturer data value used when advertising. - -#### Syntax - -``` -BLE.setManufacturerData(data, length) - -``` - -#### Parameters - -- **data:** byte array containing manufacturer data -- **length:** length of manufacturer data array - -#### Returns -Nothing - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - byte data[5] = { 0x01, 0x02, 0x03, 0x04, 0x05}; - - BLE.setManufacturerData(data, 5); - - // ... - - // start advertising - BLE.advertise(); - - - -``` - -### `BLE.setLocalName()` - -Set the local value used when advertising. - -#### Syntax - -``` -BLE.setLocalName(name) - -``` - -#### Parameters - -- **name:** local name value to use when advertising - -#### Returns -Nothing - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - BLE.setLocalName("LED"); - - // ... - - // start advertising - BLE.advertise(); - - - -``` - -### `BLE.setDeviceName()` - -Set the device name in the built in device name characteristic. If not set, the value defaults to “Arduino”. - -#### Syntax - -``` -BLE.setDeviceName(name) - -``` - -#### Parameters - -- **name:** device name value - -#### Returns -Nothing - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - BLE.setDeviceName("LED"); - - // ... - - // start advertising - BLE.advertise(); - - - -``` - -### `BLE.setAppearance()` - -Set the appearance in the built in appearance characteristic. If not set, the value defaults to 0x0000. - -#### Syntax - -``` -BLE.setAppearance(appearance) - -``` - -#### Parameters - -- **appearance:** appearance value - -#### Returns -Nothing - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - BLE.setAppearance(0x8000); - - // ... - - // start advertising - BLE.advertise(); - - - -``` - -### `BLE.addService()` - -Add a BLEService to the set of services the Bluetooth® Low Energy device provides - -#### Syntax - -``` -BLE.addService(service) - -``` - -#### Parameters - -- **service:** BLEService to add - -#### Returns -Nothing - -#### Example - -```arduino - -BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // Bluetooth® Low Energy LED Service - - - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - // ... - - BLE.addService(ledService); - - // ... - - -``` - -### `BLE.advertise()` - -Start advertising. - -#### Syntax - -``` -BLE.advertise() - -``` - -#### Parameters - -None - -#### Returns -- 1 on success, -- 0 on failure. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - // ... - - BLE.advertise(); - - // ... - - -``` - -### `BLE.stopAdvertise()` - -Stop advertising. - -#### Syntax - -``` -BLE.stopAdvertise() - -``` - -#### Parameters - -None - -#### Returns -Nothing - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - // ... - - BLE.advertise(); - - // ... - - BLE.stopAdvertise(); - - -``` - -### `BLE.central()` - -Query the central Bluetooth® Low Energy device connected. - -#### Syntax - -``` -BLE.central() - -``` - -#### Parameters - -None - -#### Returns -- **BLEDevice** representing the central. - -#### Example - -```arduino - - // listen for Bluetooth® Low Energy peripherals to connect: - BLEDevice central = BLE.central(); - - // if a central is connected to peripheral: - if (central) { - Serial.print("Connected to central: "); - // print the central's MAC address: - Serial.println(central.address()); - } - - -``` - -### `BLE.setAdvertisingInterval()` - -Set the advertising interval in units of 0.625 ms. Defaults to 100ms (160 * 0.625 ms) if not provided. - -#### Syntax - -``` -BLE.setAdvertisingInterval(advertisingInterval) - -``` - -#### Parameters - -- **advertisingInterval:** advertising interval in units of 0.625 ms - -#### Returns -Nothing. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - // ... - - BLE.setAdvertisingInterval(320); // 200 * 0.625 ms - - BLE.advertise(); - - -``` - -### `BLE.setConnectionInterval()` - -Set the minimum and maximum desired connection intervals in units of 1.25 ms. - -#### Syntax - -``` -BLE.setConnectionInterval(minimum, maximum) - -``` - -#### Parameters - -- **minimum:** minimum desired connection interval in units of 1.25 ms -- **maximum:** maximum desired connection interval in units of 1.25 ms - -#### Returns -Nothing. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - // ... - - BLE.setConnectionInterval(0x0006, 0x0c80); // 7.5 ms minimum, 4 s maximum - - - -``` - -### `BLE.setConnectable()` - -Set if the device is connectable after advertising, defaults to **true**. - -#### Syntax - -``` -BLE.setConnectable(connectable) - -``` - -#### Parameters - -- **true**: the device will be connectable when advertising -- **false**: the device will NOT be connectable when advertising - -#### Returns -Nothing. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - // ... - - BLE.setConnectable(false); // make the device unconnectable when advertising - - - -``` - -### `BLE.scan()` - -Start scanning for Bluetooth® Low Energy devices that are advertising. - -#### Syntax - -``` -BLE.scan() -BLE.scan(withDuplicates) - -``` - -#### Parameters - -- **withDuplicates:** optional, defaults to **false**. If **true**, advertisements received more than once will not be filtered - -#### Returns -- 1 on success, -- 0 on failure. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - } - - -``` - -### `BLE.scanForName()` - -Start scanning for Bluetooth® Low Energy devices that are advertising with a particular (local) name. - -#### Syntax - -``` -BLE.scanForName(name) -BLE.scanForName(name, withDuplicates) - -``` - -#### Parameters - -- **name:** (local) name of device (as a **String**) to filter for -- **withDuplicates:** optional, defaults to **false**. If **true**, advertisements received more than once will not be filtered. - -#### Returns -- 1 on success, -- 0 on failure. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scanForName("LED"); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - } - - -``` - -### `BLE.scanForAddress()` - -Start scanning for Bluetooth® Low Energy devices that are advertising with a particular (Bluetooth®) address. - -#### Syntax - -``` -BLE.scanForAddress(address) -BLE.scanForAddress(address, withDuplicates) - -``` - -#### Parameters - -- **address:** (Bluetooth®) address (as a String) to filter for -- **withDuplicates:** optional, defaults to **false**. If **true**, advertisements received more than once will not be filtered - -#### Returns -- 1 on success, -- 0 on failure. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scanForAddress("aa:bb:cc:ee:dd:ff"); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - } - - -``` - -### `BLE.scanForUuid()` - -Start scanning for Bluetooth® Low Energy devices that are advertising with a particular (service) UUID. - -#### Syntax - -``` -BLE.scanForUuid(uuid) -BLE.scanForUuid(uuid, withDuplicates) - -``` - -#### Parameters - -- **uuid:** (service) UUID (as a **String**) to filter for -- **withDuplicates:** optional, defaults to **false**. If **true**, advertisements received more than once will not be filtered. - -#### Returns -- 1 on success, -- 0 on failure. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scanForUuid("aa10"); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - } - - -``` - -### `BLE.stopScan()` - -Stop scanning for Bluetooth® Low Energy devices that are advertising. - -#### Syntax - -``` -BLE.stopScan() - -``` - -#### Parameters - -None - -#### Returns -Nothing - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - BLE.stopScan(); - - -``` - -### `BLE.available()` - -Query for a discovered Bluetooth® Low Energy device that was found during scanning. - -#### Syntax - -``` -BLE.available() - -``` - -#### Parameters - -Nothing - -#### Returns -- **BLEDevice** representing the discovered device. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - } - - -``` - -## BLEDevice Class - -Used to get information about the devices connected or discovered while scanning - -### `bleDevice.poll()` - -Poll for Bluetooth® Low Energy radio events for the specified Bluetooth® Low Energy device and handle them. - -#### Syntax - -``` -bleDevice.poll() -bleDevice.poll(timeout) - -``` - -#### Parameters - -- **timeout**: optional timeout in ms, to wait for event. If not specified defaults to 0 ms. - -#### Returns -Nothing - -#### Example - -```arduino - - // listen for Bluetooth® Low Energy centrals to connect: - BLEDevice central = BLE.central(); - - // if a central is connected to peripheral: - if (central) { - central.poll(); - - // ... - } - - -``` - -### `bleDevice.connected()` - -Query if a Bluetooth® Low Energy device is connected - -#### Syntax - -``` -bleDevice.connected() - -``` - -#### Parameters - -None - -#### Returns -- **true** if the Bluetooth® Low Energy device is connected, -- otherwise **false**. - -#### Example - -```arduino - - // listen for Bluetooth® Low Energy centrals to connect: - BLEDevice central = BLE.central(); - - // while the central is still connected - while (central.connected()) { - - // ... - } - - -``` - -### `bleDevice.disconnect()` - -Disconnect the Bluetooth® Low Energy device, if connected - -#### Syntax - -``` -bleDevice.disconnect() - -``` - -#### Parameters - -None - -#### Returns -- **true** if the Bluetooth® Low Energy device was disconnected, -- otherwise **false**. - -#### Example - -```arduino - - // listen for Bluetooth® Low Energy centrals to connect: - BLEDevice central = BLE.central(); - - - central.disconnect(); - - -``` - -### `bleDevice.address()` - -Query the Bluetooth® address of the Bluetooth® Low Energy device. - -#### Syntax - -``` -bleDevice.address() - -``` - -#### Parameters - -None - -#### Returns -- **Bluetooth® address** of the Bluetooth® Low Energy device (as a String). - -#### Example - -```arduino - - // listen for Bluetooth® Low Energy peripherals to connect: - BLEDevice central = BLE.central(); - - // if a central is connected to peripheral: - if (central) { - Serial.print("Connected to central: "); - // print the central's MAC address: - Serial.println(central.address()); - } - - -``` - -### `bleDevice.rssi()` - -Query the RSSI (Received signal strength indication) of the Bluetooth® Low Energy device. - -#### Syntax - -``` -bleDevice.rssi() - -``` - -#### Parameters - -None - -#### Returns -- **RSSI** of the connected Bluetooth® Low Energy device, 127 if the Bluetooth® Low Energy device is not connected. - -#### Example - -```arduino - - if (bleDevice.connected()) { - Serial.print("RSSI = "); - Serial.println(bleDevice.rssi()); - } - - -``` - -### `bleDevice.characteristic()` - -Get a BLECharacteristic representing a Bluetooth® Low Energy characteristic the device provides. - -#### Syntax - -``` -bleDevice.characteristic(index) -bleDevice.characteristic(uuid) -bleDevice.characteristic(uuid, index) - -``` - -#### Parameters - -- **index**: index of characteristic -- **uuid**: uuid (as a **String**) - -#### Returns -- **BLECharacteristic** for provided parameters - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - - Serial.println("Connecting ..."); - - if (peripheral.connect()) { - Serial.println("Connected"); - } else { - Serial.println("Failed to connect!"); - return; - } - - // discover peripheral attributes - Serial.println("Discovering attributes ..."); - if (peripheral.discoverAttributes()) { - Serial.println("Attributes discovered"); - } else { - Serial.println("Attribute discovery failed!"); - peripheral.disconnect(); - return; - } - - BLECharacteristic batteryLevelCharacteristic = peripheral.characteristic("2a19"); - - if (batteryLevelCharacteristic) { - // use the characteristic - } else { - Serial.println("Peripheral does NOT have battery level characteristic"); - } - - // ... - } - - -``` - -### `bleDevice.discoverAttributes()` - -Discover all of the attributes of Bluetooth® Low Energy device. - -#### Syntax - -``` -bleDevice.discoverAttributes() - -``` - -#### Parameters - -None - -#### Returns -- **true**, if successful, -- **false** on failure. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - - Serial.println("Connecting ..."); - - if (peripheral.connect()) { - Serial.println("Connected"); - } else { - Serial.println("Failed to connect!"); - return; - } - - // discover peripheral attributes - Serial.println("Discovering attributes ..."); - if (peripheral.discoverAttributes()) { - Serial.println("Attributes discovered"); - } else { - Serial.println("Attribute discovery failed!"); - peripheral.disconnect(); - return; - } - - // ... - } - - -``` - -### `bleDevice.discoverService()` - -Discover the attributes of a particular service on the Bluetooth® Low Energy device. - -#### Syntax - -``` -bleDevice.discoverService(serviceUuid) - -``` - -#### Parameters - -- **serviceUuid:** service UUID to discover (as a **String**) - -#### Returns -- **true**, if successful, -- **false** on failure. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - - Serial.println("Connecting ..."); - - if (peripheral.connect()) { - Serial.println("Connected"); - } else { - Serial.println("Failed to connect!"); - return; - } - - // discover service attributes - Serial.println("Discovering service attributes ..."); - if (peripheral.serviceUuid("fffe")) { - Serial.println("Service attributes discovered"); - } else { - Serial.println("Service attribute discovery failed!"); - peripheral.disconnect(); - return; - } - - // ... - } - - -``` - -### `bleDevice.deviceName()` - -Query the device name (BLE characteristic UUID 0x2a00) of a Bluetooth® Low Energy device. - -#### Syntax - -``` -bleDevice.deviceName() - -``` - -#### Parameters - -None - -#### Returns -- **Device name** (as a String). - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - - Serial.println("Connecting ..."); - - if (peripheral.connect()) { - Serial.println("Connected"); - } else { - Serial.println("Failed to connect!"); - return; - } - - // discover peripheral attributes - Serial.println("Discovering attributes ..."); - if (peripheral.discoverAttributes()) { - Serial.println("Attributes discovered"); - } else { - Serial.println("Attribute discovery failed!"); - peripheral.disconnect(); - return; - } - - // read and print device name of peripheral - Serial.println(); - Serial.print("Device name: "); - Serial.println(peripheral.deviceName()); - Serial.print("Appearance: 0x"); - Serial.println(peripheral.appearance(), HEX); - Serial.println(); - - // ... - } - - -``` - -### `bleDevice.appearance()` - -Query the appearance (BLE characteristic UUID 0x2a01) of a Bluetooth® Low Energy device. - -#### Syntax - -``` -bleDevice.appearance() - -``` - -#### Parameters - -None - -#### Returns -- **Appearance value** (as a number). - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - - Serial.println("Connecting ..."); - - if (peripheral.connect()) { - Serial.println("Connected"); - } else { - Serial.println("Failed to connect!"); - return; - } - - // discover peripheral attributes - Serial.println("Discovering attributes ..."); - if (peripheral.discoverAttributes()) { - Serial.println("Attributes discovered"); - } else { - Serial.println("Attribute discovery failed!"); - peripheral.disconnect(); - return; - } - - // read and print device name of peripheral - Serial.println(); - Serial.print("Device name: "); - Serial.println(peripheral.deviceName()); - Serial.print("Appearance: 0x"); - Serial.println(peripheral.appearance(), HEX); - Serial.println(); - - // ... - } - - -``` - -### `bleDevice.serviceCount()` - -Query the number of services discovered for the Bluetooth® Low Energy device. - -#### Syntax - -``` -bleDevice.serviceCount() - -``` - -#### Parameters - -None - -#### Returns -- The number of **services discovered** for the Bluetooth® Low Energy device. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - - Serial.println("Connecting ..."); - - if (peripheral.connect()) { - Serial.println("Connected"); - } else { - Serial.println("Failed to connect!"); - return; - } - - // discover peripheral attributes - Serial.println("Discovering attributes ..."); - if (peripheral.discoverAttributes()) { - Serial.println("Attributes discovered"); - } else { - Serial.println("Attribute discovery failed!"); - peripheral.disconnect(); - return; - } - - int serviceCount = peripheral.serviceCount(); - - Serial.print(serviceCount); - Serial.println(" services discovered"); - - // ... - } - - -``` - -### `bleDevice.hasService()` - -Query if the Bluetooth® Low Energy device has a particular service. - -#### Syntax - -``` -bleDevice.hasService(uuid) -bleDevice.hasService(uuid, index) - -``` - -#### Parameters - -- **uuid**: uuid to check (as a **String**) -- **index**: optional, index of service to check if the device provides more than on. Defaults to 0, if not provided. - -#### Returns -- **true**, if the device provides the service, -- **false** otherwise. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - - Serial.println("Connecting ..."); - - if (peripheral.connect()) { - Serial.println("Connected"); - } else { - Serial.println("Failed to connect!"); - return; - } - - // discover peripheral attributes - Serial.println("Discovering attributes ..."); - if (peripheral.discoverAttributes()) { - Serial.println("Attributes discovered"); - } else { - Serial.println("Attribute discovery failed!"); - peripheral.disconnect(); - return; - } - - if (peripheral.hasService("180f")) { - Serial.println("Peripheral has battery service"); - } - - // ... - } - - -``` - -### `bleDevice.service()` - -Get a BLEService representing a Bluetooth® Low Energy service the device provides. - -#### Syntax - -``` -bleDevice.service(index) -bleDevice.service(uuid) -bleDevice.service(uuid, index) - -``` - -#### Parameters - -- **index**: index of service -- **uuid**: uuid (as a **String**) - -#### Returns -- **BLEService** for provided parameters - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - - Serial.println("Connecting ..."); - - if (peripheral.connect()) { - Serial.println("Connected"); - } else { - Serial.println("Failed to connect!"); - return; - } - - // discover peripheral attributes - Serial.println("Discovering attributes ..."); - if (peripheral.discoverAttributes()) { - Serial.println("Attributes discovered"); - } else { - Serial.println("Attribute discovery failed!"); - peripheral.disconnect(); - return; - } - - BLEService batteryService = peripheral.service("180f"); - - if (batteryService) { - // use the service - } else { - Serial.println("Peripheral does NOT have battery service"); - } - - // ... - } - - -``` - -### `bleDevice.characteristicCount()` - -Query the number of characteristics discovered for the Bluetooth® Low Energy device. - -#### Syntax - -``` -bleDevice.characteristicCount() - -``` - -#### Parameters - -None - -#### Returns -- The **number of characteristics** discovered for the Bluetooth® Low Energy device. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - - Serial.println("Connecting ..."); - - if (peripheral.connect()) { - Serial.println("Connected"); - } else { - Serial.println("Failed to connect!"); - return; - } - - // discover peripheral attributes - Serial.println("Discovering attributes ..."); - if (peripheral.discoverAttributes()) { - Serial.println("Attributes discovered"); - } else { - Serial.println("Attribute discovery failed!"); - peripheral.disconnect(); - return; - } - - int characteristicCount = peripheral.characteristicCount(); - - Serial.print(characteristicCount); - Serial.println(" characteristics discovered"); - - // ... - } - - -``` - -### `bleDevice.hasCharacteristic()` - -Query if the Bluetooth® Low Energy device has a particular characteristic. - -#### Syntax - -``` -bleDevice.hasCharacteristic(uuid) -bleDevice.hasCharacteristic(uuid, index) - -``` - -#### Parameters - -- **uuid**: uuid to check (as a **String**) -- **index**: optional, index of characteristic to check if the device provides more than on. Defaults to 0, if not provided. - -#### Returns -- **true**, if the device provides the characteristic, -- **false** otherwise. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - - Serial.println("Connecting ..."); - - if (peripheral.connect()) { - Serial.println("Connected"); - } else { - Serial.println("Failed to connect!"); - return; - } - - // discover peripheral attributes - Serial.println("Discovering attributes ..."); - if (peripheral.discoverAttributes()) { - Serial.println("Attributes discovered"); - } else { - Serial.println("Attribute discovery failed!"); - peripheral.disconnect(); - return; - } - - if (peripheral.hasCharacteristic("2a19")) { - Serial.println("Peripheral has battery level characteristic"); - } - - // ... - } - - -``` - -### `bleDevice.hasLocalName()` - -Query if a discovered Bluetooth® Low Energy device is advertising a local name. - -#### Syntax - -``` -bleDevice.hasLocalName() - -``` - -#### Parameters - -Nothing - -#### Returns -- **true**, if the device is advertising a local name, -- **false** otherwise. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - - // print the local name, if present - if (peripheral.hasLocalName()) { - Serial.print("Local Name: "); - Serial.println(peripheral.localName()); - } - - // ... - } - - -``` - -### `bleDevice.hasAdvertisedServiceUuid()` - -Query if a discovered Bluetooth® Low Energy device is advertising a service UUID. - -#### Syntax - -``` -bleDevice.hasAdvertisedServiceUuid() -bleDevice.hasAdvertisedServiceUuid(index) - -``` - -#### Parameters - -- **index**: optional, defaults to 0, the index of the service UUID, if the device is advertising more than one. - -#### Returns -- **true**, if the device is advertising a service UUID, -- **false** otherwise. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - - // print the advertised service UUIDs, if present - if (peripheral.hasAdvertisedServiceUuid()) { - Serial.print("Service UUIDs: "); - for (int i = 0; i < peripheral.advertisedServiceUuidCount(); i++) { - Serial.print(peripheral.advertisedServiceUuid(i)); - Serial.print(" "); - } - Serial.println(); - } - - // ... - } - - -``` - -### `bleDevice.advertisedServiceUuidCount()` - -Query the number of advertised services a discovered Bluetooth® Low Energy device is advertising. - -#### Syntax - -``` -bleDevice.advertisedServiceUuidCount() - -``` - -#### Parameters - -None - -#### Returns -- The **number of advertised services** a discovered Bluetooth® Low Energy device is advertising. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - - // print the advertised service UUIDs, if present - if (peripheral.hasAdvertisedServiceUuid()) { - Serial.print("Service UUIDs: "); - for (int i = 0; i < peripheral.advertisedServiceUuidCount(); i++) { - Serial.print(peripheral.advertisedServiceUuid(i)); - Serial.print(" "); - } - Serial.println(); - } - - // ... - } - - -``` - -### `bleDevice.localName()` - -Query the local name a discovered Bluetooth® Low Energy device is advertising with. - -#### Syntax - -``` -bleDevice.localName() - -``` - -#### Parameters - -Nothing - -#### Returns -- **Advertised local name** (as a String). - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - - // print the local name, if present - if (peripheral.hasLocalName()) { - Serial.print("Local Name: "); - Serial.println(peripheral.localName()); - } - - // ... - } - - -``` - -### `bleDevice.advertisedServiceUuid()` - -Query an advertised service UUID discovered Bluetooth® Low Energy device is advertising. - -#### Syntax - -``` -bleDevice.advertisedServiceUuid() -bleDevice.advertisedServiceUuid(index) - -``` - -#### Parameters - -- **index**: optional, defaults to 0, the index of the **service UUID**, if the device is advertising more than one. - -#### Returns -- Advertised service **UUID** (as a String). - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - - // print the advertised service UUIDs, if present - if (peripheral.hasAdvertisedServiceUuid()) { - Serial.print("Service UUIDs: "); - for (int i = 0; i < peripheral.advertisedServiceUuidCount(); i++) { - Serial.print(peripheral.advertisedServiceUuid(i)); - Serial.print(" "); - } - Serial.println(); - } - - // ... - } - - -``` - -### `bleDevice.connect()` - -Connect to a Bluetooth® Low Energy device. - -#### Syntax - -``` -bleDevice.connect() - -``` - -#### Parameters - -None - -#### Returns -- **true**, if the connection was successful, -- **false** otherwise. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - - Serial.println("Connecting ..."); - - if (peripheral.connect()) { - Serial.println("Connected"); - } else { - Serial.println("Failed to connect!"); - return; - } - - // ... - } - - -``` - -## BLEService Class - -Used to enable the services board provides or interact with services a remote board provides. - -### `BLEService()` - -Create a new Bluetooth® Low Energy service. - -#### Syntax - -``` -BLEService(uuid) - -``` - -#### Parameters - -- **uuid**: 16-bit or 128-bit UUID in **String** format - -#### Returns -- New **BLEService** with the specified **UUID** - -#### Example - -```arduino - -BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // Bluetooth® Low Energy LED Service - - -``` - -### `bleService.uuid()` - -Query the UUID of the specified BLEService. - -#### Syntax - -``` -bleService.uuid() - -``` - -#### Parameters - -None - -#### Returns -- UUID of the Bluetooth® Low Energy service as a **String**. - -#### Example - -```arduino - -BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // Bluetooth® Low Energy LED Service - - -Serial.print("LED service UUID = "); -Serial.println(ledService.uuid()); - - - -``` - -### `bleService.addCharacteristic()` - -Add a BLECharacteristic to the Bluetooth® Low Energy service. - -#### Syntax - -``` -bleService.addCharacteristic(bleCharacteristic) - -``` - -#### Parameters - -None - -#### Returns -Nothing - -#### Example - -```arduino - -BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // Bluetooth® Low Energy LED Service - -// Bluetooth® Low Energy LED Switch Characteristic - custom 128-bit UUID, readable and writable by central -BLECharacteristic switchCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite, 1); - - - - -// add the characteristic to the service -ledService.addCharacteristic(switchCharacteristic); - - - -``` - -### `bleService.characteristicCount()` - -Query the number of characteristics discovered for the Bluetooth® Low Energy service. - -#### Syntax - -``` -bleService.characteristicCount() - -``` - -#### Parameters - -None - -#### Returns -- The **number of characteristics** discovered for the Bluetooth® Low Energy service. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - - Serial.println("Connecting ..."); - - if (peripheral.connect()) { - Serial.println("Connected"); - } else { - Serial.println("Failed to connect!"); - return; - } - - // discover peripheral attributes - Serial.println("Discovering attributes ..."); - if (peripheral.discoverAttributes()) { - Serial.println("Attributes discovered"); - } else { - Serial.println("Attribute discovery failed!"); - peripheral.disconnect(); - return; - } - - BLEService batteryService = peripheral.service("180f"); - - if (batteryService) { - // use the service - int characteristicCount = batteryService.characteristicCount(); - - Serial.print(characteristicCount); - Serial.println(" characteristics discovered in battery service"); - } else { - Serial.println("Peripheral does NOT have battery service"); - } - - // ... - } - - -``` - -### `bleService.hasCharacteristic()` - -Query if the Bluetooth® Low Energy service has a particular characteristic. - -#### Syntax - -``` -bleService.hasCharacteristic(uuid) -bleService.hasCharacteristic(uuid, index) - -``` - -#### Parameters - -- **uuid**: uuid to check (as a **String**) -- **index**: optional, index of characteristic to check if the device provides more than on. Defaults to 0, if not provided. - -#### Returns -- **true**, if the service provides the characteristic, -- **false** otherwise. - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - - Serial.println("Connecting ..."); - - if (peripheral.connect()) { - Serial.println("Connected"); - } else { - Serial.println("Failed to connect!"); - return; - } - - // discover peripheral attributes - Serial.println("Discovering attributes ..."); - if (peripheral.discoverAttributes()) { - Serial.println("Attributes discovered"); - } else { - Serial.println("Attribute discovery failed!"); - peripheral.disconnect(); - return; - } - - BLEService batteryService = peripheral.service("180f"); - - if (batteryService) { - // use the service - if (batteryService.hasCharacteristic("2a19")) { - Serial.println("Battery service has battery level characteristic"); - } - } else { - Serial.println("Peripheral does NOT have battery service"); - } - - // ... - } - - -``` - -### `bleService.characteristic()` - -Get a BLECharacteristic representing a Bluetooth® Low Energy characteristic the service provides. - -#### Syntax - -``` -bleService.characteristic(index) -bleService.characteristic(uuid) -bleService.characteristic(uuid, index) - -``` - -#### Parameters - -- **index**: index of characteristic -- **uuid**: uuid (as a **String**) - -#### Returns -- **BLECharacteristic** for provided parameters - -#### Example - -```arduino - - // begin initialization - if (!BLE.begin()) { - Serial.println("starting Bluetooth® Low Energy module failed!"); - - while (1); - } - - Serial.println("BLE Central scan"); - - // start scanning for peripheral - BLE.scan(); - - - BLEDevice peripheral = BLE.available(); - - if (peripheral) { - // ... - - Serial.println("Connecting ..."); - - if (peripheral.connect()) { - Serial.println("Connected"); - } else { - Serial.println("Failed to connect!"); - return; - } - - // discover peripheral attributes - Serial.println("Discovering attributes ..."); - if (peripheral.discoverAttributes()) { - Serial.println("Attributes discovered"); - } else { - Serial.println("Attribute discovery failed!"); - peripheral.disconnect(); - return; - } - - BLEService batteryService = peripheral.service("180f"); - - if (batteryService) { - // use the service - BLECharacteristic batteryLevelCharacteristic = peripheral.characteristic("2a19"); - - if (batteryLevelCharacteristic) { - // use the characteristic - } else { - Serial.println("Peripheral does NOT have battery level characteristic"); - } - } else { - Serial.println("Peripheral does NOT have battery service"); - } - - // ... - } - - -``` - -## BLECharacteristic Class - -Used to enable the characteristics board offers in a service or interact with characteristics a remote board provides. - -### `BLECharacteristic()` - -Create a new Bluetooth® Low Energy characteristic. - -#### Syntax - -``` -BLECharacteristic(uuid, properties, value, valueSize) -BLECharacteristic(uuid, properties, stringValue) - -BLEBoolCharacteristic(uuid, properties) -BLEBooleanCharacteristic(uuid, properties) -BLECharCharacteristic(uuid, properties) -BLEUnsignedCharCharacteristic(uuid, properties) -BLEByteCharacteristic(uuid, properties) -BLEShortCharacteristic(uuid, properties) -BLEUnsignedShortCharacteristic(uuid, properties) -BLEWordCharacteristic(uuid, properties) -BLEIntCharacteristic(uuid, properties) -BLEUnsignedIntCharacteristic(uuid, properties) -BLELongCharacteristic(uuid, properties) -BLEUnsignedLongCharacteristic(uuid, properties) -BLEFloatCharacteristic(uuid, properties) -BLEDoubleCharacteristic(uuid, properties) -``` - -#### Parameters - -- **uuid**: 16-bit or 128-bit UUID in **String** format -- **properties**: mask of the properties (BLEBroadcast, BLERead, BLEWriteWithoutResponse, BLEWrite, BLENotify, BLEIndicate) -- **valueSize**: (maximum) size of characteristic value -- **stringValue**: value as a string - -#### Returns -- New **BLECharacteristic** with the specified **UUID** and value - -#### Example - -```arduino - -// Bluetooth® Low Energy Battery Level Characteristic -BLEUnsignedCharCharacteristic batteryLevelChar("2A19", // standard 16-bit characteristic UUID - BLERead | BLENotify); // remote clients will be able to get notifications if this characteristic changes - - - -``` - -### `bleCharacteristic.uuid()` - -Query the UUID of the specified BLECharacteristic. - -#### Syntax - -``` -bleCharacteristic.uuid() - -``` - -#### Parameters - -None - -#### Returns -- **UUID** of the Bluetooth® Low Energy service as a **String**. - -#### Example - -```arduino - -// Bluetooth® Low Energy LED Switch Characteristic - custom 128-bit UUID, read and writable by central -BLEByteCharacteristic switchCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite); - - -Serial.print("Switch characteristic UUID = "); -Serial.println(switchCharacteristic.uuid()); - - - -``` - -### `bleCharacteristic.properties()` - -Query the property mask of the specified BLECharacteristic. - -#### Syntax - -``` -bleCharacteristic.properties() - -``` - -#### Parameters - -None - -#### Returns -- **Properties of the characteristic masked** (BLEBroadcast, BLERead, BLEWriteWithoutResponse, BLEWrite, BLENotify, BLEIndicate) - -#### Example - -```arduino - -// Bluetooth® Low Energy LED Switch Characteristic - custom 128-bit UUID, read and writable by central -BLEByteCharacteristic switchCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite); - - -byte properties = switchCharacteristic.properties(); - -if (properties & BLERead) { - // characteristic is readable ... -} - -if (properties & (BLEWrite | BLEWriteWithoutResponse)) { - // characteristic is writable ... -} - - -``` - -### `bleCharacteristic.valueSize()` - -Query the maximum value size of the specified BLECharacteristic. - -#### Syntax - -``` -bleCharacteristic.valueSize() - -``` - -#### Parameters - -None - -#### Returns -- The **maximum value** size of the characteristic (in bytes) - -#### Example - -```arduino - -// Bluetooth® Low Energy LED Switch Characteristic - custom 128-bit UUID, read and writable by central -BLEByteCharacteristic switchCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite); - - - -Serial.print("value size = "); -Serial.println(switchCharacteristic.valueSize()); - - -``` - -### `bleCharacteristic.value()` - -Query the current value of the specified BLECharacteristic. - -#### Syntax - -``` -bleCharacteristic.value() - -``` - -#### Parameters - -None - -#### Returns -- The **current value** of the characteristic, value type depends on the constructor used - -#### Example - -```arduino - -// Bluetooth® Low Energy LED Switch Characteristic - custom 128-bit UUID, read and writable by central -BLEByteCharacteristic switchCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite); - - - - if (switchCharacteristic.value()) { // any value other than 0 - Serial.println("LED on"); - digitalWrite(ledPin, HIGH); // will turn the LED on - } else { // a 0 value - Serial.println(F("LED off")); - digitalWrite(ledPin, LOW); // will turn the LED off - } - - - -``` - -### `bleCharacteristic.valueLength()` - -Query the current value size of the specified BLECharacteristic. - -#### Syntax - -``` -bleCharacteristic.valueLength() - -``` - -#### Parameters - -None - -#### Returns -- The **current value** size of the characteristic (in bytes) - -#### Example - -```arduino - -// Bluetooth® Low Energy LED Switch Characteristic - custom 128-bit UUID, read and writable by central -BLEByteCharacteristic switchCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite); - - - -Serial.print("value length = "); -Serial.println(switchCharacteristic.valueLength()); - - -``` - -### `bleCharacteristic.readValue()` - -Read the current value of the characteristic. If the characteristic is on a remote device, a read request will be sent. - -#### Syntax - -``` -bleCharacteristic.readValue(buffer, length) -bleCharacteristic.readValue(value) - -``` - -#### Parameters - -- **buffer:** byte array to read value into length: size of buffer argument in bytes -- **value**: variable to read value into (by reference) - -#### Returns -- **Number of bytes** read - -#### Example - -```arduino - - while (peripheral.connected()) { - // while the peripheral is connected - - // check if the value of the simple key characteristic has been updated - if (simpleKeyCharacteristic.valueUpdated()) { - // yes, get the value, characteristic is 1 byte so use byte value - byte value = 0; - - simpleKeyCharacteristic.readValue(value); - - if (value & 0x01) { - // first bit corresponds to the right button - Serial.println("Right button pressed"); - } - - if (value & 0x02) { - // second bit corresponds to the left button - Serial.println("Left button pressed"); - } - } - } - - -``` - -### `bleCharacteristic.writeValue()` - -Write the value of the characteristic. If the characteristic is on a remote device, a write request or command will be sent. - -#### Syntax - -``` -bleCharacteristic.writeValue(buffer, length) -bleCharacteristic.writeValue(value) - -``` - -#### Parameters - -- **buffer**: byte array to write value with -- **length**: number of bytes of the buffer argument to write -- **value**: value to write - -#### Returns -- 1 on success, -- 0 on failure - -#### Example - -```arduino - - // read the button pin - int buttonState = digitalRead(buttonPin); - - if (oldButtonState != buttonState) { - // button changed - oldButtonState = buttonState; - - if (buttonState) { - Serial.println("button pressed"); - - // button is pressed, write 0x01 to turn the LED on - ledCharacteristic.writeValue((byte)0x01); - } else { - Serial.println("button released"); - - // button is released, write 0x00 to turn the LED off - ledCharacteristic.writeValue((byte)0x00); - } - } - - -``` - -### `bleCharacteristic.setEventHandler()` - -Set the event handler (callback) function that will be called when the specified event occurs. - -#### Syntax - -``` -bleCharacteristic.setEventHandler(eventType, callback) - -``` - -#### Parameters - -- **eventType**: event type (BLESubscribed, BLEUnsubscribed, BLERead, BLEWritten) -- **callback**: function to call when the event occurs - -#### Returns -Nothing - -#### Example - -```arduino - -// create switch characteristic and allow remote device to read and write -BLEByteCharacteristic switchCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite); - - - - - // assign event handlers for characteristic - switchCharacteristic.setEventHandler(BLEWritten, switchCharacteristicWritten); - - - -void switchCharacteristicWritten(BLEDevice central, BLECharacteristic characteristic) { - // central wrote new value to characteristic, update LED - Serial.print("Characteristic event, written: "); - - if (switchCharacteristic.value()) { - Serial.println("LED on"); - digitalWrite(ledPin, HIGH); - } else { - Serial.println("LED off"); - digitalWrite(ledPin, LOW); - } -} - - -``` - -### `bleCharacteristic.broadcast()` - -Broadcast the characteristics value as service data when advertising. - -#### Syntax - -``` -bleCharacteristic.broadcast() - -``` - -#### Parameters - -None - -#### Returns -- 1 on success, -- 0 on failure - -#### Example - -```arduino - -// create button characteristic and allow remote device to get notifications -BLEByteCharacteristic buttonCharacteristic("19B10012-E8F2-537E-4F6C-D104768A1214", BLERead | BLENotify | BLEBroadcast); - - - -buttonCharacteristic.broadcast(); - - - -``` - -### `bleCharacteristic.written()` - -Query if the characteristic value has been written by another Bluetooth® Low Energy device. - -#### Syntax - -``` -bleCharacteristic.written() - -``` - -#### Parameters - -None - -#### Returns -- **true** if the characteristic value has been written by another Bluetooth® Low Energy device, -- **false** otherwise - -#### Example - -```arduino - -// Bluetooth® Low Energy LED Switch Characteristic - custom 128-bit UUID, read and writable by central -BLEByteCharacteristic switchCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite); - - - - - // listen for Bluetooth® Low Energy peripherals to connect: - BLEDevice central = BLE.central(); - - // if a central is connected to peripheral: - if (central) { - Serial.print("Connected to central: "); - // print the central's MAC address: - Serial.println(central.address()); - - // while the central is still connected to peripheral: - while (central.connected()) { - // if the remote device wrote to the characteristic, - // use the value to control the LED: - if (switchCharacteristic.written()) { - if (switchCharacteristic.value()) { // any value other than 0 - Serial.println("LED on"); - digitalWrite(ledPin, HIGH); // will turn the LED on - } else { // a 0 value - Serial.println(F("LED off")); - digitalWrite(ledPin, LOW); // will turn the LED off - } - } - } - - // when the central disconnects, print it out: - Serial.print(F("Disconnected from central: ")); - Serial.println(central.address()); - } - - - - -``` - -### `bleCharacteristic.subscribed()` - -Query if the characteristic has been subscribed to by another Bluetooth® Low Energy device. - -#### Syntax - -``` -bleCharacteristic.subscribed() - -``` - -#### Parameters - -None - -#### Returns -- **true** if the characteristic value has been subscribed to by another Bluetooth® Low Energy device, -- **false** otherwise - -#### Example - -```arduino - -// Bluetooth® Low Energy Battery Level Characteristic -BLEUnsignedCharCharacteristic batteryLevelChar("2A19", // standard 16-bit characteristic UUID - BLERead | BLENotify); // remote clients will be able to get notifications if this characteristic changes - - - - - - if (batteryLevelChar.subscribed()) { - // set a new value , that well be pushed to subscribed Bluetooth® Low Energy devices - batteryLevelChar.writeValue(0xab); - } - - -``` - -### `bleCharacteristic.addDescriptor()` - -Add a BLEDescriptor to the characteristic. - -#### Syntax - -``` -bleCharacteristic.addDescriptor(bleDescriptor) - -``` - -#### Parameters - -- **bleDescriptor**: descriptor to add to the characteristic - -#### Returns -Nothing - -#### Example - -```arduino - -// Bluetooth® Low Energy Battery Level Characteristic -BLEUnsignedCharCharacteristic batteryLevelChar("2A19", // standard 16-bit characteristic UUID - BLERead | BLENotify); // remote clients will be able to get notifications if this characteristic changes - -BLEDescriptor batteryLevelDescriptor("2901", "millis"); - - - - - - batteryLevelChar.addDescriptor(batteryLevelDescriptor); - - -``` - -### `bleCharacteristic.descriptorCount()` - -Query the number of Bluetooth® Low Energy descriptors discovered for the characteristic. - -#### Syntax - -``` -bleCharacteristic.descriptorCount() - -``` - -#### Parameters - -None - -#### Returns -- The **number of Bluetooth® Low Energy descriptors** discovered for the characteristic - -#### Example - -```arduino - - // loop the descriptors of the characteristic and explore each - for (int i = 0; i < characteristic.descriptorCount(); i++) { - BLEDescriptor descriptor = characteristic.descriptor(i); - - // ... - } - - -``` - -### `bleCharacteristic.hasDescriptor()` - -Check if a characteristic has a particular descriptor. - -#### Syntax - -``` -bleCharacteristic.hasDescriptor(uuid) -bleCharacteristic.hasDescriptor(uuid, index) - -``` - -#### Parameters - -- **index**: index of descriptor -- **uuid**: uuid (as a **String**) - -#### Returns -- **true**, if the characteristic has a matching descriptor, -- otherwise **false**. - -#### Example - -```arduino - - if (characteristic.hasDescriptor("2901")) { - Serial.println("characteristic has description descriptor"); - } - - -``` - -### `bleCharacteristic.descriptor()` - -Get a BLEDescriptor that represents a characteristics Bluetooth® Low Energy descriptor. - -#### Syntax - -``` -bleCharacteristic.descriptor(index) -bleCharacteristic.descriptor(uuid) -bleCharacteristic.descriptor(uuid, index) - -``` - -#### Parameters - -- **index**: index of descriptor -- **uuid**: uuid (as a **String**) - -#### Returns -- BLEDescriptor that represents a characteristics Bluetooth® Low Energy descriptor - -#### Example - -```arduino - - if (characteristic.hasDescriptor("2901")) { - Serial.println("characteristic has description descriptor"); - } - - -``` - -### `bleCharacteristic.canRead()` - -Query if a Bluetooth® Low Energy characteristic is readable. - -#### Syntax - -``` -bleCharacteristic.canRead() - -``` - -#### Parameters - -None - -#### Returns -- **true**, if characteristic is readable, -- **false** otherwise - -#### Example - -```arduino - - if (characteristic.canRead("2901")) { - Serial.println("characteristic is readable"); - } - - -``` - -read - -Perform a read request for the characteristic. - -#### Syntax - -``` -bleCharacteristic.read() - -``` - -#### Parameters - -None - -#### Returns -- **true**, if successful, -- **false** on failure - -#### Example - -```arduino - - if (characteristic.read()) { - Serial.println("characteristic value read"); - - // ... - } else { - Serial.println("error reading characteristic value"); - } - - -``` - -### `bleCharacteristic.canWrite()` - -Query if a Bluetooth® Low Energy characteristic is writable. - -#### Syntax - -``` -bleCharacteristic.canWrite() - -``` - -#### Parameters - -None - -#### Returns -- **true**, if characteristic is writable, -- **false** otherwise - -#### Example - -```arduino - - if (characteristic.canWrite()) { - Serial.println("characteristic is writable"); - } - - -``` - -### `bleCharacteristic.canSubscribe()` - -Query if a Bluetooth® Low Energy characteristic is subscribable. - -#### Syntax - -``` -bleCharacteristic.canSubscribe() - -``` - -#### Parameters - -None - -#### Returns -- **true**, if characteristic is subscribable, -- **false** otherwise - -#### Example - -```arduino - - if (characteristic.canSubscribe()) { - Serial.println("characteristic is subscribable"); - } - - -``` - -### `bleCharacteristic.subscribe()` - -Subscribe to a Bluetooth® Low Energy characteristics notification or indications. - -#### Syntax - -``` -bleCharacteristic.subscribe() - -``` - -#### Parameters - -None - -#### Returns -- **true**, on success, -- **false** on failure - -#### Example - -```arduino - - // ... - - // retrieve the simple key characteristic - BLECharacteristic simpleKeyCharacteristic = peripheral.characteristic("ffe1"); - - // subscribe to the simple key characteristic - Serial.println("Subscribing to simple key characteristic ..."); - if (!simpleKeyCharacteristic) { - Serial.println("no simple key characteristic found!"); - peripheral.disconnect(); - return; - } else if (!simpleKeyCharacteristic.canSubscribe()) { - Serial.println("simple key characteristic is not subscribable!"); - peripheral.disconnect(); - return; - } else if (!simpleKeyCharacteristic.subscribe()) { - Serial.println("subscription failed!"); - peripheral.disconnect(); - return; - } - - // ... - - -``` - -### `bleCharacteristic.canUnsubscribe()` - -Query if a Bluetooth® Low Energy characteristic is unsubscribable. - -#### Syntax - -``` -bleCharacteristic.canUnsubscribe() - -``` - -#### Parameters - -None - -#### Returns -- **true**, if characteristic is unsubscribable, -- **false** otherwise - -#### Example - -```arduino - - if (characteristic.canUnsubscribe()) { - Serial.println("characteristic is unsubscribable"); - } - - -``` - -### `bleCharacteristic.unsubscribe()` - -Unsubscribe to a Bluetooth® Low Energy characteristics notifications or indications. - -#### Syntax - -``` -bleCharacteristic.unsubscribe() - -``` - -#### Parameters - -None - -#### Returns -- **true**, on success, -- **false** on failure - -#### Example - -```arduino - - // ... - - // retrieve the simple key characteristic - BLECharacteristic simpleKeyCharacteristic = peripheral.characteristic("ffe1"); - - // subscribe to the simple key characteristic - Serial.println("Subscribing to simple key characteristic ..."); - if (!simpleKeyCharacteristic) { - Serial.println("no simple key characteristic found!"); - peripheral.disconnect(); - return; - } else if (!simpleKeyCharacteristic.canSubscribe()) { - Serial.println("simple key characteristic is not subscribable!"); - peripheral.disconnect(); - return; - } else if (!simpleKeyCharacteristic.subscribe()) { - Serial.println("subscription failed!"); - peripheral.disconnect(); - return; - } - - // ... - - simpleKeyCharacteristic.unsubscribe(); - - -``` - -### `bleCharacteristic.valueUpdated()` - -Has the characteristics value been updated via a notification or indication. - -#### Syntax - -``` -bleCharacteristic.valueUpdated() - -``` - -#### Parameters - -None - -#### Returns -- **true**, if the characteristics value been updated via a notification or indication - -#### Example - -```arduino - - while (peripheral.connected()) { - // while the peripheral is connected - - // check if the value of the simple key characteristic has been updated - if (simpleKeyCharacteristic.valueUpdated()) { - // yes, get the value, characteristic is 1 byte so use byte value - byte value = 0; - - simpleKeyCharacteristic.readValue(value); - - if (value & 0x01) { - // first bit corresponds to the right button - Serial.println("Right button pressed"); - } - - if (value & 0x02) { - // second bit corresponds to the left button - Serial.println("Left button pressed"); - } - } - } - - -``` - -## BLEDescriptor Class - -Used to describe a characteristic the board offers - -### `BLEDescriptor()` - -Create a new Bluetooth® Low Energy descriptor. - -#### Syntax - -``` -BLEDescriptor(uuid, value, valueSize) -BLEDescriptor(uuid, stringValue) - -``` - -#### Parameters - -- **uuid**: 16-bit or 128-bit UUID in string format -- **value**: byte array value -- **valueSize**: size of byte array value -- **stringValue**: value as a string - -#### Returns -- New **BLEDescriptor** with the specified **UUID** and value - -#### Example - -```arduino - -BLEDescriptor millisLabelDescriptor("2901", "millis"); - - -``` - -### `bleDescriptor.uuid()` - -Query the UUID of the specified BLEDescriptor. - -#### Syntax - -``` -bleDescriptor.uuid() - -``` - -#### Parameters - -None - -#### Returns -- **UUID** of the Bluetooth® Low Energy descriptor (as a String). - -#### Example - -```arduino - -BLEDescriptor millisLabelDescriptor("2901", "millis"); - - -Serial.print("millis label descriptor UUID = "); -Serial.println(millisLabelDescriptor.uuid()); - - - -``` - -### `bleDescriptor.valueSize()` - -Query the value size of the specified BLEDescriptor. - -#### Syntax - -``` -bleDescriptor.valueSize() - -``` - -#### Parameters - -None - -#### Returns -- **Value size** (in bytes) of the Bluetooth® Low Energy descriptor. - -#### Example - -```arduino - -BLEDescriptor millisLabelDescriptor("2901", "millis"); - - -Serial.print("millis label descriptor value size = "); -Serial.println(millisLabelDescriptor.valueSize()); - - - -``` - -### `bleDescriptor.valueLength()` - -Query the length, in bytes, of the descriptor current value. - -#### Syntax - -``` -bleDescriptor.valueLength() - -``` - -#### Parameters - -None - -#### Returns -- **Length of descriptor** value in bytes. - -#### Example - -```arduino - - // read the descriptor value - descriptor.read(); - - // print out the value of the descriptor - Serial.print(", value 0x"); - printData(descriptor.value(), descriptor.valueLength()); - - // ... - - void printData(const unsigned char data[], int length) { - for (int i = 0; i < length; i++) { - unsigned char b = data[i]; - - if (b < 16) { - Serial.print("0"); - } - - Serial.print(b, HEX); - } - } - - -``` - -### `bleDescriptor.value()` - -Query the value of the specified BLEDescriptor. - -#### Syntax - -``` -bleDescriptor.value() - -``` - -#### Parameters - -None - -#### Returns -- Value byte array of the **BLE descriptor**. - -#### Example - -```arduino - -BLEDescriptor millisLabelDescriptor("2901", "millis"); - - - - int descriptorValueSize = millisLabelDescriptor.valueSize(); - byte descriptorValue[descriptorValueSize]; - - for (int i = 0; i < descriptorValueSize; i++) { - descriptorValue[i] = millisLabelDescriptor.value()[i]; - } - - - -``` - -### `bleDescriptor.readValue()` - -Read the current value of the descriptor. If the descriptor is on a remote device, a read request will be sent. - -#### Syntax - -``` -bleDescriptor.readValue(buffer, length) -bleDescriptor.readValue(value) - -``` - -#### Parameters - -- **buffer**: byte array to read value into -- **length**: size of buffer argument in bytes -- **value**: variable to read value into (by reference) - -#### Returns -- **Number of bytes** read - -#### Example - - -```arduino - - byte value = 0; - - // get the value, descriptor is 1 byte so use byte value - descriptor.readValue(value); - - -``` - -### `bleDescriptor.read()` - -Perform a read request for the descriptor. - -#### Syntax - -``` -bleDescriptor.read() - -``` - -#### Parameters - -None - -#### Returns -- **true**, if successful, -- **false** on failure - -#### Example - -```arduino - - if (descriptor.read()) { - Serial.println("descriptor value read"); - - // ... - } else { - Serial.println("error reading descriptor value"); - } - -``` diff --git a/docs/assets/ble-bulletin-board-model.png b/docs/assets/ble-bulletin-board-model.png deleted file mode 100644 index 409ae9e8..00000000 Binary files a/docs/assets/ble-bulletin-board-model.png and /dev/null differ diff --git a/docs/readme.md b/docs/readme.md deleted file mode 100644 index b584d71e..00000000 --- a/docs/readme.md +++ /dev/null @@ -1,91 +0,0 @@ -# ArduinoBLE library - -This library supports all the Arduino boards that have the hardware enabled for Bluetooth® Low Energy and Bluetooth® 4.0 and above; these include Nano 33 BLE, Arduino NANO 33 IoT, Uno WiFi Rev2, MKR WiFi 1010, Nicla Sense ME. - -To use this library -``#include `` - -## A quick introduction to BLE - -Bluetooth® 4.0 includes both traditional Bluetooth®, now labeled "Bluetooth® Classic", and the Bluetooth® Low Energy. Bluetooth® Low Energy is optimized for low power use at low data rates, and was designed to operate from simple lithium coin cell batteries. - -Unlike standard Bluetooth® communication basically based on an asynchronous serial connection (UART) a Bluetooth® LE radio acts like a community bulletin board. The computers that connect to it are like community members that read the bulletin board. Each radio acts as either the bulletin board or the reader. If your radio is a bulletin board (called a peripheral device in Bluetooth® LE parlance) it posts data for all radios in the community to read. If your radio is a reader (called a central device in Bluetooth LE terms) it reads from any of the bulletin boards (peripheral devices) that have information about which it cares. You can also think of peripheral devices as the servers in a client-server transaction, because they contain the information that reader radios ask for. Similarly, central devices are the clients of the Bluetooth® LE world because they read information available from the peripherals. - -![Communication between central and peripheral devices](https://raw.githubusercontent.com/arduino-libraries/ArduinoBLE/master/docs/assets/ble-bulletin-board-model.png) - -Think of a Bluetooth® LE peripheral device as a bulletin board and central devices as viewers of the board. Central devices view the services, get the data, then move on. Each transaction is quick (a few milliseconds), so multiple central devices can get data from one peripheral. - -The information presented by a peripheral is structured as **services**, each of which is subdivided into **characteristics**. You can think of services as the notices on a bulletin board, and characteristics as the individual paragraphs of those notices. If you're a peripheral device, you just update each service characteristic when it needs updating and don't worry about whether the central devices read them or not. If you're a central device, you connect to the peripheral then read the boxes you want. If a given characteristic is readable and writable, then the peripheral and central can both change it. - -## Notify - -The Bluetooth® LE specification includes a mechanism known as **notify** that lets you know when data's changed. When notify on a characteristic is enabled and the sender writes to it, the new value is automatically sent to the receiver, without the receiver explicitly issuing a read command. This is commonly used for streaming data such as accelerometer or other sensor readings. There's a variation on this specification called **indicate** which works similarly, but in the indicate specification, the reader sends an acknowledgment of the pushed data. - -The client-server structure of Bluetooth® LE, combined with the notify characteristic, is generally called a **publish-and-subscribe model**. - -## Update a characteristic - -Your peripheral should update characteristics when there's a significant change to them. For example, when a switch changes from off to on, update its characteristic. When an analog sensor changes by a significant amount, update its characteristic. - -Just as with writing to a characteristic, you could update your characteristics on a regular interval, but this wastes processing power and energy if the characteristic has not changed. - -## Central and Peripheral Devices - -**Central** devices are **clients**. They read and write data from peripheral devices. **Peripheral** devices are **servers**. They provide data from sensors as readable characteristics, and provide read/writable characteristics to control actuators like motors, lights, and so forth. - -## Services, characteristics, and UUIDs - -A Bluetooth® Low Energy peripheral will provide **services**, which in turn provide **characteristics**. You can define your own services, or use standard services (see section 3.4 in the [Assigned Numbers document](https://www.bluetooth.com/specifications/assigned-numbers/)). - -Services are identified by unique numbers known as UUIDs. You know about UUIDs from other contexts. Standard services have a 16-bit UUID and custom services have a 128-bit UUID. The ability to define services and characteristics depends on the radio you're using and its firmware. - -## Service design patterns - -A characteristic value can be up to 512 bytes long. This is a key constraint in designing services. Given this limit, you should consider how best to store data about your sensors and actuators most effectively for your application. The simplest design pattern is to store one sensor or actuator value per characteristic, in ASCII encoded values. - -|**Characteristic**|**Value**| -|------------------|---------| -|Accelerometer X|200| -|Accelerometer Y|134| -|Accelerometer Z|150| - -This is also the most expensive in memory terms, and would take the longest to read. But it's the simplest for development and debugging. - -You could also combine readings into a single characteristic, when a given sensor or actuator has multiple values associated with it. - -|**Characteristic**|**Value**| -|------------------|---------| -|Motor Speed, Direction|150,1| -|Accelerometer X, Y, Z|200,133,150| - -This is more efficient, but you need to be careful not to exceed the 512-byte limit. The accelerometer characteristic above, for example, takes 11 bytes as an ASCII-encoded string. - -## Read/write/notify/indicate - -There are 4 things a central device can do with a characteristic: - -- **Read:** ask the peripheral to send back the current value of the characteristic. Often used for characteristics that don't change very often, for example characteristics used for configuration, version numbers, etc. -- **Write:** modify the value of the characteristic. Often used for things that are like commands, for example telling the peripheral to turn a motor on or off. -- **Indicate** and **Notify:** ask the peripheral to continuously send updated values of the characteristic, without the central having to constantly ask for it. - -## Advertising and GAP - -BLE devices let other devices know that they exist by advertising using the **General Advertising Profile (GAP)**. Advertising packets can contain a device name, some other information, and also a list of the services it provides. - -Advertising packets have a limited size. You will only be able to fit a single 128-bit service UUID in the packet. Make sure the device name is not too long, or you won't even be able to fit that. - -You can provide additional services that are not advertised. Central devices will learn about these through the connection/bonding process. Non-advertised services cannot be used to discover devices, though. Sometimes this is not an issue. For example, you may have a custom peripheral device with a custom service, but in your central device app you may know that it also provides the Battery Service and other services. - -## GATT - -The Bluetooth LE protocol operates on multiple layers. **General Attribute Profile (GATT)** is the layer that defines services and characteristics and enables read/write/notify/indicate operations on them. When reading more about GATT, you may encounter GATT concepts of a "server" and "client". These don't always correspond to central and peripherals. In most cases, though, the peripheral is the GATT server (since it provides the services and characteristics), while the central is the GATT client. - -## Library structure - -As the library enables multiple types of functionality, there are a number of different classes. - -- `BLE` used to enable the Bluetooth® Low Energy module. -- `BLEDevice` used to get information about the devices connected or discovered while scanning. -- `BLEService` used to enable the services board provides or interact with services a remote board provides. -- `BLECharacteristic` used to enable the characteristics board offers in a service or interact with characteristics a remote board provides. -- `BLEDescriptor` used to describe a characteristic the board offers. diff --git a/examples/Central/LedControl/LedControl.ino b/examples/Central/LedControl/LedControl.ino index 953de7d8..cbda07d1 100644 --- a/examples/Central/LedControl/LedControl.ino +++ b/examples/Central/LedControl/LedControl.ino @@ -6,9 +6,7 @@ it will remotely control the Bluetooth® Low Energy peripheral's LED, when the button is pressed or released. The circuit: - - Arduino MKR WiFi 1010, Arduino Uno WiFi Rev2 board, Arduino Nano 33 IoT, - Arduino Nano 33 BLE, or Arduino Nano 33 BLE Sense board. - - Button with pull-up resistor connected to pin 2. + - Board with supported BLE modules. You can use it with another board that is compatible with this library and the Peripherals -> LED example. @@ -16,26 +14,44 @@ This example code is in the public domain. */ -#include +#include // variables for button -const int buttonPin = 2; +#ifdef USER_BTN +const int buttonPin = USER_BTN; // set buttonPin to on-board button +#else +const int buttonPin = PC13; // set buttonPin to digital pin PC13 */ +#endif int oldButtonState = LOW; +int initialButtonState = LOW; void setup() { Serial.begin(9600); while (!Serial); // configure the button pin as input - pinMode(buttonPin, INPUT); + pinMode(buttonPin, INPUT_PULLUP); // initialize the Bluetooth® Low Energy hardware BLE.begin(); + // Get initial button state + initialButtonState = digitalRead(buttonPin); + oldButtonState = initialButtonState; + Serial.println("Bluetooth® Low Energy Central - LED control"); // start scanning for peripherals - BLE.scanForUuid("19b10000-e8f2-537e-4f6c-d104768a1214"); + int ret = 1; + do + { + ret = BLE.scanForUuid("19b10000-e8f2-537e-4f6c-d104768a1214"); + if (ret == 0) + { + BLE.end(); + BLE.begin(); + } + } while(ret == 0); } void loop() { @@ -57,12 +73,30 @@ void loop() { } // stop scanning - BLE.stopScan(); + int ret = 1; + do + { + ret = BLE.stopScan(); + if (ret == 0) + { + BLE.end(); + BLE.begin(); + } + } while(ret == 0); controlLed(peripheral); // peripheral disconnected, start scanning again - BLE.scanForUuid("19b10000-e8f2-537e-4f6c-d104768a1214"); + ret = 1; + do + { + ret = BLE.scanForUuid("19b10000-e8f2-537e-4f6c-d104768a1214"); + if (ret == 0) + { + BLE.end(); + BLE.begin(); + } + } while(ret == 0); } } @@ -110,7 +144,7 @@ void controlLed(BLEDevice peripheral) { // button changed oldButtonState = buttonState; - if (buttonState) { + if (buttonState != initialButtonState) { Serial.println("button pressed"); // button is pressed, write 0x01 to turn the LED on diff --git a/examples/Central/PeripheralExplorer/PeripheralExplorer.ino b/examples/Central/PeripheralExplorer/PeripheralExplorer.ino index 919cdde0..7d4841ae 100644 --- a/examples/Central/PeripheralExplorer/PeripheralExplorer.ino +++ b/examples/Central/PeripheralExplorer/PeripheralExplorer.ino @@ -5,8 +5,7 @@ is found. Then connects, and discovers + prints all the peripheral's attributes. The circuit: - - Arduino MKR WiFi 1010, Arduino Uno WiFi Rev2 board, Arduino Nano 33 IoT, - Arduino Nano 33 BLE, or Arduino Nano 33 BLE Sense board. + - Board with supported BLE modules. You can use it with another board that is compatible with this library and the Peripherals -> LED example. @@ -14,7 +13,7 @@ This example code is in the public domain. */ -#include +#include void setup() { Serial.begin(9600); @@ -30,7 +29,16 @@ void setup() { Serial.println("Bluetooth® Low Energy Central - Peripheral Explorer"); // start scanning for peripherals - BLE.scan(); + int ret = 1; + do + { + ret = BLE.scan(); + if (ret == 0) + { + BLE.end(); + BLE.begin(); + } + } while(ret == 0); } void loop() { @@ -50,7 +58,16 @@ void loop() { // see if peripheral is a LED if (peripheral.localName() == "LED") { // stop scanning - BLE.stopScan(); + int ret = 1; + do + { + ret = BLE.stopScan(); + if (ret == 0) + { + BLE.end(); + BLE.begin(); + } + } while(ret == 0); explorerPeripheral(peripheral); diff --git a/examples/Central/Scan/Scan.ino b/examples/Central/Scan/Scan.ino index 162e3c07..ca6b2b9a 100644 --- a/examples/Central/Scan/Scan.ino +++ b/examples/Central/Scan/Scan.ino @@ -5,13 +5,12 @@ address, local name, advertised service UUID's. The circuit: - - Arduino MKR WiFi 1010, Arduino Uno WiFi Rev2 board, Arduino Nano 33 IoT, - Arduino Nano 33 BLE, or Arduino Nano 33 BLE Sense board. + - Board with supported BLE modules. This example code is in the public domain. */ -#include +#include void setup() { Serial.begin(9600); @@ -26,8 +25,17 @@ void setup() { Serial.println("Bluetooth® Low Energy Central scan"); - // start scanning for peripheral - BLE.scan(); + // start scanning for peripherals + int ret = 1; + do + { + ret = BLE.scan(); + if (ret == 0) + { + BLE.end(); + BLE.begin(); + } + } while(ret == 0); } void loop() { diff --git a/examples/Central/ScanCallback/ScanCallback.ino b/examples/Central/ScanCallback/ScanCallback.ino index 2687a3b9..cc33ee85 100644 --- a/examples/Central/ScanCallback/ScanCallback.ino +++ b/examples/Central/ScanCallback/ScanCallback.ino @@ -7,13 +7,12 @@ reported for every single advertisement it makes. The circuit: - - Arduino MKR WiFi 1010, Arduino Uno WiFi Rev2 board, Arduino Nano 33 IoT, - Arduino Nano 33 BLE, or Arduino Nano 33 BLE Sense board. + - Board with supported BLE modules. This example code is in the public domain. */ -#include +#include void setup() { Serial.begin(9600); @@ -32,7 +31,16 @@ void setup() { BLE.setEventHandler(BLEDiscovered, bleCentralDiscoverHandler); // start scanning for peripherals with duplicates - BLE.scan(true); + int ret = 1; + do + { + ret = BLE.scan(true); + if (ret == 0) + { + BLE.end(); + BLE.begin(); + } + } while(ret == 0); } void loop() { diff --git a/examples/Central/SensorTagButton/SensorTagButton.ino b/examples/Central/SensorTagButton/SensorTagButton.ino index 27c421fe..f063ac68 100644 --- a/examples/Central/SensorTagButton/SensorTagButton.ino +++ b/examples/Central/SensorTagButton/SensorTagButton.ino @@ -8,14 +8,13 @@ outputted to the Serial Monitor when one is pressed. The circuit: - - Arduino MKR WiFi 1010, Arduino Uno WiFi Rev2 board, Arduino Nano 33 IoT, - Arduino Nano 33 BLE, or Arduino Nano 33 BLE Sense board. + - Board with supported BLE modules. - TI SensorTag This example code is in the public domain. */ -#include +#include void setup() { Serial.begin(9600); @@ -31,8 +30,17 @@ void setup() { Serial.println("Bluetooth® Low Energy Central - SensorTag button"); Serial.println("Make sure to turn on the device."); - // start scanning for peripheral - BLE.scan(); + // start scanning for peripherals + int ret = 1; + do + { + ret = BLE.scan(); + if (ret == 0) + { + BLE.end(); + BLE.begin(); + } + } while(ret == 0); } void loop() { @@ -53,12 +61,30 @@ void loop() { // "CC2650 SensorTag" if (peripheral.localName() == "CC2650 SensorTag") { // stop scanning - BLE.stopScan(); + int ret = 1; + do + { + ret = BLE.stopScan(); + if (ret == 0) + { + BLE.end(); + BLE.begin(); + } + } while(ret == 0); monitorSensorTagButtons(peripheral); // peripheral disconnected, start scanning again - BLE.scan(); + ret = 1; + do + { + ret = BLE.scan(); + if (ret == 0) + { + BLE.end(); + BLE.begin(); + } + } while(ret == 0); } } } diff --git a/examples/Peripheral/Advertising/EnhancedAdvertising/EnhancedAdvertising.ino b/examples/Peripheral/Advertising/EnhancedAdvertising/EnhancedAdvertising.ino index 979b69a8..806c41bd 100644 --- a/examples/Peripheral/Advertising/EnhancedAdvertising/EnhancedAdvertising.ino +++ b/examples/Peripheral/Advertising/EnhancedAdvertising/EnhancedAdvertising.ino @@ -1,4 +1,4 @@ -#include +#include BLEService myService("fff0"); BLEIntCharacteristic myCharacteristic("fff1", BLERead | BLEBroadcast); diff --git a/examples/Peripheral/Advertising/RawDataAdvertising/RawDataAdvertising.ino b/examples/Peripheral/Advertising/RawDataAdvertising/RawDataAdvertising.ino index 5e7ba7f3..88b17e29 100644 --- a/examples/Peripheral/Advertising/RawDataAdvertising/RawDataAdvertising.ino +++ b/examples/Peripheral/Advertising/RawDataAdvertising/RawDataAdvertising.ino @@ -1,4 +1,4 @@ -#include +#include BLEService myService("fff0"); BLEIntCharacteristic myCharacteristic("fff1", BLERead | BLEBroadcast); diff --git a/examples/Peripheral/BatteryMonitor/BatteryMonitor.ino b/examples/Peripheral/BatteryMonitor/BatteryMonitor.ino index 0d786627..3413127e 100644 --- a/examples/Peripheral/BatteryMonitor/BatteryMonitor.ino +++ b/examples/Peripheral/BatteryMonitor/BatteryMonitor.ino @@ -5,8 +5,7 @@ level characteristic. The A0 pin is used to calculate the battery level. The circuit: - - Arduino MKR WiFi 1010, Arduino Uno WiFi Rev2 board, Arduino Nano 33 IoT, - Arduino Nano 33 BLE, or Arduino Nano 33 BLE Sense board. + - Board with supported BLE modules. You can use a generic Bluetooth® Low Energy central app, like LightBlue (iOS and Android) or nRF Connect (Android), to interact with the services and characteristics @@ -15,7 +14,7 @@ This example code is in the public domain. */ -#include +#include // Bluetooth® Low Energy Battery Service BLEService batteryService("180F"); diff --git a/examples/Peripheral/ButtonLED/ButtonLED.ino b/examples/Peripheral/ButtonLED/ButtonLED.ino index cbc14dd8..8ae7d665 100644 --- a/examples/Peripheral/ButtonLED/ButtonLED.ino +++ b/examples/Peripheral/ButtonLED/ButtonLED.ino @@ -6,9 +6,7 @@ represents the state of the button. The circuit: - - Arduino MKR WiFi 1010, Arduino Uno WiFi Rev2 board, Arduino Nano 33 IoT, - Arduino Nano 33 BLE, or Arduino Nano 33 BLE Sense board. - - Button connected to pin 4 + - Board with supported BLE modules. You can use a generic Bluetooth® Low Energy central app, like LightBlue (iOS and Android) or nRF Connect (Android), to interact with the services and characteristics @@ -17,10 +15,14 @@ This example code is in the public domain. */ -#include +#include const int ledPin = LED_BUILTIN; // set ledPin to on-board LED -const int buttonPin = 4; // set buttonPin to digital pin 4 +#ifdef USER_BTN +const int buttonPin = USER_BTN; // set buttonPin to on-board button +#else +const int buttonPin = PC13; // set buttonPin to digital pin PC13 */ +#endif BLEService ledService("19B10010-E8F2-537E-4F6C-D104768A1214"); // create service @@ -34,7 +36,7 @@ void setup() { while (!Serial); pinMode(ledPin, OUTPUT); // use the LED as an output - pinMode(buttonPin, INPUT); // use button pin as an input + pinMode(buttonPin, INPUT_PULLUP); // use button pin as an input // begin initialization if (!BLE.begin()) { diff --git a/examples/Peripheral/CallbackLED/CallbackLED.ino b/examples/Peripheral/CallbackLED/CallbackLED.ino index 59bda5ed..8bb90106 100644 --- a/examples/Peripheral/CallbackLED/CallbackLED.ino +++ b/examples/Peripheral/CallbackLED/CallbackLED.ino @@ -6,8 +6,7 @@ library are used. The circuit: - - Arduino MKR WiFi 1010, Arduino Uno WiFi Rev2 board, Arduino Nano 33 IoT, - Arduino Nano 33 BLE, or Arduino Nano 33 BLE Sense board. + - Board with supported BLE modules. You can use a generic Bluetooth® Low Energy central app, like LightBlue (iOS and Android) or nRF Connect (Android), to interact with the services and characteristics @@ -16,7 +15,7 @@ This example code is in the public domain. */ -#include +#include BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // create service diff --git a/examples/Peripheral/EncryptedBatteryMonitor/EncryptedBatteryMonitor.ino b/examples/Peripheral/EncryptedBatteryMonitor/EncryptedBatteryMonitor.ino index dfc9f4a0..6b84fa34 100644 --- a/examples/Peripheral/EncryptedBatteryMonitor/EncryptedBatteryMonitor.ino +++ b/examples/Peripheral/EncryptedBatteryMonitor/EncryptedBatteryMonitor.ino @@ -5,8 +5,7 @@ level characteristic. The A0 pin is used to calculate the battery level. The circuit: - - Arduino MKR WiFi 1010, Arduino Uno WiFi Rev2 board, Arduino Nano 33 IoT, - Arduino Nano 33 BLE, or Arduino Nano 33 BLE Sense board. + - Board with supported BLE modules. You can use a generic BLE central app, like LightBlue (iOS and Android) or nRF Connect (Android), to interact with the services and characteristics @@ -15,7 +14,7 @@ This example code is in the public domain. */ -#include +#include #define PAIR_BUTTON 3 // button for pairing diff --git a/examples/Peripheral/LED/LED.ino b/examples/Peripheral/LED/LED.ino index 65b88605..7223365f 100644 --- a/examples/Peripheral/LED/LED.ino +++ b/examples/Peripheral/LED/LED.ino @@ -5,8 +5,7 @@ characteristic to control an LED. The circuit: - - Arduino MKR WiFi 1010, Arduino Uno WiFi Rev2 board, Arduino Nano 33 IoT, - Arduino Nano 33 BLE, or Arduino Nano 33 BLE Sense board. + - Board with supported BLE modules. You can use a generic Bluetooth® Low Energy central app, like LightBlue (iOS and Android) or nRF Connect (Android), to interact with the services and characteristics @@ -15,7 +14,7 @@ This example code is in the public domain. */ -#include +#include BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // Bluetooth® Low Energy LED Service diff --git a/extras/STM32_WPAN/0001-chore-adapt-STM32_WPAN-sources.patch b/extras/STM32_WPAN/0001-chore-adapt-STM32_WPAN-sources.patch new file mode 100644 index 00000000..a3f62011 --- /dev/null +++ b/extras/STM32_WPAN/0001-chore-adapt-STM32_WPAN-sources.patch @@ -0,0 +1,310 @@ +From 7f99c89e8a6f834daf4a76bf98307e9ebcd01c91 Mon Sep 17 00:00:00 2001 +From: Frederic Pillon +Date: Wed, 10 Jan 2024 18:16:01 +0100 +Subject: [PATCH 1/4] chore: adapt STM32_WPAN sources + +Signed-off-by: Frederic Pillon +--- + src/utility/STM32_WPAN/app_conf_default.h | 49 +++++++++++++++++++---- + src/utility/STM32_WPAN/hw.h | 13 +++++- + src/utility/STM32_WPAN/hw_ipcc.c | 4 +- + src/utility/STM32_WPAN/shci.c | 2 + + src/utility/STM32_WPAN/shci_tl.c | 17 ++++++++ + src/utility/STM32_WPAN/stm_list.c | 6 ++- + src/utility/STM32_WPAN/tl_mbox.c | 6 +++ + 7 files changed, 85 insertions(+), 12 deletions(-) + +diff --git a/src/utility/STM32_WPAN/app_conf_default.h b/src/utility/STM32_WPAN/app_conf_default.h +index 71fc107..bf2274a 100644 +--- a/src/utility/STM32_WPAN/app_conf_default.h ++++ b/src/utility/STM32_WPAN/app_conf_default.h +@@ -1,9 +1,9 @@ + /* USER CODE BEGIN Header */ + /** + ****************************************************************************** +- * @file app_conf.h ++ * @file app_conf_default.h + * @author MCD Application Team +- * @brief Application configuration file for STM32WPAN Middleware. ++ * @brief Default application configuration file for STM32WPAN Middleware. + ****************************************************************************** + * @attention + * +@@ -19,18 +19,40 @@ + /* USER CODE END Header */ + + /* Define to prevent recursive inclusion -------------------------------------*/ +-#ifndef APP_CONF_H +-#define APP_CONF_H ++#ifndef APP_CONF_DEFAULT_H ++#define APP_CONF_DEFAULT_H + ++#if 0 + #include "hw.h" + #include "hw_conf.h" + #include "hw_if.h" + #include "ble_bufsize.h" ++#endif + + /****************************************************************************** + * Application Config + ******************************************************************************/ + ++/**< generic parameters ******************************************************/ ++/* HCI related defines */ ++ ++#define ACI_HAL_SET_TX_POWER_LEVEL 0xFC0F ++#define ACI_WRITE_CONFIG_DATA_OPCODE 0xFC0C ++#define ACI_READ_CONFIG_DATA_OPCODE 0xFC0D ++#define MAX_HCI_ACL_PACKET_SIZE (sizeof(TL_PacketHeader_t) + 5 + 251) ++#define HCI_RESET 0x0C03 ++ ++#ifndef BLE_SHARED_MEM_BYTE_ORDER ++ #define BLE_SHARED_MEM_BYTE_ORDER MSBFIRST ++#endif ++#define BLE_MODULE_SHARED_MEM_BUFFER_SIZE 128 ++ ++/** ++ * Define Tx Power ++ */ ++#define CFG_TX_POWER (0x18) /* -0.15dBm */ ++ ++#if 0 + /** + * Define Secure Connections Support + */ +@@ -104,6 +126,7 @@ + #define CFG_FW_SUBVERSION (1) + #define CFG_FW_BRANCH (0) + #define CFG_FW_BUILD (0) ++#endif + + /****************************************************************************** + * BLE Stack +@@ -250,7 +273,7 @@ + * 0: LE Power Class 2-3 + * other bits: complete with Options_extension flag + */ +-#define CFG_BLE_OPTIONS (SHCI_C2_BLE_INIT_OPTIONS_LL_HOST | SHCI_C2_BLE_INIT_OPTIONS_WITH_SVC_CHANGE_DESC | SHCI_C2_BLE_INIT_OPTIONS_DEVICE_NAME_RW | SHCI_C2_BLE_INIT_OPTIONS_EXT_ADV | SHCI_C2_BLE_INIT_OPTIONS_CS_ALGO2 | SHCI_C2_BLE_INIT_OPTIONS_FULL_GATTDB_NVM | SHCI_C2_BLE_INIT_OPTIONS_GATT_CACHING_NOTUSED | SHCI_C2_BLE_INIT_OPTIONS_POWER_CLASS_2_3) ++#define CFG_BLE_OPTIONS (SHCI_C2_BLE_INIT_OPTIONS_LL_ONLY | SHCI_C2_BLE_INIT_OPTIONS_WITH_SVC_CHANGE_DESC | SHCI_C2_BLE_INIT_OPTIONS_DEVICE_NAME_RW | SHCI_C2_BLE_INIT_OPTIONS_EXT_ADV | SHCI_C2_BLE_INIT_OPTIONS_CS_ALGO2 | SHCI_C2_BLE_INIT_OPTIONS_FULL_GATTDB_NVM | SHCI_C2_BLE_INIT_OPTIONS_GATT_CACHING_NOTUSED | SHCI_C2_BLE_INIT_OPTIONS_POWER_CLASS_2_3) + + /** + * BLE stack Options_extension flags to be configured with: +@@ -292,7 +315,11 @@ + * This parameter is considered by the CPU2 when CFG_BLE_OPTIONS has SHCI_C2_BLE_INIT_OPTIONS_EXT_ADV flag set + */ + +-#define CFG_BLE_MAX_ADV_SET_NBR (8) ++#if defined(STM32WB15xx) ++ #define CFG_BLE_MAX_ADV_SET_NBR (3) ++#else ++ #define CFG_BLE_MAX_ADV_SET_NBR (8) ++#endif + + /* Maximum advertising data length (in bytes) + * Range: 31 .. 1650 with limitation: +@@ -301,7 +328,11 @@ + * This parameter is considered by the CPU2 when CFG_BLE_OPTIONS has SHCI_C2_BLE_INIT_OPTIONS_EXT_ADV flag set + */ + +-#define CFG_BLE_MAX_ADV_DATA_LEN (207) ++#if defined(STM32WB15xx) ++ #define CFG_BLE_MAX_ADV_DATA_LEN (414) ++#else ++ #define CFG_BLE_MAX_ADV_DATA_LEN (207) ++#endif + + /* RF TX Path Compensation Value (16-bit signed integer). Units: 0.1 dB. + * Range: -1280 .. 1280 +@@ -324,6 +355,7 @@ + + #define CFG_BLE_CORE_VERSION (SHCI_C2_BLE_INIT_BLE_CORE_5_4) + ++#if 0 + /****************************************************************************** + * Transport Layer + ******************************************************************************/ +@@ -660,4 +692,5 @@ typedef enum + + #define CFG_OTP_END_ADRESS OTP_AREA_END_ADDR + +-#endif /*APP_CONF_H */ ++#endif ++#endif /*APP_CONF_DEFAULT_H */ +diff --git a/src/utility/STM32_WPAN/hw.h b/src/utility/STM32_WPAN/hw.h +index 651e1f1..1472a5e 100644 +--- a/src/utility/STM32_WPAN/hw.h ++++ b/src/utility/STM32_WPAN/hw.h +@@ -26,14 +26,23 @@ extern "C" { + #endif + + /* Includes ------------------------------------------------------------------*/ ++#include "stm32_def.h" ++#include "stm32wbxx_ll_bus.h" ++#include "stm32wbxx_ll_exti.h" ++#include "stm32wbxx_ll_system.h" ++#include "stm32wbxx_ll_rcc.h" ++#include "stm32wbxx_ll_ipcc.h" ++#include "stm32wbxx_ll_cortex.h" ++#include "stm32wbxx_ll_utils.h" ++#include "stm32wbxx_ll_pwr.h" + + /****************************************************************************** + * HW IPCC + ******************************************************************************/ + void HW_IPCC_Enable( void ); + void HW_IPCC_Init( void ); +- void HW_IPCC_Rx_Handler( void ); +- void HW_IPCC_Tx_Handler( void ); ++#define HW_IPCC_Rx_Handler IPCC_C1_RX_IRQHandler ++#define HW_IPCC_Tx_Handler IPCC_C1_TX_IRQHandler + + void HW_IPCC_BLE_Init( void ); + void HW_IPCC_BLE_SendCmd( void ); +diff --git a/src/utility/STM32_WPAN/hw_ipcc.c b/src/utility/STM32_WPAN/hw_ipcc.c +index 6a311b1..ad3c9d4 100644 +--- a/src/utility/STM32_WPAN/hw_ipcc.c ++++ b/src/utility/STM32_WPAN/hw_ipcc.c +@@ -18,8 +18,9 @@ + */ + /* USER CODE END Header */ + ++#if defined(STM32WBxx) + /* Includes ------------------------------------------------------------------*/ +-#include "app_common.h" ++#include "hw.h" + #include "mbox_def.h" + #include "utilities_conf.h" + +@@ -745,3 +746,4 @@ static void HW_IPCC_TRACES_EvtHandler( void ) + } + + __weak void HW_IPCC_TRACES_EvtNot( void ){}; ++#endif /* STM32WBxx */ +diff --git a/src/utility/STM32_WPAN/shci.c b/src/utility/STM32_WPAN/shci.c +index 5c32555..40110f4 100644 +--- a/src/utility/STM32_WPAN/shci.c ++++ b/src/utility/STM32_WPAN/shci.c +@@ -17,6 +17,7 @@ + */ + + ++#if defined(STM32WBxx) + /* Includes ------------------------------------------------------------------*/ + #include "stm32_wpan_common.h" + +@@ -759,3 +760,4 @@ SHCI_CmdStatus_t SHCI_GetWirelessFwInfo( WirelessFwInfo_t* pWirelessInfo ) + + return (SHCI_Success); + } ++#endif /* STM32WBxx */ +diff --git a/src/utility/STM32_WPAN/shci_tl.c b/src/utility/STM32_WPAN/shci_tl.c +index 0f60430..daa988c 100644 +--- a/src/utility/STM32_WPAN/shci_tl.c ++++ b/src/utility/STM32_WPAN/shci_tl.c +@@ -17,11 +17,13 @@ + */ + + ++#if defined(STM32WBxx) + /* Includes ------------------------------------------------------------------*/ + #include "stm32_wpan_common.h" + + #include "stm_list.h" + #include "shci_tl.h" ++#include "stm32_def.h" + + /* Private typedef -----------------------------------------------------------*/ + typedef enum +@@ -168,6 +170,20 @@ void shci_send( uint16_t cmd_code, uint8_t len_cmd_payload, uint8_t * p_cmd_payl + return; + } + ++void shci_notify_asynch_evt(void *pdata) ++{ ++ UNUSED(pdata); ++ /* Need to parse data in future version */ ++ shci_user_evt_proc(); ++} ++ ++void shci_register_io_bus(tSHciIO *fops) ++{ ++ /* Register IO bus services */ ++ fops->Init = TL_SYS_Init; ++ fops->Send = TL_SYS_SendCmd; ++} ++ + /* Private functions ---------------------------------------------------------*/ + static void TlInit( TL_CmdPacket_t * p_cmdbuffer ) + { +@@ -250,3 +266,4 @@ __WEAK void shci_cmd_resp_release(uint32_t flag) + + return; + } ++#endif /* STM32WBxx */ +diff --git a/src/utility/STM32_WPAN/stm_list.c b/src/utility/STM32_WPAN/stm_list.c +index 4c92864..df6c215 100644 +--- a/src/utility/STM32_WPAN/stm_list.c ++++ b/src/utility/STM32_WPAN/stm_list.c +@@ -17,10 +17,13 @@ + */ + + ++#if defined(STM32WBxx) + /****************************************************************************** + * Include Files + ******************************************************************************/ +-#include "utilities_common.h" ++#include "stdint.h" ++#include "cmsis_gcc.h" ++#include "stm32_wpan_common.h" + + #include "stm_list.h" + +@@ -204,3 +207,4 @@ void LST_get_prev_node (tListNode * ref_node, tListNode ** node) + + __set_PRIMASK(primask_bit); /**< Restore PRIMASK bit*/ + } ++#endif /* STM32WBxx */ +diff --git a/src/utility/STM32_WPAN/tl_mbox.c b/src/utility/STM32_WPAN/tl_mbox.c +index df07a19..9a2a297 100644 +--- a/src/utility/STM32_WPAN/tl_mbox.c ++++ b/src/utility/STM32_WPAN/tl_mbox.c +@@ -16,6 +16,7 @@ + ****************************************************************************** + */ + ++#if defined(STM32WBxx) + /* Includes ------------------------------------------------------------------*/ + #include "stm32_wpan_common.h" + #include "hw.h" +@@ -51,8 +52,10 @@ PLACE_IN_SECTION("MB_MEM1") ALIGN(4) static MB_BleLldTable_t TL_BleLldTable; + PLACE_IN_SECTION("MB_MEM1") ALIGN(4) static MB_SysTable_t TL_SysTable; + PLACE_IN_SECTION("MB_MEM1") ALIGN(4) static MB_MemManagerTable_t TL_MemManagerTable; + PLACE_IN_SECTION("MB_MEM1") ALIGN(4) static MB_TracesTable_t TL_TracesTable; ++#if 0 + PLACE_IN_SECTION("MB_MEM1") ALIGN(4) static MB_Mac_802_15_4_t TL_Mac_802_15_4_Table; + PLACE_IN_SECTION("MB_MEM1") ALIGN(4) static MB_ZigbeeTable_t TL_Zigbee_Table; ++#endif + + /**< tables */ + PLACE_IN_SECTION("MB_MEM1") ALIGN(4) static tListNode FreeBufQueue; +@@ -97,8 +100,10 @@ void TL_Init( void ) + TL_RefTable.p_sys_table = &TL_SysTable; + TL_RefTable.p_mem_manager_table = &TL_MemManagerTable; + TL_RefTable.p_traces_table = &TL_TracesTable; ++#if 0 + TL_RefTable.p_mac_802_15_4_table = &TL_Mac_802_15_4_Table; + TL_RefTable.p_zigbee_table = &TL_Zigbee_Table; ++#endif + HW_IPCC_Init(); + + return; +@@ -847,3 +852,4 @@ static void OutputDbgTrace(TL_MB_PacketType_t packet_type, uint8_t* buffer) + + return; + } ++#endif /* STM32WBxx */ +-- +2.34.1 + diff --git a/extras/STM32_WPAN/0002-fix-include-a-timeout-when-waiting-for-the-cmd_resp.patch b/extras/STM32_WPAN/0002-fix-include-a-timeout-when-waiting-for-the-cmd_resp.patch new file mode 100644 index 00000000..bd6f66a2 --- /dev/null +++ b/extras/STM32_WPAN/0002-fix-include-a-timeout-when-waiting-for-the-cmd_resp.patch @@ -0,0 +1,41 @@ +From a33328182e334e1ddedd368a047d75cf1662e330 Mon Sep 17 00:00:00 2001 +From: Frederic Pillon +Date: Thu, 13 Jul 2023 17:16:40 +0200 +Subject: [PATCH 2/4] fix: include a timeout when waiting for the cmd_resp + +Signed-off-by: Frederic Pillon +--- + src/utility/STM32_WPAN/shci_tl.c | 10 ++++++---- + 1 file changed, 6 insertions(+), 4 deletions(-) + +diff --git a/src/utility/STM32_WPAN/shci_tl.c b/src/utility/STM32_WPAN/shci_tl.c +index daa988c..25e1a21 100644 +--- a/src/utility/STM32_WPAN/shci_tl.c ++++ b/src/utility/STM32_WPAN/shci_tl.c +@@ -24,6 +24,7 @@ + #include "stm_list.h" + #include "shci_tl.h" + #include "stm32_def.h" ++#include "wiring_time.h" + + /* Private typedef -----------------------------------------------------------*/ + typedef enum +@@ -251,10 +252,11 @@ static void TlUserEvtReceived(TL_EvtPacket_t *shcievt) + /* Weak implementation ----------------------------------------------------------------*/ + __WEAK void shci_cmd_resp_wait(uint32_t timeout) + { +- (void)timeout; +- +- while(CmdRspStatusFlag != SHCI_TL_CMD_RESP_RELEASE); +- ++ for (unsigned long start = millis(); (millis() - start) < timeout;) { ++ if (CmdRspStatusFlag == SHCI_TL_CMD_RESP_RELEASE) { ++ break; ++ } ++ } + return; + } + +-- +2.34.1 + diff --git a/extras/STM32_WPAN/0003-chore-add-support-for-customize-app_conf_default.h.patch b/extras/STM32_WPAN/0003-chore-add-support-for-customize-app_conf_default.h.patch new file mode 100644 index 00000000..3c5e66ae --- /dev/null +++ b/extras/STM32_WPAN/0003-chore-add-support-for-customize-app_conf_default.h.patch @@ -0,0 +1,135 @@ +From a973b405bf34a93b0c300c8bbc4aa5d59fa182e5 Mon Sep 17 00:00:00 2001 +From: Frederic Pillon +Date: Wed, 10 Jan 2024 18:45:17 +0100 +Subject: [PATCH 3/4] chore: add support for customize app_conf_default.h + +Signed-off-by: Frederic Pillon +--- + src/utility/STM32_WPAN/app_conf_default.h | 58 ++++++++++++++++++----- + 1 file changed, 45 insertions(+), 13 deletions(-) + +diff --git a/src/utility/STM32_WPAN/app_conf_default.h b/src/utility/STM32_WPAN/app_conf_default.h +index bf2274a..ff2dc01 100644 +--- a/src/utility/STM32_WPAN/app_conf_default.h ++++ b/src/utility/STM32_WPAN/app_conf_default.h +@@ -50,7 +50,9 @@ + /** + * Define Tx Power + */ +-#define CFG_TX_POWER (0x18) /* -0.15dBm */ ++#ifndef CFG_TX_POWER ++ #define CFG_TX_POWER (0x18) /* -0.15dBm */ ++#endif + + #if 0 + /** +@@ -135,13 +137,25 @@ + * Maximum number of simultaneous connections that the device will support. + * Valid values are from 1 to 8 + */ +-#define CFG_BLE_NUM_LINK 8 ++#ifndef CFG_BLE_NUM_LINK ++#ifdef STM32WB15xx ++ #define CFG_BLE_NUM_LINK 3 ++#else ++ #define CFG_BLE_NUM_LINK 8 ++#endif ++#endif + + /** + * Maximum number of Services that can be stored in the GATT database. + * Note that the GAP and GATT services are automatically added so this parameter should be 2 plus the number of user services + */ +-#define CFG_BLE_NUM_GATT_SERVICES 8 ++#ifndef CFG_BLE_NUM_GATT_SERVICES ++#ifdef STM32WB15xx ++ #define CFG_BLE_NUM_GATT_SERVICES 4 ++#else ++ #define CFG_BLE_NUM_GATT_SERVICES 8 ++#endif ++#endif + + /** + * Maximum number of Attributes +@@ -150,7 +164,13 @@ + * Note that certain characteristics and relative descriptors are added automatically during device initialization + * so this parameters should be 9 plus the number of user Attributes + */ +-#define CFG_BLE_NUM_GATT_ATTRIBUTES 68 ++#ifndef CFG_BLE_NUM_GATT_ATTRIBUTES ++#ifdef STM32WB15xx ++ #define CFG_BLE_NUM_GATT_ATTRIBUTES 30 ++#else ++ #define CFG_BLE_NUM_GATT_ATTRIBUTES 68 ++#endif ++#endif + + /** + * Maximum supported ATT_MTU size +@@ -186,12 +206,16 @@ + /** + * Enable or disable the Extended Packet length feature. Valid values are 0 or 1. + */ +-#define CFG_BLE_DATA_LENGTH_EXTENSION 1 ++#ifndef CFG_BLE_DATA_LENGTH_EXTENSION ++ #define CFG_BLE_DATA_LENGTH_EXTENSION 1 ++#endif + + /** + * Sleep clock accuracy in Peripheral mode (ppm value) + */ +-#define CFG_BLE_PERIPHERAL_SCA 500 ++#ifndef CFG_BLE_PERIPHERAL_SCA ++ #define CFG_BLE_PERIPHERAL_SCA 500 ++#endif + + /** + * Sleep clock accuracy in Central mode +@@ -204,7 +228,9 @@ + * 6 : 21 ppm to 30 ppm + * 7 : 0 ppm to 20 ppm + */ +-#define CFG_BLE_CENTRAL_SCA 0 ++#ifndef CFG_BLE_CENTRAL_SCA ++ #define CFG_BLE_CENTRAL_SCA 0 ++#endif + + /** + * LsSource +@@ -213,21 +239,27 @@ + * - bit 1: 1: STM32WB5M Module device 0: Other devices as STM32WBxx SOC, STM32WB1M module + * - bit 2: 1: HSE/1024 Clock config 0: LSE Clock config + */ +-#if defined(STM32WB5Mxx) +- #define CFG_BLE_LS_SOURCE (SHCI_C2_BLE_INIT_CFG_BLE_LS_NOCALIB | SHCI_C2_BLE_INIT_CFG_BLE_LS_MOD5MM_DEV | SHCI_C2_BLE_INIT_CFG_BLE_LS_CLK_LSE) +-#else +- #define CFG_BLE_LS_SOURCE (SHCI_C2_BLE_INIT_CFG_BLE_LS_NOCALIB | SHCI_C2_BLE_INIT_CFG_BLE_LS_OTHER_DEV | SHCI_C2_BLE_INIT_CFG_BLE_LS_CLK_LSE) ++#ifndef CFG_BLE_LS_SOURCE ++ #if defined(STM32WB5Mxx) ++ #define CFG_BLE_LS_SOURCE (SHCI_C2_BLE_INIT_CFG_BLE_LS_NOCALIB | SHCI_C2_BLE_INIT_CFG_BLE_LS_MOD5MM_DEV | SHCI_C2_BLE_INIT_CFG_BLE_LS_CLK_LSE) ++ #else ++ #define CFG_BLE_LS_SOURCE (SHCI_C2_BLE_INIT_CFG_BLE_LS_NOCALIB | SHCI_C2_BLE_INIT_CFG_BLE_LS_OTHER_DEV | SHCI_C2_BLE_INIT_CFG_BLE_LS_CLK_LSE) ++ #endif + #endif + + /** + * Start up time of the high speed (16 or 32 MHz) crystal oscillator in units of 625/256 us (~2.44 us) + */ +-#define CFG_BLE_HSE_STARTUP_TIME 0x148 ++#ifndef CFG_BLE_HSE_STARTUP_TIME ++ #define CFG_BLE_HSE_STARTUP_TIME 0x148 ++#endif + + /** + * Maximum duration of the connection event when the device is in Peripheral mode in units of 625/256 us (~2.44 us) + */ +-#define CFG_BLE_MAX_CONN_EVENT_LENGTH (0xFFFFFFFF) ++#ifndef CFG_BLE_MAX_CONN_EVENT_LENGTH ++ #define CFG_BLE_MAX_CONN_EVENT_LENGTH (0xFFFFFFFF) ++#endif + + /** + * Viterbi Mode +-- +2.34.1 + diff --git a/extras/STM32_WPAN/0004-fix-TL_Evt_t-payload-size-for-reset.patch b/extras/STM32_WPAN/0004-fix-TL_Evt_t-payload-size-for-reset.patch new file mode 100644 index 00000000..110a8410 --- /dev/null +++ b/extras/STM32_WPAN/0004-fix-TL_Evt_t-payload-size-for-reset.patch @@ -0,0 +1,30 @@ +From 324eef795bfd0a754aae4d5f9b528d4c8ad706c8 Mon Sep 17 00:00:00 2001 +From: Frederic Pillon +Date: Mon, 24 Jul 2023 10:55:20 +0200 +Subject: [PATCH 4/4] fix: TL_Evt_t payload size for reset + +Within STM32CubeWB v1.17.0 update TL_Evt_t payload size was reduced. +This produce a warning -Warray-bounds due to the reset management +which require 4 bytes. + +Signed-off-by: Frederic Pillon +--- + src/utility/STM32_WPAN/tl.h | 2 +- + 1 file changed, 1 insertion(+), 1 deletion(-) + +diff --git a/src/utility/STM32_WPAN/tl.h b/src/utility/STM32_WPAN/tl.h +index 8e8c6cb..7452087 100644 +--- a/src/utility/STM32_WPAN/tl.h ++++ b/src/utility/STM32_WPAN/tl.h +@@ -108,7 +108,7 @@ typedef PACKED_STRUCT + { + uint8_t evtcode; + uint8_t plen; +- uint8_t payload[2]; ++ uint8_t payload[4]; + } TL_Evt_t; + + typedef PACKED_STRUCT +-- +2.34.1 + diff --git a/extras/arduino-ble-parser.py b/extras/arduino-ble-parser.py deleted file mode 100644 index 8f678711..00000000 --- a/extras/arduino-ble-parser.py +++ /dev/null @@ -1,85 +0,0 @@ -''' -Convert ArduinoBLE debug files into Btsnoop files ready to be analyzed using wireshark or hcidump -Btsnoop file format reference - https://www.fte.com/WebHelpII/Sodera/Content/Technical_Information/BT_Snoop_File_Format.htm -''' - -import os -import argparse - -DEBUG = False - -parser = argparse.ArgumentParser() -parser.add_argument('-i', dest='inputPath', type=str, required=True, help='input file containing debug log') -parser.add_argument('-o', dest='outputPath', type=str, required=True, help='result file that will contain the btsnoop encoded debug file') -args = parser.parse_args() - -# Extract only hci debug messages -def extractHCIDebugPrint(inputPath, outputPath): - inputFile = open(inputPath, 'r') - outputFile = open(outputPath, 'w') - for inputLine in inputFile: - lineItems = inputLine.split() - if (len(lineItems) < 7) or (lineItems[1] != "->") or (lineItems[2] != "HCI"): - if (len(lineItems) < 4) or (lineItems[0] != "HCI") or ((lineItems[3] != "<-") and (lineItems[3] != "->")): - continue - outputFile.write(inputLine) - outputFile.close() - -# Return packet in btsnoop format -def buildBinaryPacket(hciMessage, hciDirection, hciType): - commandFlag = 1 if (hciType == "COMMAND" or hciType == "EVENT") else 0 - directionFlag = 0 if (hciDirection == "TX") else 1 - flagHex = ("0" * 7) + str((commandFlag * 2) + directionFlag) - timestampHex = "0" * 16 - packetDropHex = "0" * 8 - dataLengthHex = format( (int(len(hciMessage) / 2)), 'x') - packetLengthHex = ("0" * (8 - len(dataLengthHex))) + dataLengthHex - binaryPacket = bytearray.fromhex(packetLengthHex + packetLengthHex + flagHex + packetDropHex + timestampHex + hciMessage) - if DEBUG: - print(len(hciMessage)) - print(dataLengthHex) - print(packetLengthHex) - print(flagHex) - print('\n') - return binaryPacket - -def buildBinaryHeader(): - defaultHeader = "6274736e6f6f700000000001000003ea" - binaryHeader = bytearray.fromhex(defaultHeader) - return binaryHeader - -def convertToBtsnoop(inputPath, outputPath): - # Open output file and write the Btsnoop header - outputFile = open(outputPath,'wb') - header = buildBinaryHeader() - outputFile.write(header) - - # Open input file containing HCI debug packets - inputFile = open(inputPath, 'r') - for inputLine in inputFile: - lineItems = inputLine.split() - # For a safer script, do not use indexes but look for symbols in the line - baseIndex = lineItems.index("HCI") - hciMessage = lineItems[baseIndex + 4] - hciDirection = lineItems[baseIndex + 2] - hciType = lineItems[baseIndex + 1] - # Build and write the encoded line - btsnoopPacket = buildBinaryPacket(hciMessage, hciDirection, hciType) - outputFile.write(btsnoopPacket) - if DEBUG: - print(hciDirection) - print(hciMessage) - print(hciType) - print('\n') - outputFile.close() - -inputPath = args.inputPath -outputPath = args.outputPath -tempFile = "temp-debug-print.txt" -# Run -extractHCIDebugPrint(inputPath,tempFile) -convertToBtsnoop(tempFile, outputPath) -# Delete temp file -os.remove(tempFile) - diff --git a/extras/test/.gitignore b/extras/test/.gitignore deleted file mode 100644 index c795b054..00000000 --- a/extras/test/.gitignore +++ /dev/null @@ -1 +0,0 @@ -build \ No newline at end of file diff --git a/extras/test/CMakeLists.txt b/extras/test/CMakeLists.txt deleted file mode 100644 index bbba16ca..00000000 --- a/extras/test/CMakeLists.txt +++ /dev/null @@ -1,126 +0,0 @@ -########################################################################## - -set(CMAKE_VERBOSE_MAKEFILE ON) -cmake_minimum_required(VERSION 2.8) - -########################################################################## - -project(testArduinoBLE) - -########################################################################## - -set(CMAKE_CXX_STANDARD 11) -set(CMAKE_RUNTIME_OUTPUT_DIRECTORY ${CMAKE_BINARY_DIR}/bin) - -########################################################################## - -set(COMMON_TEST_SRCS - src/test_main.cpp - src/Arduino.cpp - src/util/itoa.c - src/util/TestUtil.cpp - src/util/String.cpp - src/util/Common.cpp -) - -set(DUT_SRCS - ../../src/utility/BLEUuid.cpp - ../../src/BLEDevice.cpp - ../../src/BLECharacteristic.cpp - ../../src/BLEDescriptor.cpp - ../../src/BLEService.cpp - ../../src/BLEAdvertisingData.cpp - ../../src/utility/ATT.cpp - ../../src/utility/GAP.cpp - ../../src/utility/HCI.cpp - ../../src/utility/GATT.cpp - ../../src/utility/L2CAPSignaling.cpp - ../../src/local/BLELocalAttribute.cpp - ../../src/local/BLELocalCharacteristic.cpp - ../../src/local/BLELocalDescriptor.cpp - ../../src/local/BLELocalDevice.cpp - ../../src/local/BLELocalService.cpp - ../../src/remote/BLERemoteAttribute.cpp - ../../src/remote/BLERemoteCharacteristic.cpp - ../../src/remote/BLERemoteDescriptor.cpp - ../../src/remote/BLERemoteDevice.cpp - ../../src/remote/BLERemoteService.cpp - ../../src/BLEStringCharacteristic.cpp - ../../src/BLETypedCharacteristics.cpp -) - -set(TEST_TARGET_UUID_SRCS - # Test files - ${COMMON_TEST_SRCS} - src/test_uuid/test_uuid.cpp - # DUT files - #${DUT_SRCS} - ../../src/utility/BLEUuid.cpp -) - -set(TEST_TARGET_DISC_DEVICE_SRCS - # Test files - ${COMMON_TEST_SRCS} - src/test_discovered_device/test_discovered_device.cpp - # DUT files - ${DUT_SRCS} - # Fake classes files - src/util/HCIFakeTransport.cpp - src/test_discovered_device/FakeGAP.cpp -) - -set(TEST_TARGET_ADVERTISING_DATA_SRCS - # Test files - ${COMMON_TEST_SRCS} - src/test_advertising_data/test_advertising_data.cpp - src/test_advertising_data/test_service.cpp - src/test_advertising_data/test_local_name.cpp - src/test_advertising_data/test_manufacturer.cpp - # DUT files - ${DUT_SRCS} - # Fake classes files - src/util/HCIFakeTransport.cpp - src/test_advertising_data/FakeBLELocalDevice.cpp -) - -########################################################################## - -set(CMAKE_C_FLAGS ${CMAKE_C_FLAGS} "--coverage") -set(CMAKE_CXX_FLAGS ${CMAKE_CXX_FLAGS} "--coverage") - -########################################################################## - -add_executable(TEST_TARGET_UUID ${TEST_TARGET_UUID_SRCS}) -add_executable(TEST_TARGET_DISC_DEVICE ${TEST_TARGET_DISC_DEVICE_SRCS}) -add_executable(TEST_TARGET_ADVERTISING_DATA ${TEST_TARGET_ADVERTISING_DATA_SRCS}) - -########################################################################## - -include_directories(include) -include_directories(include/util) -include_directories(../../src) -include_directories(../../src/local) -include_directories(../../src/remote) -include_directories(../../src/utility) -include_directories(external/catch/v2.12.1/include) - -target_include_directories(TEST_TARGET_DISC_DEVICE PUBLIC include/test_discovered_device) -target_include_directories(TEST_TARGET_ADVERTISING_DATA PUBLIC include/test_advertising_data) - -########################################################################## - -target_compile_definitions(TEST_TARGET_DISC_DEVICE PUBLIC FAKE_GAP) -target_compile_definitions(TEST_TARGET_ADVERTISING_DATA PUBLIC FAKE_BLELOCALDEVICE) - -########################################################################## - -# Build unit tests as a post build step -add_custom_command(TARGET TEST_TARGET_UUID POST_BUILD - COMMAND ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/TEST_TARGET_UUID -) -add_custom_command(TARGET TEST_TARGET_DISC_DEVICE POST_BUILD - COMMAND ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/TEST_TARGET_DISC_DEVICE -) -add_custom_command(TARGET TEST_TARGET_ADVERTISING_DATA POST_BUILD - COMMAND ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/TEST_TARGET_ADVERTISING_DATA -) diff --git a/extras/test/external/catch/v2.12.1/include/catch.hpp b/extras/test/external/catch/v2.12.1/include/catch.hpp deleted file mode 100644 index 1d2c9bb6..00000000 --- a/extras/test/external/catch/v2.12.1/include/catch.hpp +++ /dev/null @@ -1,17698 +0,0 @@ -/* - * Catch v2.12.1 - * Generated: 2020-04-21 19:29:20.964532 - * ---------------------------------------------------------- - * This file has been merged from multiple headers. Please don't edit it directly - * Copyright (c) 2020 Two Blue Cubes Ltd. All rights reserved. - * - * Distributed under the Boost Software License, Version 1.0. (See accompanying - * file LICENSE_1_0.txt or copy at http://www.boost.org/LICENSE_1_0.txt) - */ -#ifndef TWOBLUECUBES_SINGLE_INCLUDE_CATCH_HPP_INCLUDED -#define TWOBLUECUBES_SINGLE_INCLUDE_CATCH_HPP_INCLUDED -// start catch.hpp - - -#define CATCH_VERSION_MAJOR 2 -#define CATCH_VERSION_MINOR 12 -#define CATCH_VERSION_PATCH 1 - -#ifdef __clang__ -# pragma clang system_header -#elif defined __GNUC__ -# pragma GCC system_header -#endif - -// start catch_suppress_warnings.h - -#ifdef __clang__ -# ifdef __ICC // icpc defines the __clang__ macro -# pragma warning(push) -# pragma warning(disable: 161 1682) -# else // __ICC -# pragma clang diagnostic push -# pragma clang diagnostic ignored "-Wpadded" -# pragma clang diagnostic ignored "-Wswitch-enum" -# pragma clang diagnostic ignored "-Wcovered-switch-default" -# endif -#elif defined __GNUC__ - // Because REQUIREs trigger GCC's -Wparentheses, and because still - // supported version of g++ have only buggy support for _Pragmas, - // Wparentheses have to be suppressed globally. -# pragma GCC diagnostic ignored "-Wparentheses" // See #674 for details - -# pragma GCC diagnostic push -# pragma GCC diagnostic ignored "-Wunused-variable" -# pragma GCC diagnostic ignored "-Wpadded" -#endif -// end catch_suppress_warnings.h -#if defined(CATCH_CONFIG_MAIN) || defined(CATCH_CONFIG_RUNNER) -# define CATCH_IMPL -# define CATCH_CONFIG_ALL_PARTS -#endif - -// In the impl file, we want to have access to all parts of the headers -// Can also be used to sanely support PCHs -#if defined(CATCH_CONFIG_ALL_PARTS) -# define CATCH_CONFIG_EXTERNAL_INTERFACES -# if defined(CATCH_CONFIG_DISABLE_MATCHERS) -# undef CATCH_CONFIG_DISABLE_MATCHERS -# endif -# if !defined(CATCH_CONFIG_ENABLE_CHRONO_STRINGMAKER) -# define CATCH_CONFIG_ENABLE_CHRONO_STRINGMAKER -# endif -#endif - -#if !defined(CATCH_CONFIG_IMPL_ONLY) -// start catch_platform.h - -#ifdef __APPLE__ -# include -# if TARGET_OS_OSX == 1 -# define CATCH_PLATFORM_MAC -# elif TARGET_OS_IPHONE == 1 -# define CATCH_PLATFORM_IPHONE -# endif - -#elif defined(linux) || defined(__linux) || defined(__linux__) -# define CATCH_PLATFORM_LINUX - -#elif defined(WIN32) || defined(__WIN32__) || defined(_WIN32) || defined(_MSC_VER) || defined(__MINGW32__) -# define CATCH_PLATFORM_WINDOWS -#endif - -// end catch_platform.h - -#ifdef CATCH_IMPL -# ifndef CLARA_CONFIG_MAIN -# define CLARA_CONFIG_MAIN_NOT_DEFINED -# define CLARA_CONFIG_MAIN -# endif -#endif - -// start catch_user_interfaces.h - -namespace Catch { - unsigned int rngSeed(); -} - -// end catch_user_interfaces.h -// start catch_tag_alias_autoregistrar.h - -// start catch_common.h - -// start catch_compiler_capabilities.h - -// Detect a number of compiler features - by compiler -// The following features are defined: -// -// CATCH_CONFIG_COUNTER : is the __COUNTER__ macro supported? -// CATCH_CONFIG_WINDOWS_SEH : is Windows SEH supported? -// CATCH_CONFIG_POSIX_SIGNALS : are POSIX signals supported? -// CATCH_CONFIG_DISABLE_EXCEPTIONS : Are exceptions enabled? -// **************** -// Note to maintainers: if new toggles are added please document them -// in configuration.md, too -// **************** - -// In general each macro has a _NO_ form -// (e.g. CATCH_CONFIG_NO_POSIX_SIGNALS) which disables the feature. -// Many features, at point of detection, define an _INTERNAL_ macro, so they -// can be combined, en-mass, with the _NO_ forms later. - -#ifdef __cplusplus - -# if (__cplusplus >= 201402L) || (defined(_MSVC_LANG) && _MSVC_LANG >= 201402L) -# define CATCH_CPP14_OR_GREATER -# endif - -# if (__cplusplus >= 201703L) || (defined(_MSVC_LANG) && _MSVC_LANG >= 201703L) -# define CATCH_CPP17_OR_GREATER -# endif - -#endif - -#if defined(__cpp_lib_uncaught_exceptions) -# define CATCH_INTERNAL_CONFIG_CPP17_UNCAUGHT_EXCEPTIONS -#endif - -// We have to avoid both ICC and Clang, because they try to mask themselves -// as gcc, and we want only GCC in this block -#if defined(__GNUC__) && !defined(__clang__) && !defined(__ICC) -# define CATCH_INTERNAL_START_WARNINGS_SUPPRESSION _Pragma( "GCC diagnostic push" ) -# define CATCH_INTERNAL_STOP_WARNINGS_SUPPRESSION _Pragma( "GCC diagnostic pop" ) - -# define CATCH_INTERNAL_IGNORE_BUT_WARN(...) (void)__builtin_constant_p(__VA_ARGS__) - -#endif - -#if defined(__clang__) - -# define CATCH_INTERNAL_START_WARNINGS_SUPPRESSION _Pragma( "clang diagnostic push" ) -# define CATCH_INTERNAL_STOP_WARNINGS_SUPPRESSION _Pragma( "clang diagnostic pop" ) - -// As of this writing, IBM XL's implementation of __builtin_constant_p has a bug -// which results in calls to destructors being emitted for each temporary, -// without a matching initialization. In practice, this can result in something -// like `std::string::~string` being called on an uninitialized value. -// -// For example, this code will likely segfault under IBM XL: -// ``` -// REQUIRE(std::string("12") + "34" == "1234") -// ``` -// -// Therefore, `CATCH_INTERNAL_IGNORE_BUT_WARN` is not implemented. -# if !defined(__ibmxl__) -# define CATCH_INTERNAL_IGNORE_BUT_WARN(...) (void)__builtin_constant_p(__VA_ARGS__) /* NOLINT(cppcoreguidelines-pro-type-vararg) */ -# endif - -# define CATCH_INTERNAL_SUPPRESS_GLOBALS_WARNINGS \ - _Pragma( "clang diagnostic ignored \"-Wexit-time-destructors\"" ) \ - _Pragma( "clang diagnostic ignored \"-Wglobal-constructors\"") - -# define CATCH_INTERNAL_SUPPRESS_PARENTHESES_WARNINGS \ - _Pragma( "clang diagnostic ignored \"-Wparentheses\"" ) - -# define CATCH_INTERNAL_SUPPRESS_UNUSED_WARNINGS \ - _Pragma( "clang diagnostic ignored \"-Wunused-variable\"" ) - -# define CATCH_INTERNAL_SUPPRESS_ZERO_VARIADIC_WARNINGS \ - _Pragma( "clang diagnostic ignored \"-Wgnu-zero-variadic-macro-arguments\"" ) - -# define CATCH_INTERNAL_SUPPRESS_UNUSED_TEMPLATE_WARNINGS \ - _Pragma( "clang diagnostic ignored \"-Wunused-template\"" ) - -#endif // __clang__ - -//////////////////////////////////////////////////////////////////////////////// -// Assume that non-Windows platforms support posix signals by default -#if !defined(CATCH_PLATFORM_WINDOWS) - #define CATCH_INTERNAL_CONFIG_POSIX_SIGNALS -#endif - -//////////////////////////////////////////////////////////////////////////////// -// We know some environments not to support full POSIX signals -#if defined(__CYGWIN__) || defined(__QNX__) || defined(__EMSCRIPTEN__) || defined(__DJGPP__) - #define CATCH_INTERNAL_CONFIG_NO_POSIX_SIGNALS -#endif - -#ifdef __OS400__ -# define CATCH_INTERNAL_CONFIG_NO_POSIX_SIGNALS -# define CATCH_CONFIG_COLOUR_NONE -#endif - -//////////////////////////////////////////////////////////////////////////////// -// Android somehow still does not support std::to_string -#if defined(__ANDROID__) -# define CATCH_INTERNAL_CONFIG_NO_CPP11_TO_STRING -# define CATCH_INTERNAL_CONFIG_ANDROID_LOGWRITE -#endif - -//////////////////////////////////////////////////////////////////////////////// -// Not all Windows environments support SEH properly -#if defined(__MINGW32__) -# define CATCH_INTERNAL_CONFIG_NO_WINDOWS_SEH -#endif - -//////////////////////////////////////////////////////////////////////////////// -// PS4 -#if defined(__ORBIS__) -# define CATCH_INTERNAL_CONFIG_NO_NEW_CAPTURE -#endif - -//////////////////////////////////////////////////////////////////////////////// -// Cygwin -#ifdef __CYGWIN__ - -// Required for some versions of Cygwin to declare gettimeofday -// see: http://stackoverflow.com/questions/36901803/gettimeofday-not-declared-in-this-scope-cygwin -# define _BSD_SOURCE -// some versions of cygwin (most) do not support std::to_string. Use the libstd check. -// https://gcc.gnu.org/onlinedocs/gcc-4.8.2/libstdc++/api/a01053_source.html line 2812-2813 -# if !((__cplusplus >= 201103L) && defined(_GLIBCXX_USE_C99) \ - && !defined(_GLIBCXX_HAVE_BROKEN_VSWPRINTF)) - -# define CATCH_INTERNAL_CONFIG_NO_CPP11_TO_STRING - -# endif -#endif // __CYGWIN__ - -//////////////////////////////////////////////////////////////////////////////// -// Visual C++ -#if defined(_MSC_VER) - -# define CATCH_INTERNAL_START_WARNINGS_SUPPRESSION __pragma( warning(push) ) -# define CATCH_INTERNAL_STOP_WARNINGS_SUPPRESSION __pragma( warning(pop) ) - -# if _MSC_VER >= 1900 // Visual Studio 2015 or newer -# define CATCH_INTERNAL_CONFIG_CPP17_UNCAUGHT_EXCEPTIONS -# endif - -// Universal Windows platform does not support SEH -// Or console colours (or console at all...) -# if defined(WINAPI_FAMILY) && (WINAPI_FAMILY == WINAPI_FAMILY_APP) -# define CATCH_CONFIG_COLOUR_NONE -# else -# define CATCH_INTERNAL_CONFIG_WINDOWS_SEH -# endif - -// MSVC traditional preprocessor needs some workaround for __VA_ARGS__ -// _MSVC_TRADITIONAL == 0 means new conformant preprocessor -// _MSVC_TRADITIONAL == 1 means old traditional non-conformant preprocessor -# if !defined(__clang__) // Handle Clang masquerading for msvc -# if !defined(_MSVC_TRADITIONAL) || (defined(_MSVC_TRADITIONAL) && _MSVC_TRADITIONAL) -# define CATCH_INTERNAL_CONFIG_TRADITIONAL_MSVC_PREPROCESSOR -# endif // MSVC_TRADITIONAL -# endif // __clang__ - -#endif // _MSC_VER - -#if defined(_REENTRANT) || defined(_MSC_VER) -// Enable async processing, as -pthread is specified or no additional linking is required -# define CATCH_INTERNAL_CONFIG_USE_ASYNC -#endif // _MSC_VER - -//////////////////////////////////////////////////////////////////////////////// -// Check if we are compiled with -fno-exceptions or equivalent -#if defined(__EXCEPTIONS) || defined(__cpp_exceptions) || defined(_CPPUNWIND) -# define CATCH_INTERNAL_CONFIG_EXCEPTIONS_ENABLED -#endif - -//////////////////////////////////////////////////////////////////////////////// -// DJGPP -#ifdef __DJGPP__ -# define CATCH_INTERNAL_CONFIG_NO_WCHAR -#endif // __DJGPP__ - -//////////////////////////////////////////////////////////////////////////////// -// Embarcadero C++Build -#if defined(__BORLANDC__) - #define CATCH_INTERNAL_CONFIG_POLYFILL_ISNAN -#endif - -//////////////////////////////////////////////////////////////////////////////// - -// Use of __COUNTER__ is suppressed during code analysis in -// CLion/AppCode 2017.2.x and former, because __COUNTER__ is not properly -// handled by it. -// Otherwise all supported compilers support COUNTER macro, -// but user still might want to turn it off -#if ( !defined(__JETBRAINS_IDE__) || __JETBRAINS_IDE__ >= 20170300L ) - #define CATCH_INTERNAL_CONFIG_COUNTER -#endif - -//////////////////////////////////////////////////////////////////////////////// - -// RTX is a special version of Windows that is real time. -// This means that it is detected as Windows, but does not provide -// the same set of capabilities as real Windows does. -#if defined(UNDER_RTSS) || defined(RTX64_BUILD) - #define CATCH_INTERNAL_CONFIG_NO_WINDOWS_SEH - #define CATCH_INTERNAL_CONFIG_NO_ASYNC - #define CATCH_CONFIG_COLOUR_NONE -#endif - -#if !defined(_GLIBCXX_USE_C99_MATH_TR1) -#define CATCH_INTERNAL_CONFIG_GLOBAL_NEXTAFTER -#endif - -// Various stdlib support checks that require __has_include -#if defined(__has_include) - // Check if string_view is available and usable - #if __has_include() && defined(CATCH_CPP17_OR_GREATER) - # define CATCH_INTERNAL_CONFIG_CPP17_STRING_VIEW - #endif - - // Check if optional is available and usable - # if __has_include() && defined(CATCH_CPP17_OR_GREATER) - # define CATCH_INTERNAL_CONFIG_CPP17_OPTIONAL - # endif // __has_include() && defined(CATCH_CPP17_OR_GREATER) - - // Check if byte is available and usable - # if __has_include() && defined(CATCH_CPP17_OR_GREATER) - # define CATCH_INTERNAL_CONFIG_CPP17_BYTE - # endif // __has_include() && defined(CATCH_CPP17_OR_GREATER) - - // Check if variant is available and usable - # if __has_include() && defined(CATCH_CPP17_OR_GREATER) - # if defined(__clang__) && (__clang_major__ < 8) - // work around clang bug with libstdc++ https://bugs.llvm.org/show_bug.cgi?id=31852 - // fix should be in clang 8, workaround in libstdc++ 8.2 - # include - # if defined(__GLIBCXX__) && defined(_GLIBCXX_RELEASE) && (_GLIBCXX_RELEASE < 9) - # define CATCH_CONFIG_NO_CPP17_VARIANT - # else - # define CATCH_INTERNAL_CONFIG_CPP17_VARIANT - # endif // defined(__GLIBCXX__) && defined(_GLIBCXX_RELEASE) && (_GLIBCXX_RELEASE < 9) - # else - # define CATCH_INTERNAL_CONFIG_CPP17_VARIANT - # endif // defined(__clang__) && (__clang_major__ < 8) - # endif // __has_include() && defined(CATCH_CPP17_OR_GREATER) -#endif // defined(__has_include) - -#if defined(CATCH_INTERNAL_CONFIG_COUNTER) && !defined(CATCH_CONFIG_NO_COUNTER) && !defined(CATCH_CONFIG_COUNTER) -# define CATCH_CONFIG_COUNTER -#endif -#if defined(CATCH_INTERNAL_CONFIG_WINDOWS_SEH) && !defined(CATCH_CONFIG_NO_WINDOWS_SEH) && !defined(CATCH_CONFIG_WINDOWS_SEH) && !defined(CATCH_INTERNAL_CONFIG_NO_WINDOWS_SEH) -# define CATCH_CONFIG_WINDOWS_SEH -#endif -// This is set by default, because we assume that unix compilers are posix-signal-compatible by default. -#if defined(CATCH_INTERNAL_CONFIG_POSIX_SIGNALS) && !defined(CATCH_INTERNAL_CONFIG_NO_POSIX_SIGNALS) && !defined(CATCH_CONFIG_NO_POSIX_SIGNALS) && !defined(CATCH_CONFIG_POSIX_SIGNALS) -# define CATCH_CONFIG_POSIX_SIGNALS -#endif -// This is set by default, because we assume that compilers with no wchar_t support are just rare exceptions. -#if !defined(CATCH_INTERNAL_CONFIG_NO_WCHAR) && !defined(CATCH_CONFIG_NO_WCHAR) && !defined(CATCH_CONFIG_WCHAR) -# define CATCH_CONFIG_WCHAR -#endif - -#if !defined(CATCH_INTERNAL_CONFIG_NO_CPP11_TO_STRING) && !defined(CATCH_CONFIG_NO_CPP11_TO_STRING) && !defined(CATCH_CONFIG_CPP11_TO_STRING) -# define CATCH_CONFIG_CPP11_TO_STRING -#endif - -#if defined(CATCH_INTERNAL_CONFIG_CPP17_OPTIONAL) && !defined(CATCH_CONFIG_NO_CPP17_OPTIONAL) && !defined(CATCH_CONFIG_CPP17_OPTIONAL) -# define CATCH_CONFIG_CPP17_OPTIONAL -#endif - -#if defined(CATCH_INTERNAL_CONFIG_CPP17_UNCAUGHT_EXCEPTIONS) && !defined(CATCH_CONFIG_NO_CPP17_UNCAUGHT_EXCEPTIONS) && !defined(CATCH_CONFIG_CPP17_UNCAUGHT_EXCEPTIONS) -# define CATCH_CONFIG_CPP17_UNCAUGHT_EXCEPTIONS -#endif - -#if defined(CATCH_INTERNAL_CONFIG_CPP17_STRING_VIEW) && !defined(CATCH_CONFIG_NO_CPP17_STRING_VIEW) && !defined(CATCH_CONFIG_CPP17_STRING_VIEW) -# define CATCH_CONFIG_CPP17_STRING_VIEW -#endif - -#if defined(CATCH_INTERNAL_CONFIG_CPP17_VARIANT) && !defined(CATCH_CONFIG_NO_CPP17_VARIANT) && !defined(CATCH_CONFIG_CPP17_VARIANT) -# define CATCH_CONFIG_CPP17_VARIANT -#endif - -#if defined(CATCH_INTERNAL_CONFIG_CPP17_BYTE) && !defined(CATCH_CONFIG_NO_CPP17_BYTE) && !defined(CATCH_CONFIG_CPP17_BYTE) -# define CATCH_CONFIG_CPP17_BYTE -#endif - -#if defined(CATCH_CONFIG_EXPERIMENTAL_REDIRECT) -# define CATCH_INTERNAL_CONFIG_NEW_CAPTURE -#endif - -#if defined(CATCH_INTERNAL_CONFIG_NEW_CAPTURE) && !defined(CATCH_INTERNAL_CONFIG_NO_NEW_CAPTURE) && !defined(CATCH_CONFIG_NO_NEW_CAPTURE) && !defined(CATCH_CONFIG_NEW_CAPTURE) -# define CATCH_CONFIG_NEW_CAPTURE -#endif - -#if !defined(CATCH_INTERNAL_CONFIG_EXCEPTIONS_ENABLED) && !defined(CATCH_CONFIG_DISABLE_EXCEPTIONS) -# define CATCH_CONFIG_DISABLE_EXCEPTIONS -#endif - -#if defined(CATCH_INTERNAL_CONFIG_POLYFILL_ISNAN) && !defined(CATCH_CONFIG_NO_POLYFILL_ISNAN) && !defined(CATCH_CONFIG_POLYFILL_ISNAN) -# define CATCH_CONFIG_POLYFILL_ISNAN -#endif - -#if defined(CATCH_INTERNAL_CONFIG_USE_ASYNC) && !defined(CATCH_INTERNAL_CONFIG_NO_ASYNC) && !defined(CATCH_CONFIG_NO_USE_ASYNC) && !defined(CATCH_CONFIG_USE_ASYNC) -# define CATCH_CONFIG_USE_ASYNC -#endif - -#if defined(CATCH_INTERNAL_CONFIG_ANDROID_LOGWRITE) && !defined(CATCH_CONFIG_NO_ANDROID_LOGWRITE) && !defined(CATCH_CONFIG_ANDROID_LOGWRITE) -# define CATCH_CONFIG_ANDROID_LOGWRITE -#endif - -#if defined(CATCH_INTERNAL_CONFIG_GLOBAL_NEXTAFTER) && !defined(CATCH_CONFIG_NO_GLOBAL_NEXTAFTER) && !defined(CATCH_CONFIG_GLOBAL_NEXTAFTER) -# define CATCH_CONFIG_GLOBAL_NEXTAFTER -#endif - -// Even if we do not think the compiler has that warning, we still have -// to provide a macro that can be used by the code. -#if !defined(CATCH_INTERNAL_START_WARNINGS_SUPPRESSION) -# define CATCH_INTERNAL_START_WARNINGS_SUPPRESSION -#endif -#if !defined(CATCH_INTERNAL_STOP_WARNINGS_SUPPRESSION) -# define CATCH_INTERNAL_STOP_WARNINGS_SUPPRESSION -#endif -#if !defined(CATCH_INTERNAL_SUPPRESS_PARENTHESES_WARNINGS) -# define CATCH_INTERNAL_SUPPRESS_PARENTHESES_WARNINGS -#endif -#if !defined(CATCH_INTERNAL_SUPPRESS_GLOBALS_WARNINGS) -# define CATCH_INTERNAL_SUPPRESS_GLOBALS_WARNINGS -#endif -#if !defined(CATCH_INTERNAL_SUPPRESS_UNUSED_WARNINGS) -# define CATCH_INTERNAL_SUPPRESS_UNUSED_WARNINGS -#endif -#if !defined(CATCH_INTERNAL_SUPPRESS_ZERO_VARIADIC_WARNINGS) -# define CATCH_INTERNAL_SUPPRESS_ZERO_VARIADIC_WARNINGS -#endif - -// The goal of this macro is to avoid evaluation of the arguments, but -// still have the compiler warn on problems inside... -#if !defined(CATCH_INTERNAL_IGNORE_BUT_WARN) -# define CATCH_INTERNAL_IGNORE_BUT_WARN(...) -#endif - -#if defined(__APPLE__) && defined(__apple_build_version__) && (__clang_major__ < 10) -# undef CATCH_INTERNAL_SUPPRESS_UNUSED_TEMPLATE_WARNINGS -#elif defined(__clang__) && (__clang_major__ < 5) -# undef CATCH_INTERNAL_SUPPRESS_UNUSED_TEMPLATE_WARNINGS -#endif - -#if !defined(CATCH_INTERNAL_SUPPRESS_UNUSED_TEMPLATE_WARNINGS) -# define CATCH_INTERNAL_SUPPRESS_UNUSED_TEMPLATE_WARNINGS -#endif - -#if defined(CATCH_CONFIG_DISABLE_EXCEPTIONS) -#define CATCH_TRY if ((true)) -#define CATCH_CATCH_ALL if ((false)) -#define CATCH_CATCH_ANON(type) if ((false)) -#else -#define CATCH_TRY try -#define CATCH_CATCH_ALL catch (...) -#define CATCH_CATCH_ANON(type) catch (type) -#endif - -#if defined(CATCH_INTERNAL_CONFIG_TRADITIONAL_MSVC_PREPROCESSOR) && !defined(CATCH_CONFIG_NO_TRADITIONAL_MSVC_PREPROCESSOR) && !defined(CATCH_CONFIG_TRADITIONAL_MSVC_PREPROCESSOR) -#define CATCH_CONFIG_TRADITIONAL_MSVC_PREPROCESSOR -#endif - -// end catch_compiler_capabilities.h -#define INTERNAL_CATCH_UNIQUE_NAME_LINE2( name, line ) name##line -#define INTERNAL_CATCH_UNIQUE_NAME_LINE( name, line ) INTERNAL_CATCH_UNIQUE_NAME_LINE2( name, line ) -#ifdef CATCH_CONFIG_COUNTER -# define INTERNAL_CATCH_UNIQUE_NAME( name ) INTERNAL_CATCH_UNIQUE_NAME_LINE( name, __COUNTER__ ) -#else -# define INTERNAL_CATCH_UNIQUE_NAME( name ) INTERNAL_CATCH_UNIQUE_NAME_LINE( name, __LINE__ ) -#endif - -#include -#include -#include - -// We need a dummy global operator<< so we can bring it into Catch namespace later -struct Catch_global_namespace_dummy {}; -std::ostream& operator<<(std::ostream&, Catch_global_namespace_dummy); - -namespace Catch { - - struct CaseSensitive { enum Choice { - Yes, - No - }; }; - - class NonCopyable { - NonCopyable( NonCopyable const& ) = delete; - NonCopyable( NonCopyable && ) = delete; - NonCopyable& operator = ( NonCopyable const& ) = delete; - NonCopyable& operator = ( NonCopyable && ) = delete; - - protected: - NonCopyable(); - virtual ~NonCopyable(); - }; - - struct SourceLineInfo { - - SourceLineInfo() = delete; - SourceLineInfo( char const* _file, std::size_t _line ) noexcept - : file( _file ), - line( _line ) - {} - - SourceLineInfo( SourceLineInfo const& other ) = default; - SourceLineInfo& operator = ( SourceLineInfo const& ) = default; - SourceLineInfo( SourceLineInfo&& ) noexcept = default; - SourceLineInfo& operator = ( SourceLineInfo&& ) noexcept = default; - - bool empty() const noexcept { return file[0] == '\0'; } - bool operator == ( SourceLineInfo const& other ) const noexcept; - bool operator < ( SourceLineInfo const& other ) const noexcept; - - char const* file; - std::size_t line; - }; - - std::ostream& operator << ( std::ostream& os, SourceLineInfo const& info ); - - // Bring in operator<< from global namespace into Catch namespace - // This is necessary because the overload of operator<< above makes - // lookup stop at namespace Catch - using ::operator<<; - - // Use this in variadic streaming macros to allow - // >> +StreamEndStop - // as well as - // >> stuff +StreamEndStop - struct StreamEndStop { - std::string operator+() const; - }; - template - T const& operator + ( T const& value, StreamEndStop ) { - return value; - } -} - -#define CATCH_INTERNAL_LINEINFO \ - ::Catch::SourceLineInfo( __FILE__, static_cast( __LINE__ ) ) - -// end catch_common.h -namespace Catch { - - struct RegistrarForTagAliases { - RegistrarForTagAliases( char const* alias, char const* tag, SourceLineInfo const& lineInfo ); - }; - -} // end namespace Catch - -#define CATCH_REGISTER_TAG_ALIAS( alias, spec ) \ - CATCH_INTERNAL_START_WARNINGS_SUPPRESSION \ - CATCH_INTERNAL_SUPPRESS_GLOBALS_WARNINGS \ - namespace{ Catch::RegistrarForTagAliases INTERNAL_CATCH_UNIQUE_NAME( AutoRegisterTagAlias )( alias, spec, CATCH_INTERNAL_LINEINFO ); } \ - CATCH_INTERNAL_STOP_WARNINGS_SUPPRESSION - -// end catch_tag_alias_autoregistrar.h -// start catch_test_registry.h - -// start catch_interfaces_testcase.h - -#include - -namespace Catch { - - class TestSpec; - - struct ITestInvoker { - virtual void invoke () const = 0; - virtual ~ITestInvoker(); - }; - - class TestCase; - struct IConfig; - - struct ITestCaseRegistry { - virtual ~ITestCaseRegistry(); - virtual std::vector const& getAllTests() const = 0; - virtual std::vector const& getAllTestsSorted( IConfig const& config ) const = 0; - }; - - bool isThrowSafe( TestCase const& testCase, IConfig const& config ); - bool matchTest( TestCase const& testCase, TestSpec const& testSpec, IConfig const& config ); - std::vector filterTests( std::vector const& testCases, TestSpec const& testSpec, IConfig const& config ); - std::vector const& getAllTestCasesSorted( IConfig const& config ); - -} - -// end catch_interfaces_testcase.h -// start catch_stringref.h - -#include -#include -#include -#include - -namespace Catch { - - /// A non-owning string class (similar to the forthcoming std::string_view) - /// Note that, because a StringRef may be a substring of another string, - /// it may not be null terminated. - class StringRef { - public: - using size_type = std::size_t; - using const_iterator = const char*; - - private: - static constexpr char const* const s_empty = ""; - - char const* m_start = s_empty; - size_type m_size = 0; - - public: // construction - constexpr StringRef() noexcept = default; - - StringRef( char const* rawChars ) noexcept; - - constexpr StringRef( char const* rawChars, size_type size ) noexcept - : m_start( rawChars ), - m_size( size ) - {} - - StringRef( std::string const& stdString ) noexcept - : m_start( stdString.c_str() ), - m_size( stdString.size() ) - {} - - explicit operator std::string() const { - return std::string(m_start, m_size); - } - - public: // operators - auto operator == ( StringRef const& other ) const noexcept -> bool; - auto operator != (StringRef const& other) const noexcept -> bool { - return !(*this == other); - } - - auto operator[] ( size_type index ) const noexcept -> char { - assert(index < m_size); - return m_start[index]; - } - - public: // named queries - constexpr auto empty() const noexcept -> bool { - return m_size == 0; - } - constexpr auto size() const noexcept -> size_type { - return m_size; - } - - // Returns the current start pointer. If the StringRef is not - // null-terminated, throws std::domain_exception - auto c_str() const -> char const*; - - public: // substrings and searches - // Returns a substring of [start, start + length). - // If start + length > size(), then the substring is [start, size()). - // If start > size(), then the substring is empty. - auto substr( size_type start, size_type length ) const noexcept -> StringRef; - - // Returns the current start pointer. May not be null-terminated. - auto data() const noexcept -> char const*; - - constexpr auto isNullTerminated() const noexcept -> bool { - return m_start[m_size] == '\0'; - } - - public: // iterators - constexpr const_iterator begin() const { return m_start; } - constexpr const_iterator end() const { return m_start + m_size; } - }; - - auto operator += ( std::string& lhs, StringRef const& sr ) -> std::string&; - auto operator << ( std::ostream& os, StringRef const& sr ) -> std::ostream&; - - constexpr auto operator "" _sr( char const* rawChars, std::size_t size ) noexcept -> StringRef { - return StringRef( rawChars, size ); - } -} // namespace Catch - -constexpr auto operator "" _catch_sr( char const* rawChars, std::size_t size ) noexcept -> Catch::StringRef { - return Catch::StringRef( rawChars, size ); -} - -// end catch_stringref.h -// start catch_preprocessor.hpp - - -#define CATCH_RECURSION_LEVEL0(...) __VA_ARGS__ -#define CATCH_RECURSION_LEVEL1(...) CATCH_RECURSION_LEVEL0(CATCH_RECURSION_LEVEL0(CATCH_RECURSION_LEVEL0(__VA_ARGS__))) -#define CATCH_RECURSION_LEVEL2(...) CATCH_RECURSION_LEVEL1(CATCH_RECURSION_LEVEL1(CATCH_RECURSION_LEVEL1(__VA_ARGS__))) -#define CATCH_RECURSION_LEVEL3(...) CATCH_RECURSION_LEVEL2(CATCH_RECURSION_LEVEL2(CATCH_RECURSION_LEVEL2(__VA_ARGS__))) -#define CATCH_RECURSION_LEVEL4(...) CATCH_RECURSION_LEVEL3(CATCH_RECURSION_LEVEL3(CATCH_RECURSION_LEVEL3(__VA_ARGS__))) -#define CATCH_RECURSION_LEVEL5(...) CATCH_RECURSION_LEVEL4(CATCH_RECURSION_LEVEL4(CATCH_RECURSION_LEVEL4(__VA_ARGS__))) - -#ifdef CATCH_CONFIG_TRADITIONAL_MSVC_PREPROCESSOR -#define INTERNAL_CATCH_EXPAND_VARGS(...) __VA_ARGS__ -// MSVC needs more evaluations -#define CATCH_RECURSION_LEVEL6(...) CATCH_RECURSION_LEVEL5(CATCH_RECURSION_LEVEL5(CATCH_RECURSION_LEVEL5(__VA_ARGS__))) -#define CATCH_RECURSE(...) CATCH_RECURSION_LEVEL6(CATCH_RECURSION_LEVEL6(__VA_ARGS__)) -#else -#define CATCH_RECURSE(...) CATCH_RECURSION_LEVEL5(__VA_ARGS__) -#endif - -#define CATCH_REC_END(...) -#define CATCH_REC_OUT - -#define CATCH_EMPTY() -#define CATCH_DEFER(id) id CATCH_EMPTY() - -#define CATCH_REC_GET_END2() 0, CATCH_REC_END -#define CATCH_REC_GET_END1(...) CATCH_REC_GET_END2 -#define CATCH_REC_GET_END(...) CATCH_REC_GET_END1 -#define CATCH_REC_NEXT0(test, next, ...) next CATCH_REC_OUT -#define CATCH_REC_NEXT1(test, next) CATCH_DEFER ( CATCH_REC_NEXT0 ) ( test, next, 0) -#define CATCH_REC_NEXT(test, next) CATCH_REC_NEXT1(CATCH_REC_GET_END test, next) - -#define CATCH_REC_LIST0(f, x, peek, ...) , f(x) CATCH_DEFER ( CATCH_REC_NEXT(peek, CATCH_REC_LIST1) ) ( f, peek, __VA_ARGS__ ) -#define CATCH_REC_LIST1(f, x, peek, ...) , f(x) CATCH_DEFER ( CATCH_REC_NEXT(peek, CATCH_REC_LIST0) ) ( f, peek, __VA_ARGS__ ) -#define CATCH_REC_LIST2(f, x, peek, ...) f(x) CATCH_DEFER ( CATCH_REC_NEXT(peek, CATCH_REC_LIST1) ) ( f, peek, __VA_ARGS__ ) - -#define CATCH_REC_LIST0_UD(f, userdata, x, peek, ...) , f(userdata, x) CATCH_DEFER ( CATCH_REC_NEXT(peek, CATCH_REC_LIST1_UD) ) ( f, userdata, peek, __VA_ARGS__ ) -#define CATCH_REC_LIST1_UD(f, userdata, x, peek, ...) , f(userdata, x) CATCH_DEFER ( CATCH_REC_NEXT(peek, CATCH_REC_LIST0_UD) ) ( f, userdata, peek, __VA_ARGS__ ) -#define CATCH_REC_LIST2_UD(f, userdata, x, peek, ...) f(userdata, x) CATCH_DEFER ( CATCH_REC_NEXT(peek, CATCH_REC_LIST1_UD) ) ( f, userdata, peek, __VA_ARGS__ ) - -// Applies the function macro `f` to each of the remaining parameters, inserts commas between the results, -// and passes userdata as the first parameter to each invocation, -// e.g. CATCH_REC_LIST_UD(f, x, a, b, c) evaluates to f(x, a), f(x, b), f(x, c) -#define CATCH_REC_LIST_UD(f, userdata, ...) CATCH_RECURSE(CATCH_REC_LIST2_UD(f, userdata, __VA_ARGS__, ()()(), ()()(), ()()(), 0)) - -#define CATCH_REC_LIST(f, ...) CATCH_RECURSE(CATCH_REC_LIST2(f, __VA_ARGS__, ()()(), ()()(), ()()(), 0)) - -#define INTERNAL_CATCH_EXPAND1(param) INTERNAL_CATCH_EXPAND2(param) -#define INTERNAL_CATCH_EXPAND2(...) INTERNAL_CATCH_NO## __VA_ARGS__ -#define INTERNAL_CATCH_DEF(...) INTERNAL_CATCH_DEF __VA_ARGS__ -#define INTERNAL_CATCH_NOINTERNAL_CATCH_DEF -#define INTERNAL_CATCH_STRINGIZE(...) INTERNAL_CATCH_STRINGIZE2(__VA_ARGS__) -#ifndef CATCH_CONFIG_TRADITIONAL_MSVC_PREPROCESSOR -#define INTERNAL_CATCH_STRINGIZE2(...) #__VA_ARGS__ -#define INTERNAL_CATCH_STRINGIZE_WITHOUT_PARENS(param) INTERNAL_CATCH_STRINGIZE(INTERNAL_CATCH_REMOVE_PARENS(param)) -#else -// MSVC is adding extra space and needs another indirection to expand INTERNAL_CATCH_NOINTERNAL_CATCH_DEF -#define INTERNAL_CATCH_STRINGIZE2(...) INTERNAL_CATCH_STRINGIZE3(__VA_ARGS__) -#define INTERNAL_CATCH_STRINGIZE3(...) #__VA_ARGS__ -#define INTERNAL_CATCH_STRINGIZE_WITHOUT_PARENS(param) (INTERNAL_CATCH_STRINGIZE(INTERNAL_CATCH_REMOVE_PARENS(param)) + 1) -#endif - -#define INTERNAL_CATCH_MAKE_NAMESPACE2(...) ns_##__VA_ARGS__ -#define INTERNAL_CATCH_MAKE_NAMESPACE(name) INTERNAL_CATCH_MAKE_NAMESPACE2(name) - -#define INTERNAL_CATCH_REMOVE_PARENS(...) INTERNAL_CATCH_EXPAND1(INTERNAL_CATCH_DEF __VA_ARGS__) - -#ifndef CATCH_CONFIG_TRADITIONAL_MSVC_PREPROCESSOR -#define INTERNAL_CATCH_MAKE_TYPE_LIST2(...) decltype(get_wrapper()) -#define INTERNAL_CATCH_MAKE_TYPE_LIST(...) INTERNAL_CATCH_MAKE_TYPE_LIST2(INTERNAL_CATCH_REMOVE_PARENS(__VA_ARGS__)) -#else -#define INTERNAL_CATCH_MAKE_TYPE_LIST2(...) INTERNAL_CATCH_EXPAND_VARGS(decltype(get_wrapper())) -#define INTERNAL_CATCH_MAKE_TYPE_LIST(...) INTERNAL_CATCH_EXPAND_VARGS(INTERNAL_CATCH_MAKE_TYPE_LIST2(INTERNAL_CATCH_REMOVE_PARENS(__VA_ARGS__))) -#endif - -#define INTERNAL_CATCH_MAKE_TYPE_LISTS_FROM_TYPES(...)\ - CATCH_REC_LIST(INTERNAL_CATCH_MAKE_TYPE_LIST,__VA_ARGS__) - -#define INTERNAL_CATCH_REMOVE_PARENS_1_ARG(_0) INTERNAL_CATCH_REMOVE_PARENS(_0) -#define INTERNAL_CATCH_REMOVE_PARENS_2_ARG(_0, _1) INTERNAL_CATCH_REMOVE_PARENS(_0), INTERNAL_CATCH_REMOVE_PARENS_1_ARG(_1) -#define INTERNAL_CATCH_REMOVE_PARENS_3_ARG(_0, _1, _2) INTERNAL_CATCH_REMOVE_PARENS(_0), INTERNAL_CATCH_REMOVE_PARENS_2_ARG(_1, _2) -#define INTERNAL_CATCH_REMOVE_PARENS_4_ARG(_0, _1, _2, _3) INTERNAL_CATCH_REMOVE_PARENS(_0), INTERNAL_CATCH_REMOVE_PARENS_3_ARG(_1, _2, _3) -#define INTERNAL_CATCH_REMOVE_PARENS_5_ARG(_0, _1, _2, _3, _4) INTERNAL_CATCH_REMOVE_PARENS(_0), INTERNAL_CATCH_REMOVE_PARENS_4_ARG(_1, _2, _3, _4) -#define INTERNAL_CATCH_REMOVE_PARENS_6_ARG(_0, _1, _2, _3, _4, _5) INTERNAL_CATCH_REMOVE_PARENS(_0), INTERNAL_CATCH_REMOVE_PARENS_5_ARG(_1, _2, _3, _4, _5) -#define INTERNAL_CATCH_REMOVE_PARENS_7_ARG(_0, _1, _2, _3, _4, _5, _6) INTERNAL_CATCH_REMOVE_PARENS(_0), INTERNAL_CATCH_REMOVE_PARENS_6_ARG(_1, _2, _4, _5, _6) -#define INTERNAL_CATCH_REMOVE_PARENS_8_ARG(_0, _1, _2, _3, _4, _5, _6, _7) INTERNAL_CATCH_REMOVE_PARENS(_0), INTERNAL_CATCH_REMOVE_PARENS_7_ARG(_1, _2, _3, _4, _5, _6, _7) -#define INTERNAL_CATCH_REMOVE_PARENS_9_ARG(_0, _1, _2, _3, _4, _5, _6, _7, _8) INTERNAL_CATCH_REMOVE_PARENS(_0), INTERNAL_CATCH_REMOVE_PARENS_8_ARG(_1, _2, _3, _4, _5, _6, _7, _8) -#define INTERNAL_CATCH_REMOVE_PARENS_10_ARG(_0, _1, _2, _3, _4, _5, _6, _7, _8, _9) INTERNAL_CATCH_REMOVE_PARENS(_0), INTERNAL_CATCH_REMOVE_PARENS_9_ARG(_1, _2, _3, _4, _5, _6, _7, _8, _9) -#define INTERNAL_CATCH_REMOVE_PARENS_11_ARG(_0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10) INTERNAL_CATCH_REMOVE_PARENS(_0), INTERNAL_CATCH_REMOVE_PARENS_10_ARG(_1, _2, _3, _4, _5, _6, _7, _8, _9, _10) - -#define INTERNAL_CATCH_VA_NARGS_IMPL(_0, _1, _2, _3, _4, _5, _6, _7, _8, _9, _10, N, ...) N - -#define INTERNAL_CATCH_TYPE_GEN\ - template struct TypeList {};\ - template\ - constexpr auto get_wrapper() noexcept -> TypeList { return {}; }\ - template class...> struct TemplateTypeList{};\ - template class...Cs>\ - constexpr auto get_wrapper() noexcept -> TemplateTypeList { return {}; }\ - template\ - struct append;\ - template\ - struct rewrap;\ - template class, typename...>\ - struct create;\ - template class, typename>\ - struct convert;\ - \ - template \ - struct append { using type = T; };\ - template< template class L1, typename...E1, template class L2, typename...E2, typename...Rest>\ - struct append, L2, Rest...> { using type = typename append, Rest...>::type; };\ - template< template class L1, typename...E1, typename...Rest>\ - struct append, TypeList, Rest...> { using type = L1; };\ - \ - template< template class Container, template class List, typename...elems>\ - struct rewrap, List> { using type = TypeList>; };\ - template< template class Container, template class List, class...Elems, typename...Elements>\ - struct rewrap, List, Elements...> { using type = typename append>, typename rewrap, Elements...>::type>::type; };\ - \ - template