From db9a189fcb619011f632346b9d6b2d3bc23e2f67 Mon Sep 17 00:00:00 2001 From: Mark Leavitt Date: Fri, 19 Feb 2021 18:10:41 -0800 Subject: [PATCH 1/3] Added paragraph describing BLE.setScanCoded() API, with brief explanation of BLE Coded Phy. --- src/content/reference/device-os/firmware.md | 11 +++++++++++ 1 file changed, 11 insertions(+) diff --git a/src/content/reference/device-os/firmware.md b/src/content/reference/device-os/firmware.md index ff8df9c1f2..ced8a3f286 100644 --- a/src/content/reference/device-os/firmware.md +++ b/src/content/reference/device-os/firmware.md @@ -8403,6 +8403,17 @@ int setScanParameters(const BleScanParams* params) const; See [`BleScanParams`](/reference/device-os/firmware/#blescanparams) for more information. +#### BLE.setScanCoded() + +Sets the physical layer used in scanning. If called with the argument "true", scanning will respond only to advertisements in Coded Phy, 125 MBPS format. If called with the argument "false", scanning will respond only to advertisements in the standard 1 MBPS format. (Note that these are mutually exclusive.) + +Coded Phy is a new feature in BLE 5 that employs redundancy and error-correction, trading off speed in favor of noise immunity. In theory it could double the range achievable, but in practice you may expect closer to a 50% increase in range. + +```cpp +// PROTOTYPE +int setScanCoded(bool use_coded) const; +``` + #### BLE.connect() In a central device the logic typically involves: From 66aaecbbb69c246697c8cf7294055bbbab97df30 Mon Sep 17 00:00:00 2001 From: Mark Leavitt Date: Fri, 19 Feb 2021 18:25:42 -0800 Subject: [PATCH 2/3] Rewrote for better consistency and clarity. --- src/content/reference/device-os/firmware.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/src/content/reference/device-os/firmware.md b/src/content/reference/device-os/firmware.md index ced8a3f286..75a9433dc2 100644 --- a/src/content/reference/device-os/firmware.md +++ b/src/content/reference/device-os/firmware.md @@ -8405,9 +8405,9 @@ See [`BleScanParams`](/reference/device-os/firmware/#blescanparams) for more inf #### BLE.setScanCoded() -Sets the physical layer used in scanning. If called with the argument "true", scanning will respond only to advertisements in Coded Phy, 125 MBPS format. If called with the argument "false", scanning will respond only to advertisements in the standard 1 MBPS format. (Note that these are mutually exclusive.) +Controls coding in the physical layer used during scanning. If called with the argument "true", scanning will respond only to advertisements in PHY_CODED format. If called with the argument "false", scanning will respond only to advertisements in the standard PHY_1MBPS format. Note that these are mutually exclusive; advertisements in the unselected format will not be detected. Before the API is called, the default mode is standard PHY_1MBPS format. -Coded Phy is a new feature in BLE 5 that employs redundancy and error-correction, trading off speed in favor of noise immunity. In theory it could double the range achievable, but in practice you may expect closer to a 50% increase in range. +PHY_CODED is a new feature in BLE 5 that employs redundancy and error-correction, trading off speed in favor of noise immunity. In theory it could double the range achievable, but in practice you may expect closer to a 50% increase in range. ```cpp // PROTOTYPE From 8079082d01bfc98b40bcd1f213efcc31c35e4638 Mon Sep 17 00:00:00 2001 From: Mark Leavitt Date: Thu, 4 Mar 2021 05:51:37 -0800 Subject: [PATCH 3/3] Update documentation to support advertising and scanning in coded phy. --- src/content/reference/device-os/firmware.md | 17 +++++------------ 1 file changed, 5 insertions(+), 12 deletions(-) diff --git a/src/content/reference/device-os/firmware.md b/src/content/reference/device-os/firmware.md index 75a9433dc2..7c5e8cff3f 100644 --- a/src/content/reference/device-os/firmware.md +++ b/src/content/reference/device-os/firmware.md @@ -8394,7 +8394,7 @@ See [`BleScanParams`](/reference/device-os/firmware/#blescanparams) for more inf #### BLE.setScanParameters() -Sets the parameters used for scanning. Typically you will only ever need to change the scan timeout, but if you need finer control you can use this function. +Sets the parameters used for scanning. Typically you will only ever need to change the scan timeout, but if you need finer control you can use this function. Also used to set up scanning for devices advertising in BLE 5 Coded Phy mode. ```cpp // PROTOTYPE @@ -8403,17 +8403,6 @@ int setScanParameters(const BleScanParams* params) const; See [`BleScanParams`](/reference/device-os/firmware/#blescanparams) for more information. -#### BLE.setScanCoded() - -Controls coding in the physical layer used during scanning. If called with the argument "true", scanning will respond only to advertisements in PHY_CODED format. If called with the argument "false", scanning will respond only to advertisements in the standard PHY_1MBPS format. Note that these are mutually exclusive; advertisements in the unselected format will not be detected. Before the API is called, the default mode is standard PHY_1MBPS format. - -PHY_CODED is a new feature in BLE 5 that employs redundancy and error-correction, trading off speed in favor of noise immunity. In theory it could double the range achievable, but in practice you may expect closer to a 50% increase in range. - -```cpp -// PROTOTYPE -int setScanCoded(bool use_coded) const; -``` - #### BLE.connect() In a central device the logic typically involves: @@ -9673,6 +9662,7 @@ uint16_t timeout; hal_ble_adv_evt_type_t type; uint8_t filter_policy; uint8_t inc_tx_power; +uint8_t primary_phy; uint8_t reserved; // EXAMPLE @@ -9688,6 +9678,7 @@ int res = BLE.getAdvertisingParameters(¶m); - `timeout` Advertising timeout in 10 ms units. Default is 0. - `type` See [`BleAdvertisingEventType`](/reference/device-os/firmware/#bleadvertisingeventtype). Default is `CONNECTABLE_SCANNABLE_UNDIRECTED` (0). - `filter_policy` Default is 0. +- `primary_phy` Default is BLE_PHY_1MBPS (standard). Set to BLE_PHY_CODED for BLE 5 Coded Phy (long range). - `inc_tx_power` Default is 0. ### BleScanParams @@ -9702,6 +9693,7 @@ uint16_t interval; uint16_t window; uint16_t timeout; uint8_t active; uint8_t filter_policy; +uint8_t scan_phys; // EXAMPLE BleScanParams scanParams; @@ -9717,6 +9709,7 @@ int res = BLE.getScanParameters(&scanParams); - `timeout` Scan timeout in 10 ms units. Default value is 500. - `active` Boolean value, typically 1. - `filter_policy` Default is 0. +- `scan_phys` Default is BLE_PHYS_1MBPS. Use BLE_PHYS_CODED to scan for Coded Phy, or (BLE_PHYS_1MBPS | BLE_PHYS_CODED) to scan for both. ### iBeacon