Skip to content

OS Management

The Simple Management Protocol (SMP) OS Management group.

EchoWriteRequest

Bases: WriteRequest

Echo back the provided string.

Source code in smp/os_management.py 
13
14
15
16
17
18
19
20
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 smp/os_management.py 
23
24
25
26
27
28
29
30
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.

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 smp/os_management.py 
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
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
    """

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

ResetWriteResponse

Bases: WriteResponse

Success response to a reset request.

Source code in smp/os_management.py 
59
60
61
62
63
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 smp/os_management.py 
66
67
68
69
70
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 smp/os_management.py 
 73
 74
 75
 76
 77
 78
 79
 80
 81
 82
 83
 84
 85
 86
 87
 88
 89
 90
 91
 92
 93
 94
 95
 96
 97
 98
 99
100
101
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.
    """
    stksize: 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.

stksize: 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.

TaskStatisticsReadResponse

Bases: ReadResponse

Task statistics response.

Source code in smp/os_management.py 
104
105
106
107
108
109
110
111
class TaskStatisticsReadResponse(message.ReadResponse):
    """Task statistics response."""

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

    tasks: Dict[str, TaskStatistics]
    """Task statistics map."""

tasks: Dict[str, TaskStatistics] instance-attribute

Task statistics map.

MemoryPoolStatisticsReadRequest

Bases: ReadRequest

Request memory pool statistics.

Source code in smp/os_management.py 
114
115
116
117
118
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 smp/os_management.py 
121
122
123
124
125
126
127
128
129
130
131
132
133
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 smp/os_management.py 
136
137
138
139
140
141
142
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 smp/os_management.py 
145
146
147
148
149
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 smp/os_management.py 
152
153
154
155
156
157
158
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 smp/os_management.py 
161
162
163
164
165
166
167
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 smp/os_management.py 
170
171
172
173
174
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 smp/os_management.py 
177
178
179
180
181
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 smp/os_management.py 
184
185
186
187
188
189
190
191
192
193
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 smp/os_management.py 
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
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 smp/os_management.py 
224
225
226
227
228
229
230
231
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 smp/os_management.py 
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
class BootloaderInformationReadRequest(message.ReadRequest):
    """Request bootloader information."""

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

    query: str | None = None
    """Is string representing query for parameters.

    With no restrictions how the query looks like as processing of query is left
    for bootloader backend. If there is no query, then response will return string
    identifying the bootloader.

    MCUboot supports the query string,"mode".  The response to mode is of type
    `MCUbootMode`.
    """

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

Is string representing query for parameters.

With no restrictions how the query looks like as processing of query is left for bootloader backend. If there is no query, then response will return string identifying the bootloader.

MCUboot supports the query string,"mode". The response to mode is of type MCUbootMode.

MCUbootMode

Bases: IntEnum

Source code in smp/os_management.py 
252
253
254
255
256
257
258
259
260
261
@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

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

MCUbootModeQueryResponse

Bases: BaseModel

Response to a MCUboot mode query.

Source code in smp/os_management.py 
264
265
266
267
268
269
270
class MCUbootModeQueryResponse(BaseModel):
    """Response to a MCUboot mode query."""

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

    mode: MCUbootMode
    no_downgrade: bool | None = Field(alias="no-downgrade", default=None)

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

mode: MCUbootMode instance-attribute

no_downgrade: bool | None = Field(alias='no-downgrade', default=None) class-attribute instance-attribute

BootloaderInformationReadResponse

Bases: ReadResponse

Success response to a bootloader information request.

Source code in smp/os_management.py 
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
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"."""
    response: MCUbootModeQueryResponse | Any | None = None
    """Response to “query”.

    This is optional and may be left out in case when query yields no response,
    SMP version 2 error code of `OS_MGMT_ERR_QUERY_YIELDS_NO_ANSWER` is
    expected. Response may have more than one parameter reported back or it may
    be a map, that is dependent on bootloader backend and query."""

bootloader: str instance-attribute

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

response: MCUbootModeQueryResponse | Any | None = None class-attribute instance-attribute

Response to “query”.

This is optional and may be left out in case when query yields no response, SMP version 2 error code of OS_MGMT_ERR_QUERY_YIELDS_NO_ANSWER is expected. Response may have more than one parameter reported back or it may be a map, that is dependent on bootloader backend and query.

OS_MGMT_RET_RC

Bases: IntEnum

OS Management return codes.

Source code in smp/os_management.py 
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
@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 smp/os_management.py 
313
314
315
316
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 smp/os_management.py 
319
320
321
322
class OSManagementErrorV2(error.ErrorV2[OS_MGMT_RET_RC]):
    """OS Management error response."""

    _GROUP_ID = header.GroupId.OS_MANAGEMENT