1.. zephyr:code-sample:: bluetooth_mtu_update
2   :name: MTU Update
3   :relevant-api: bt_gatt bluetooth
4
5   Configure and exchange MTU between two devices.
6
7Q&A:
8****
9
10  Question: What do I have to do to update my ATT MTU?
11
12| Answer: To get an ATT MTU of x octets, do the following:
13| Set :kconfig:option:`CONFIG_BT_L2CAP_TX_MTU` to at least x
14| Set :kconfig:option:`CONFIG_BT_BUF_ACL_RX_SIZE` to at least x + L2CAP header
15  size (4 octets).
16| Set :kconfig:option:`CONFIG_BT_BUF_ACL_RX_SIZE` to at least x + L2CAP header +
17  SDU length field length (6 octets) if using
18  :kconfig:option:`CONFIG_BT_EATT`.
19| Ensure the remote side supports the same MTUs.
20
21  Question: I only want to *send* large packets. I don't need to receive large
22  ones.
23  Do I still need to set :kconfig:option:`CONFIG_BT_BUF_ACL_RX_SIZE`?
24
25Answer: Yes. [#mtu_exchange]_ The Bluetooth specification mandates a symmetric MTU for ATT.
26
27Overview:
28*********
29
30This sample demonstrates the exchange of MTU between two devices to allow a
31large notification to be sent.
32Updating the MTU can be useful to send bigger packets and so have a better
33throughput.
34
35To be able to send a large notification both the server and the client need to
36update their MTU. The MTU is not a negotiated value, the client and the server
37will exchange their MTUs and choose the minimum of the two. Thus the two MTU can
38be set to a different value, but the MTU of the server must be greater or equal
39to the MTU of the client.
40
41According to the Bluetooth specification, [#mtu]_ MTU is the maximum size of
42SDUs.
43However, in Zephyr, we can assume that it also represents the maximum size of
44the PDUs. Because, in Bluetooth LE, [#sud_encapsulation]_ unless we are using L2CAP dynamic
45channels, SDUs are not segmented.
46The Kconfig symbol used to configure the size of the TX MTU is
47:kconfig:option:`CONFIG_BT_L2CAP_TX_MTU`. There is no Kconfig symbol to update
48the size of the RX MTU, because Zephyr uses a buffer pool for ACL RX buffers
49coming from the controller.
50The L2CAP RX MTU is defined as the maximum size of ACL RX buffers minus the
51L2CAP header size.
52That maximum ACL RX buffer size is configured with
53:kconfig:option:`CONFIG_BT_BUF_ACL_RX_SIZE`.
54The resulting L2CAP RX MTU will be the value of this Kconfig symbol minus the
55L2CAP header size.
56
57.. figure:: img/mtu.svg
58     :align: center
59     :alt: Diagram of the MTUs and their corresponding Kconfig symbols
60
61     Diagram of the MTUs and their corresponding Kconfig symbols
62
63Hardware Setup
64**************
65
66This sample use two applications, two devices need to be setup.
67The first one should be flashed with the central and the second one with the
68peripheral.
69
70The two devices will connect only if they are close to each other, because of
71RSSI filtering.
72
73Building and Running
74********************
75
76This sample can be found under :zephyr_file:`samples/bluetooth/mtu_update` in
77the Zephyr tree.
78
79See :zephyr:code-sample-category:`bluetooth` samples for details.
80
81If the devices are close enough, the central should connect to the peripheral
82and send his MTU to the other device. If the MTU exchange succeeds, the central
83should subscribe and then the peripheral will send a large notification. Right
84after receiving the notification the central should unsubscribe.
85
86Here are the outputs you should have on the devices:
87
88Central:
89
90.. code-block:: console
91
92  *** Booting Zephyr OS build zephyr-v3.2.0-2251-g95d8943c69ce ***
93  Bluetooth initialized
94  Scanning successfully started
95  Device found: EB:BF:36:26:42:09 (random) (RSSI -34)
96  Connected: EB:BF:36:26:42:09 (random)
97  mtu_exchange: Current MTU = 23
98  mtu_exchange: Exchange MTU...
99  mtu_exchange_cb: MTU exchange successful (247)
100  [ATTRIBUTE] handle 16
101  [ATTRIBUTE] handle 17
102  [ATTRIBUTE] handle 19
103  [SUBSCRIBED]
104  [NOTIFICATION] data 0x20004b73 length 100
105  [UNSUBSCRIBED]
106
107Peripheral:
108
109.. code-block:: console
110
111  *** Booting Zephyr OS build zephyr-v3.2.0-2251-g95d8943c69ce ***
112  Updated MTU: TX: 23 RX: 23 bytes
113  Updated MTU: TX: 247 RX: 247 bytes
114  MTU Test Update: notifications enabled
115  MTU Test Update: notifications disabled
116
117References
118**********
119
120.. [#mtu_exchange] Bluetooth Core Specification v. 5.3: Vol. 3, Part F, 3.4.2
121.. [#mtu] Bluetooth Core Specification v. 5.3: Vol. 3, Part A, 5.1
122.. [#sud_encapsulation] Bluetooth Core Specification v. 5.3: Vol. 3, Part A, 7.3
123