Doc/optimize doc for ble (IDFGH-13260) #14193
Conversation
|
|
👋 Hello esp-zbw, we appreciate your contribution to this project! 📘 Please review the project's Contributions Guide for key guidelines on code, documentation, testing, and more. 🖊️ Please also make sure you have read and signed the Contributor License Agreement for this project. Click to see more instructions ...
Review and merge process you can expect ...
|
github-actions
bot
changed the title
esp-zbw
force-pushed
the
doc/optimize_doc_for_ble
branch
from
2e5a094
to
d9ef999
Compare
| BTC_GAP_BLE_ACT_CONFIG_LOCAL_PRIVACY, //Bluetooth GAP action type for configuring local privacy. | ||
| BTC_GAP_BLE_ACT_CONFIG_LOCAL_ICON, //Bluetooth GAP action type for configuring local icon. | ||
| BTC_GAP_BLE_ACT_UPDATE_WHITE_LIST, //Bluetooth GAP action type for updating white list. | ||
| BTC_GAP_BLE_ACT_CLEAR_WHITE_LIST, // Bluetooth GAP action type for clearing white list. |
| #endif //#if (BLE_FEAT_PERIODIC_ADV_SYNC_TRANSFER == TRUE) | ||
| BTC_GAP_BLE_PERIODIC_ADV_RECV_ENABLE, //Bluetooth GAP action type for enabling periodic advertising receive. | ||
| BTC_GAP_BLE_PERIODIC_ADV_SYNC_TRANS, //Bluetooth GAP action type for periodic advertising synchronization transfer. | ||
| BTC_GAP_BLE_PERIODIC_ADV_SET_INFO_TRANS,// Bluetooth GAP action type for periodic advertising set information transfer. |
| esp_bd_addr_t remote_device; | ||
| uint16_t tx_data_length; | ||
| esp_bd_addr_t remote_device; //Remote device address | ||
| uint16_t tx_data_length; //Transmit data length,For BLE 4.x without Data Length Extension (DLE) support, common default maximum value is 27 bytes (if no negotiated MTU extension). |
There was a problem hiding this comment.
这里描述不正确
see: BLUETOOTH SPECIFICATION Version 4.2 [Vol 2, Part E] page 1021
| @@ -199,7 +247,8 @@ typedef union { | |||
| uint8_t *raw_scan_rsp; | |||
| uint32_t raw_scan_rsp_len; | |||
| } cfg_scan_rsp_data_raw; | |||
| #endif // #if (BLE_42_FEATURE_SUPPORT == TRUE) | |||
| #endif | |||
There was a problem hiding this comment.
#endif // #if (BLE_42_FEATURE_SUPPORT == TRUE)
There was a problem hiding this comment.
@esp-zbw Thanks for your hardworking on reviewing. I have left comments. Some of them are applied to the whole document. Also, I would suggest building the docs locally to preview the document.
| # Bluedroid host Examples for BLE_50 | ||
|
|
||
| Note: To use examples in this directory, you need to have BLE enabled in configuration and Bluedroid selected as the host stack. | ||
|
|
There was a problem hiding this comment.
BLE 5.0 features have to be enabled, right? If I remember correctly, there is one option in memuconfig to enable ble 5.0 features. please double-check.
| # Bluedroid host Examples for BLE | ||
|
|
||
| Note: To use examples in this directory, you need to have BLE enabled in configuration and Bluedroid selected as the host stack. | ||
|
|
There was a problem hiding this comment.
I would suggest mentioning how to enable BLE and select Bluedroid host. Maybe list the parameters in menuconfig
| # Example Layout | ||
|
|
||
| The examples are grouped into subdirectories by category. Each category directory contains one or more example projects: | ||
| * `ble_ancs` Demonstrates how to use the ESP-IDF BLE ANCS (Apple Notification Center Service) on ESP32 series chips to access notifications generated on iOS devices via a Bluetooth low-energy link, and includes instructions for setting the correct chip target, authorizing access to ANCS characteristics, and building, flashing, and monitoring the project. See the [ble_ancs](./ble_ancs/README.md) about example. |
There was a problem hiding this comment.
See the README for more details about this example
| * `ble_ancs` Demonstrates how to use the ESP-IDF BLE ANCS (Apple Notification Center Service) on ESP32 series chips to access notifications generated on iOS devices via a Bluetooth low-energy link, and includes instructions for setting the correct chip target, authorizing access to ANCS characteristics, and building, flashing, and monitoring the project. See the [ble_ancs](./ble_ancs/README.md) about example. | ||
| * `ble_compatibility_test` Demonstrates how to use the ESP32 series chips to perform Eddystone-compatible BLE scanning of eddystone frames, including UID and URL, aimed at improving proximity-based experiences on both Android and iOS platforms. See the [ble_compatibility_test](./ble_compatibility_test/README.md) about example. | ||
| * `ble_eddystone` Demonstrates how to use the ESP32 series chips to perform Eddystone-compatible BLE scanning of eddystone frames, including UID and URL, aimed at improving proximity-based experiences on both Android and iOS platforms. See the [ble_eddystone](./ble_eddystone/README.md) about example. | ||
| * `ble_hid_device_demo` Demonstrates how to implement a BLE HID device profile with four different reports (Mouse, Keyboard and LED, Consumer Devices, Vendor devices) on ESP32 series chips, allowing users to set the correct chip target and configure the project according to their application scenarios. See the [ble_hid_device_demo](./ble_hid_device_demo/README.md) about example. |
There was a problem hiding this comment.
with four different reports? is this word used correctly?
| # Example Layout | ||
|
|
||
| The examples are grouped into subdirectories by category. Each category directory contains one or more example projects: | ||
| * `ble_ancs` Demonstrates how to use the ESP-IDF BLE ANCS (Apple Notification Center Service) on ESP32 series chips to access notifications generated on iOS devices via a Bluetooth low-energy link, and includes instructions for setting the correct chip target, authorizing access to ANCS characteristics, and building, flashing, and monitoring the project. See the [ble_ancs](./ble_ancs/README.md) about example. |
There was a problem hiding this comment.
I would suggest not mentioning ESP32 series chips in this readme. It may be confusing that these examples could be supported on ESP32 chips only.
|
|
||
| /** | ||
| * @brief BLE SRK keys | ||
| * @brief bluetooth low energy signature resolving keys |
There was a problem hiding this comment.
Signature Resolving Key (SRK)
There was a problem hiding this comment.
Please check the term in the spec. Some of them are capitalized. Include the abbreviation.
| uint32_t counter; /*!< The counter value. */ | ||
| uint16_t div; /*!< The diversifier value. */ | ||
| uint8_t sec_level; /*!< The security level of the security link. */ | ||
| esp_bt_octet16_t csrk; /*!< The connection signature resolving key value. */ |
There was a problem hiding this comment.
Connection Signature Resolving Key (CSRK)
|
|
||
|
|
||
| /** | ||
| * @brief union type of the security key value | ||
| * the union to the bluetooth low energy key value type |
There was a problem hiding this comment.
? I am not able to understand this explanation
|
|
||
| /** | ||
| * @brief structure type of the ble local oob data value | ||
| * @brief structure type of the bluetooth low energy local oob data value |
| /** | ||
| * @brief union associated with ble security | ||
| esp_bd_addr_t bd_addr; /*!< Basic rate address peer device. */ | ||
| bool key_present; /*!< Valid link key value in key element */ |
There was a problem hiding this comment.
For the boolean type, please indicate which behavior corresponds to true and which corresponds to false.
For example:
True if xxxxx; false otherwise
esp-zbw
force-pushed
the
doc/optimize_doc_for_ble
branch
2 times, most recently
from
cdaa7e5
to
1fbb50d
Compare
esp-zbw
force-pushed
the
doc/optimize_doc_for_ble
branch
3 times, most recently
from
ef57320
to
7e7d245
Compare
esp-zbw
force-pushed
the
doc/optimize_doc_for_ble
branch
from
7e7d245
to
37fcaae
Compare
esp-zbw
force-pushed
the
doc/optimize_doc_for_ble
branch
from
3ef5bf5
to
9615add
Compare
esp-zbw
force-pushed
the
doc/optimize_doc_for_ble
branch
3 times, most recently
from
fe8e31c
to
1e9465e
Compare
esp-zbw
force-pushed
the
doc/optimize_doc_for_ble
branch
6 times, most recently
from
3660b2c
to
1ad1d7b
Compare
esp-zbw
force-pushed
the
doc/optimize_doc_for_ble
branch
from
1ad1d7b
to
76fe8de
Compare
esp-zbw
force-pushed
the
doc/optimize_doc_for_ble
branch
from
76fe8de
to
41643ad
Compare
Add summary list of examples on ble and ble_50
Modified api about ble_gap: esp_gap_ble_api.h, btc_gap_ble.h