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