BLE: Add ATT_MTU and Data Length docs #937

paul-szczepanek-arm · 2019-02-04T11:50:56Z

No description provided.

pan- · 2019-02-04T13:58:08Z

Corresponding PR in mbed-os: ARMmbed/mbed-os#9537 .

docs/api/bluetooth/Gap.md

docs/api/bluetooth/GattClient.md

pan- · 2019-02-04T14:12:30Z

docs/api/bluetooth/GattClient.md

@@ -16,6 +16,14 @@ As a result of the discovery process, the client can start interacting with the

 Mbed BLE abstracts read and write operations to offer a single API that can be used to read or write characteristic values. The application code does not have to handle the necessary fragmentation or reassembly process if the attribute value to be transported can't fit in a single data packet.

+#### ATT_MTU
+
+ATT_MTU is the maximum size of the attribute that can fit in an L2CAP packet. This is independent of the Data Length which controls the over-the-air packet payload size (which is dealt with in the GAP). An L2CAP packet will be fragmented over many such packets if required.


I think we can improve the first sentence. What do you think of:
The GATT Maximum Transmission Unit (MTU) is the maximum size of a GATT packet exchanged between a client and a server. Then mention L2CAP as a protocol that allows segmentation and reassembly, ...

pan- · 2019-02-04T14:13:28Z

docs/api/bluetooth/GattClient.md

+
+ATT_MTU is the maximum size of the attribute that can fit in an L2CAP packet. This is independent of the Data Length which controls the over-the-air packet payload size (which is dealt with in the GAP). An L2CAP packet will be fragmented over many such packets if required.
+
+Only `GattClient` can trigger the exchange of ATT_MTU between client and server. The host may trigger the exchange which may also be requested manually using `negotiateAttMtu`. If an exchange happens the biggest value possible across both devices will be used. Negotiation is only a best effort process and does not guarantee a higher value being set. 


It would be interesting to detail the negotiation behaviour and clarify the term host.

docs/api/bluetooth/GattServer.md

paul-szczepanek-arm · 2019-02-04T15:39:58Z

thanks for the comments, hopefully I have integrated them to your satisfaction

pan-

Thanks for the change. It looks good.

Rearrange content for flow, and edit mostly for precise language and international spelling.

paul-szczepanek-arm · 2019-02-05T16:11:36Z

docs/api/bluetooth/Gap.md


-In addition to modulation schemes, MTU (Maximum Transmission Unit) size also strongly affects throughput. Newer controllers will allow you to negotiate bigger MTUs. Since each packet contains overhead bigger packets maximise throughput.
+In addition to modulation schemes, Maximum Transmission Unit (MTU) size also strongly affects throughput. Newer controllers allow you to negotiate bigger MTUs. Because each packet contains overhead, bigger packets maximize throughput.


Why is Because superior to Since in this case? Maybe I can try to choose the right one in the future.

Great question. "Since" shows time passed (for example, "We've been open since 1952"). "Because" shows cause and effect.

Not trying to open a debate here (you know better than us @AnotherButler) but there is other usages of since (see https://dictionary.cambridge.org/us/grammar/british-grammar/as-because-or-since). Should we avoid these forms in our documentation ?

Please do. We try to be consistent in our documentation, and our internal style guide states "Because implies causality; since implies the passing of time. Examples: The program ran because I did it right. Arm has been in business since the 1990s." and "But also note that using "as" when you mean "because" can confuse non-native speakers, so it's best to avoid it." Please don't hesitate to look up words in our style guide if you ever have questions. We can add to it if anything's missing.

We're also happy to answer questions like this one :)

docs/api/bluetooth/Gap.md

Make minor edits, mostly for active voice.

Edit file, mostly for active voice.

AnotherButler · 2019-02-05T21:23:10Z

docs/api/bluetooth/GattServer.md

@@ -14,6 +16,16 @@ You must access values of the characteristic and the characteristic descriptor p

 You can query the server by invoking the function `areUpdatesEnabled()` to find out if a client has subscribed to a given characteristic's value update.

+#### Attribute Protocol Maximum Transmission Unit (ATT_MTU)


Because this section is an exact duplicate, can we instead replace it with a link to the relevant section in GattClient.md?

OK. The client version is the fuller one as this one shortens the paragraph about what the client does. How do I link?

The link to GattClient is "../apis/gattclient.html"

paul-szczepanek-arm · 2019-02-15T11:09:57Z

Code this documents has been merged

AnotherButler · 2019-02-19T16:27:03Z

To clarify, this should only go into 5.12, right? Not 5.11?

paul-szczepanek-arm · 2019-02-19T16:33:44Z

yes, corresponding PR merged into master for 5.12

Add one sentence of context in link to GattClient.md.

AnotherButler

Thanks for the great work on this 👍

add BLE ATT_MTU and Data Length docs

11bcb20

pan- requested changes Feb 4, 2019

View reviewed changes

review edits

184ca7d

paul-szczepanek-arm added 4 commits February 5, 2019 10:46

Update GattClient.md

3288074

Update GattServer.md

6a551b7

Update GattClient.md

a3e9ae1

Update GattServer.md

b4fd1fb

pan- approved these changes Feb 5, 2019

View reviewed changes

Edit and rearrange Gap.md

3b2d5a0

Rearrange content for flow, and edit mostly for precise language and international spelling.

paul-szczepanek-arm commented Feb 5, 2019

View reviewed changes

AnotherButler reviewed Feb 5, 2019

View reviewed changes

docs/api/bluetooth/Gap.md Outdated Show resolved Hide resolved

Amanda Butler added 2 commits February 5, 2019 15:19

Edit GattClient.md

6ec7367

Make minor edits, mostly for active voice.

Edit GattServer.md

5e84262

Edit file, mostly for active voice.

AnotherButler reviewed Feb 5, 2019

View reviewed changes

AnotherButler added the code dependency label Feb 5, 2019

paul-szczepanek-arm added 2 commits February 6, 2019 08:09

Update docs/api/bluetooth/Gap.md

a297fe7

add link to gattclient

ec646b8

AnotherButler removed the code dependency label Feb 19, 2019

Add sentence to GattServer.md

c4f6254

Add one sentence of context in link to GattClient.md.

AnotherButler approved these changes Feb 19, 2019

View reviewed changes

AnotherButler merged commit ae53ff0 into ARMmbed:development Feb 19, 2019


		ATT_MTU is the maximum size of the attribute that can fit in an L2CAP packet. This is independent of the Data Length which controls the over-the-air packet payload size (which is dealt with in the GAP). An L2CAP packet will be fragmented over many such packets if required.

		Only `GattClient` can trigger the exchange of ATT_MTU between client and server. The host may trigger the exchange which may also be requested manually using `negotiateAttMtu`. If an exchange happens the biggest value possible across both devices will be used. Negotiation is only a best effort process and does not guarantee a higher value being set.


		In addition to modulation schemes, MTU (Maximum Transmission Unit) size also strongly affects throughput. Newer controllers will allow you to negotiate bigger MTUs. Since each packet contains overhead bigger packets maximise throughput.
		In addition to modulation schemes, Maximum Transmission Unit (MTU) size also strongly affects throughput. Newer controllers allow you to negotiate bigger MTUs. Because each packet contains overhead, bigger packets maximize throughput.

		@@ -14,6 +16,16 @@ You must access values of the characteristic and the characteristic descriptor p

		You can query the server by invoking the function `areUpdatesEnabled()` to find out if a client has subscribed to a given characteristic's value update.

		#### Attribute Protocol Maximum Transmission Unit (ATT_MTU)

BLE: Add ATT_MTU and Data Length docs #937

BLE: Add ATT_MTU and Data Length docs #937

Uh oh!

Conversation

paul-szczepanek-arm commented Feb 4, 2019

Uh oh!

pan- commented Feb 4, 2019

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

paul-szczepanek-arm commented Feb 4, 2019

Uh oh!

pan- left a comment

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

pan- Feb 5, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

paul-szczepanek-arm commented Feb 15, 2019

Uh oh!

AnotherButler commented Feb 19, 2019

Uh oh!

paul-szczepanek-arm commented Feb 19, 2019 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

AnotherButler left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

pan- Feb 5, 2019 •

edited

Loading

paul-szczepanek-arm commented Feb 19, 2019 •

edited

Loading