Skip to content

File Management

The Simple Management Protocol (SMP) File Management group.

FileDownloadRequest

Bases: ReadRequest

Download contents of an existing file from specified path.

Client applications must keep track of data they have already downloaded and where their position in the file is, 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 SMP, for the time of download session, and may change between requests or even be removed.

Source code in smp/file_management.py 
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
class FileDownloadRequest(message.ReadRequest):
    """Download contents of an existing file from specified path.

    Client applications must keep track of data they have already downloaded and
    where their position in the file is, 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 SMP, for the time of download
    session, and may change between requests or even be removed.
    """

    _GROUP_ID = header.GroupId.FILE_MANAGEMENT
    _COMMAND_ID = header.CommandId.FileManagement.FILE_DOWNLOAD_UPLOAD

    off: int
    """Offset in the file to read from."""
    name: str
    """Name of the file to download."""

off: int instance-attribute

Offset in the file to read from.

name: str instance-attribute

Name of the file to download.

FileDownloadResponse

Bases: ReadResponse

Success response to a file download request.

Source code in smp/file_management.py 
37
38
39
40
41
42
43
44
45
46
47
48
class FileDownloadResponse(message.ReadResponse):
    """Success response to a file download request."""

    _GROUP_ID = header.GroupId.FILE_MANAGEMENT
    _COMMAND_ID = header.CommandId.FileManagement.FILE_DOWNLOAD_UPLOAD

    off: int
    """Offset that this response is for."""
    data: bytes
    """Data read from the file."""
    len: int | None = None
    """The length of the file, only mandatory if “off” is 0."""

off: int instance-attribute

Offset that this response is for.

data: bytes instance-attribute

Data read from the file.

len: int | None = None class-attribute instance-attribute

The length of the file, only mandatory if “off” is 0.

FileUploadRequest

Bases: WriteRequest

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 SMP, 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.

Source code in smp/file_management.py 
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
class FileUploadRequest(message.WriteRequest):
    """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
    SMP, 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.
    """

    _GROUP_ID = header.GroupId.FILE_MANAGEMENT
    _COMMAND_ID = header.CommandId.FileManagement.FILE_DOWNLOAD_UPLOAD

    off: int
    """Offset to start/continue writing to."""
    data: bytes
    """Data to write to the file."""
    name: str
    """Name of the file to upload."""
    len: int | None = None
    """The length of the file, only mandatory if “off” is 0."""

off: int instance-attribute

Offset to start/continue writing to.

data: bytes instance-attribute

Data to write to the file.

name: str instance-attribute

Name of the file to upload.

len: int | None = None class-attribute instance-attribute

The length of the file, only mandatory if “off” is 0.

FileUploadResponse

Bases: WriteResponse

Success response to a file upload request.

Source code in smp/file_management.py 
82
83
84
85
86
87
88
89
class FileUploadResponse(message.WriteResponse):
    """Success response to a file upload request."""

    _GROUP_ID = header.GroupId.FILE_MANAGEMENT
    _COMMAND_ID = header.CommandId.FileManagement.FILE_DOWNLOAD_UPLOAD

    off: int
    """Offset of the file."""

off: int instance-attribute

Offset of the file.

FileStatusRequest

Bases: ReadRequest

Retrieve status of an existing file from specified path of a target device.

Source code in smp/file_management.py 
92
93
94
95
96
97
98
class FileStatusRequest(message.ReadRequest):
    """Retrieve status of an existing file from specified path of a target device."""

    _GROUP_ID = header.GroupId.FILE_MANAGEMENT
    _COMMAND_ID = header.CommandId.FileManagement.FILE_STATUS

    name: str

name: str instance-attribute

FileStatusResponse

Bases: ReadResponse

Success response to a file status request.

Source code in smp/file_management.py 
101
102
103
104
105
106
107
class FileStatusResponse(message.ReadResponse):
    """Success response to a file status request."""

    _GROUP_ID = header.GroupId.FILE_MANAGEMENT
    _COMMAND_ID = header.CommandId.FileManagement.FILE_STATUS

    len: int

len: int instance-attribute

FileHashChecksumRequest

Bases: ReadRequest

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 CONFIG_MCUMGR_GRP_FS_CHECKSUM_HASH to be enabled for the base functionality, supported hash/checksum are opt-in with CONFIG_MCUMGR_GRP_FS_CHECKSUM_IEEE_CRC32 or CONFIG_MCUMGR_GRP_FS_HASH_SHA256.

Source code in smp/file_management.py 
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
class FileHashChecksumRequest(message.ReadRequest):
    """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 `CONFIG_MCUMGR_GRP_FS_CHECKSUM_HASH` to
    be enabled for the base functionality, supported hash/checksum are opt-in
    with `CONFIG_MCUMGR_GRP_FS_CHECKSUM_IEEE_CRC32` or
    `CONFIG_MCUMGR_GRP_FS_HASH_SHA256`.
    """

    _GROUP_ID = header.GroupId.FILE_MANAGEMENT
    _COMMAND_ID = header.CommandId.FileManagement.FILE_HASH_CHECKSUM

    name: str
    """Absolute path to the file to generate hash/checksum for."""
    type: Literal["crc32", "sha256"] | None = None
    """Type of hash/checksum to generate, if not provided, default is used."""
    off: int | None = None
    """Offset to start hash/checksum generation from, default 0."""
    len: int | None = None
    """Maximum length of the file to generate hash/checksum for, default is entire file."""

name: str instance-attribute

Absolute path to the file to generate hash/checksum for.

type: Literal['crc32', 'sha256'] | None = None class-attribute instance-attribute

Type of hash/checksum to generate, if not provided, default is used.

off: int | None = None class-attribute instance-attribute

Offset to start hash/checksum generation from, default 0.

len: int | None = None class-attribute instance-attribute

Maximum length of the file to generate hash/checksum for, default is entire file.

FileHashChecksumResponse

Bases: ReadResponse

Success response to a file hash/checksum request.

Source code in smp/file_management.py 
134
135
136
137
138
139
140
141
142
143
144
145
146
class FileHashChecksumResponse(message.ReadResponse):
    """Success response to a file hash/checksum request."""

    _GROUP_ID = header.GroupId.FILE_MANAGEMENT
    _COMMAND_ID = header.CommandId.FileManagement.FILE_HASH_CHECKSUM

    type: Literal["crc32", "sha256"]
    off: int | None = None
    """Only present if not 0."""
    len: int
    """Length of input data used to generate hash/checksum."""
    output: int | bytes
    """Output hash/checksum, depending on the type requested."""

type: Literal['crc32', 'sha256'] instance-attribute

off: int | None = None class-attribute instance-attribute

Only present if not 0.

len: int instance-attribute

Length of input data used to generate hash/checksum.

output: int | bytes instance-attribute

Output hash/checksum, depending on the type requested.

SupportedFileHashChecksumTypesRequest

Bases: ReadRequest

List the hash and checksum types are available on a device.

Requires Kconfig CONFIG_MCUMGR_GRP_FS_CHECKSUM_HASH_SUPPORTED_CMD to be enabled.

Source code in smp/file_management.py 
149
150
151
152
153
154
155
156
class SupportedFileHashChecksumTypesRequest(message.ReadRequest):
    """List the hash and checksum types are available on a device.

    Requires Kconfig `CONFIG_MCUMGR_GRP_FS_CHECKSUM_HASH_SUPPORTED_CMD` to be enabled.
    """

    _GROUP_ID = header.GroupId.FILE_MANAGEMENT
    _COMMAND_ID = header.CommandId.FileManagement.SUPPORTED_FILE_HASH_CHECKSUM_TYPES

HashChecksumFormat

Bases: IntEnum

Format that the hash/checksum returns where 0 is for numerical and 1 is for byte array.

Source code in smp/file_management.py 
159
160
161
162
163
class HashChecksumFormat(IntEnum):
    """Format that the hash/checksum returns where 0 is for numerical and 1 is for byte array."""

    NUMERICAL = 0
    BYTE_ARRAY = 1

NUMERICAL = 0 class-attribute instance-attribute

BYTE_ARRAY = 1 class-attribute instance-attribute

HashChecksumType

Bases: BaseModel

Hash and checksum type supported by the device.

Source code in smp/file_management.py 
166
167
168
169
170
171
172
173
174
class HashChecksumType(BaseModel):
    """Hash and checksum type supported by the device."""

    model_config = ConfigDict(extra="forbid", frozen=True)

    format: HashChecksumFormat
    """Format that the hash/checksum returns where 0 is for numerical and 1 is for byte array."""
    size: int
    """Size of the hash/checksum in bytes."""

model_config = ConfigDict(extra='forbid', frozen=True) class-attribute instance-attribute

format: HashChecksumFormat instance-attribute

Format that the hash/checksum returns where 0 is for numerical and 1 is for byte array.

size: int instance-attribute

Size of the hash/checksum in bytes.

SupportedFileHashChecksumTypesResponse

Bases: ReadResponse

Success response to a supported file hash/checksum types request.

Source code in smp/file_management.py 
177
178
179
180
181
182
183
184
class SupportedFileHashChecksumTypesResponse(message.ReadResponse):
    """Success response to a supported file hash/checksum types request."""

    _GROUP_ID = header.GroupId.FILE_MANAGEMENT
    _COMMAND_ID = header.CommandId.FileManagement.SUPPORTED_FILE_HASH_CHECKSUM_TYPES

    types: Dict[Literal["crc32", "sha256"], HashChecksumType]
    """The map of supported hash/checksum types."""

types: Dict[Literal['crc32', 'sha256'], HashChecksumType] instance-attribute

The map of supported hash/checksum types.

FileCloseRequest

Bases: WriteRequest

Close all open file handles held by fs_mgmt upload/download requests.

Source code in smp/file_management.py 
187
188
189
190
191
class FileCloseRequest(message.WriteRequest):
    """Close all open file handles held by fs_mgmt upload/download requests."""

    _GROUP_ID = header.GroupId.FILE_MANAGEMENT
    _COMMAND_ID = header.CommandId.FileManagement.FILE_CLOSE

FileCloseResponse

Bases: WriteResponse

Success response to a file close request.

Source code in smp/file_management.py 
194
195
196
197
198
class FileCloseResponse(message.WriteResponse):
    """Success response to a file close request."""

    _GROUP_ID = header.GroupId.FILE_MANAGEMENT
    _COMMAND_ID = header.CommandId.FileManagement.FILE_CLOSE

FS_MGMT_ERR

Bases: IntEnum

File System Management error codes.

Source code in smp/file_management.py 
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
@unique
class FS_MGMT_ERR(IntEnum):
    """File System Management error codes."""

    OK = 0
    """No error (success)."""

    UNKNOWN = 1
    """ Unknown error. """

    FILE_INVALID_NAME = 2
    """The specified file name is not valid."""

    FILE_NOT_FOUND = 3
    """The specified file does not exist."""

    FILE_IS_DIRECTORY = 4
    """The specified file is a directory, not a file. """

    FILE_OPEN_FAILED = 5
    """Error occurred whilst attempting to open a file."""

    FILE_SEEK_FAILED = 6
    """Error occurred whilst attempting to seek to an offset in a file. """

    FILE_READ_FAILED = 7
    """Error occurred whilst attempting to read data from a file."""

    FILE_TRUNCATE_FAILED = 8
    """Error occurred whilst trying to truncate file."""

    FILE_DELETE_FAILED = 9
    """Error occurred whilst trying to delete file."""

    FILE_WRITE_FAILED = 10
    """Error occurred whilst attempting to write data to a file."""

    FILE_OFFSET_NOT_VALID = 11
    """The specified data offset is not valid, this could indicate that the file on the device has
    changed since the previous command. The length of the current file on the device is returned as
    "len", the user application needs to decide how to handle this (e.g. the hash of the file could
    be requested and compared with the hash of the length of the file being uploaded to see if they
    match or not)."""

    FILE_OFFSET_LARGER_THAN_FILE = 12
    """The requested offset is larger than the size of the file on the device."""

    CHECKSUM_HASH_NOT_FOUND = 13
    """The requested checksum or hash type was not found or is not supported by this build."""

    MOUNT_POINT_NOT_FOUND = 14
    """The specified mount point was not found or is not mounted."""

    READ_ONLY_FILESYSTEM = 15
    """The specified mount point is that of a read-only filesystem."""

    FILE_EMPTY = 16
    """The operation cannot be performed because the file is empty with no contents. """

OK = 0 class-attribute instance-attribute

No error (success).

UNKNOWN = 1 class-attribute instance-attribute

Unknown error.

FILE_INVALID_NAME = 2 class-attribute instance-attribute

The specified file name is not valid.

FILE_NOT_FOUND = 3 class-attribute instance-attribute

The specified file does not exist.

FILE_IS_DIRECTORY = 4 class-attribute instance-attribute

The specified file is a directory, not a file.

FILE_OPEN_FAILED = 5 class-attribute instance-attribute

Error occurred whilst attempting to open a file.

FILE_SEEK_FAILED = 6 class-attribute instance-attribute

Error occurred whilst attempting to seek to an offset in a file.

FILE_READ_FAILED = 7 class-attribute instance-attribute

Error occurred whilst attempting to read data from a file.

FILE_TRUNCATE_FAILED = 8 class-attribute instance-attribute

Error occurred whilst trying to truncate file.

FILE_DELETE_FAILED = 9 class-attribute instance-attribute

Error occurred whilst trying to delete file.

FILE_WRITE_FAILED = 10 class-attribute instance-attribute

Error occurred whilst attempting to write data to a file.

FILE_OFFSET_NOT_VALID = 11 class-attribute instance-attribute

The specified data offset is not valid, this could indicate that the file on the device has changed since the previous command. The length of the current file on the device is returned as "len", the user application needs to decide how to handle this (e.g. the hash of the file could be requested and compared with the hash of the length of the file being uploaded to see if they match or not).

FILE_OFFSET_LARGER_THAN_FILE = 12 class-attribute instance-attribute

The requested offset is larger than the size of the file on the device.

CHECKSUM_HASH_NOT_FOUND = 13 class-attribute instance-attribute

The requested checksum or hash type was not found or is not supported by this build.

MOUNT_POINT_NOT_FOUND = 14 class-attribute instance-attribute

The specified mount point was not found or is not mounted.

READ_ONLY_FILESYSTEM = 15 class-attribute instance-attribute

The specified mount point is that of a read-only filesystem.

FILE_EMPTY = 16 class-attribute instance-attribute

The operation cannot be performed because the file is empty with no contents.

FileSystemManagementErrorV1

Bases: ErrorV1

File System Management error response.

Source code in smp/file_management.py 
261
262
263
264
class FileSystemManagementErrorV1(error.ErrorV1):
    """File System Management error response."""

    _GROUP_ID = header.GroupId.FILE_MANAGEMENT

FileSystemManagementErrorV2

Bases: ErrorV2[FS_MGMT_ERR]

File System Management error response.

Source code in smp/file_management.py 
267
268
269
270
class FileSystemManagementErrorV2(error.ErrorV2[FS_MGMT_ERR]):
    """File System Management error response."""

    _GROUP_ID = header.GroupId.FILE_MANAGEMENT