diff --git a/doc/releases/migration-guide-3.7.rst b/doc/releases/migration-guide-3.7.rst index 5d95189f690..10ab8d4a511 100644 --- a/doc/releases/migration-guide-3.7.rst +++ b/doc/releases/migration-guide-3.7.rst @@ -208,6 +208,20 @@ Bluetooth Classic Removed the :kconfig:option:`CONFIG_BT_BREDR`. It is replaced by new option :kconfig:option:`CONFIG_BT_CLASSIC`. (:github:`69651`) +Bluetooth Host +============== + +* The advertiser options :code:`BT_LE_ADV_OPT_USE_NAME` and :code:`BT_LE_ADV_OPT_FORCE_NAME_IN_AD` + are deprecated in this release. The application need to include the device name explicitly. One + way to do it is by adding the following to the advertising data or scan response data passed to + the host: + + .. code-block:: c + + BT_DATA(BT_DATA_NAME_COMPLETE, CONFIG_BT_DEVICE_NAME, sizeof(CONFIG_BT_DEVICE_NAME) - 1) + + (:github:`71686`) + Networking ********** diff --git a/doc/releases/release-notes-3.7.rst b/doc/releases/release-notes-3.7.rst index 99adbae07e2..5529504fd7e 100644 --- a/doc/releases/release-notes-3.7.rst +++ b/doc/releases/release-notes-3.7.rst @@ -28,6 +28,27 @@ https://docs.zephyrproject.org/latest/security/vulnerabilities.html * CVE-2024-3077 `Zephyr project bug tracker GHSA-gmfv-4vfh-2mh8 `_ +API Changes +*********** + +Deprecated in this release +========================== + + * Bluetooth advertiser options :code:`BT_LE_ADV_OPT_USE_NAME` and + :code:`BT_LE_ADV_OPT_FORCE_NAME_IN_AD` are now deprecated. That means the following macro are + deprecated: + + * :c:macro:`BT_LE_ADV_CONN_NAME` + * :c:macro:`BT_LE_ADV_CONN_NAME_AD` + * :c:macro:`BT_LE_ADV_NCONN_NAME` + * :c:macro:`BT_LE_EXT_ADV_CONN_NAME` + * :c:macro:`BT_LE_EXT_ADV_SCAN_NAME` + * :c:macro:`BT_LE_EXT_ADV_NCONN_NAME` + * :c:macro:`BT_LE_EXT_ADV_CODED_NCONN_NAME` + + Application developer will now need to set the advertised name themselves by updating the advertising data + or the scan response data. + Architectures ************* diff --git a/include/zephyr/bluetooth/bluetooth.h b/include/zephyr/bluetooth/bluetooth.h index cc99de26706..d1621e86bdd 100644 --- a/include/zephyr/bluetooth/bluetooth.h +++ b/include/zephyr/bluetooth/bluetooth.h @@ -549,25 +549,29 @@ enum { */ BT_LE_ADV_OPT_USE_IDENTITY = BIT(2), - /** Advertise using GAP device name. + /** + * @deprecated This option will be removed in the near future, see + * https://github.com/zephyrproject-rtos/zephyr/issues/71686 * - * Include the GAP device name automatically when advertising. - * By default the GAP device name is put at the end of the scan - * response data. - * When advertising using @ref BT_LE_ADV_OPT_EXT_ADV and not - * @ref BT_LE_ADV_OPT_SCANNABLE then it will be put at the end of the - * advertising data. - * If the GAP device name does not fit into advertising data it will be - * converted to a shortened name if possible. - * @ref BT_LE_ADV_OPT_FORCE_NAME_IN_AD can be used to force the device - * name to appear in the advertising data of an advert with scan - * response data. + * @brief Advertise using GAP device name. * - * The application can set the device name itself by including the - * following in the advertising data. - * @code - * BT_DATA(BT_DATA_NAME_COMPLETE, name, sizeof(name) - 1) - * @endcode + * Include the GAP device name automatically when advertising. + * By default the GAP device name is put at the end of the scan + * response data. + * When advertising using @ref BT_LE_ADV_OPT_EXT_ADV and not + * @ref BT_LE_ADV_OPT_SCANNABLE then it will be put at the end of the + * advertising data. + * If the GAP device name does not fit into advertising data it will be + * converted to a shortened name if possible. + * @ref BT_LE_ADV_OPT_FORCE_NAME_IN_AD can be used to force the device + * name to appear in the advertising data of an advert with scan + * response data. + * + * The application can set the device name itself by including the + * following in the advertising data. + * @code + * BT_DATA(BT_DATA_NAME_COMPLETE, name, sizeof(name) - 1) + * @endcode */ BT_LE_ADV_OPT_USE_NAME = BIT(3), @@ -691,10 +695,13 @@ enum { BT_LE_ADV_OPT_DISABLE_CHAN_39 = BIT(17), /** + * @deprecated This option will be removed in the near future, see + * https://github.com/zephyrproject-rtos/zephyr/issues/71686 + * * @brief Put GAP device name into advert data * - * Will place the GAP device name into the advertising data rather - * than the scan response data. + * Will place the GAP device name into the advertising data rather than + * the scan response data. * * @note Requires @ref BT_LE_ADV_OPT_USE_NAME */ @@ -905,16 +912,26 @@ struct bt_le_per_adv_param { BT_GAP_ADV_FAST_INT_MIN_2, \ BT_GAP_ADV_FAST_INT_MAX_2, NULL) +/** + * @deprecated This macro will be removed in the near future, see + * https://github.com/zephyrproject-rtos/zephyr/issues/71686 + */ #define BT_LE_ADV_CONN_NAME BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE | \ BT_LE_ADV_OPT_USE_NAME, \ BT_GAP_ADV_FAST_INT_MIN_2, \ - BT_GAP_ADV_FAST_INT_MAX_2, NULL) + BT_GAP_ADV_FAST_INT_MAX_2, NULL) \ + __DEPRECATED_MACRO +/** + * @deprecated This macro will be removed in the near future, see + * https://github.com/zephyrproject-rtos/zephyr/issues/71686 + */ #define BT_LE_ADV_CONN_NAME_AD BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE | \ BT_LE_ADV_OPT_USE_NAME | \ BT_LE_ADV_OPT_FORCE_NAME_IN_AD, \ BT_GAP_ADV_FAST_INT_MIN_2, \ - BT_GAP_ADV_FAST_INT_MAX_2, NULL) + BT_GAP_ADV_FAST_INT_MAX_2, NULL) \ + __DEPRECATED_MACRO #define BT_LE_ADV_CONN_DIR_LOW_DUTY(_peer) \ BT_LE_ADV_PARAM(BT_LE_ADV_OPT_CONNECTABLE | BT_LE_ADV_OPT_ONE_TIME | \ @@ -926,10 +943,16 @@ struct bt_le_per_adv_param { #define BT_LE_ADV_NCONN BT_LE_ADV_PARAM(0, BT_GAP_ADV_FAST_INT_MIN_2, \ BT_GAP_ADV_FAST_INT_MAX_2, NULL) -/** Non-connectable advertising with @ref BT_LE_ADV_OPT_USE_NAME */ +/** + * @deprecated This macro will be removed in the near future, see + * https://github.com/zephyrproject-rtos/zephyr/issues/71686 + * + * Non-connectable advertising with @ref BT_LE_ADV_OPT_USE_NAME + */ #define BT_LE_ADV_NCONN_NAME BT_LE_ADV_PARAM(BT_LE_ADV_OPT_USE_NAME, \ BT_GAP_ADV_FAST_INT_MIN_2, \ - BT_GAP_ADV_FAST_INT_MAX_2, NULL) + BT_GAP_ADV_FAST_INT_MAX_2, NULL) \ + __DEPRECATED_MACRO /** Non-connectable advertising with @ref BT_LE_ADV_OPT_USE_IDENTITY */ #define BT_LE_ADV_NCONN_IDENTITY BT_LE_ADV_PARAM(BT_LE_ADV_OPT_USE_IDENTITY, \ @@ -944,13 +967,19 @@ struct bt_le_per_adv_param { BT_GAP_ADV_FAST_INT_MAX_2, \ NULL) -/** Connectable extended advertising with @ref BT_LE_ADV_OPT_USE_NAME */ +/** + * @deprecated This macro will be removed in the near future, see + * https://github.com/zephyrproject-rtos/zephyr/issues/71686 + * + * Connectable extended advertising with @ref BT_LE_ADV_OPT_USE_NAME + */ #define BT_LE_EXT_ADV_CONN_NAME BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | \ BT_LE_ADV_OPT_CONNECTABLE | \ BT_LE_ADV_OPT_USE_NAME, \ BT_GAP_ADV_FAST_INT_MIN_2, \ BT_GAP_ADV_FAST_INT_MAX_2, \ - NULL) + NULL) \ + __DEPRECATED_MACRO /** Scannable extended advertising */ #define BT_LE_EXT_ADV_SCAN BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | \ @@ -959,25 +988,37 @@ struct bt_le_per_adv_param { BT_GAP_ADV_FAST_INT_MAX_2, \ NULL) -/** Scannable extended advertising with @ref BT_LE_ADV_OPT_USE_NAME */ +/** + * @deprecated This macro will be removed in the near future, see + * https://github.com/zephyrproject-rtos/zephyr/issues/71686 + * + * Scannable extended advertising with @ref BT_LE_ADV_OPT_USE_NAME + */ #define BT_LE_EXT_ADV_SCAN_NAME BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | \ BT_LE_ADV_OPT_SCANNABLE | \ BT_LE_ADV_OPT_USE_NAME, \ BT_GAP_ADV_FAST_INT_MIN_2, \ BT_GAP_ADV_FAST_INT_MAX_2, \ - NULL) + NULL) \ + __DEPRECATED_MACRO /** Non-connectable extended advertising with private address */ #define BT_LE_EXT_ADV_NCONN BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV, \ BT_GAP_ADV_FAST_INT_MIN_2, \ BT_GAP_ADV_FAST_INT_MAX_2, NULL) -/** Non-connectable extended advertising with @ref BT_LE_ADV_OPT_USE_NAME */ +/** + * @deprecated This macro will be removed in the near future, see + * https://github.com/zephyrproject-rtos/zephyr/issues/71686 + * + * Non-connectable extended advertising with @ref BT_LE_ADV_OPT_USE_NAME + */ #define BT_LE_EXT_ADV_NCONN_NAME BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | \ BT_LE_ADV_OPT_USE_NAME, \ BT_GAP_ADV_FAST_INT_MIN_2, \ BT_GAP_ADV_FAST_INT_MAX_2, \ - NULL) + NULL) \ + __DEPRECATED_MACRO /** Non-connectable extended advertising with @ref BT_LE_ADV_OPT_USE_IDENTITY */ #define BT_LE_EXT_ADV_NCONN_IDENTITY \ @@ -993,14 +1034,19 @@ struct bt_le_per_adv_param { BT_GAP_ADV_FAST_INT_MAX_2, \ NULL) -/** Non-connectable extended advertising on coded PHY with - * @ref BT_LE_ADV_OPT_USE_NAME +/** + * @deprecated This macro will be removed in the near future, see + * https://github.com/zephyrproject-rtos/zephyr/issues/71686 + * + * Non-connectable extended advertising on coded PHY with + * @ref BT_LE_ADV_OPT_USE_NAME */ #define BT_LE_EXT_ADV_CODED_NCONN_NAME \ BT_LE_ADV_PARAM(BT_LE_ADV_OPT_EXT_ADV | BT_LE_ADV_OPT_CODED | \ BT_LE_ADV_OPT_USE_NAME, \ BT_GAP_ADV_FAST_INT_MIN_2, \ - BT_GAP_ADV_FAST_INT_MAX_2, NULL) + BT_GAP_ADV_FAST_INT_MAX_2, NULL) \ + __DEPRECATED_MACRO /** Non-connectable extended advertising on coded PHY with * @ref BT_LE_ADV_OPT_USE_IDENTITY