diff --git a/.codespellrc b/.codespellrc new file mode 100644 index 00000000..cffc2173 --- /dev/null +++ b/.codespellrc @@ -0,0 +1,9 @@ +# Source: https://github.com/arduino/tooling-project-assets/blob/main/workflow-templates/assets/spell-check/.codespellrc +# See: https://github.com/codespell-project/codespell#using-a-config-file +[codespell] +# In the event of a false positive, add the problematic word, in all lowercase, to a comma-separated list here: +ignore-words-list = , +skip = ./.git,./.licenses,__pycache__,node_modules,./go.mod,./go.sum,./package-lock.json,./poetry.lock,./yarn.lock,./extras/test +builtin = clear,informal,en-GB_to_en-US +check-filenames = +check-hidden = diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 00000000..f2bfa724 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,13 @@ +# 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 a14882ff..d97458e6 100644 --- a/.github/workflows/compile-examples.yml +++ b/.github/workflows/compile-examples.yml @@ -1,24 +1,115 @@ name: Compile Examples + +# See: https://docs.github.com/en/free-pro-team@latest/actions/reference/events-that-trigger-workflows on: - - push - - pull_request + push: + paths: + - ".github/workflows/compile-examples.yml" + - "examples/**" + - "src/**" + pull_request: + paths: + - ".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 }} + 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: - - arduino:samd:mkrwifi1010 - - arduino:samd:nano_33_iot - - arduino:megaavr:uno2018:mode=on - - arduino:mbed:nano33ble - - arduino:mbed_nano:nanorp2040connect + - esp32:esp32:esp32 + - esp32:esp32:esp32s3 + - esp32:esp32:esp32c3 + - esp32:esp32:esp32c6 + - esp32:esp32:esp32h2 + # Not supported out of the box by ESP32 Arduino core + #- esp32:esp32:esp32c2 steps: - - uses: actions/checkout@v2 + - uses: actions/checkout@v4 - uses: arduino/compile-sketches@v1 with: 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 + sketch-paths: | + - examples/Central/Scan + - examples/Central/PeripheralExplorer + - examples/Central/ScanCallback + - examples/Central/SensorTagButton + - examples/Peripheral/Advertising/EnhancedAdvertising + - examples/Peripheral/Advertising/RawDataAdvertising + cli-compile-flags: | + - --warnings="none" diff --git a/.github/workflows/report-size-deltas.yml b/.github/workflows/report-size-deltas.yml new file mode 100644 index 00000000..39e2a0ad --- /dev/null +++ b/.github/workflows/report-size-deltas.yml @@ -0,0 +1,24 @@ +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 6c44bcfb..6faf09c8 100644 --- a/.github/workflows/spell-check.yml +++ b/.github/workflows/spell-check.yml @@ -1,16 +1,25 @@ +# Source: https://github.com/per1234/.github/blob/main/workflow-templates/spell-check.md name: Spell Check -on: [push, pull_request] +# See: https://docs.github.com/en/actions/reference/events-that-trigger-workflows +on: + push: + pull_request: + schedule: + # Run every Tuesday at 8 AM UTC to catch new misspelling detections resulting from dictionary updates. + - cron: "0 8 * * TUE" + workflow_dispatch: + repository_dispatch: jobs: - build: + spellcheck: runs-on: ubuntu-latest + permissions: + contents: read steps: - - name: Checkout - uses: actions/checkout@v2 + - name: Checkout repository + uses: actions/checkout@v4 - name: Spell check - uses: arduino/actions/libraries/spell-check@master - with: - skip-paths: ./extras/test \ No newline at end of file + uses: codespell-project/actions-codespell@v2 diff --git a/.github/workflows/sync-labels.yml b/.github/workflows/sync-labels.yml new file mode 100644 index 00000000..53a9f54f --- /dev/null +++ b/.github/workflows/sync-labels.yml @@ -0,0 +1,138 @@ +# 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/.github/workflows/unit-tests.yml b/.github/workflows/unit-tests.yml new file mode 100644 index 00000000..2a96b8a5 --- /dev/null +++ b/.github/workflows/unit-tests.yml @@ -0,0 +1,58 @@ +name: Unit Tests + +on: + pull_request: + paths: + - ".github/workflows/unit-tests.yml" + - 'extras/test/**' + - 'src/**' + + push: + paths: + - ".github/workflows/unit-tests.yml" + - 'extras/test/**' + - 'src/**' + +jobs: + test: + name: Run unit tests + runs-on: ubuntu-latest + + env: + COVERAGE_DATA_PATH: extras/coverage-data/coverage.info + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - uses: arduino/cpp-test-action@main + with: + runtime-paths: | + - extras/test/build/bin/TEST_TARGET_UUID + - extras/test/build/bin/TEST_TARGET_DISC_DEVICE + - extras/test/build/bin/TEST_TARGET_ADVERTISING_DATA + coverage-exclude-paths: | + - '*/extras/test/*' + - '/usr/*' + coverage-data-path: ${{ env.COVERAGE_DATA_PATH }} + + # A token is used to avoid intermittent spurious job failures caused by rate limiting. + - name: Set up Codecov upload token + run: | + if [[ "${{ github.repository }}" == "arduino-libraries/ArduinoBLE" ]]; then + # In order to avoid uploads of data from forks, only use the token for runs in the parent repo. + # Token is intentionally exposed. + # See: https://community.codecov.com/t/upload-issues-unable-to-locate-build-via-github-actions-api/3954 + CODECOV_TOKEN="8118de48-b2af-48b4-a66a-26026847bfc5" + else + # codecov/codecov-action does unauthenticated upload if empty string is passed via the `token` input. + CODECOV_TOKEN="" + fi + echo "CODECOV_TOKEN=$CODECOV_TOKEN" >> "$GITHUB_ENV" + + - name: Upload coverage report to Codecov + uses: codecov/codecov-action@v3 + with: + file: "${{ env.COVERAGE_DATA_PATH }}" + fail_ci_if_error: true + token: ${{ env.CODECOV_TOKEN }} diff --git a/CHANGELOG b/CHANGELOG index a29f8598..d8a84716 100644 --- a/CHANGELOG +++ b/CHANGELOG @@ -2,7 +2,7 @@ ArduinoBLE ?.?.? - ????.??.?? ArduinoBLE 1.1.2 - 2019.11.12 -* cordio: switch to lower power when polling with timeout +* cordio: switch to lower power when polling with timeout * Fixed issue with wrong types for disconnection event handling. Thanks @cparata ArduinoBLE 1.1.1 - 2019.09.05 diff --git a/README.md b/README.md index b2f649ca..b0027583 100644 --- a/README.md +++ b/README.md @@ -2,11 +2,13 @@ [![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) -Enables BLE connectivity on the Arduino MKR WiFi 1010, Arduino UNO WiFi Rev.2, Arduino Nano 33 IoT, and Arduino Nano 33 BLE. +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. -This library supports creating a BLE peripheral and BLE central mode. +This library supports creating a Bluetooth® Low Energy peripheral & central mode. -For the Arduino MKR WiFi 1010, Arduino UNO WiFi Rev.2, 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. +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. + +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. For more information about this library please visit us at: diff --git a/docs/api.md b/docs/api.md index dab294ab..d80d0cdc 100644 --- a/docs/api.md +++ b/docs/api.md @@ -2,11 +2,11 @@ ## BLE class -Used to enable the BLE module. +Used to enable the Bluetooth® Low Energy module. -### `begin()` +### `BLE.begin()` -Initializes the BLE device. +Initializes the Bluetooth® Low Energy device. #### Syntax @@ -20,7 +20,8 @@ BLE.begin() None #### Returns -1 on success, 0 on failure. +- 1 on success +- 0 on failure #### Example @@ -28,7 +29,7 @@ None // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -36,9 +37,9 @@ None ``` -### `end()` +### `BLE.end()` -Stops the BLE device. +Stops the Bluetooth® Low Energy device. #### Syntax @@ -60,7 +61,7 @@ Nothing // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -72,14 +73,15 @@ Nothing ``` -### `poll()` +### `BLE.poll()` -Poll for BLE radio events and handle them. +Poll for Bluetooth® Low Energy radio events and handle them. #### Syntax ``` -BLE.poll() BLE.poll(timeout) +BLE.poll() +BLE.poll(timeout) ``` @@ -98,14 +100,13 @@ Nothing BLE.setEventHandler(BLEConnected, blePeripheralConnectHandler); BLE.setEventHandler(BLEDisconnected, blePeripheralDisconnectHandler); - BLE.poll(); ``` -### `setEventHandler()` +### `BLE.setEventHandler()` Set the event handler (callback) function that will be called when the specified event occurs. @@ -118,8 +119,8 @@ BLE.setEventHandler(eventType, callback) #### Parameters -**eventType**: event type (BLEConnected, BLEDisconnected) -**callback**: function to call when event occurs +- **eventType**: event type (BLEConnected, BLEDisconnected) +- **callback**: function to call when event occurs #### Returns Nothing. @@ -129,7 +130,7 @@ Nothing. // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -140,7 +141,6 @@ Nothing. BLE.setEventHandler(BLEConnected, blePeripheralConnectHandler); BLE.setEventHandler(BLEDisconnected, blePeripheralDisconnectHandler); - void blePeripheralConnectHandler(BLEDevice central) { @@ -158,9 +158,9 @@ void blePeripheralDisconnectHandler(BLEDevice central) { ``` -### `connected()` +### `BLE.connected()` -Query if another BLE device is connected +Query if another Bluetooth® Low Energy device is connected #### Syntax @@ -174,7 +174,8 @@ BLE.connected() None #### Returns -**true** if another BLE device is connected, otherwise **false**. +- **true** if another Bluetooth® Low Energy device is connected, +- otherwise **false**. #### Example @@ -189,9 +190,9 @@ None ``` -### `disconnect()` +### `BLE.disconnect()` -Disconnect any BLE devices that are connected +Disconnect any Bluetooth® Low Energy devices that are connected #### Syntax @@ -205,24 +206,23 @@ BLE.disconnect() None #### Returns -**true** if any BLE device that was previously connected was disconnected, otherwise **false**. +- **true** if any Bluetooth® Low Energy device that was previously connected was disconnected, +- otherwise **false**. #### Example ```arduino if (BLE.connected()) { - - BLE.disconnect(); } ``` -### `address()` +### `BLE.address()` -Query the Bluetooth address of the BLE device. +Query the Bluetooth® address of the Bluetooth® Low Energy device. #### Syntax @@ -236,23 +236,23 @@ BLE.address() None #### Returns -The **Bluetooth address** of the BLE device (as a String). +- The **Bluetooth® address** of the Bluetooth® Low Energy device (as a String). #### Example ```arduino - **String** address = BLE.address(); + String address = BLE.address(); - Serial.print(“Local address is: “); + Serial.print("Local address is: "); Serial.println(address); ``` -### `rssi()` +### `BLE.rssi()` -Query the RSSI (Received signal strength indication) of the connected BLE device. +Query the RSSI (Received signal strength indication) of the connected Bluetooth® Low Energy device. #### Syntax @@ -266,23 +266,21 @@ BLE.rssi() None #### Returns -The **RSSI** of the connected BLE device, 127 if no BLE device is connected. +- 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.print("RSSI = "); Serial.println(BLE.rssi()); } ``` -### `setAdvertisedServiceUuid()` +### `BLE.setAdvertisedServiceUuid()` Set the advertised service UUID used when advertising. @@ -295,7 +293,7 @@ BLE.setAdvertisedServiceUuid(uuid) #### Parameters -**uuid:** 16-bit or 128-bit BLE UUID in **String** format +- **uuid:** 16-bit or 128-bit Bluetooth® Low Energy UUID in **String** format #### Returns Nothing @@ -306,14 +304,14 @@ Nothing // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } - BLE.setAdvertisedServiceUuid(“19B10000-E8F2-537E-4F6C-D104768A1214"); + BLE.setAdvertisedServiceUuid("19B10000-E8F2-537E-4F6C-D104768A1214"); - // ... + // ... // start advertising BLE.advertise(); @@ -321,7 +319,7 @@ Nothing ``` -### `setAdvertisedService()` +### `BLE.setAdvertisedService()` Set the advertised service UUID used when advertising to the value of the BLEService provided. @@ -334,7 +332,7 @@ BLE.setAdvertisedService(bleService) #### Parameters -**bleService:** BLEService to use UUID from +- **bleService:** BLEService to use UUID from #### Returns Nothing @@ -343,20 +341,20 @@ Nothing ```arduino -BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // BLE LED Service +BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // Bluetooth® Low Energy LED Service // ... // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } BLE.setAdvertisedService(ledService); - // ... + // ... // start advertising BLE.advertise(); @@ -364,7 +362,7 @@ BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // BLE LED Servic ``` -### `setManufacturerData()` +### `BLE.setManufacturerData()` Set the manufacturer data value used when advertising. @@ -377,8 +375,8 @@ BLE.setManufacturerData(data, length) #### Parameters -**data:** byte array containing manufacturer data -**length:** length of manufacturer data array +- **data:** byte array containing manufacturer data +- **length:** length of manufacturer data array #### Returns Nothing @@ -389,7 +387,7 @@ Nothing // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -398,7 +396,7 @@ Nothing BLE.setManufacturerData(data, 5); - // ... + // ... // start advertising BLE.advertise(); @@ -407,7 +405,7 @@ Nothing ``` -### `setLocalName()` +### `BLE.setLocalName()` Set the local value used when advertising. @@ -420,7 +418,7 @@ BLE.setLocalName(name) #### Parameters -**name:** local name value to use when advertising +- **name:** local name value to use when advertising #### Returns Nothing @@ -431,14 +429,14 @@ Nothing // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } BLE.setLocalName("LED"); - // ... + // ... // start advertising BLE.advertise(); @@ -447,9 +445,9 @@ Nothing ``` -### `setDeviceName()` +### `BLE.setDeviceName()` -Set the device name in the built in device name characteristic. If not set, the value defaults “Arduino”. +Set the device name in the built in device name characteristic. If not set, the value defaults to “Arduino”. #### Syntax @@ -460,7 +458,7 @@ BLE.setDeviceName(name) #### Parameters -**name:** device name value +- **name:** device name value #### Returns Nothing @@ -471,14 +469,14 @@ Nothing // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } BLE.setDeviceName("LED"); - // ... + // ... // start advertising BLE.advertise(); @@ -487,9 +485,9 @@ Nothing ``` -### `setAppearance()` +### `BLE.setAppearance()` -Set the appearance in the built in appearance characteristic. If not set, the value defaults 0x0000. +Set the appearance in the built in appearance characteristic. If not set, the value defaults to 0x0000. #### Syntax @@ -500,7 +498,7 @@ BLE.setAppearance(appearance) #### Parameters -**appearance:** appearance value +- **appearance:** appearance value #### Returns Nothing @@ -511,14 +509,14 @@ Nothing // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } BLE.setAppearance(0x8000); - // ... + // ... // start advertising BLE.advertise(); @@ -527,9 +525,9 @@ Nothing ``` -### `addService()` +### `BLE.addService()` -Add a BLEService to the set of services the BLE device provides +Add a BLEService to the set of services the Bluetooth® Low Energy device provides #### Syntax @@ -540,7 +538,7 @@ BLE.addService(service) #### Parameters -**service:** BLEService to add +- **service:** BLEService to add #### Returns Nothing @@ -549,13 +547,13 @@ Nothing ```arduino -BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // BLE LED Service +BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // Bluetooth® Low Energy LED Service // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -564,12 +562,12 @@ BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // BLE LED Servic BLE.addService(ledService); - // ... + // ... ``` -### `advertise()` +### `BLE.advertise()` Start advertising. @@ -585,7 +583,8 @@ BLE.advertise() None #### Returns -1 on success, 0 on failure. +- 1 on success, +- 0 on failure. #### Example @@ -593,7 +592,7 @@ None // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -602,12 +601,12 @@ None BLE.advertise(); - // ... + // ... ``` -### `stopAdvertise()` +### `BLE.stopAdvertise()` Stop advertising. @@ -631,7 +630,7 @@ Nothing // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -640,16 +639,16 @@ Nothing BLE.advertise(); - // ... + // ... BLE.stopAdvertise(); ``` -### `central()` +### `BLE.central()` -Query the central BLE device connected. +Query the central Bluetooth® Low Energy device connected. #### Syntax @@ -663,13 +662,13 @@ BLE.central() None #### Returns -**BLEDevice** representing the central. +- **BLEDevice** representing the central. #### Example ```arduino - // listen for BLE peripherals to connect: + // listen for Bluetooth® Low Energy peripherals to connect: BLEDevice central = BLE.central(); // if a central is connected to peripheral: @@ -677,14 +676,12 @@ None Serial.print("Connected to central: "); // print the central's MAC address: Serial.println(central.address()); - - } ``` -### `setAdvertisingInterval()` +### `BLE.setAdvertisingInterval()` Set the advertising interval in units of 0.625 ms. Defaults to 100ms (160 * 0.625 ms) if not provided. @@ -697,7 +694,7 @@ BLE.setAdvertisingInterval(advertisingInterval) #### Parameters -**advertisingInterval:** advertising interval in units of 0.625 ms +- **advertisingInterval:** advertising interval in units of 0.625 ms #### Returns Nothing. @@ -708,7 +705,7 @@ Nothing. // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -722,7 +719,7 @@ Nothing. ``` -### `setConnectionInterval()` +### `BLE.setConnectionInterval()` Set the minimum and maximum desired connection intervals in units of 1.25 ms. @@ -735,8 +732,8 @@ 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 +- **minimum:** minimum desired connection interval in units of 1.25 ms +- **maximum:** maximum desired connection interval in units of 1.25 ms #### Returns Nothing. @@ -747,7 +744,7 @@ Nothing. // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -760,7 +757,7 @@ Nothing. ``` -### `setConnectable()` +### `BLE.setConnectable()` Set if the device is connectable after advertising, defaults to **true**. @@ -773,8 +770,8 @@ BLE.setConnectable(connectable) #### Parameters -**true**: the device will be connectable when advertising -**false**: the device will NOT be connectable when advertising +- **true**: the device will be connectable when advertising +- **false**: the device will NOT be connectable when advertising #### Returns Nothing. @@ -785,7 +782,7 @@ Nothing. // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -798,9 +795,9 @@ Nothing. ``` -### `scan()` +### `BLE.scan()` -Start scanning for BLE devices that are advertising. +Start scanning for Bluetooth® Low Energy devices that are advertising. #### Syntax @@ -812,10 +809,11 @@ BLE.scan(withDuplicates) #### Parameters -**withDuplicates:** optional, defaults to **false**. If **true**, advertisements received more than once will not be filtered +- **withDuplicates:** optional, defaults to **false**. If **true**, advertisements received more than once will not be filtered #### Returns -1 on success, 0 on failure. +- 1 on success, +- 0 on failure. #### Example @@ -823,7 +821,7 @@ BLE.scan(withDuplicates) // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -833,7 +831,6 @@ BLE.scan(withDuplicates) // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); @@ -844,9 +841,9 @@ BLE.scan(withDuplicates) ``` -### `scanForName()` +### `BLE.scanForName()` -Start scanning for BLE devices that are advertising with a particular (local) name. +Start scanning for Bluetooth® Low Energy devices that are advertising with a particular (local) name. #### Syntax @@ -858,11 +855,12 @@ 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. +- **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. +- 1 on success, +- 0 on failure. #### Example @@ -870,7 +868,7 @@ BLE.scanForName(name, withDuplicates) // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -880,7 +878,6 @@ BLE.scanForName(name, withDuplicates) // start scanning for peripheral BLE.scanForName("LED"); - BLEDevice peripheral = BLE.available(); @@ -891,9 +888,9 @@ BLE.scanForName(name, withDuplicates) ``` -### `scanForAddress()` +### `BLE.scanForAddress()` -Start scanning for BLE devices that are advertising with a particular (Bluetooth) address. +Start scanning for Bluetooth® Low Energy devices that are advertising with a particular (Bluetooth®) address. #### Syntax @@ -905,11 +902,12 @@ 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 +- **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. +- 1 on success, +- 0 on failure. #### Example @@ -917,7 +915,7 @@ BLE.scanForAddress(address, withDuplicates) // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -927,7 +925,6 @@ BLE.scanForAddress(address, withDuplicates) // start scanning for peripheral BLE.scanForAddress("aa:bb:cc:ee:dd:ff"); - BLEDevice peripheral = BLE.available(); @@ -938,9 +935,9 @@ BLE.scanForAddress(address, withDuplicates) ``` -### `scanForUuid()` +### `BLE.scanForUuid()` -Start scanning for BLE devices that are advertising with a particular (service) UUID. +Start scanning for Bluetooth® Low Energy devices that are advertising with a particular (service) UUID. #### Syntax @@ -952,11 +949,12 @@ 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. +- **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. +- 1 on success, +- 0 on failure. #### Example @@ -964,7 +962,7 @@ BLE.scanForUuid(uuid, withDuplicates) // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -974,7 +972,6 @@ BLE.scanForUuid(uuid, withDuplicates) // start scanning for peripheral BLE.scanForUuid("aa10"); - BLEDevice peripheral = BLE.available(); @@ -985,9 +982,9 @@ BLE.scanForUuid(uuid, withDuplicates) ``` -### `stopScan()` +### `BLE.stopScan()` -Stop scanning for BLE devices that are advertising. +Stop scanning for Bluetooth® Low Energy devices that are advertising. #### Syntax @@ -1009,7 +1006,7 @@ Nothing // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -1019,15 +1016,14 @@ Nothing // start scanning for peripheral BLE.scan(); - BLE.stopScan(); ``` -### `available()` +### `BLE.available()` -Query for a discovered BLE device that was found during scanning. +Query for a discovered Bluetooth® Low Energy device that was found during scanning. #### Syntax @@ -1041,7 +1037,7 @@ BLE.available() Nothing #### Returns -**BLEDevice** representing the discovered device. +- **BLEDevice** representing the discovered device. #### Example @@ -1049,7 +1045,7 @@ Nothing // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -1059,7 +1055,6 @@ Nothing // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); @@ -1074,9 +1069,9 @@ Nothing Used to get information about the devices connected or discovered while scanning -### `poll()` +### `bleDevice.poll()` -Poll for BLE radio events for the specified BLE device and handle them. +Poll for Bluetooth® Low Energy radio events for the specified Bluetooth® Low Energy device and handle them. #### Syntax @@ -1088,7 +1083,7 @@ bleDevice.poll(timeout) #### Parameters -**timeout**: optional timeout in ms, to wait for event. If not specified defaults to 0 ms. +- **timeout**: optional timeout in ms, to wait for event. If not specified defaults to 0 ms. #### Returns Nothing @@ -1097,13 +1092,11 @@ Nothing ```arduino - // listen for BLE centrals to connect: + // listen for Bluetooth® Low Energy centrals to connect: BLEDevice central = BLE.central(); // if a central is connected to peripheral: if (central) { - - central.poll(); // ... @@ -1112,9 +1105,9 @@ Nothing ``` -### `connected()` +### `bleDevice.connected()` -Query if a BLE device is connected +Query if a Bluetooth® Low Energy device is connected #### Syntax @@ -1128,13 +1121,14 @@ bleDevice.connected() None #### Returns -**true** if the BLE device is connected, otherwise **false**. +- **true** if the Bluetooth® Low Energy device is connected, +- otherwise **false**. #### Example ```arduino - // listen for BLE centrals to connect: + // listen for Bluetooth® Low Energy centrals to connect: BLEDevice central = BLE.central(); // while the central is still connected @@ -1146,9 +1140,9 @@ None ``` -### `disconnect()` +### `bleDevice.disconnect()` -Disconnect the BLE device, if connected +Disconnect the Bluetooth® Low Energy device, if connected #### Syntax @@ -1162,25 +1156,25 @@ bleDevice.disconnect() None #### Returns -**true** if the BLE device was disconnected, otherwise **false**. +- **true** if the Bluetooth® Low Energy device was disconnected, +- otherwise **false**. #### Example ```arduino - // listen for BLE centrals to connect: + // listen for Bluetooth® Low Energy centrals to connect: BLEDevice central = BLE.central(); - central.disconnect(); ``` -### `address()` +### `bleDevice.address()` -Query the Bluetooth address of the BLE device. +Query the Bluetooth® address of the Bluetooth® Low Energy device. #### Syntax @@ -1194,13 +1188,13 @@ bleDevice.address() None #### Returns -The **Bluetooth address** of the BLE device (as a String). +- **Bluetooth® address** of the Bluetooth® Low Energy device (as a String). #### Example ```arduino - // listen for BLE peripherals to connect: + // listen for Bluetooth® Low Energy peripherals to connect: BLEDevice central = BLE.central(); // if a central is connected to peripheral: @@ -1208,16 +1202,14 @@ The **Bluetooth address** of the BLE device (as a String). Serial.print("Connected to central: "); // print the central's MAC address: Serial.println(central.address()); - - . } ``` -### `rssi()` +### `bleDevice.rssi()` -Query the RSSI (Received signal strength indication) of the BLE device. +Query the RSSI (Received signal strength indication) of the Bluetooth® Low Energy device. #### Syntax @@ -1231,25 +1223,23 @@ bleDevice.rssi() None #### Returns -The **RSSI** of the connected BLE device, 127 if the BLE device is not connected. +- **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.print("RSSI = "); Serial.println(bleDevice.rssi()); } ``` -### `characteristic()` +### `bleDevice.characteristic()` -Get a BLECharacteristic representing a BLE characteristic the device provides. +Get a BLECharacteristic representing a Bluetooth® Low Energy characteristic the device provides. #### Syntax @@ -1262,11 +1252,11 @@ bleDevice.characteristic(uuid, index) #### Parameters -**index**: index of characteristic -**uuid**: uuid (as a **String**) +- **index**: index of characteristic +- **uuid**: uuid (as a **String**) #### Returns -**BLECharacteristic** for provided parameters +- **BLECharacteristic** for provided parameters #### Example @@ -1274,7 +1264,7 @@ bleDevice.characteristic(uuid, index) // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -1284,7 +1274,6 @@ bleDevice.characteristic(uuid, index) // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); @@ -1310,9 +1299,9 @@ bleDevice.characteristic(uuid, index) return; } - BLECharacteristic batteryLevelCharacterisic = peripheral.characteristic("2a19"); + BLECharacteristic batteryLevelCharacteristic = peripheral.characteristic("2a19"); - if (batteryLevelCharacterisic) { + if (batteryLevelCharacteristic) { // use the characteristic } else { Serial.println("Peripheral does NOT have battery level characteristic"); @@ -1324,9 +1313,9 @@ bleDevice.characteristic(uuid, index) ``` -### `discoverAttributes()` +### `bleDevice.discoverAttributes()` -Discover all of the attributes of BLE device. +Discover all of the attributes of Bluetooth® Low Energy device. #### Syntax @@ -1340,7 +1329,8 @@ bleDevice.discoverAttributes() None #### Returns -**true**, if successful, **false** on failure. +- **true**, if successful, +- **false** on failure. #### Example @@ -1348,7 +1338,7 @@ None // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -1358,7 +1348,6 @@ None // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); @@ -1390,9 +1379,9 @@ None ``` -### `discoverService()` +### `bleDevice.discoverService()` -Discover the attributes of a particular service on the BLE device. +Discover the attributes of a particular service on the Bluetooth® Low Energy device. #### Syntax @@ -1403,10 +1392,11 @@ bleDevice.discoverService(serviceUuid) #### Parameters -**serviceUuid:** service UUID to discover (as a **String**) +- **serviceUuid:** service UUID to discover (as a **String**) #### Returns -**true**, if successful, **false** on failure. +- **true**, if successful, +- **false** on failure. #### Example @@ -1414,7 +1404,7 @@ bleDevice.discoverService(serviceUuid) // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -1424,7 +1414,6 @@ bleDevice.discoverService(serviceUuid) // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); @@ -1456,9 +1445,9 @@ bleDevice.discoverService(serviceUuid) ``` -### `deviceName()` +### `bleDevice.deviceName()` -Query the device name (BLE characteristic UUID 0x2a00) of a BLE device. +Query the device name (BLE characteristic UUID 0x2a00) of a Bluetooth® Low Energy device. #### Syntax @@ -1472,7 +1461,7 @@ bleDevice.deviceName() None #### Returns -**Device name** (as a String). +- **Device name** (as a String). #### Example @@ -1480,7 +1469,7 @@ None // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -1490,7 +1479,6 @@ None // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); @@ -1530,9 +1518,9 @@ None ``` -### `appearance()` +### `bleDevice.appearance()` -Query the appearance (BLE characteristic UUID 0x2a01) of a BLE device. +Query the appearance (BLE characteristic UUID 0x2a01) of a Bluetooth® Low Energy device. #### Syntax @@ -1546,7 +1534,7 @@ bleDevice.appearance() None #### Returns -**Appearance value** (as a number). +- **Appearance value** (as a number). #### Example @@ -1554,7 +1542,7 @@ None // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -1564,7 +1552,6 @@ None // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); @@ -1604,9 +1591,9 @@ None ``` -### `serviceCount()` +### `bleDevice.serviceCount()` -Query the number of services discovered for the BLE device. +Query the number of services discovered for the Bluetooth® Low Energy device. #### Syntax @@ -1620,7 +1607,7 @@ bleDevice.serviceCount() None #### Returns -The number of **services discovered** for the BLE device. +- The number of **services discovered** for the Bluetooth® Low Energy device. #### Example @@ -1628,7 +1615,7 @@ The number of **services discovered** for the BLE device. // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -1638,7 +1625,6 @@ The number of **services discovered** for the BLE device. // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); @@ -1675,9 +1661,9 @@ The number of **services discovered** for the BLE device. ``` -### `hasService()` +### `bleDevice.hasService()` -Query if the BLE device has a particular service. +Query if the Bluetooth® Low Energy device has a particular service. #### Syntax @@ -1689,11 +1675,12 @@ 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. +- **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. +- **true**, if the device provides the service, +- **false** otherwise. #### Example @@ -1701,7 +1688,7 @@ bleDevice.hasService(uuid, index) // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -1711,7 +1698,6 @@ bleDevice.hasService(uuid, index) // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); @@ -1747,9 +1733,9 @@ bleDevice.hasService(uuid, index) ``` -### `service()` +### `bleDevice.service()` -Get a BLEService representing a BLE service the device provides. +Get a BLEService representing a Bluetooth® Low Energy service the device provides. #### Syntax @@ -1762,11 +1748,11 @@ bleDevice.service(uuid, index) #### Parameters -**index**: index of service -**uuid**: uuid (as a **String**) +- **index**: index of service +- **uuid**: uuid (as a **String**) #### Returns -**BLEService** for provided parameters +- **BLEService** for provided parameters #### Example @@ -1774,7 +1760,7 @@ bleDevice.service(uuid, index) // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -1784,7 +1770,6 @@ bleDevice.service(uuid, index) // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); @@ -1824,9 +1809,9 @@ bleDevice.service(uuid, index) ``` -### `characteristicCount()` +### `bleDevice.characteristicCount()` -Query the number of characteristics discovered for the BLE device. +Query the number of characteristics discovered for the Bluetooth® Low Energy device. #### Syntax @@ -1840,7 +1825,7 @@ bleDevice.characteristicCount() None #### Returns -The **number of characteristics** discovered for the BLE device. +- The **number of characteristics** discovered for the Bluetooth® Low Energy device. #### Example @@ -1848,7 +1833,7 @@ The **number of characteristics** discovered for the BLE device. // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -1858,7 +1843,6 @@ The **number of characteristics** discovered for the BLE device. // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); @@ -1887,7 +1871,7 @@ The **number of characteristics** discovered for the BLE device. int characteristicCount = peripheral.characteristicCount(); Serial.print(characteristicCount); - Serial.println(" characteristis discovered"); + Serial.println(" characteristics discovered"); // ... } @@ -1895,9 +1879,9 @@ The **number of characteristics** discovered for the BLE device. ``` -### `hasCharacteristic()` +### `bleDevice.hasCharacteristic()` -Query if the BLE device has a particular characteristic. +Query if the Bluetooth® Low Energy device has a particular characteristic. #### Syntax @@ -1909,11 +1893,12 @@ 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. +- **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. +- **true**, if the device provides the characteristic, +- **false** otherwise. #### Example @@ -1921,7 +1906,7 @@ bleDevice.hasCharacteristic(uuid, index) // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -1931,7 +1916,6 @@ bleDevice.hasCharacteristic(uuid, index) // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); @@ -1967,9 +1951,9 @@ bleDevice.hasCharacteristic(uuid, index) ``` -### `hasLocalName()` +### `bleDevice.hasLocalName()` -Query if a discovered BLE device is advertising a local name. +Query if a discovered Bluetooth® Low Energy device is advertising a local name. #### Syntax @@ -1983,7 +1967,8 @@ bleDevice.hasLocalName() Nothing #### Returns -**true**, if the device is advertising a local name, **false** otherwise. +- **true**, if the device is advertising a local name, +- **false** otherwise. #### Example @@ -1991,7 +1976,7 @@ Nothing // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -2001,7 +1986,6 @@ Nothing // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); @@ -2020,9 +2004,9 @@ Nothing ``` -### `hasAdvertisedServiceUuid()` +### `bleDevice.hasAdvertisedServiceUuid()` -Query if a discovered BLE device is advertising a service UUID. +Query if a discovered Bluetooth® Low Energy device is advertising a service UUID. #### Syntax @@ -2034,10 +2018,11 @@ bleDevice.hasAdvertisedServiceUuid(index) #### Parameters -**index**: optional, defaults to 0, the index of the service UUID, if the device is advertising more than one. +- **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. +- **true**, if the device is advertising a service UUID, +- **false** otherwise. #### Example @@ -2045,7 +2030,7 @@ bleDevice.hasAdvertisedServiceUuid(index) // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -2055,7 +2040,6 @@ bleDevice.hasAdvertisedServiceUuid(index) // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); @@ -2078,9 +2062,9 @@ bleDevice.hasAdvertisedServiceUuid(index) ``` -### `advertisedServiceUuidCount()` +### `bleDevice.advertisedServiceUuidCount()` -Query the number of advertised services a discovered BLE device is advertising. +Query the number of advertised services a discovered Bluetooth® Low Energy device is advertising. #### Syntax @@ -2094,7 +2078,7 @@ bleDevice.advertisedServiceUuidCount() None #### Returns -The **number of advertised services** a discovered BLE device is advertising. +- The **number of advertised services** a discovered Bluetooth® Low Energy device is advertising. #### Example @@ -2102,7 +2086,7 @@ The **number of advertised services** a discovered BLE device is advertising. // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -2112,7 +2096,6 @@ The **number of advertised services** a discovered BLE device is advertising. // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); @@ -2135,9 +2118,9 @@ The **number of advertised services** a discovered BLE device is advertising. ``` -### `localName()` +### `bleDevice.localName()` -Query the local name a discovered BLE device is advertising with. +Query the local name a discovered Bluetooth® Low Energy device is advertising with. #### Syntax @@ -2151,7 +2134,7 @@ bleDevice.localName() Nothing #### Returns -**Advertised local name** (as a String). +- **Advertised local name** (as a String). #### Example @@ -2159,7 +2142,7 @@ Nothing // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -2169,7 +2152,6 @@ Nothing // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); @@ -2188,9 +2170,9 @@ Nothing ``` -### `advertisedServiceUuid()` +### `bleDevice.advertisedServiceUuid()` -Query an advertised service UUID discovered BLE device is advertising. +Query an advertised service UUID discovered Bluetooth® Low Energy device is advertising. #### Syntax @@ -2202,10 +2184,10 @@ bleDevice.advertisedServiceUuid(index) #### Parameters -**index**: optional, defaults to 0, the index of the **service UUID**, if the device is advertising more than one. +- **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). +- Advertised service **UUID** (as a String). #### Example @@ -2213,7 +2195,7 @@ Advertised service **UUID** (as a String). // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -2223,7 +2205,6 @@ Advertised service **UUID** (as a String). // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); @@ -2246,9 +2227,9 @@ Advertised service **UUID** (as a String). ``` -### `connect()` +### `bleDevice.connect()` -Connect to a BLE device. +Connect to a Bluetooth® Low Energy device. #### Syntax @@ -2262,7 +2243,8 @@ bleDevice.connect() None #### Returns -**true**, if the connection was successful, **false** otherwise. +- **true**, if the connection was successful, +- **false** otherwise. #### Example @@ -2270,7 +2252,7 @@ None // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -2280,7 +2262,6 @@ None // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); @@ -2308,7 +2289,7 @@ Used to enable the services board provides or interact with services a remote bo ### `BLEService()` -Create a new BLE service. +Create a new Bluetooth® Low Energy service. #### Syntax @@ -2319,21 +2300,21 @@ BLEService(uuid) #### Parameters -**uuid**: 16-bit or 128-bit UUID in **String** format +- **uuid**: 16-bit or 128-bit UUID in **String** format #### Returns -New **BLEService** with the specified **UUID** +- New **BLEService** with the specified **UUID** #### Example ```arduino -BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // BLE LED Service +BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // Bluetooth® Low Energy LED Service ``` -### `uuid()` +### `bleService.uuid()` Query the UUID of the specified BLEService. @@ -2349,25 +2330,25 @@ bleService.uuid() None #### Returns -UUID of the BLE service as a **String**. +- UUID of the Bluetooth® Low Energy service as a **String**. #### Example ```arduino -BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // BLE LED Service +BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // Bluetooth® Low Energy LED Service -Serial.print(“LED service UUID = “); +Serial.print("LED service UUID = "); Serial.println(ledService.uuid()); ``` -### `addCharacteristic()` +### `bleService.addCharacteristic()` -Add a BLECharateristic to the BLE service. +Add a BLECharacteristic to the Bluetooth® Low Energy service. #### Syntax @@ -2387,9 +2368,9 @@ Nothing ```arduino -BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // BLE LED Service +BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // Bluetooth® Low Energy LED Service -// BLE LED Switch Characteristic - custom 128-bit UUID, readable and writable by central +// 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); @@ -2402,9 +2383,9 @@ ledService.addCharacteristic(switchCharacteristic); ``` -### `characteristicCount()` +### `bleService.characteristicCount()` -Query the number of characteristics discovered for the BLE service. +Query the number of characteristics discovered for the Bluetooth® Low Energy service. #### Syntax @@ -2418,7 +2399,7 @@ bleService.characteristicCount() None #### Returns -The **number of characteristics** discovered for the BLE service. +- The **number of characteristics** discovered for the Bluetooth® Low Energy service. #### Example @@ -2426,7 +2407,7 @@ The **number of characteristics** discovered for the BLE service. // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -2436,7 +2417,6 @@ The **number of characteristics** discovered for the BLE service. // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); @@ -2480,9 +2460,9 @@ The **number of characteristics** discovered for the BLE service. ``` -### `hasCharacteristic()` +### `bleService.hasCharacteristic()` -Query if the BLE service has a particular characteristic. +Query if the Bluetooth® Low Energy service has a particular characteristic. #### Syntax @@ -2494,11 +2474,12 @@ 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. +- **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. +- **true**, if the service provides the characteristic, +- **false** otherwise. #### Example @@ -2506,7 +2487,7 @@ bleService.hasCharacteristic(uuid, index) // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -2516,7 +2497,6 @@ bleService.hasCharacteristic(uuid, index) // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); if (peripheral) { @@ -2558,9 +2538,9 @@ bleService.hasCharacteristic(uuid, index) ``` -### `characteristic()` +### `bleService.characteristic()` -Get a BLECharacteristic representing a BLE characteristic the service provides. +Get a BLECharacteristic representing a Bluetooth® Low Energy characteristic the service provides. #### Syntax @@ -2573,11 +2553,11 @@ bleService.characteristic(uuid, index) #### Parameters -**index**: index of characteristic -**uuid**: uuid (as a **String**) +- **index**: index of characteristic +- **uuid**: uuid (as a **String**) #### Returns -**BLECharacteristic** for provided parameters +- **BLECharacteristic** for provided parameters #### Example @@ -2585,7 +2565,7 @@ bleService.characteristic(uuid, index) // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -2595,7 +2575,6 @@ bleService.characteristic(uuid, index) // start scanning for peripheral BLE.scan(); - BLEDevice peripheral = BLE.available(); @@ -2625,9 +2604,9 @@ bleService.characteristic(uuid, index) if (batteryService) { // use the service - BLECharacteristic batteryLevelCharacterisic = peripheral.characteristic("2a19"); + BLECharacteristic batteryLevelCharacteristic = peripheral.characteristic("2a19"); - if (batteryLevelCharacterisic) { + if (batteryLevelCharacteristic) { // use the characteristic } else { Serial.println("Peripheral does NOT have battery level characteristic"); @@ -2648,12 +2627,13 @@ Used to enable the characteristics board offers in a service or interact with ch ### `BLECharacteristic()` -Create a new BLE characteristic. +Create a new Bluetooth® Low Energy characteristic. #### Syntax ``` -BLECharacteristic(uuid, properties, value, valueSize) +BLECharacteristic(uuid, properties, valueSize) +BLECharacteristic(uuid, properties, valueSize, fixedLength) BLECharacteristic(uuid, properties, stringValue) BLEBoolCharacteristic(uuid, properties) @@ -2674,19 +2654,20 @@ 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 +- **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 +- **fixedLength**: if true, size of characteristic value is fixed +- **stringValue**: value as a string #### Returns -New **BLECharacteristic** with the specified **UUID** and value +- New **BLECharacteristic** with the specified **UUID** and value #### Example ```arduino -// BLE Battery Level Characteristic +// 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 @@ -2694,7 +2675,7 @@ BLEUnsignedCharCharacteristic batteryLevelChar("2A19", // standard 16-bit chara ``` -### `uuid()` +### `bleCharacteristic.uuid()` Query the UUID of the specified BLECharacteristic. @@ -2710,24 +2691,24 @@ bleCharacteristic.uuid() None #### Returns -**UUID** of the BLE service as a **String**. +- **UUID** of the Bluetooth® Low Energy service as a **String**. #### Example ```arduino -// BLE LED Switch Characteristic - custom 128-bit UUID, read and writable by central +// 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.print("Switch characteristic UUID = "); Serial.println(switchCharacteristic.uuid()); ``` -### `properties()` +### `bleCharacteristic.properties()` Query the property mask of the specified BLECharacteristic. @@ -2743,13 +2724,13 @@ bleCharacteristic.properties() None #### Returns -**Properties of the characteristic masked** (BLEBroadcast, BLERead, BLEWriteWithoutResponse, BLEWrite, BLENotify, BLEIndicate) +- **Properties of the characteristic masked** (BLEBroadcast, BLERead, BLEWriteWithoutResponse, BLEWrite, BLENotify, BLEIndicate) #### Example ```arduino -// BLE LED Switch Characteristic - custom 128-bit UUID, read and writable by central +// Bluetooth® Low Energy LED Switch Characteristic - custom 128-bit UUID, read and writable by central BLEByteCharacteristic switchCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite); @@ -2766,7 +2747,7 @@ if (properties & (BLEWrite | BLEWriteWithoutResponse)) { ``` -### `valueSize()` +### `bleCharacteristic.valueSize()` Query the maximum value size of the specified BLECharacteristic. @@ -2782,24 +2763,24 @@ bleCharacteristic.valueSize() None #### Returns -The **maximum value** size of the characteristic (in bytes) +- The **maximum value** size of the characteristic (in bytes) #### Example ```arduino -// BLE LED Switch Characteristic - custom 128-bit UUID, read and writable by central +// 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.print("value size = "); Serial.println(switchCharacteristic.valueSize()); ``` -### `value()` +### `bleCharacteristic.value()` Query the current value of the specified BLECharacteristic. @@ -2815,30 +2796,30 @@ bleCharacteristic.value() None #### Returns -The **current value** of the characteristic, value type depends on the constructor used +- The **current value** of the characteristic, value type depends on the constructor used #### Example ```arduino -// BLE LED Switch Characteristic - custom 128-bit UUID, read and writable by central +// 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 - } + 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 + } ``` -### `valueLength()` +### `bleCharacteristic.valueLength()` Query the current value size of the specified BLECharacteristic. @@ -2854,24 +2835,24 @@ bleCharacteristic.valueLength() None #### Returns -The **current value** size of the characteristic (in bytes) +- The **current value** size of the characteristic (in bytes) #### Example ```arduino -// BLE LED Switch Characteristic - custom 128-bit UUID, read and writable by central +// 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.print("value length = "); Serial.println(switchCharacteristic.valueLength()); ``` -### `readValue()` +### `bleCharacteristic.readValue()` Read the current value of the characteristic. If the characteristic is on a remote device, a read request will be sent. @@ -2885,11 +2866,11 @@ 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) +- **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 +- **Number of bytes** read #### Example @@ -2920,7 +2901,7 @@ Number of bytes read ``` -### `writeValue()` +### `bleCharacteristic.writeValue()` Write the value of the characteristic. If the characteristic is on a remote device, a write request or command will be sent. @@ -2934,12 +2915,13 @@ 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 +- **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 +- 1 on success, +- 0 on failure #### Example @@ -2968,7 +2950,7 @@ bleCharacteristic.writeValue(value) ``` -### `setEventHandler()` +### `bleCharacteristic.setEventHandler()` Set the event handler (callback) function that will be called when the specified event occurs. @@ -2981,8 +2963,8 @@ bleCharacteristic.setEventHandler(eventType, callback) #### Parameters -**eventType**: event type (BLESubscribed, BLEUnsubscribed, BLERead, BLEWritten) -**callback**: function to call when the event occurs +- **eventType**: event type (BLESubscribed, BLEUnsubscribed, BLERead, BLEWritten) +- **callback**: function to call when the event occurs #### Returns Nothing @@ -3015,11 +2997,10 @@ void switchCharacteristicWritten(BLEDevice central, BLECharacteristic characteri } } - ``` -### `broadcast()` +### `bleCharacteristic.broadcast()` Broadcast the characteristics value as service data when advertising. @@ -3035,7 +3016,8 @@ bleCharacteristic.broadcast() None #### Returns -1 on success, 0 on failure +- 1 on success, +- 0 on failure #### Example @@ -3052,9 +3034,9 @@ buttonCharacteristic.broadcast(); ``` -### `written()` +### `bleCharacteristic.written()` -Query if the characteristic value has been written by another BLE device. +Query if the characteristic value has been written by another Bluetooth® Low Energy device. #### Syntax @@ -3068,19 +3050,20 @@ bleCharacteristic.written() None #### Returns -**true** if the characteristic value has been written by another BLE device, **false** otherwise +- **true** if the characteristic value has been written by another Bluetooth® Low Energy device, +- **false** otherwise #### Example ```arduino -// BLE LED Switch Characteristic - custom 128-bit UUID, read and writable by central +// 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 BLE peripherals to connect: + // listen for Bluetooth® Low Energy peripherals to connect: BLEDevice central = BLE.central(); // if a central is connected to peripheral: @@ -3114,9 +3097,9 @@ BLEByteCharacteristic switchCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1214 ``` -### `subscribed()` +### `bleCharacteristic.subscribed()` -Query if the characteristic has been subscribed to by another BLE device. +Query if the characteristic has been subscribed to by another Bluetooth® Low Energy device. #### Syntax @@ -3130,13 +3113,14 @@ bleCharacteristic.subscribed() None #### Returns -**true** if the characteristic value has been subscribed to by another BLE device, **false** otherwise +- **true** if the characteristic value has been subscribed to by another Bluetooth® Low Energy device, +- **false** otherwise #### Example ```arduino -// BLE Battery Level Characteristic +// 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 @@ -3145,14 +3129,14 @@ BLEUnsignedCharCharacteristic batteryLevelChar("2A19", // standard 16-bit chara if (batteryLevelChar.subscribed()) { - // set a new value , that well be pushed to subscribed BLE devices + // set a new value , that well be pushed to subscribed Bluetooth® Low Energy devices batteryLevelChar.writeValue(0xab); } ``` -### `addDescriptor()` +### `bleCharacteristic.addDescriptor()` Add a BLEDescriptor to the characteristic. @@ -3165,7 +3149,7 @@ bleCharacteristic.addDescriptor(bleDescriptor) #### Parameters -**bleDescriptor**: descriptor to add to the characteristic +- **bleDescriptor**: descriptor to add to the characteristic #### Returns Nothing @@ -3174,7 +3158,7 @@ Nothing ```arduino -// BLE Battery Level Characteristic +// 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 @@ -3189,9 +3173,9 @@ BLEDescriptor batteryLevelDescriptor("2901", "millis"); ``` -### `descriptorCount` +### `bleCharacteristic.descriptorCount()` -Query the number of BLE descriptors discovered for the characteristic. +Query the number of Bluetooth® Low Energy descriptors discovered for the characteristic. #### Syntax @@ -3205,7 +3189,7 @@ bleCharacteristic.descriptorCount() None #### Returns -The **number of BLE descriptors** discovered for the characteristic +- The **number of Bluetooth® Low Energy descriptors** discovered for the characteristic #### Example @@ -3221,7 +3205,7 @@ The **number of BLE descriptors** discovered for the characteristic ``` -### `hasDescriptor` +### `bleCharacteristic.hasDescriptor()` Check if a characteristic has a particular descriptor. @@ -3235,11 +3219,12 @@ bleCharacteristic.hasDescriptor(uuid, index) #### Parameters -**index**: index of descriptor -**uuid**: uuid (as a **String**) +- **index**: index of descriptor +- **uuid**: uuid (as a **String**) #### Returns -**true**, if the characteristic has a matching descriptor, otherwise **false**. +- **true**, if the characteristic has a matching descriptor, +- otherwise **false**. #### Example @@ -3252,9 +3237,9 @@ bleCharacteristic.hasDescriptor(uuid, index) ``` -### `descriptor()` +### `bleCharacteristic.descriptor()` -Get a BLEDescriptor that represents a characteristics BLE descriptor. +Get a BLEDescriptor that represents a characteristics Bluetooth® Low Energy descriptor. #### Syntax @@ -3267,11 +3252,11 @@ bleCharacteristic.descriptor(uuid, index) #### Parameters -**index**: index of descriptor -**uuid**: uuid (as a **String**) +- **index**: index of descriptor +- **uuid**: uuid (as a **String**) #### Returns -BLEDescriptor that represents a characteristics BLE descriptor +- BLEDescriptor that represents a characteristics Bluetooth® Low Energy descriptor #### Example @@ -3284,9 +3269,9 @@ BLEDescriptor that represents a characteristics BLE descriptor ``` -### `canRead()` +### `bleCharacteristic.canRead()` -Query if a BLE characteristic is readable. +Query if a Bluetooth® Low Energy characteristic is readable. #### Syntax @@ -3300,7 +3285,8 @@ bleCharacteristic.canRead() None #### Returns -**true**, if characteristic is readable, **false** otherwise +- **true**, if characteristic is readable, +- **false** otherwise #### Example @@ -3329,7 +3315,8 @@ bleCharacteristic.read() None #### Returns -**true**, if successful, **false** on failure +- **true**, if successful, +- **false** on failure #### Example @@ -3346,9 +3333,9 @@ None ``` -### `canWrite()` +### `bleCharacteristic.canWrite()` -Query if a BLE characteristic is writable. +Query if a Bluetooth® Low Energy characteristic is writable. #### Syntax @@ -3362,7 +3349,8 @@ bleCharacteristic.canWrite() None #### Returns -**true**, if characteristic is writable, **false** otherwise +- **true**, if characteristic is writable, +- **false** otherwise #### Example @@ -3375,9 +3363,9 @@ None ``` -### `canSubscribe()` +### `bleCharacteristic.canSubscribe()` -Query if a BLE characteristic is subscribable. +Query if a Bluetooth® Low Energy characteristic is subscribable. #### Syntax @@ -3391,7 +3379,8 @@ bleCharacteristic.canSubscribe() None #### Returns -**true**, if characteristic is subscribable, **false** otherwise +- **true**, if characteristic is subscribable, +- **false** otherwise #### Example @@ -3404,9 +3393,9 @@ None ``` -### `subscribe()` +### `bleCharacteristic.subscribe()` -Subscribe to a BLE characteristics notification or indications. +Subscribe to a Bluetooth® Low Energy characteristics notification or indications. #### Syntax @@ -3420,7 +3409,8 @@ bleCharacteristic.subscribe() None #### Returns -**true**, on success, **false** on failure +- **true**, on success, +- **false** on failure #### Example @@ -3452,9 +3442,9 @@ None ``` -### `canUnsubscribe()` +### `bleCharacteristic.canUnsubscribe()` -Query if a BLE characteristic is unsubscribable. +Query if a Bluetooth® Low Energy characteristic is unsubscribable. #### Syntax @@ -3468,7 +3458,8 @@ bleCharacteristic.canUnsubscribe() None #### Returns -**true**, if characteristic is unsubscribable, **false** otherwise +- **true**, if characteristic is unsubscribable, +- **false** otherwise #### Example @@ -3481,9 +3472,9 @@ None ``` -### `unsubscribe()` +### `bleCharacteristic.unsubscribe()` -Unsubscribe to a BLE characteristics notifications or indications. +Unsubscribe to a Bluetooth® Low Energy characteristics notifications or indications. #### Syntax @@ -3497,7 +3488,8 @@ bleCharacteristic.unsubscribe() None #### Returns -**true**, on success, **false** on failure +- **true**, on success, +- **false** on failure #### Example @@ -3531,7 +3523,7 @@ None ``` -### `valueUpdated()` +### `bleCharacteristic.valueUpdated()` Has the characteristics value been updated via a notification or indication. @@ -3547,7 +3539,7 @@ bleCharacteristic.valueUpdated() None #### Returns -**true**, if the characteristics value been updated via a notification or indication +- **true**, if the characteristics value been updated via a notification or indication #### Example @@ -3584,7 +3576,7 @@ Used to describe a characteristic the board offers ### `BLEDescriptor()` -Create a new BLE descriptor. +Create a new Bluetooth® Low Energy descriptor. #### Syntax @@ -3596,13 +3588,13 @@ 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 +- **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 +- New **BLEDescriptor** with the specified **UUID** and value #### Example @@ -3613,7 +3605,7 @@ BLEDescriptor millisLabelDescriptor("2901", "millis"); ``` -### `uuid()` +### `bleDescriptor.uuid()` Query the UUID of the specified BLEDescriptor. @@ -3629,7 +3621,7 @@ bleDescriptor.uuid() None #### Returns -**UUID** of the BLE descriptor (as a String). +- **UUID** of the Bluetooth® Low Energy descriptor (as a String). #### Example @@ -3638,14 +3630,14 @@ None BLEDescriptor millisLabelDescriptor("2901", "millis"); -Serial.print(“millis label descriptor UUID = “); +Serial.print("millis label descriptor UUID = "); Serial.println(millisLabelDescriptor.uuid()); ``` -### `valueSize()` +### `bleDescriptor.valueSize()` Query the value size of the specified BLEDescriptor. @@ -3661,7 +3653,7 @@ bleDescriptor.valueSize() None #### Returns -**Value size** (in bytes) of the BLE descriptor. +- **Value size** (in bytes) of the Bluetooth® Low Energy descriptor. #### Example @@ -3670,14 +3662,14 @@ None BLEDescriptor millisLabelDescriptor("2901", "millis"); -Serial.print(“millis label descriptor value size = “); +Serial.print("millis label descriptor value size = "); Serial.println(millisLabelDescriptor.valueSize()); ``` -### `valueLength()` +### `bleDescriptor.valueLength()` Query the length, in bytes, of the descriptor current value. @@ -3693,7 +3685,7 @@ bleDescriptor.valueLength() None #### Returns -**Length of descriptor** value in bytes. +- **Length of descriptor** value in bytes. #### Example @@ -3723,7 +3715,7 @@ None ``` -### `value()` +### `bleDescriptor.value()` Query the value of the specified BLEDescriptor. @@ -3739,7 +3731,7 @@ bleDescriptor.value() None #### Returns -Value byte array of the **BLE descriptor**. +- Value byte array of the **BLE descriptor**. #### Example @@ -3760,7 +3752,7 @@ BLEDescriptor millisLabelDescriptor("2901", "millis"); ``` -### `readValue()` +### `bleDescriptor.readValue()` Read the current value of the descriptor. If the descriptor is on a remote device, a read request will be sent. @@ -3774,12 +3766,12 @@ 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) +- **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 +- **Number of bytes** read #### Example @@ -3788,13 +3780,13 @@ bleDescriptor.readValue(value) byte value = 0; - /get the value, descriptor is 1 byte so use byte value + // get the value, descriptor is 1 byte so use byte value descriptor.readValue(value); ``` -### `read()` +### `bleDescriptor.read()` Perform a read request for the descriptor. @@ -3810,7 +3802,8 @@ bleDescriptor.read() None #### Returns -**true**, if successful, **false** on failure +- **true**, if successful, +- **false** on failure #### Example diff --git a/docs/assets/ble-bulletin-board-model.png b/docs/assets/ble-bulletin-board-model.png new file mode 100644 index 00000000..409ae9e8 Binary files /dev/null and b/docs/assets/ble-bulletin-board-model.png differ diff --git a/docs/readme.md b/docs/readme.md index e9e36fc3..b584d71e 100644 --- a/docs/readme.md +++ b/docs/readme.md @@ -1,27 +1,27 @@ # ArduinoBLE library -This library supports all the Arduino boards that have the hardware enabled for BLE and Bluetooth 4.0 and above; these include Nano 33 BLE, Arduino NANO 33 IoT, Uno WiFi Rev 2, MKR WiFi 1010, Nicla Sense ME. +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 LE, or BLE). BLE is optimized for low power use at low data rates, and was designed to operate from simple lithium coin cell batteries. +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 Blueooth 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. +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](www.arduino.cc/en/uploads/Reference/ble-bulletin-board-model.png) +![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. +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 acknowledgement of the pushed data. +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**. +The client-server structure of Bluetooth® LE, combined with the notify characteristic, is generally called a **publish-and-subscribe model**. ## Update a characteristic @@ -35,7 +35,7 @@ Just as with writing to a characteristic, you could update your characteristics ## Services, characteristics, and UUIDs -A BLE peripheral will provide **services**, which in turn provide **characteristics**. You can define your own services, or use [standard services](https://developer.bluetooth.org/gatt/services/Pages/ServicesHome.aspx). +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. @@ -58,7 +58,7 @@ You could also combine readings into a single characteristic, when a given senso |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 a ASCII-encoded string. +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 @@ -84,8 +84,8 @@ The Bluetooth LE protocol operates on multiple layers. **General Attribute Profi As the library enables multiple types of functionality, there are a number of different classes. -- BLE used to enable the BLE 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. +- `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 8301a311..953de7d8 100644 --- a/examples/Central/LedControl/LedControl.ino +++ b/examples/Central/LedControl/LedControl.ino @@ -1,9 +1,9 @@ /* LED Control - This example scans for BLE peripherals until one with the advertised service + This example scans for Bluetooth® Low Energy peripherals until one with the advertised service "19b10000-e8f2-537e-4f6c-d104768a1214" UUID is found. Once discovered and connected, - it will remotely control the BLE Peripheral's LED, when the button is pressed or released. + 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, @@ -29,10 +29,10 @@ void setup() { // configure the button pin as input pinMode(buttonPin, INPUT); - // initialize the BLE hardware + // initialize the Bluetooth® Low Energy hardware BLE.begin(); - Serial.println("BLE Central - LED control"); + Serial.println("Bluetooth® Low Energy Central - LED control"); // start scanning for peripherals BLE.scanForUuid("19b10000-e8f2-537e-4f6c-d104768a1214"); diff --git a/examples/Central/PeripheralExplorer/PeripheralExplorer.ino b/examples/Central/PeripheralExplorer/PeripheralExplorer.ino index 100225d6..919cdde0 100644 --- a/examples/Central/PeripheralExplorer/PeripheralExplorer.ino +++ b/examples/Central/PeripheralExplorer/PeripheralExplorer.ino @@ -1,7 +1,7 @@ /* Peripheral Explorer - This example scans for BLE peripherals until one with a particular name ("LED") + This example scans for Bluetooth® Low Energy peripherals until one with a particular name ("LED") is found. Then connects, and discovers + prints all the peripheral's attributes. The circuit: @@ -22,12 +22,12 @@ void setup() { // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } - Serial.println("BLE Central - Peripheral Explorer"); + Serial.println("Bluetooth® Low Energy Central - Peripheral Explorer"); // start scanning for peripherals BLE.scan(); diff --git a/examples/Central/Scan/Scan.ino b/examples/Central/Scan/Scan.ino index 3126d1a6..162e3c07 100644 --- a/examples/Central/Scan/Scan.ino +++ b/examples/Central/Scan/Scan.ino @@ -1,7 +1,7 @@ /* Scan - This example scans for BLE peripherals and prints out their advertising details: + This example scans for Bluetooth® Low Energy peripherals and prints out their advertising details: address, local name, advertised service UUID's. The circuit: @@ -19,12 +19,12 @@ void setup() { // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } - Serial.println("BLE Central scan"); + Serial.println("Bluetooth® Low Energy Central scan"); // start scanning for peripheral BLE.scan(); diff --git a/examples/Central/ScanCallback/ScanCallback.ino b/examples/Central/ScanCallback/ScanCallback.ino index 28ab9e9e..2687a3b9 100644 --- a/examples/Central/ScanCallback/ScanCallback.ino +++ b/examples/Central/ScanCallback/ScanCallback.ino @@ -1,7 +1,7 @@ /* Scan Callback - This example scans for BLE peripherals and prints out their advertising details: + This example scans for Bluetooth® Low Energy peripherals and prints out their advertising details: address, local name, advertised service UUIDs. Unlike the Scan example, it uses the callback style APIs and disables filtering so the peripheral discovery is reported for every single advertisement it makes. @@ -21,12 +21,12 @@ void setup() { // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } - Serial.println("BLE Central scan callback"); + Serial.println("Bluetooth® Low Energy Central scan callback"); // set the discovered event handle BLE.setEventHandler(BLEDiscovered, bleCentralDiscoverHandler); diff --git a/examples/Central/SensorTagButton/SensorTagButton.ino b/examples/Central/SensorTagButton/SensorTagButton.ino index 72dad90b..27c421fe 100644 --- a/examples/Central/SensorTagButton/SensorTagButton.ino +++ b/examples/Central/SensorTagButton/SensorTagButton.ino @@ -1,7 +1,7 @@ /* SensorTag Button - This example scans for BLE peripherals until a TI SensorTag is discovered. + This example scans for Bluetooth® Low Energy peripherals until a TI SensorTag is discovered. It then connects to it, discovers the attributes of the 0xffe0 service, subscribes to the Simple Key Characteristic (UUID 0xffe1). When a button is pressed on the SensorTag a notification is received and the button state is @@ -23,12 +23,12 @@ void setup() { // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } - Serial.println("BLE Central - SensorTag button"); + Serial.println("Bluetooth® Low Energy Central - SensorTag button"); Serial.println("Make sure to turn on the device."); // start scanning for peripheral @@ -114,7 +114,7 @@ void monitorSensorTagButtons(BLEDevice peripheral) { if (simpleKeyCharacteristic.valueUpdated()) { // yes, get the value, characteristic is 1 byte so use byte value byte value = 0; - + simpleKeyCharacteristic.readValue(value); if (value & 0x01) { diff --git a/examples/Peripheral/Advertising/EnhancedAdvertising/EnhancedAdvertising.ino b/examples/Peripheral/Advertising/EnhancedAdvertising/EnhancedAdvertising.ino new file mode 100644 index 00000000..979b69a8 --- /dev/null +++ b/examples/Peripheral/Advertising/EnhancedAdvertising/EnhancedAdvertising.ino @@ -0,0 +1,44 @@ +#include + +BLEService myService("fff0"); +BLEIntCharacteristic myCharacteristic("fff1", BLERead | BLEBroadcast); + +// Advertising parameters should have a global scope. Do NOT define them in 'setup' or in 'loop' +const uint8_t manufactData[4] = {0x01, 0x02, 0x03, 0x04}; +const uint8_t serviceData[3] = {0x00, 0x01, 0x02}; + +void setup() { + Serial.begin(9600); + while (!Serial); + + if (!BLE.begin()) { + Serial.println("failed to initialize BLE!"); + while (1); + } + + myService.addCharacteristic(myCharacteristic); + BLE.addService(myService); + + // Build scan response data packet + BLEAdvertisingData scanData; + // Set parameters for scan response packet + scanData.setLocalName("Test enhanced advertising"); + // Copy set parameters in the actual scan response packet + BLE.setScanResponseData(scanData); + + // Build advertising data packet + BLEAdvertisingData advData; + // Set parameters for advertising packet + advData.setManufacturerData(0x004C, manufactData, sizeof(manufactData)); + advData.setAdvertisedService(myService); + advData.setAdvertisedServiceData(0xfff0, serviceData, sizeof(serviceData)); + // Copy set parameters in the actual advertising packet + BLE.setAdvertisingData(advData); + + BLE.advertise(); + Serial.println("advertising ..."); +} + +void loop() { + BLE.poll(); +} diff --git a/examples/Peripheral/Advertising/RawDataAdvertising/RawDataAdvertising.ino b/examples/Peripheral/Advertising/RawDataAdvertising/RawDataAdvertising.ino new file mode 100644 index 00000000..5e7ba7f3 --- /dev/null +++ b/examples/Peripheral/Advertising/RawDataAdvertising/RawDataAdvertising.ino @@ -0,0 +1,41 @@ +#include + +BLEService myService("fff0"); +BLEIntCharacteristic myCharacteristic("fff1", BLERead | BLEBroadcast); + +// Advertising parameters should have a global scope. Do NOT define them in 'setup' or in 'loop' +const uint8_t completeRawAdvertisingData[] = {0x02,0x01,0x06,0x09,0xff,0x01,0x01,0x00,0x01,0x02,0x03,0x04,0x05}; + +void setup() { + Serial.begin(9600); + while (!Serial); + + if (!BLE.begin()) { + Serial.println("failed to initialize BLE!"); + while (1); + } + + myService.addCharacteristic(myCharacteristic); + BLE.addService(myService); + + // Build advertising data packet + BLEAdvertisingData advData; + // If a packet has a raw data parameter, then all the other parameters of the packet will be ignored + advData.setRawData(completeRawAdvertisingData, sizeof(completeRawAdvertisingData)); + // Copy set parameters in the actual advertising packet + BLE.setAdvertisingData(advData); + + // Build scan response data packet + BLEAdvertisingData scanData; + scanData.setLocalName("Test advertising raw data"); + // Copy set parameters in the actual scan response packet + BLE.setScanResponseData(scanData); + + BLE.advertise(); + + Serial.println("advertising ..."); +} + +void loop() { + BLE.poll(); +} diff --git a/examples/Peripheral/BatteryMonitor/BatteryMonitor.ino b/examples/Peripheral/BatteryMonitor/BatteryMonitor.ino index 6c5d3d30..0d786627 100644 --- a/examples/Peripheral/BatteryMonitor/BatteryMonitor.ino +++ b/examples/Peripheral/BatteryMonitor/BatteryMonitor.ino @@ -1,14 +1,14 @@ /* Battery Monitor - This example creates a BLE peripheral with the standard battery service and + This example creates a Bluetooth® Low Energy peripheral with the standard battery service and 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. - You can use a generic BLE central app, like LightBlue (iOS and Android) or + 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 created in this sketch. @@ -17,10 +17,10 @@ #include - // BLE Battery Service + // Bluetooth® Low Energy Battery Service BLEService batteryService("180F"); -// BLE Battery Level Characteristic +// 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 @@ -40,9 +40,9 @@ void setup() { while (1); } - /* Set a local name for the BLE device + /* Set a local name for the Bluetooth® Low Energy device This name will appear in advertising packets - and can be used by remote devices to identify this BLE device + and can be used by remote devices to identify this Bluetooth® Low Energy device The name can be changed but maybe be truncated based on space left in advertisement packet */ BLE.setLocalName("BatteryMonitor"); @@ -51,18 +51,18 @@ void setup() { BLE.addService(batteryService); // Add the battery service batteryLevelChar.writeValue(oldBatteryLevel); // set initial value for this characteristic - /* Start advertising BLE. It will start continuously transmitting BLE - advertising packets and will be visible to remote BLE central devices + /* Start advertising Bluetooth® Low Energy. It will start continuously transmitting Bluetooth® Low Energy + advertising packets and will be visible to remote Bluetooth® Low Energy central devices until it receives a new connection */ // start advertising BLE.advertise(); - Serial.println("Bluetooth device active, waiting for connections..."); + Serial.println("Bluetooth® device active, waiting for connections..."); } void loop() { - // wait for a BLE central + // wait for a Bluetooth® Low Energy central BLEDevice central = BLE.central(); // if a central is connected to the peripheral: @@ -73,11 +73,11 @@ void loop() { // turn on the LED to indicate the connection: digitalWrite(LED_BUILTIN, HIGH); - // check the battery level every 200ms + // check the battery level every 200 ms // while the central is connected: while (central.connected()) { long currentMillis = millis(); - // if 200ms have passed, check the battery level: + // if 200 ms have passed, check the battery level: if (currentMillis - previousMillis >= 200) { previousMillis = currentMillis; updateBatteryLevel(); diff --git a/examples/Peripheral/ButtonLED/ButtonLED.ino b/examples/Peripheral/ButtonLED/ButtonLED.ino index bd373731..cbc14dd8 100644 --- a/examples/Peripheral/ButtonLED/ButtonLED.ino +++ b/examples/Peripheral/ButtonLED/ButtonLED.ino @@ -1,7 +1,7 @@ /* Button LED - This example creates a BLE peripheral with service that contains a + This example creates a Bluetooth® Low Energy peripheral with service that contains a characteristic to control an LED and another characteristic that represents the state of the button. @@ -10,7 +10,7 @@ Arduino Nano 33 BLE, or Arduino Nano 33 BLE Sense board. - Button connected to pin 4 - You can use a generic BLE central app, like LightBlue (iOS and Android) or + 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 created in this sketch. @@ -38,7 +38,7 @@ void setup() { // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -61,18 +61,18 @@ void setup() { // start advertising BLE.advertise(); - Serial.println("Bluetooth device active, waiting for connections..."); + Serial.println("Bluetooth® device active, waiting for connections..."); } void loop() { - // poll for BLE events + // poll for Bluetooth® Low Energy events BLE.poll(); // read the current button pin state char buttonValue = digitalRead(buttonPin); // has the value changed since the last read - boolean buttonChanged = (buttonCharacteristic.value() != buttonValue); + bool buttonChanged = (buttonCharacteristic.value() != buttonValue); if (buttonChanged) { // button state changed, update characteristics diff --git a/examples/Peripheral/CallbackLED/CallbackLED.ino b/examples/Peripheral/CallbackLED/CallbackLED.ino index a874a77b..59bda5ed 100644 --- a/examples/Peripheral/CallbackLED/CallbackLED.ino +++ b/examples/Peripheral/CallbackLED/CallbackLED.ino @@ -1,7 +1,7 @@ /* Callback LED - This example creates a BLE peripheral with service that contains a + This example creates a Bluetooth® Low Energy peripheral with service that contains a characteristic to control an LED. The callback features of the library are used. @@ -9,7 +9,7 @@ - Arduino MKR WiFi 1010, Arduino Uno WiFi Rev2 board, Arduino Nano 33 IoT, Arduino Nano 33 BLE, or Arduino Nano 33 BLE Sense board. - You can use a generic BLE central app, like LightBlue (iOS and Android) or + 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 created in this sketch. @@ -28,12 +28,12 @@ const int ledPin = LED_BUILTIN; // pin to use for the LED void setup() { Serial.begin(9600); while (!Serial); - + pinMode(ledPin, OUTPUT); // use the LED pin as an output // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -61,11 +61,11 @@ void setup() { // start advertising BLE.advertise(); - Serial.println(("Bluetooth device active, waiting for connections...")); + Serial.println(("Bluetooth® device active, waiting for connections...")); } void loop() { - // poll for BLE events + // poll for Bluetooth® Low Energy events BLE.poll(); } diff --git a/examples/Peripheral/EncryptedBatteryMonitor/EncryptedBatteryMonitor.ino b/examples/Peripheral/EncryptedBatteryMonitor/EncryptedBatteryMonitor.ino new file mode 100644 index 00000000..dfc9f4a0 --- /dev/null +++ b/examples/Peripheral/EncryptedBatteryMonitor/EncryptedBatteryMonitor.ino @@ -0,0 +1,265 @@ +/* + Battery Monitor + + This example creates a BLE peripheral with the standard battery service and + 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. + + You can use a generic BLE central app, like LightBlue (iOS and Android) or + nRF Connect (Android), to interact with the services and characteristics + created in this sketch. + + This example code is in the public domain. +*/ + +#include + + +#define PAIR_BUTTON 3 // button for pairing +#define PAIR_LED 24 // LED used to signal pairing +#define PAIR_LED_ON LOW // Blue LED on Nano BLE has inverted logic +#define PAIR_INTERVAL 30000 // interval for pairing after button press in ms + +#define CTRL_LED LED_BUILTIN + + + // BLE Battery Service +BLEService batteryService("180F"); + +// BLE 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 +BLEStringCharacteristic stringcharacteristic("183E", BLERead | BLEWrite, 31); + + +// Add BLEEncryption tag to require pairing. This controls the LED. +BLEUnsignedCharCharacteristic secretValue("2a3F", BLERead | BLEWrite | BLEEncryption); + +int oldBatteryLevel = 0; // last battery level reading from analog input +unsigned long previousMillis = 0; // last time the battery level was checked, in ms +unsigned long pairingStarted = 0; // pairing start time when button is pressed +bool wasConnected = 0; +bool acceptOrReject = true; + +void setup() { + Serial.begin(9600); // initialize serial communication + while (!Serial); + + pinMode(CTRL_LED, OUTPUT); // initialize the built-in LED pin to indicate when a central is connected + pinMode(PAIR_LED, OUTPUT); + pinMode(PAIR_BUTTON, INPUT_PULLUP); + + + Serial.println("Serial connected"); + + // Callback function with confirmation code when new device is pairing. + BLE.setDisplayCode([](uint32_t confirmCode){ + Serial.println("New device pairing request."); + Serial.print("Confirm code matches pairing device: "); + char code[6]; + sprintf(code, "%06d", confirmCode); + Serial.println(code); + }); + + // Callback to allow accepting or rejecting pairing + BLE.setBinaryConfirmPairing([&acceptOrReject](){ + Serial.print("Should we confirm pairing? "); + delay(5000); + if(acceptOrReject){ + acceptOrReject = false; + Serial.println("yes"); + return true; + }else{ + acceptOrReject = true; + Serial.println("no"); + return false; + } + }); + + // IRKs are keys that identify the true owner of a random mac address. + // Add IRKs of devices you are bonded with. + BLE.setGetIRKs([](uint8_t* nIRKs, uint8_t** BDaddrTypes, uint8_t*** BDAddrs, uint8_t*** IRKs){ + // Set to number of devices + *nIRKs = 2; + + *BDAddrs = new uint8_t*[*nIRKs]; + *IRKs = new uint8_t*[*nIRKs]; + *BDaddrTypes = new uint8_t[*nIRKs]; + + // Set these to the mac and IRK for your bonded devices as printed in the serial console after bonding. + uint8_t device1Mac[6] = {0x00, 0x00, 0x00, 0x00, 0x00, 0x00}; + uint8_t device1IRK[16] = {0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}; + + uint8_t device2Mac[6] = {0x00, 0x00, 0x00, 0x00, 0x00, 0x00}; + uint8_t device2IRK[16] = {0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}; + + + (*BDaddrTypes)[0] = 0; // Type 0 is for pubc address, type 1 is for static random + (*BDAddrs)[0] = new uint8_t[6]; + (*IRKs)[0] = new uint8_t[16]; + memcpy((*IRKs)[0] , device1IRK,16); + memcpy((*BDAddrs)[0], device1Mac, 6); + + + (*BDaddrTypes)[1] = 0; + (*BDAddrs)[1] = new uint8_t[6]; + (*IRKs)[1] = new uint8_t[16]; + memcpy((*IRKs)[1] , device2IRK,16); + memcpy((*BDAddrs)[1], device2Mac, 6); + + + return 1; + }); + // The LTK is the secret key which is used to encrypt bluetooth traffic + BLE.setGetLTK([](uint8_t* address, uint8_t* LTK){ + // address is input + Serial.print("Received request for address: "); + btct.printBytes(address,6); + + // Set these to the MAC and LTK of your devices after bonding. + uint8_t device1Mac[6] = {0x00, 0x00, 0x00, 0x00, 0x00, 0x00}; + uint8_t device1LTK[16] = {0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}; + uint8_t device2Mac[6] = {0x00, 0x00, 0x00, 0x00, 0x00, 0x00}; + uint8_t device2LTK[16] = {0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00, 0x00}; + + + if(memcmp(device1Mac, address, 6) == 0) { + memcpy(LTK, device1LTK, 16); + return 1; + }else if(memcmp(device2Mac, address, 6) == 0) { + memcpy(LTK, device2LTK, 16); + return 1; + } + return 0; + }); + BLE.setStoreIRK([](uint8_t* address, uint8_t* IRK){ + Serial.print(F("New device with MAC : ")); + btct.printBytes(address,6); + Serial.print(F("Need to store IRK : ")); + btct.printBytes(IRK,16); + return 1; + }); + BLE.setStoreLTK([](uint8_t* address, uint8_t* LTK){ + Serial.print(F("New device with MAC : ")); + btct.printBytes(address,6); + Serial.print(F("Need to store LTK : ")); + btct.printBytes(LTK,16); + return 1; + }); + + while(1){ + // begin initialization + if (!BLE.begin()) { + Serial.println("starting BLE failed!"); + delay(200); + continue; + } + Serial.println("BT init"); + delay(200); + + /* Set a local name for the BLE device + This name will appear in advertising packets + and can be used by remote devices to identify this BLE device + The name can be changed but maybe be truncated based on space left in advertisement packet + */ + + BLE.setDeviceName("Arduino"); + BLE.setLocalName("BatteryMonitor"); + + BLE.setAdvertisedService(batteryService); // add the service UUID + batteryService.addCharacteristic(batteryLevelChar); // add the battery level characteristic + batteryService.addCharacteristic(stringcharacteristic); + batteryService.addCharacteristic(secretValue); + + BLE.addService(batteryService); // Add the battery service + batteryLevelChar.writeValue(oldBatteryLevel); // set initial value for this characteristic + char* stringCharValue = new char[32]; + stringCharValue = "string"; + stringcharacteristic.writeValue(stringCharValue); + secretValue.writeValue(0); + + delay(1000); + + // prevent pairing until button is pressed (will show a pairing rejected message) + BLE.setPairable(false); + + /* Start advertising BLE. It will start continuously transmitting BLE + advertising packets and will be visible to remote BLE central devices + until it receives a new connection */ + + // start advertising + if(!BLE.advertise()){ + Serial.println("failed to advertise bluetooth."); + BLE.stopAdvertise(); + delay(500); + }else{ + Serial.println("advertising..."); + break; + } + BLE.end(); + delay(100); + } +} + + +void loop() { + // wait for a BLE central + BLEDevice central = BLE.central(); + + + // If button is pressed, allow pairing for 30 sec + if (!BLE.pairable() && digitalRead(PAIR_BUTTON) == LOW){ + pairingStarted = millis(); + BLE.setPairable(Pairable::ONCE); + Serial.println("Accepting pairing for 30 s"); + } else if (BLE.pairable() && millis() > pairingStarted + PAIR_INTERVAL){ + BLE.setPairable(false); + Serial.println("No longer accepting pairing"); + } + // Make LED blink while pairing is allowed + digitalWrite(PAIR_LED, (BLE.pairable() ? (millis()%400)<200 : BLE.paired()) ? PAIR_LED_ON : !PAIR_LED_ON); + + + // if a central is connected to the peripheral: + if (central && central.connected()) { + if (!wasConnected){ + wasConnected = true; + Serial.print("Connected to central: "); + // print the central's BT address: + Serial.println(central.address()); + } + + // check the battery level every 200ms + // while the central is connected: + long currentMillis = millis(); + // if 200ms have passed, check the battery level: + if (currentMillis - previousMillis >= 1000) { + previousMillis = currentMillis; + updateBatteryLevel(); + digitalWrite(CTRL_LED, secretValue.value()>0 ? HIGH : LOW); + } + } else if (wasConnected){ + wasConnected = false; + Serial.print("Disconnected from central: "); + Serial.println(central.address()); + } + +} + +void updateBatteryLevel() { + /* Read the current voltage level on the A0 analog input pin. + This is used here to simulate the charge level of a battery. + */ + int battery = analogRead(A0); + int batteryLevel = map(battery, 0, 1023, 0, 100); + + if (batteryLevel != oldBatteryLevel) { // if the battery level has changed + // Serial.print("Battery Level % is now: "); // print it + // Serial.println(batteryLevel); + batteryLevelChar.writeValue(batteryLevel); // and update the battery level characteristic + oldBatteryLevel = batteryLevel; // save the level for next comparison + } +} \ No newline at end of file diff --git a/examples/Peripheral/LED/LED.ino b/examples/Peripheral/LED/LED.ino index 1ede6535..65b88605 100644 --- a/examples/Peripheral/LED/LED.ino +++ b/examples/Peripheral/LED/LED.ino @@ -1,14 +1,14 @@ /* LED - This example creates a BLE peripheral with service that contains a + This example creates a Bluetooth® Low Energy peripheral with service that contains a 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. - You can use a generic BLE central app, like LightBlue (iOS and Android) or + 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 created in this sketch. @@ -17,9 +17,9 @@ #include -BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // BLE LED Service +BLEService ledService("19B10000-E8F2-537E-4F6C-D104768A1214"); // Bluetooth® Low Energy LED Service -// BLE LED Switch Characteristic - custom 128-bit UUID, read and writable by central +// Bluetooth® Low Energy LED Switch Characteristic - custom 128-bit UUID, read and writable by central BLEByteCharacteristic switchCharacteristic("19B10001-E8F2-537E-4F6C-D104768A1214", BLERead | BLEWrite); const int ledPin = LED_BUILTIN; // pin to use for the LED @@ -33,7 +33,7 @@ void setup() { // begin initialization if (!BLE.begin()) { - Serial.println("starting BLE failed!"); + Serial.println("starting Bluetooth® Low Energy module failed!"); while (1); } @@ -48,7 +48,7 @@ void setup() { // add service BLE.addService(ledService); - // set the initial value for the characeristic: + // set the initial value for the characteristic: switchCharacteristic.writeValue(0); // start advertising @@ -58,7 +58,7 @@ void setup() { } void loop() { - // listen for BLE peripherals to connect: + // listen for Bluetooth® Low Energy peripherals to connect: BLEDevice central = BLE.central(); // if a central is connected to peripheral: diff --git a/extras/test/.gitignore b/extras/test/.gitignore index c795b054..7e9215ee 100644 --- a/extras/test/.gitignore +++ b/extras/test/.gitignore @@ -1 +1,17 @@ -build \ No newline at end of file +build +### CMake ### +CMakeLists.txt.user +CMakeCache.txt +CMakeFiles +CMakeScripts +Testing +Makefile +cmake_install.cmake +install_manifest.txt +compile_commands.json +CTestTestfile.cmake +_deps + +### CMake Patch ### +# External projects +*-prefix/ \ No newline at end of file diff --git a/extras/test/CMakeLists.txt b/extras/test/CMakeLists.txt index bbba16ca..5e66e18b 100644 --- a/extras/test/CMakeLists.txt +++ b/extras/test/CMakeLists.txt @@ -1,12 +1,22 @@ ########################################################################## set(CMAKE_VERBOSE_MAKEFILE ON) -cmake_minimum_required(VERSION 2.8) +cmake_minimum_required(VERSION 3.5) ########################################################################## project(testArduinoBLE) +Include(FetchContent) + +FetchContent_Declare( + Catch2 + GIT_REPOSITORY https://github.com/catchorg/Catch2.git + GIT_TAG v3.4.0 +) + +FetchContent_MakeAvailable(Catch2) + ########################################################################## set(CMAKE_CXX_STANDARD 11) @@ -35,6 +45,9 @@ set(DUT_SRCS ../../src/utility/HCI.cpp ../../src/utility/GATT.cpp ../../src/utility/L2CAPSignaling.cpp + ../../src/utility/keyDistribution.cpp + ../../src/utility/bitDescriptions.cpp + ../../src/utility/btct.cpp ../../src/local/BLELocalAttribute.cpp ../../src/local/BLELocalCharacteristic.cpp ../../src/local/BLELocalDescriptor.cpp @@ -83,6 +96,18 @@ set(TEST_TARGET_ADVERTISING_DATA_SRCS src/test_advertising_data/FakeBLELocalDevice.cpp ) +set(TEST_TARGET_CHARACTERISTIC_SRCS + # Test files + ${COMMON_TEST_SRCS} + src/test_characteristic/test_permissions.cpp + src/test_characteristic/test_writeValue.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") @@ -93,6 +118,7 @@ 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}) +add_executable(TEST_TARGET_CHARACTERISTIC_DATA ${TEST_TARGET_CHARACTERISTIC_SRCS}) ########################################################################## @@ -102,15 +128,16 @@ 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_include_directories(TEST_TARGET_CHARACTERISTIC_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) +target_compile_definitions(TEST_TARGET_CHARACTERISTIC_DATA PUBLIC FAKE_BLELOCALDEVICE) ########################################################################## @@ -124,3 +151,14 @@ add_custom_command(TARGET TEST_TARGET_DISC_DEVICE POST_BUILD add_custom_command(TARGET TEST_TARGET_ADVERTISING_DATA POST_BUILD COMMAND ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/TEST_TARGET_ADVERTISING_DATA ) + +add_custom_command(TARGET TEST_TARGET_CHARACTERISTIC_DATA POST_BUILD + COMMAND ${CMAKE_RUNTIME_OUTPUT_DIRECTORY}/TEST_TARGET_CHARACTERISTIC_DATA +) + +########################################################################## + +target_link_libraries( TEST_TARGET_UUID Catch2WithMain ) +target_link_libraries( TEST_TARGET_DISC_DEVICE Catch2WithMain ) +target_link_libraries( TEST_TARGET_ADVERTISING_DATA Catch2WithMain ) +target_link_libraries( TEST_TARGET_CHARACTERISTIC_DATA Catch2WithMain ) 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