BLE: Add ATT_MTU and Data Length docs #937
Conversation
|
Corresponding PR in mbed-os: ARMmbed/mbed-os#9537 . |
docs/api/bluetooth/GattClient.md
Outdated
|
|
||
| #### 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. |
There was a problem hiding this comment.
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, ...
docs/api/bluetooth/GattClient.md
Outdated
|
|
||
| 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. |
There was a problem hiding this comment.
It would be interesting to detail the negotiation behaviour and clarify the term host.
|
thanks for the comments, hopefully I have integrated them to your satisfaction |
Rearrange content for flow, and edit mostly for precise language and international spelling.
| #### Data length (over-the-air MTU) | ||
|
|
||
| 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. |
There was a problem hiding this comment.
Why is Because superior to Since in this case? Maybe I can try to choose the right one in the future.
There was a problem hiding this comment.
Great question. "Since" shows time passed (for example, "We've been open since 1952"). "Because" shows cause and effect.
There was a problem hiding this comment.
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 ?
There was a problem hiding this comment.
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 :)
Make minor edits, mostly for active voice.
Edit file, mostly for active voice.
|
|
||
| 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) |
There was a problem hiding this comment.
Because this section is an exact duplicate, can we instead replace it with a link to the relevant section in GattClient.md?
There was a problem hiding this comment.
OK. The client version is the fuller one as this one shortens the paragraph about what the client does. How do I link?
There was a problem hiding this comment.
The link to GattClient is "../apis/gattclient.html"
|
Code this documents has been merged |
|
To clarify, this should only go into 5.12, right? Not 5.11? |
|
yes, corresponding PR merged into master for 5.12 |
Add one sentence of context in link to GattClient.md.
3 participants
No description provided.