1.. _mcumgr_smp_transport_specification:
2
3SMP Transport Specification
4###########################
5
6The documents specifies information needed for implementing server and client
7side SMP transports.
8
9.. _mcumgr_smp_transport_ble:
10
11BLE (Bluetooth Low Energy)
12**************************
13
14MCUmgr Clients need to use following BLE Characteristics, when implementing
15SMP client:
16
17- **Service UUID**: ``8D53DC1D-1DB7-4CD3-868B-8A527460AA84``
18- **Characteristic UUID**: ``DA2E7828-FBCE-4E01-AE9E-261174997C48``
19
20All SMP communication utilizes a single GATT characteristic.  An SMP request is
21sent via a GATT Write Without Response command. An SMP response is sent in the form
22of a GATT Notification
23
24If an SMP request or response is too large to fit in a single GATT command, the
25sender fragments it across several packets.  No additional framing is
26introduced when a request or response is fragmented; the payload is simply
27split among several packets. Since GATT guarantees ordered delivery of
28packets, the SMP header in the first fragment contains sufficient information
29for reassembly.
30
31.. _mcumgr_smp_transport_uart:
32
33UART/serial and console
34***********************
35
36SMP protocol specification by MCUmgr subsystem of Zephyr uses basic framing
37of data to allow multiplexing of UART channel. Multiplexing requires
38prefixing each frame with two byte marker and terminating it with newline.
39Currently MCUmgr imposes a 127 byte limit on frame size, although there
40are no real protocol constraints that require that limit.
41The limit includes the prefix and the newline character, so the allowed payload
42size is actually 124 bytes.
43
44Although no such transport exists in Zephyr, it is possible to implement
45MCUmgr client/server over UART transport that does not have framing at all,
46or uses hardware serial port control, or other means of framing.
47
48Frame fragmenting
49=================
50
51SMP protocol over serial is fragmented into MTU size frames; each
52frame consists of two byte start marker, body and terminating newline
53character.
54
55There are four types of types of frames: initial, partial, partial-final
56and initial-final; each frame type differs by start marker and/or body
57contents.
58
59Frame formats
60-------------
61
62Initial frame requires to be followed by optional sequence of partial
63frames and finally by partial-final frame.
64Body is always Base64 encoded, so the body size, here described as
65MTU - 3, is able to actually carry N = (MTU - 3) / 4 * 3 bytes
66of raw data.
67
68Body of initial frame is preceded by two byte total packet length,
69encoded in Big Endian, and equals size of a raw body plus two bytes,
70size of CRC16; this means that actual body size allowed into an
71initial frame is N - 2.
72
73If a body size is smaller than N - 4, than it is possible to carry
74entire body with preceding length and following it CRC in a single
75frame, here called initial-final; for the description of initial-final
76frame look below.
77
78Initial frame format:
79
80.. table::
81    :align: center
82
83    +---------------+---------------+---------------------------+
84    | Content       | Size          | Description               |
85    +===============+===============+===========================+
86    | 0x06 0x09     | 2 bytes       | Frame start marker        |
87    +---------------+---------------+---------------------------+
88    | <base64-i>    | no more than  | Base64 encoded body       |
89    |               | MTU - 3 bytes |                           |
90    +---------------+---------------+---------------------------+
91    | 0x0a          | 1 byte        | Frame termination         |
92    +---------------+---------------+---------------------------+
93
94``<base64-i>`` is Base64 encoded body of format:
95
96.. table::
97    :align: center
98
99    +---------------+---------------+---------------------------+
100    | Content       | Size          | Description               |
101    +===============+===============+===========================+
102    | total length  | 2 bytes       | Big endian 16-bit value   |
103    |               |               | representing total length |
104    |               |               | of body + 2 bytes for     |
105    |               |               | CRC16; note that size of  |
106    |               |               | total length field is not |
107    |               |               | added to total length     |
108    |               |               | value.                    |
109    +---------------+---------------+---------------------------+
110    | body          | no more than  | Raw body data fragment    |
111    |               | MTU - 5       |                           |
112    +---------------+---------------+---------------------------+
113
114Initial-final frame format is similar to initial frame format,
115but differs by ``<base64-i>`` definition.
116
117``<base64-i>`` of initial-final frame, is Base64 encoded data taking
118form:
119
120.. table::
121    :align: center
122
123    +---------------+---------------+---------------------------+
124    | Content       | Size          | Description               |
125    +===============+===============+===========================+
126    | total length  | 2 bytes       | Big endian 16-bit value   |
127    |               |               | representing total length |
128    |               |               | of body + 2 bytes for     |
129    |               |               | CRC16; note that size of  |
130    |               |               | total length field is not |
131    |               |               | added to total length     |
132    |               |               | value.                    |
133    +---------------+---------------+---------------------------+
134    | body          | no more than  | Raw body data fragment    |
135    |               | MTU - 7       |                           |
136    +---------------+---------------+---------------------------+
137    | crc16         | 2 bytes       | CRC16 of entire packet    |
138    |               |               | body, preceding length    |
139    |               |               | not included.             |
140    +---------------+---------------+---------------------------+
141
142Partial frame is continuation after previous initial or other partial
143frame. Partial frame takes form:
144
145.. table::
146    :align: center
147
148    +---------------+---------------+---------------------------+
149    | Content       | Size          | Description               |
150    +===============+===============+===========================+
151    | 0x04 0x14     | 2 bytes       | Frame start marker        |
152    +---------------+---------------+---------------------------+
153    | <base64-i>    | no more than  | Base64 encoded body       |
154    |               | MTU - 3 bytes |                           |
155    +---------------+---------------+---------------------------+
156    | 0x0a          | 1 byte        | Frame termination         |
157    +---------------+---------------+---------------------------+
158
159The ``<base64-i>`` of partial frame is Base64 encoding of data,
160taking form:
161
162.. table::
163    :align: center
164
165    +---------------+---------------+---------------------------+
166    | Content       | Size          | Description               |
167    +===============+===============+===========================+
168    | body          | no more than  | Raw body data fragment    |
169    |               | MTU - 3       |                           |
170    +---------------+---------------+---------------------------+
171
172The ``<base64-i>`` of partial-final frame is Base64 encoding of data,
173taking form:
174
175.. table::
176    :align: center
177
178    +---------------+---------------+---------------------------+
179    | Content       | Size          | Description               |
180    +===============+===============+===========================+
181    | body          | no more than  | Raw body data fragment    |
182    |               | MTU - 5       |                           |
183    +---------------+---------------+---------------------------+
184    | crc16         | 2 bytes       | CRC16 of entire packet    |
185    |               |               | body, preceding length    |
186    |               |               | not included.             |
187    +---------------+---------------+---------------------------+
188
189
190CRC Details
191-----------
192
193The CRC16 included in final type frames is calculated over only
194raw data and does not include packet length.
195CRC16 polynomial is 0x1021 and initial value is 0.
196
197API Reference
198*************
199
200.. doxygengroup:: mcumgr_transport_smp
201