Received-SPF: pass (google.com: domain of linux-bluetooth-owner@vger.kernel.org designates 23.128.96.18 as permitted sender) client-ip=23.128.96.18;
Sender: "danielwinkler via sendgmr" 
        <danielwinkler@danielwinkler-linux.mtv.corp.google.com>
Date:   Fri, 16 Oct 2020 16:34:08 -0700
Message-Id: <20201016163331.Bluez.v2.1.Ida2ffbf34e18b5a810dffd2abd2bb9e431df3ae4@changeid>
Mime-Version: 1.0
Subject: [Bluez PATCH v2] doc/advertising-api: Enable new data types in adv
 data / scan response
From:   Daniel Winkler <danielwinkler@google.com>
To:     luiz.von.dentz@intel.com
Cc:     chromeos-bluetooth-upstreaming@chromium.org,
        linux-bluetooth@vger.kernel.org,
        Daniel Winkler <danielwinkler@google.com>,
        Miao-chen Chou <mcchou@chromium.org>
Content-Type: text/plain; charset="UTF-8"
Precedence: bulk

This change allows the advertising client to specify advertising data
and scan response for any AD section types that would otherwise be
settable via the other LEAdvertisement1 properties.

Reviewed-by: Miao-chen Chou <mcchou@chromium.org>

---
Hello Maintainers,

We have a new advertising use case in which the client must be able to
specify some data fields, specifically Service UUIDs in the scan
response payload. With the current API, this is not possible, and in
addition the Data property limits the client to only setting 3
advertising section types.

This change proposes that we enable the setting of scan response, and
for both data/scan response enable the AD section types that are
already settable via the other advertisement properties. This should
minimize security concerns as it is not enabling any new advertising
types, while greatly improving client flexibility in defining their
advertising data and scan response contents.

Thank you in advance for your feedback.

Warm regards,
Daniel Winkler


Changes in v2:
- Shortened patch title to be <=72 chars

 doc/advertising-api.txt | 69 +++++++++++++++++++++++++++++++++++++----
 1 file changed, 63 insertions(+), 6 deletions(-)

diff --git a/doc/advertising-api.txt b/doc/advertising-api.txt
index b0565eab2..f60b22de6 100644
--- a/doc/advertising-api.txt
+++ b/doc/advertising-api.txt
@@ -63,12 +63,46 @@ Properties	string Type
 
 		dict Data [Experimental]
 
-			Advertising Type to include in the Advertising
-			Data. Key is the advertising type and value is the
-			data as byte array.
-
-			Note: Types already handled by other properties shall
-			not be used.
+			Data to be added into the Advertising Data payload.
+			Key is the advertising type and value is the data
+			as byte array.
+
+			"type" values supported:
+				0x02  Incomplete List of 16-bit Service UUIDs
+				0x03  Complete List of 16-bit Service UUIDs
+				0x04  Incomplete List of 32-bit Service UUIDs
+				0x05  Complete List of 32-bit Service UUIDs
+				0x06  Incomplete List of 128-bit Service UUIDs
+				0x07  Complete List of 128-bit Service UUIDs
+				0x08  Shortened Local Name
+				0x09  Complete Local Name
+				0x14  List of 16 bit Service Solicitation UUIDs
+				0x15  List of 128 bit Service Solicitation UUIDs
+				0x16  Service Data - 16 bit UUID
+				0x19  Appearance
+				0x1f  List of 32 bit Service Solicitation UUIDs
+				0x20  Service Data - 32 bit UUID
+				0x21  Service Data - 128 bit UUID
+				0x24  URI
+				0x25  Indoor Positioning
+				0x26  Transport Discovery Data
+				0xff  Manufacturer Specific Data
+
+			To ensure advertising contents maintain compliance to
+			the bluetooth specification, the provided type/data
+			sections will undergo the following validation:
+
+			- Repeated tag sections provided by Data property and
+			the other properties above will be merged together, if
+			possible.
+
+			- Misuse of Service UUID types, i.e. repeated UUID_ALL
+			sections, will result in a failed registration.
+
+			- The Appearance and Name section types may appear in
+			the Advertising data and Scan Response once in total.
+			Any redundant definitions of these tags will be
+			removed.
 
 			Possible values:
 				<type> <byte array>
@@ -78,6 +112,29 @@ Properties	string Type
 				<Transport Discovery> <Organization Flags...>
 				0x26                   0x01         0x01...
 
+		dict ScanResponseData
+
+			Data to be added into the Scan Response payload.
+			Key is the advertising type and value is the data
+			as byte array.
+
+			Note: By default, if the LocalName property is defined
+			or "local-name" is populated in the Include property,
+			the local name will be placed in the Scan Response
+			payload by default and merged with data provided in
+			ScanResponseData.
+
+			For allowed "type" values and their validation, see
+			"Data" property above.
+
+			Possible values:
+				<type> <byte array>
+				...
+
+			Example:
+				<Service Data UUID16> <HeartRate UUID  Data>
+				0x16                   0x0D 0x18       0x01...
+
 		bool Discoverable [Experimental]
 
 			Advertise as general discoverable. When present this
-- 
2.29.0.rc1.297.gfa9743e501-goog