doc/services/device_mgmt/smp_transport.rst

.. _mcumgr_smp_transport_specification:

SMP Transport Specification
###########################

The documents specifies information needed for implementing server and client
side SMP transports.

.. _mcumgr_smp_transport_ble:

BLE (Bluetooth Low Energy)
**************************

MCUmgr Clients need to use following BLE Characteristics, when implementing
SMP client:

- **Service UUID**: `8D53DC1D-1DB7-4CD3-868B-8A527460AA84`
- **Characteristic UUID**: `DA2E7828-FBCE-4E01-AE9E-261174997C48`

All SMP communication utilizes a single GATT characteristic.  An SMP request is
sent via a GATT Write Without Response command. An SMP response is sent in the form
of a GATT Notification

If an SMP request or response is too large to fit in a single GATT command, the
sender fragments it across several packets.  No additional framing is
introduced when a request or response is fragmented; the payload is simply
split among several packets. Since GATT guarantees ordered delivery of
packets, the SMP header in the first fragment contains sufficient information
for reassembly.

.. _mcumgr_smp_transport_uart:

UART/serial and console
***********************

SMP protocol specification by MCUmgr subsystem of Zephyr uses basic framing
of data to allow multiplexing of UART channel. Multiplexing requires
prefixing each frame with two byte marker and terminating it with newline.
Currently MCUmgr imposes a 127 byte limit on frame size, although there
are no real protocol constraints that require that limit.
The limit includes the prefix and the newline character, so the allowed payload
size is actually 124 bytes.

Although no such transport exists in Zephyr, it is possible to implement
MCUmgr client/server over UART transport that does not have framing at all,
or uses hardware serial port control, or other means of framing.

Frame fragmenting
=================

SMP protocol over serial is fragmented into MTU size frames; each
frame consists of two byte start marker, body and terminating newline
character.

There are four types of types of frames: initial, partial, partial-final
and initial-final; each frame type differs by start marker and/or body
contents.

Frame formats
-------------

Initial frame requires to be followed by optional sequence of partial
frames and finally by partial-final frame.
Body is always Base64 encoded, so the body size, here described as
MTU - 3, is able to actually carry N = (MTU - 3) / 4 * 3 bytes
of raw data.

Body of initial frame is preceded by two byte total packet length,
encoded in Big Endian, and equals size of a raw body plus two bytes,
size of CRC16; this means that actual body size allowed into an
initial frame is N - 2.

If a body size is smaller than N - 4, than it is possible to carry
entire body with preceding length and following it CRC in a single
frame, here called initial-final; for the description of initial-final
frame look below.

Initial frame format:

.. table::
    :align: center

    +---------------+---------------+---------------------------+
    | Content       | Size          | Description               |
    +===============+===============+===========================+
    | 0x06 0x09     | 2 bytes       | Frame start marker        |
    +---------------+---------------+---------------------------+
    | <base64-i>    | no more than  | Base64 encoded body       |
    |               | MTU - 3 bytes |                           |
    +---------------+---------------+---------------------------+
    | 0x0a          | 1 byte        | Frame termination         |
    +---------------+---------------+---------------------------+

``<base64-i>`` is Base64 encoded body of format:

.. table::
    :align: center

    +---------------+---------------+---------------------------+
    | Content       | Size          | Description               |
    +===============+===============+===========================+
    | total length  | 2 bytes       | Big endian 16-bit value   |
    |               |               | representing total length |
    |               |               | of body + 2 bytes for     |
    |               |               | CRC16; note that size of  |
    |               |               | total length field is not |
    |               |               | added to total length     |
    |               |               | value.                    |
    +---------------+---------------+---------------------------+
    | body          | no more than  | Raw body data fragment    |
    |               | MTU - 5       |                           |
    +---------------+---------------+---------------------------+

Initial-final frame format is similar to initial frame format,
but differs by ``<base64-i>`` definition.

``<base64-i>`` of initial-final frame, is Base64 encoded data taking
form:

.. table::
    :align: center

    +---------------+---------------+---------------------------+
    | Content       | Size          | Description               |
    +===============+===============+===========================+
    | total length  | 2 bytes       | Big endian 16-bit value   |
    |               |               | representing total length |
    |               |               | of body + 2 bytes for     |
    |               |               | CRC16; note that size of  |
    |               |               | total length field is not |
    |               |               | added to total length     |
    |               |               | value.                    |
    +---------------+---------------+---------------------------+
    | body          | no more than  | Raw body data fragment    |
    |               | MTU - 7       |                           |
    +---------------+---------------+---------------------------+
    | crc16         | 2 bytes       | CRC16 of entire packet    |
    |               |               | body, preceding length    |
    |               |               | not included.             |
    +---------------+---------------+---------------------------+

Partial frame is continuation after previous initial or other partial
frame. Partial frame takes form:

.. table::
    :align: center

    +---------------+---------------+---------------------------+
    | Content       | Size          | Description               |
    +===============+===============+===========================+
    | 0x04 0x14     | 2 bytes       | Frame start marker        |
    +---------------+---------------+---------------------------+
    | <base64-i>    | no more than  | Base64 encoded body       |
    |               | MTU - 3 bytes |                           |
    +---------------+---------------+---------------------------+
    | 0x0a          | 1 byte        | Frame termination         |
    +---------------+---------------+---------------------------+

The ``<base64-i>`` of partial frame is Base64 encoding of data,
taking form:

.. table::
    :align: center

    +---------------+---------------+---------------------------+
    | Content       | Size          | Description               |
    +===============+===============+===========================+
    | body          | no more than  | Raw body data fragment    |
    |               | MTU - 3       |                           |
    +---------------+---------------+---------------------------+

The ``<base64-i>`` of partial-final frame is Base64 encoding of data,
taking form:

.. table::
    :align: center

    +---------------+---------------+---------------------------+
    | Content       | Size          | Description               |
    +===============+===============+===========================+
    | body          | no more than  | Raw body data fragment    |
    |               | MTU - 3       |                           |
    +---------------+---------------+---------------------------+
    | crc16         | 2 bytes       | CRC16 of entire packet    |
    |               |               | body, preceding length    |
    |               |               | not included.             |
    +---------------+---------------+---------------------------+


CRC Details
-----------

The CRC16 included in final type frames is calculated over only
raw data and does not include packet length.
CRC16 polynomial is 0x1021 and initial value is 0.