.. _mcumgr_smp_group_8:

File management
###############

The file management group provides commands that allow to upload and download files
to/from a device.

File management group defines following commands:

.. table::
    :align: center

    +-------------------+-----------------------------------------------+
    | ``Command ID``    | Command description                           |
    +===================+===============================================+
    | ``0``             | File download/upload                          |
    +-------------------+-----------------------------------------------+
    | ``1``             | File status                                   |
    +-------------------+-----------------------------------------------+
    | ``2``             | File hash/checksum                            |
    +-------------------+-----------------------------------------------+
    | ``3``             | Supported file hash/checksum types            |
    +-------------------+-----------------------------------------------+
    | ``4``             | File close                                    |
    +-------------------+-----------------------------------------------+

File download
*************

Command allows to download contents of an existing file from specified path
of a target device. Client applications must keep track of data they have
already downloaded and where their position in the file is (MCUmgr will cache
these also), and issue subsequent requests, with modified offset, to gather
the entire file.
Request does not carry size of requested chunk, the size is specified
by application itself.
Note that file handles will remain open for consecutive requests (as long as
an idle timeout has not been reached and another transport does not make use
of uploading/downloading files using fs_mgmt), but files are not exclusively
owned by MCUmgr, for the time of download session, and may change between
requests or even be removed.

.. note::

    By default, all file upload/download requests are unconditionally allowed.
    However, if the Kconfig option
    :kconfig:option:`CONFIG_MCUMGR_GRP_FS_FILE_ACCESS_HOOK` is enabled, then an
    application can register a callback handler for
    :c:enum:`MGMT_EVT_OP_FS_MGMT_FILE_ACCESS` (see
    :ref:`MCUmgr callbacks <mcumgr_callbacks>`), which allows for allowing or
    declining access to reading/writing a particular file, or for rewriting the
    path supplied by the client.

File download request
=====================

File download request header:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``0``  | ``8``        |  ``0``         |
    +--------+--------------+----------------+

CBOR data of request:

.. code-block:: none

    {
        (str)"off" :  (uint)
        (str)"name" : (str)
    }

where:

.. table::
    :align: center

    +-----------------------+---------------------------------------------------+
    | "off"                 | offset to start download at                       |
    +-----------------------+---------------------------------------------------+
    | "name"                | absolute path to a file                           |
    +-----------------------+---------------------------------------------------+

File download response
======================

File download response header:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``1``  | ``8``        |  ``0``         |
    +--------+--------------+----------------+

CBOR data of successful response:

.. code-block:: none

    {
        (str)"off"      : (uint)
        (str)"data"     : (byte str)
        (str,opt)"len"  : (uint)
    }

In case of error the CBOR data takes the form:

.. code-block:: none

    {
        (str)"rc"           : (int)
    }

where:

.. table::
    :align: center

    +-----------------------+--------------------------------------------------+
    | "off"                 | offset the response is for                       |
    +-----------------------+--------------------------------------------------+
    | "data"                | chunk of data read from file; it is CBOR encoded |
    |                       | stream of bytes with embedded size;              |
    |                       | "data" appears only in responses where "rc" is 0 |
    +-----------------------+--------------------------------------------------+
    | "len"                 | length of file, this field is only mandatory     |
    |                       | when "off" is 0                                  |
    +-----------------------+--------------------------------------------------+
    | "rc"                  | :c:enum:`mcumgr_err_t`                           |
    |                       | only appears if non-zero (error condition).      |
    +-----------------------+--------------------------------------------------+

In case when "rc" is not 0, success, the other fields will not appear.

File upload
***********

Allows to upload a file to a specified location. Command will automatically overwrite
existing file or create a new one if it does not exist at specified path.
The protocol supports stateless upload where each requests carries different chunk
of a file and it is client side responsibility to track progress of upload.

Note that file handles will remain open for consecutive requests (as long as
an idle timeout has not been reached, but files are not exclusively owned by
MCUmgr, for the time of download session, and may change between requests or
even be removed. Note that file handles will remain open for consecutive
requests (as long as an idle timeout has not been reached and another transport
does not make use of uploading/downloading files using fs_mgmt), but files are
not exclusively owned by MCUmgr, for the time of download session, and may
change between requests or even be removed.

.. note::
    Weirdly, the current Zephyr implementation is half-stateless as is able to hold
    single upload context, holding information on ongoing upload, that consists
    of bool flag indicating in-progress upload, last successfully uploaded offset
    and total length only.

.. note::

    By default, all file upload/download requests are unconditionally allowed.
    However, if the Kconfig option
    :kconfig:option:`CONFIG_MCUMGR_GRP_FS_FILE_ACCESS_HOOK` is enabled, then an
    application can register a callback handler for
    :c:enum:`MGMT_EVT_OP_FS_MGMT_FILE_ACCESS` (see
    :ref:`MCUmgr callbacks <mcumgr_callbacks>`), which allows for allowing or
    declining access to reading/writing a particular file, or for rewriting the
    path supplied by the client.

File upload request
===================

File upload request header:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``2``  | ``8``        |  ``0``         |
    +--------+--------------+----------------+

CBOR data of request:

.. code-block:: none

    {
        (str)"off"      : (uint)
        (str)"data"     : (str)
        (str)"name"     : (str)
        (str,opt)"len"  : (uint)
    }

where:

.. table::
    :align: center

    +-----------------------+---------------------------------------------------+
    | "off"                 | offset to start/continue upload at                |
    +-----------------------+---------------------------------------------------+
    | "data"                | chunk of data to write to the file;               |
    |                       | it is CBOR encoded with length embedded           |
    +-----------------------+---------------------------------------------------+
    | "name"                | absolute path to a file                           |
    +-----------------------+---------------------------------------------------+
    | "len"                 | length of file, this field is only mandatory      |
    |                       | when "off" is 0                                   |
    +-----------------------+---------------------------------------------------+

File upload response
====================

File upload response header:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``3``  | ``8``        |  ``0``         |
    +--------+--------------+----------------+

CBOR data of successful response:

.. code-block:: none

    {
        (str)"off"      : (uint)
    }

In case of error the CBOR data takes the form:

.. code-block:: none

    {
        (str)"rc"       : (int)
    }

where:

.. table::
    :align: center

    +-----------------------+---------------------------------------------+
    | "off"                 | offset of last successfully written data.   |
    +-----------------------+---------------------------------------------+
    | "rc"                  | :c:enum:`mcumgr_err_t`                      |
    |                       | only appears if non-zero (error condition). |
    +-----------------------+---------------------------------------------+

File status
***********

Command allows to retrieve status of an existing file from specified path
of a target device.

File status request
===================

File status request header:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``0``  | ``8``        |  ``1``         |
    +--------+--------------+----------------+

CBOR data of request:

.. code-block:: none

    {
        (str)"name" : (str)
    }

where:

.. table::
    :align: center

    +-----------------------+---------------------------------------------------+
    | "name"                | absolute path to a file                           |
    +-----------------------+---------------------------------------------------+

File status response
====================

File status response header:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``1``  | ``8``        |  ``1``         |
    +--------+--------------+----------------+

CBOR data of successful response:

.. code-block:: none

    {
        (str)"len"      : (uint)
    }

In case of error the CBOR data takes form:

.. code-block:: none

    {
        (str)"rc"       : (int)
    }

where:

.. table::
    :align: center

    +-----------------------+---------------------------------------------+
    | "len"                 | length of file (in bytes)                   |
    +-----------------------+---------------------------------------------+
    | "rc"                  | :c:enum:`mcumgr_err_t`                      |
    |                       | only appears if non-zero (error condition). |
    +-----------------------+---------------------------------------------+

In case when "rc" is not 0, success, the other fields will not appear.

File hash/checksum
******************

Command allows to generate a hash/checksum of an existing file at a specified
path on a target device. Note that kernel heap memory is required for buffers to
be allocated for this to function, and large stack memory buffers are required
for generation of the output hash/checksum.
Requires :kconfig:option:`CONFIG_MCUMGR_GRP_FS_CHECKSUM_HASH` to be enabled for
the base functionality, supported hash/checksum are opt-in with
:kconfig:option:`CONFIG_MCUMGR_GRP_FS_CHECKSUM_IEEE_CRC32` or
:kconfig:option:`CONFIG_MCUMGR_GRP_FS_HASH_SHA256`.

File hash/checksum request
==========================

File hash/checksum request header:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``0``  | ``8``        |  ``2``         |
    +--------+--------------+----------------+

CBOR data of request:

.. code-block:: none

    {
        (str)"name"     : (str)
        (str,opt)"type" : (str)
        (str,opt)"off"  : (uint)
        (str,opt)"len"  : (uint)
    }

where:

.. table::
    :align: center

    +-----------------------+---------------------------------------------------+
    | "name"                | absolute path to a file                           |
    +-----------------------+---------------------------------------------------+
    | "type"                | type of hash/checksum to perform                  |
    |                       | :ref:`mcumgr_group_8_hash_checksum_types` or omit |
    |                       | to use default                                    |
    +-----------------------+---------------------------------------------------+
    | "off"                 | offset to start hash/checksum calculation at      |
    |                       | (optional, 0 if not provided)                     |
    +-----------------------+---------------------------------------------------+
    | "len"                 | maximum length of data to read from file to       |
    |                       | generate hash/checksum with (optional, full file  |
    |                       | size if not provided)                             |
    +-----------------------+---------------------------------------------------+

.. _mcumgr_group_8_hash_checksum_types:

Hash/checksum types
===================

.. table::
    :align: center

    +-------------+--------------------------------------+-------------+--------------+
    | String name | Hash/checksum                        | Byte string | Size (bytes) |
    +=============+======================================+=============+==============+
    | ``crc32``   | IEEE CRC32 checksum                  | No          | 4            |
    +-------------+--------------------------------------+-------------+--------------+
    | ``sha256``  | SHA256 (Secure Hash Algorithm)       | Yes         | 32           |
    +-------------+--------------------------------------+-------------+--------------+

Note that the default type will be crc32 if it is enabled, or sha256 if crc32 is
not enabled.

File hash/checksum response
===========================

File hash/checksum response header:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``1``  | ``8``        |  ``2``         |
    +--------+--------------+----------------+

CBOR data of successful response:

.. code-block:: none

    {
        (str)"type"     : (str)
        (str,opt)"off"  : (uint)
        (str)"len"      : (uint)
        (str)"output"   : (uint or bstr)
    }

In case of error the CBOR data takes the form:

.. code-block:: none

    {
        (str)"rc"       : (int)
    }

where:

.. table::
    :align: center

    +-----------------------+--------------------------------------------------+
    | "rc"                  | :c:enum:`mcumgr_err_t`                           |
    |                       | only appears if non-zero (error condition).      |
    +-----------------------+--------------------------------------------------+
    | "type"                | type of hash/checksum that was performed         |
    |                       | :ref:`mcumgr_group_8_hash_checksum_types`        |
    +-----------------------+--------------------------------------------------+
    | "off"                 | offset that hash/checksum calculation started at |
    |                       | (only present if off is not 0)                   |
    +-----------------------+--------------------------------------------------+
    | "len"                 | length of input data used for hash/checksum      |
    |                       | generation (in bytes)                            |
    +-----------------------+--------------------------------------------------+
    | "output"              | output hash/checksum                             |
    +-----------------------+--------------------------------------------------+

In case when "rc" is not 0, success, the other fields will not appear.

Supported file hash/checksum types
**********************************

Command allows listing which hash and checksum types are available on a device.
Requires Kconfig :kconfig:option:`CONFIG_MCUMGR_GRP_FS_CHECKSUM_HASH_SUPPORTED_CMD`
to be enabled.

Supported file hash/checksum types request
==========================================

Supported file hash/checksum types request header:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``0``  | ``8``        |  ``3``         |
    +--------+--------------+----------------+

The command sends empty CBOR map as data.

Supported file hash/checksum types response
===========================================

Supported file hash/checksum types response header:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``1``  | ``8``        |  ``3``         |
    +--------+--------------+----------------+

CBOR data of successful response:

.. code-block:: none

    format (0 = int, 1 = byte array)
    {
        (str)"types" : {
            (str)<hash_checksum_name> : {
                (str)"format"       : (uint)
                (str)"size"         : (uint)
            }
            ...
        }
    }

In case of error the CBOR data takes form:

.. code-block:: none

    {
        (str)"rc"       : (int)
    }

where:

.. table::
    :align: center

    +-----------------------+---------------------------------------------------+
    | <hash_checksum_name>  | name of the hash/checksum type                    |
    |                       | :ref:`mcumgr_group_8_hash_checksum_types`         |
    +-----------------------+---------------------------------------------------+
    | "format"              | format that the hash/checksum returns where 0 is  |
    |                       | for numerical and 1 is for byte array.            |
    +-----------------------+---------------------------------------------------+
    | "size"                | size (in bytes) of output hash/checksum response. |
    +-----------------------+---------------------------------------------------+

In case when "rc" is not 0, success, the other fields will not appear.

File close
**********

Command allows closing any open file handles held by fs_mgmt upload/download
requests that might have stalled or be incomplete.

File close request
==================

File close request header:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``2``  | ``8``        |  ``4``         |
    +--------+--------------+----------------+

The command sends empty CBOR map as data.

File close response
===================

File close response header:

.. table::
    :align: center

    +--------+--------------+----------------+
    | ``OP`` | ``Group ID`` | ``Command ID`` |
    +========+==============+================+
    | ``3``  | ``8``        |  ``4``         |
    +--------+--------------+----------------+

The command sends an empty CBOR map as data if successful.
In case of error the CBOR data takes the form:

.. code-block:: none

    {
        (str)"rc"           : (int)
    }

where:

.. table::
    :align: center

    +-----------------------+------------------------------------------------+
    | "rc"                  | :c:enum:`mcumgr_err_t`                         |
    |                       | only appears if non-zero (error condition).    |
    +-----------------------+------------------------------------------------+