Skip to content

OS Management

The Simple Management Protocol (SMP) OS Management group.

AnyBootloaderInformationReadResponse: TypeAlias = BootloaderInformationReadResponse | MCUbootModeReadResponse module-attribute

The bootloader information response variants, one per request.

EchoWriteRequest

Bases: WriteRequest

Echo back the provided string.

Source code in src/smp/os_management.py 
14
15
16
17
18
19
20
21
class EchoWriteRequest(message.WriteRequest):
    """Echo back the provided string."""

    _GROUP_ID = header.GroupId.OS_MANAGEMENT
    _COMMAND_ID = header.CommandId.OSManagement.ECHO

    d: str
    """String to echo."""

d: str instance-attribute

String to echo.

EchoWriteResponse

Bases: WriteResponse

Success response to an echo request.

Source code in src/smp/os_management.py 
24
25
26
27
28
29
30
31
class EchoWriteResponse(message.WriteResponse):
    """Success response to an echo request."""

    _GROUP_ID = header.GroupId.OS_MANAGEMENT
    _COMMAND_ID = header.CommandId.OSManagement.ECHO

    r: str
    """Echoed string."""

r: str instance-attribute

Echoed string.

BootMode

Bases: IntEnum

Boot mode requested by the OS management reset command.

Mirrors Zephyr's enum BOOT_MODE_TYPES in include/zephyr/retention/bootmode.h.

Source code in src/smp/os_management.py 
34
35
36
37
38
39
40
41
42
43
44
45
46
@unique
class BootMode(IntEnum):
    """Boot mode requested by the OS management reset command.

    Mirrors Zephyr's `enum BOOT_MODE_TYPES` in
    `include/zephyr/retention/bootmode.h`.
    """

    NORMAL = 0
    """Default (normal) boot, to the user application."""

    BOOTLOADER = 1
    """Bootloader boot mode, e.g. serial recovery for MCUboot."""

NORMAL = 0 class-attribute instance-attribute

Default (normal) boot, to the user application.

BOOTLOADER = 1 class-attribute instance-attribute

Bootloader boot mode, e.g. serial recovery for MCUboot.

ResetWriteRequest

Bases: WriteRequest

Performs reset of system.

The device should issue response before resetting so that the SMP client could receive information that the command has been accepted. By default, this command is accepted in all conditions, however if the CONFIG_MCUMGR_GRP_OS_RESET_HOOK is enabled and an application registers a callback, the callback will be called when this command is issued and can be used to perform any necessary tidy operations prior to the module rebooting, or to reject the reset request outright altogether with an error response.

For details on this functionality, see callbacks. # noqa: E501

Source code in src/smp/os_management.py 
49
50
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
80
81
82
83
84
85
86
87
88
class ResetWriteRequest(message.WriteRequest):
    """Performs reset of system.

    The device should issue response before resetting so that the SMP client
    could receive information that the command has been accepted. By default,
    this command is accepted in all conditions, however if the
    `CONFIG_MCUMGR_GRP_OS_RESET_HOOK` is enabled and an application registers a
    callback, the callback will be called when this command is issued and can be
    used to perform any necessary tidy operations prior to the module rebooting,
    or to reject the reset request outright altogether with an error response.

    For details on this functionality, see [callbacks](https://docs.zephyrproject.org/latest/services/device_mgmt/mcumgr_callbacks.html#mcumgr-callbacks).  # noqa: E501
    """

    _GROUP_ID = header.GroupId.OS_MANAGEMENT
    _COMMAND_ID = header.CommandId.OSManagement.RESET

    force: Literal[0, 1] | None = None
    """Force reset.

    Normally the command sends an empty CBOR map as data, but if a previous
    reset attempt has responded with “rc” equal to MGMT_ERR_EBUSY then the
    following map may be sent to force a reset
    """

    boot_mode: BootMode | Annotated[int, Field(ge=0, le=255)] | None = Field(
        default=None, union_mode="left_to_right"
    )
    """Boot mode to set via the retention boot mode module before resetting.

    A value of `BootMode.BOOTLOADER` (1) requests, for example, that an MCUboot
    built with `CONFIG_BOOT_SERIAL_BOOT_MODE` enter serial recovery on the next
    boot. The server casts the value to a `uint8_t`, so any value in `[0, 255]`
    is accepted and passed to `bootmode_set()`; known values are surfaced as
    `BootMode` members.

    Requires the server to be built with `CONFIG_MCUMGR_GRP_OS_RESET_BOOT_MODE`,
    which depends on `CONFIG_RETENTION_BOOT_MODE`. Added to the SMP OS
    management group in Zephyr v4.2.0 (zephyrproject-rtos/zephyr#91510).
    """

force: Literal[0, 1] | None = None class-attribute instance-attribute

Force reset.

Normally the command sends an empty CBOR map as data, but if a previous reset attempt has responded with “rc” equal to MGMT_ERR_EBUSY then the following map may be sent to force a reset

boot_mode: BootMode | Annotated[int, Field(ge=0, le=255)] | None = Field(default=None, union_mode='left_to_right') class-attribute instance-attribute

Boot mode to set via the retention boot mode module before resetting.

A value of BootMode.BOOTLOADER (1) requests, for example, that an MCUboot built with CONFIG_BOOT_SERIAL_BOOT_MODE enter serial recovery on the next boot. The server casts the value to a uint8_t, so any value in [0, 255] is accepted and passed to bootmode_set(); known values are surfaced as BootMode members.

Requires the server to be built with CONFIG_MCUMGR_GRP_OS_RESET_BOOT_MODE, which depends on CONFIG_RETENTION_BOOT_MODE. Added to the SMP OS management group in Zephyr v4.2.0 (zephyrproject-rtos/zephyr#91510).

ResetWriteResponse

Bases: WriteResponse

Success response to a reset request.

Source code in src/smp/os_management.py 
91
92
93
94
95
class ResetWriteResponse(message.WriteResponse):
    """Success response to a reset request."""

    _GROUP_ID = header.GroupId.OS_MANAGEMENT
    _COMMAND_ID = header.CommandId.OSManagement.RESET

TaskStatisticsReadRequest

Bases: ReadRequest

Request task statistics.

Source code in src/smp/os_management.py 
 98
 99
100
101
102
class TaskStatisticsReadRequest(message.ReadRequest):
    """Request task statistics."""

    _GROUP_ID = header.GroupId.OS_MANAGEMENT
    _COMMAND_ID = header.CommandId.OSManagement.TASK_STATS

TaskStatistics

Bases: BaseModel

Task statistics.

Source code in src/smp/os_management.py 
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
class TaskStatistics(BaseModel):
    """Task statistics."""

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

    prio: int
    """Task priority."""
    tid: int
    """Numeric task ID."""
    state: int
    """Numeric task state."""
    stkuse: int
    """Stack usage.

    The unit is system dependent and in case of Zephyr this is number of 4 byte words.
    """
    stksiz: int
    """Stack size.

    The unit is system dependent and in case of Zephyr this is number of 4 byte words.
    """
    cswcnt: int
    """Number of context switches."""
    runtime: int
    """Runtime in ticks."""
    last_checkin: int
    """Set to 0 by Zephyr."""
    next_checkin: int
    """Set to 0 by Zephyr."""

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

prio: int instance-attribute

Task priority.

tid: int instance-attribute

Numeric task ID.

state: int instance-attribute

Numeric task state.

stkuse: int instance-attribute

Stack usage.

The unit is system dependent and in case of Zephyr this is number of 4 byte words.

stksiz: int instance-attribute

Stack size.

The unit is system dependent and in case of Zephyr this is number of 4 byte words.

cswcnt: int instance-attribute

Number of context switches.

runtime: int instance-attribute

Runtime in ticks.

last_checkin: int instance-attribute

Set to 0 by Zephyr.

next_checkin: int instance-attribute

Set to 0 by Zephyr.

TaskStatisticsZephyr

Bases: BaseModel

Task statistics for Zephyr when CONFIG_MCUMGR_GRP_OS_TASKSTAT_ONLY_SUPPORTED_STATS=y.

In this configuration, Zephyr may omit fields that are not supported by the underlying RTOS. Only prio, tid, and state are guaranteed to be present.

Source code in src/smp/os_management.py 
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
class TaskStatisticsZephyr(BaseModel):
    """Task statistics for Zephyr when CONFIG_MCUMGR_GRP_OS_TASKSTAT_ONLY_SUPPORTED_STATS=y.

    In this configuration, Zephyr may omit fields that are not supported by the underlying RTOS.
    Only prio, tid, and state are guaranteed to be present.
    """

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

    prio: int
    """Task priority."""
    tid: int
    """Numeric task ID."""
    state: int
    """Numeric task state."""
    stkuse: int | None = None
    """Stack usage.

    The unit is system dependent and in case of Zephyr this is number of 4 byte words.
    """
    stksiz: int | None = None
    """Stack size.

    The unit is system dependent and in case of Zephyr this is number of 4 byte words.
    """
    cswcnt: int | None = None
    """Number of context switches."""
    runtime: int | None = None
    """Runtime in ticks."""
    last_checkin: int | None = None
    """Set to 0 by Zephyr."""
    next_checkin: int | None = None
    """Set to 0 by Zephyr."""

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

prio: int instance-attribute

Task priority.

tid: int instance-attribute

Numeric task ID.

state: int instance-attribute

Numeric task state.

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

Stack usage.

The unit is system dependent and in case of Zephyr this is number of 4 byte words.

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

Stack size.

The unit is system dependent and in case of Zephyr this is number of 4 byte words.

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

Number of context switches.

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

Runtime in ticks.

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

Set to 0 by Zephyr.

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

Set to 0 by Zephyr.

TaskStatisticsReadResponse

Bases: ReadResponse

Task statistics response.

Source code in src/smp/os_management.py 
171
172
173
174
175
176
177
178
class TaskStatisticsReadResponse(message.ReadResponse):
    """Task statistics response."""

    _GROUP_ID = header.GroupId.OS_MANAGEMENT
    _COMMAND_ID = header.CommandId.OSManagement.TASK_STATS

    tasks: dict[str, TaskStatistics | TaskStatisticsZephyr]
    """Task statistics map."""

tasks: dict[str, TaskStatistics | TaskStatisticsZephyr] instance-attribute

Task statistics map.

MemoryPoolStatisticsReadRequest

Bases: ReadRequest

Request memory pool statistics.

Source code in src/smp/os_management.py 
181
182
183
184
185
class MemoryPoolStatisticsReadRequest(message.ReadRequest):
    """Request memory pool statistics."""

    _GROUP_ID = header.GroupId.OS_MANAGEMENT
    _COMMAND_ID = header.CommandId.OSManagement.MEMORY_POOL_STATS

MemoryPoolStatistics

Bases: BaseModel

Memory pool statistics.

Source code in src/smp/os_management.py 
188
189
190
191
192
193
194
195
196
197
198
199
200
class MemoryPoolStatistics(BaseModel):
    """Memory pool statistics."""

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

    blksize: int
    """Size of the memory block in the pool."""
    nblks: int
    """Number of memory blocks in the pool."""
    nfree: int
    """Number of free memory blocks in the pool."""
    min: int
    """Lowest number of free blocks the pool reached during run-time."""

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

blksize: int instance-attribute

Size of the memory block in the pool.

nblks: int instance-attribute

Number of memory blocks in the pool.

nfree: int instance-attribute

Number of free memory blocks in the pool.

min: int instance-attribute

Lowest number of free blocks the pool reached during run-time.

MemoryPoolStatisticsReadResponse

Bases: ReadResponse

The memory pools are accessed by name.

Source code in src/smp/os_management.py 
203
204
205
206
207
208
209
class MemoryPoolStatisticsReadResponse(message.ReadResponse):
    """The memory pools are accessed by name."""

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

    _GROUP_ID = header.GroupId.OS_MANAGEMENT
    _COMMAND_ID = header.CommandId.OSManagement.MEMORY_POOL_STATS

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

DateTimeReadRequest

Bases: ReadRequest

Request the current date and time.

Source code in src/smp/os_management.py 
212
213
214
215
216
class DateTimeReadRequest(message.ReadRequest):
    """Request the current date and time."""

    _GROUP_ID = header.GroupId.OS_MANAGEMENT
    _COMMAND_ID = header.CommandId.OSManagement.DATETIME_STRING

DateTimeReadResponse

Bases: ReadResponse

Response to a date and time request.

Source code in src/smp/os_management.py 
219
220
221
222
223
224
225
class DateTimeReadResponse(message.ReadResponse):
    """Response to a date and time request."""

    _GROUP_ID = header.GroupId.OS_MANAGEMENT
    _COMMAND_ID = header.CommandId.OSManagement.DATETIME_STRING

    datetime: str

datetime: str instance-attribute

DateTimeWriteRequest

Bases: WriteRequest

Set the current date and time.

Source code in src/smp/os_management.py 
228
229
230
231
232
233
234
class DateTimeWriteRequest(message.WriteRequest):
    """Set the current date and time."""

    _GROUP_ID = header.GroupId.OS_MANAGEMENT
    _COMMAND_ID = header.CommandId.OSManagement.DATETIME_STRING

    datetime: str

datetime: str instance-attribute

DateTimeWriteResponse

Bases: WriteResponse

Success response to a date and time request.

Source code in src/smp/os_management.py 
237
238
239
240
241
class DateTimeWriteResponse(message.WriteResponse):
    """Success response to a date and time request."""

    _GROUP_ID = header.GroupId.OS_MANAGEMENT
    _COMMAND_ID = header.CommandId.OSManagement.DATETIME_STRING

MCUMgrParametersReadRequest

Bases: ReadRequest

Request MCU Manager parameters.

Source code in src/smp/os_management.py 
244
245
246
247
248
class MCUMgrParametersReadRequest(message.ReadRequest):
    """Request MCU Manager parameters."""

    _GROUP_ID = header.GroupId.OS_MANAGEMENT
    _COMMAND_ID = header.CommandId.OSManagement.MCUMGR_PARAMETERS

MCUMgrParametersReadResponse

Bases: ReadResponse

Success response to a MCU Manager parameters request.

Source code in src/smp/os_management.py 
251
252
253
254
255
256
257
258
259
260
class MCUMgrParametersReadResponse(message.ReadResponse):
    """Success response to a MCU Manager parameters request."""

    _GROUP_ID = header.GroupId.OS_MANAGEMENT
    _COMMAND_ID = header.CommandId.OSManagement.MCUMGR_PARAMETERS

    buf_size: int
    """Single SMP buffer size, this includes SMP header and CBOR payload."""
    buf_count: int
    """Number of SMP buffers."""

buf_size: int instance-attribute

Single SMP buffer size, this includes SMP header and CBOR payload.

buf_count: int instance-attribute

Number of SMP buffers.

OSApplicationInfoReadRequest

Bases: ReadRequest

Request information about the application running on the device.

Source code in src/smp/os_management.py 
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
class OSApplicationInfoReadRequest(message.ReadRequest):
    """Request information about the application running on the device."""

    _GROUP_ID = header.GroupId.OS_MANAGEMENT
    _COMMAND_ID = header.CommandId.OSManagement.OS_APPLICATION_INFO

    format: str | None = None
    """Format specifier of returned response.

    Fields are appended in their natural ascending index order, not the order
    of characters that are received by the command.

    Format specifiers:
    * `s` Kernel name
    * `n` Node name
    * `r` Kernel release
    * `v` Kernel version
    * `b` Build date and time (requires `CONFIG_MCUMGR_GRP_OS_INFO_BUILD_DATE_TIME`)
    * `m` Machine
    * `p` Processor
    * `i` Hardware platform
    * `o` Operating system
    * `a` All fields (shorthand for all above options)

    If this option is not provided, the `s` Kernel name option will be used.
    """

format: str | None = None class-attribute instance-attribute

Format specifier of returned response.

Fields are appended in their natural ascending index order, not the order of characters that are received by the command.

Format specifiers: * s Kernel name * n Node name * r Kernel release * v Kernel version * b Build date and time (requires CONFIG_MCUMGR_GRP_OS_INFO_BUILD_DATE_TIME) * m Machine * p Processor * i Hardware platform * o Operating system * a All fields (shorthand for all above options)

If this option is not provided, the s Kernel name option will be used.

OSApplicationInfoReadResponse

Bases: ReadResponse

Success response to an application information request.

Source code in src/smp/os_management.py 
291
292
293
294
295
296
297
298
class OSApplicationInfoReadResponse(message.ReadResponse):
    """Success response to an application information request."""

    _GROUP_ID = header.GroupId.OS_MANAGEMENT
    _COMMAND_ID = header.CommandId.OSManagement.OS_APPLICATION_INFO

    output: str
    """Text response including requested parameters."""

output: str instance-attribute

Text response including requested parameters.

BootloaderInformationReadRequest

Bases: ReadRequest

Request bootloader information.

Source code in src/smp/os_management.py 
301
302
303
304
305
class BootloaderInformationReadRequest(message.ReadRequest):
    """Request bootloader information."""

    _GROUP_ID = header.GroupId.OS_MANAGEMENT
    _COMMAND_ID = header.CommandId.OSManagement.BOOTLOADER_INFO

BootloaderInformationReadResponse

Bases: ReadResponse

Success response to a bootloader information request.

Source code in src/smp/os_management.py 
308
309
310
311
312
313
314
315
class BootloaderInformationReadResponse(message.ReadResponse):
    """Success response to a bootloader information request."""

    _GROUP_ID = header.GroupId.OS_MANAGEMENT
    _COMMAND_ID = header.CommandId.OSManagement.BOOTLOADER_INFO

    bootloader: str
    """String identifying the bootloader.  For MCUboot it will be "MCUboot"."""

bootloader: str instance-attribute

String identifying the bootloader. For MCUboot it will be "MCUboot".

MCUbootModeReadRequest

Bases: ReadRequest

Request MCUboot's mode of operation.

Source code in src/smp/os_management.py 
318
319
320
321
322
323
324
class MCUbootModeReadRequest(message.ReadRequest):
    """Request MCUboot's mode of operation."""

    _GROUP_ID = header.GroupId.OS_MANAGEMENT
    _COMMAND_ID = header.CommandId.OSManagement.BOOTLOADER_INFO

    query: Literal["mode"]

query: Literal['mode'] instance-attribute

MCUbootMode

Bases: IntEnum

Source code in src/smp/os_management.py 
327
328
329
330
331
332
333
334
335
336
337
338
339
@unique
class MCUbootMode(IntEnum):
    UNKNOWN = -1
    APPLICATION = 0
    SWAP_USING_SCRATCH = 1
    OVERWRITE_ONLY = 2
    SWAP_WITHOUT_SCRATCH = 3
    DIRECT_XIP_WITHOUT_REVERT = 4
    DIRECT_XIP_WITH_REVERT = 5
    RAM_LOADER = 6
    FIRMWARE_LOADER = 7
    SINGLE_SLOT_RAM_LOADER = 8
    SWAP_USING_OFFSET = 9

UNKNOWN = -1 class-attribute instance-attribute

APPLICATION = 0 class-attribute instance-attribute

SWAP_USING_SCRATCH = 1 class-attribute instance-attribute

OVERWRITE_ONLY = 2 class-attribute instance-attribute

SWAP_WITHOUT_SCRATCH = 3 class-attribute instance-attribute

DIRECT_XIP_WITHOUT_REVERT = 4 class-attribute instance-attribute

DIRECT_XIP_WITH_REVERT = 5 class-attribute instance-attribute

RAM_LOADER = 6 class-attribute instance-attribute

FIRMWARE_LOADER = 7 class-attribute instance-attribute

SINGLE_SLOT_RAM_LOADER = 8 class-attribute instance-attribute

SWAP_USING_OFFSET = 9 class-attribute instance-attribute

MCUbootModeReadResponse

Bases: ReadResponse

Success response to an MCUboot mode request.

Source code in src/smp/os_management.py 
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
class MCUbootModeReadResponse(message.ReadResponse):
    """Success response to an MCUboot mode request."""

    model_config = ConfigDict(populate_by_name=True)

    _GROUP_ID = header.GroupId.OS_MANAGEMENT
    _COMMAND_ID = header.CommandId.OSManagement.BOOTLOADER_INFO

    mode: MCUbootMode | Annotated[int, Field(ge=-(2**31), le=2**31 - 1)] = Field(
        union_mode="left_to_right"
    )
    no_downgrade: Literal[True] | None = Field(
        default=None, validation_alias="no-downgrade", serialization_alias="no-downgrade"
    )
    """MCUboot will not update to an image whose version is lower than the running one."""

model_config = ConfigDict(populate_by_name=True) class-attribute instance-attribute

mode: MCUbootMode | Annotated[int, Field(ge=(-2 ** 31), le=(2 ** 31 - 1))] = Field(union_mode='left_to_right') class-attribute instance-attribute

no_downgrade: Literal[True] | None = Field(default=None, validation_alias='no-downgrade', serialization_alias='no-downgrade') class-attribute instance-attribute

MCUboot will not update to an image whose version is lower than the running one.

OS_MGMT_RET_RC

Bases: IntEnum

OS Management return codes.

Source code in src/smp/os_management.py 
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
@unique
class OS_MGMT_RET_RC(IntEnum):
    """OS Management return codes."""

    OK = 0
    """No error, this is implied if there is no ret value in the response."""

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

    INVALID_FORMAT = 2
    """The provided format value is not valid."""

    QUERY_YIELDS_NO_ANSWER = 3
    """Query was not recognized."""

    RTC_NOT_SET = 4
    """RTC is not set."""

    RTC_COMMAND_FAILED = 5
    """RTC command failed."""

OK = 0 class-attribute instance-attribute

No error, this is implied if there is no ret value in the response.

UNKNOWN = 1 class-attribute instance-attribute

Unknown error occurred.

INVALID_FORMAT = 2 class-attribute instance-attribute

The provided format value is not valid.

QUERY_YIELDS_NO_ANSWER = 3 class-attribute instance-attribute

Query was not recognized.

RTC_NOT_SET = 4 class-attribute instance-attribute

RTC is not set.

RTC_COMMAND_FAILED = 5 class-attribute instance-attribute

RTC command failed.

OSManagementErrorV1

Bases: ErrorV1

OS Management error response.

Source code in src/smp/os_management.py 
397
398
399
400
class OSManagementErrorV1(error.ErrorV1):
    """OS Management error response."""

    _GROUP_ID = header.GroupId.OS_MANAGEMENT

OSManagementErrorV2

Bases: ErrorV2[OS_MGMT_RET_RC]

OS Management error response.

Source code in src/smp/os_management.py 
403
404
405
406
class OSManagementErrorV2(error.ErrorV2[OS_MGMT_RET_RC]):
    """OS Management error response."""

    _GROUP_ID = header.GroupId.OS_MANAGEMENT

loads_bootloader_information_response(data: bytes) -> AnyBootloaderInformationReadResponse

Deserialize a bootloader information response as the variant that its payload names.

Source code in src/smp/os_management.py 
365
366
367
368
369
370
371
def loads_bootloader_information_response(data: bytes) -> AnyBootloaderInformationReadResponse:
    """Deserialize a bootloader information response as the variant that its payload names."""
    return (
        MCUbootModeReadResponse.loads(data)
        if "mode" in cbor2.loads(data[header.Header.SIZE :])
        else BootloaderInformationReadResponse.loads(data)
    )