Merge pull request #937 from paul-szczepanek-arm/ble-mtu

BLE: Add ATT_MTU and Data Length docs

Author: Amanda Butler

docs/api/bluetooth/Gap.md

@@ -52,6 +52,16 @@ You may set preferred PHYs (separately for RX and TX) using `setPreferredPhys()`
 
 You may query the currently used PHY using `readPhy()`, which returns the result through a call to the registered event handler. You may register the handler with `setEventHandler()`. The events inform about the currently used PHY and of any changes to PHYs, which the controller or the peer may trigger autonomously.
 
+#### Data length (over-the-air MTU)
+
+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 are two separate MTUs to consider: the `ATT_MTU` (maximum attribute size) and data length. `GattServer` and `GattClient` affect `ATT_MTU`. `Gap` only deals with data length, which is the maximum size of the packet that carries attributes that are fragmented across many such packets.
+
+The default value of data length supported by all controllers is 23 octets. If both controllers support data length extension and a higher value is negotiated, the BLE stack will call `onDataLengthChange` in the `Gap::EventHandler` registered by the user.
+
+`ATT_MTU` and data length are independent of each other. 
+
 ### GAP class reference
 
 [![View code](https://www.mbed.com/embed/?type=library)](https://os.mbed.com/docs/development/mbed-os-api-doxy/class_gap.html)

docs/api/bluetooth/GattClient.md

@@ -1,6 +1,6 @@
 ## GattClient
 
-GattClient defines procedures required for interacting with a remote GattServer.
+You can use Generic Attribute Profile (GATT) to discover services, characteristics and descriptors and to perform operations on them. The interaction happens between two peers, one of which is the client (which initiates interactions) and the other is the server (which responds). You can use Attribute Protocol (ATT) to implement this interaction. `GattClient` defines procedures required for interacting with a remote `GattServer`.
 
 #### Discovery procedures
 
@@ -16,6 +16,16 @@ 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.
 
+#### Attribute Protocol Maximum Transmission Unit (ATT_MTU)
+
+`ATT_MTU` is the maximum size of the attribute protocol packet. Operation on attributes too large to fit into a single packet are split across multiple operations.
+
+This is independent of the data length, which controls the over-the-air packet payload size (which the GAP handles). An L2CAP packet containing the attribute protocol packet is fragmented over many packets if required.
+
+Only `GattClient` can trigger the exchange of `ATT_MTU` between client and server. Depending on the implementation of the bluetooth stack, the client may trigger the exchange upon connection. You may also manually request the exchange 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.
+
+`ATT_MTU` is at least 23 octets by default. If a larger size is negotiated, the user application will be informed through the `onAttMtuChange` function called in the `GattClient::EventHandler`. (`GattServer::EventHandler` is also informed.)
+
 #### Server initiated events
 
 When a server updates a characteristic value, it can forward the new value to any registered clients. Clients may register for these updates on a per-characteristic basis. The server sends the updates by using notifications (no confirmation from client) or indications (client confirms receipt). This mechanism minimizes the number of transactions between a client and a server by avoiding polling.

docs/api/bluetooth/GattServer.md

@@ -1,6 +1,8 @@
 ## GattServer
 
-A GattServer is a collection of GattServices. These services contain characteristics that a peer connected to the device may read or write. These characteristics may also emit updates to subscribed clients when their values change.
+You can use Generic Attribute Profile (GATT) to discover services, characteristics and descriptors and to perform operations on them. The interaction happens between two peers, one of which is the client (which initiates interactions) and the other is the server (which responds). You can use Attribute Protocol (ATT) to implement this interaction.
+
+`GattServer` is a collection of GattServices. These services contain characteristics that a `GattClient` on the peer connected to the device may read or write. These characteristics may also emit updates to subscribed clients when their values change.
 
 #### Server layout
 
@@ -14,6 +16,10 @@ 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)
+
+The Attribute Protocol Maximum Transmission Unit (`ATT_MTU`) is the maximum size of the attribute protocol packet. For details, please see the [GattClient Documentation](../apis/gattclient.html).
+
 #### Events
 
 You can register several event handlers with the GattServer that it will call to notify you of client (remote application connected to the server) and server activities: