| .. _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 | |
| +-------------------+-----------------------------------------------+ |
| |
| File download |
| ************* |
| |
| Command allows to download contents of an existing file from specified path |
| of a target device. The command is stateless and mcumgr does not hold file |
| in open state after response to the command is issued, instead a client |
| application is supposed to keep track of data it has already downloaded, |
| and issue subsequent requests, with modified offset, to gather entire file. |
| Request does not carry size of requested chunk, the size is specified |
| by application itself. |
| Mcumgr server side re-opens a file for each subsequent request, and current |
| specification does not provide means to identify subsequent requests as |
| belonging to specified download session. This means that the file is not |
| locked in any way or exclusively owned by mcumgr, for the time of download |
| session, and may change between requests or even be removed. |
| |
| 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)"rc" : (int) |
| (str,opt)"len" : (uint) |
| } |
| |
| In case of error the CBOR data takes 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" | :ref:`mcumgr_smp_protocol_status_codes` | |
| +-----------------------+---------------------------------------------------+ |
| |
| 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. |
| |
| Mcumgr server side re-opens a file for each subsequent request, and current |
| specification does not provide means to identify subsequent requests as |
| belonging to specified upload session. This means that the file is not |
| locked in any way or exclusively owned by mcumgr, for the time of upload |
| 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. |
| |
| 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 request: |
| |
| .. code-block:: none |
| |
| { |
| (str,opt)"off" : (uint) |
| (str)"rc" : (int) |
| } |
| |
| where: |
| |
| .. table:: |
| :align: center |
| |
| +-----------------------+---------------------------------------------------+ |
| | "off" | offset of last successfully written data; | |
| | | appears only when "rc" is 0 | |
| +-----------------------+---------------------------------------------------+ |
| | "rc" | :ref:`mcumgr_smp_protocol_status_codes` | |
| +-----------------------+---------------------------------------------------+ |