默认/OS 管理组

OS 管理组定义了以下命令：

`Command ID`	命令描述
`0`	Echo
`1`	控制台/终端回显控制；Zephyr 未实现
`2`	任务统计
`3`	内存池统计
`4`	日期时间字符串
`5`	系统复位
`6`	MCUMGR 参数
`7`	OS/应用信息
`8`	Bootloader 信息

Echo 命令

Echo 命令通过回传其接收到的字符串来进行响应。

Echo 请求

Echo 请求头部字段：

`OP`	`Group ID`	`Command ID`
`0` 或 `2`	`0`	`0`

请求的 CBOR 数据：

{
    (str)"d" : (str)
}

其中：

“d”	echo 服务回传的字符串。

Echo 响应

Echo 响应头部字段：

`OP`	`Group ID`	`Command ID`	说明
`1`	`0`	`0`	当请求 `OP` 为 `0` 时
`3`	`0`	`0`	当请求 `OP` 为 `2` 时

成功响应的 CBOR 数据：

{
    (str)"r"        : (str)
}

出错时，CBOR 数据的形式如下：

{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}

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

其中：

“r”	回传的 echo 字符串。
“err” -> “group”	`mcumgr_group_t` 基于分组的错误码所属的组。仅在使用 SMP 版本 2 且返回错误时出现。
“err” -> “rc”	包含基于分组的错误码的索引。仅在使用 SMP 版本 2 且该值非零（错误状态）时出现。
“rc”	`mcumgr_err_t`，仅在使用 SMP 版本 1 且该值非零（错误状态）时出现，或在使用 SMP 版本 2 且出现 SMP 错误时出现。

任务统计命令

该命令返回一些系统统计信息。

任务统计请求

任务统计请求头部字段：

`OP`	`Group ID`	`Command ID`
`0`	`0`	`2`

该命令发送一个空的 CBOR 映射作为数据。

任务统计响应

任务统计响应头部字段：

`OP`	`Group ID`	`Command ID`
`1`	`0`	`2`

成功响应的 CBOR 数据：

{
    (str)"tasks" : {
        (str)<task_name> : {
            (str)"prio"         : (uint)
            (str)"tid"          : (uint)
            (str)"state"        : (uint)
            (str)"stkuse"       : (uint)
            (str)"stksiz"       : (uint)
            (str)"cswcnt"       : (uint)
            (str)"runtime"      : (uint)
            (str)"last_checkin" : (uint)
            (str)"next_checkin" : (uint)
        }
        ...
    }
}

出错时，CBOR 数据的形式如下：

{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}

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

其中：

<task_name>	标识任务的字符串。
“prio”	任务优先级。
“tid”	数字形式的任务 ID。
“state”	数字形式的任务状态。
“stkuse”	任务/线程的栈使用量。
“stksiz”	任务/线程的栈大小。
“cswcnt”	任务/线程的上下文切换次数。
“runtime”	任务/线程以“ticks”为单位的运行时间。
“last_checkin”	由 Zephyr 设为 0。
“next_checkin”	由 Zephyr 设为 0。
“err” -> “group”	`mcumgr_group_t` 基于分组的错误码所属的组。仅在使用 SMP 版本 2 且返回错误时出现。
“err” -> “rc”	包含基于分组的错误码的索引。仅在使用 SMP 版本 2 且该值非零（错误状态）时出现。
“rc”	`mcumgr_err_t`，仅在使用 SMP 版本 1 且该值非零（错误状态）时出现，或在使用 SMP 版本 2 且出现 SMP 错误时出现。

备注

“stkuse”和“stksiz”的单位取决于系统；在 Zephyr 中为 4 字节字的数量。

Memory pool statistics

该命令用于获取正在运行系统中活动内存池的信息。

内存池统计请求

内存池统计请求头部字段：

`OP`	`Group ID`	`Command ID`
`0`	`0`	`3`

该命令发送一个空的 CBOR 映射作为数据。

内存池统计响应

内存池统计响应头部字段：

`OP`	`Group ID`	`Command ID`
`1`	`0`	`3`

成功响应的 CBOR 数据：

{
    (str)<pool_name> {
        (str)"blksiz"   : (int)
        (str)"nblks"    : (int)
        (str)"nfree"    : (int)
        (str)"min'      : (int)
    }
    ...
}

出错时，CBOR 数据的形式如下：

{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}

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

其中：

<pool_name>	表示内存池名称的字符串，用作内存池统计数据字典的键。
“blksiz”	内存池中内存块的大小。
“nblks”	内存池中的块数量。
“nfree”	空闲块数量。
“min”	运行期间内存池达到的最小空闲块数量。
“err” -> “group”	`mcumgr_group_t` 基于分组的错误码所属的组。仅在使用 SMP 版本 2 且返回错误时出现。
“err” -> “rc”	包含基于分组的错误码的索引。仅在使用 SMP 版本 2 且该值非零（错误状态）时出现。
“rc”	`mcumgr_err_t`，仅在使用 SMP 版本 1 且该值非零（错误状态）时出现，或在使用 SMP 版本 2 且出现 SMP 错误时出现。

日期时间命令

该命令用于获取表示设备上当前日期时间的字符串，或为设备设置新时间。设置和获取操作使用的时间格式为：

“yyyy-MM-dd'T'HH:mm:ss.SSSSSSZZZZZ”

获取日期时间

该命令用于从设备获取日期时间。

获取日期时间请求

日期时间请求头部字段：

`OP`	`Group ID`	`Command ID`
`0`	`0`	`4`

该命令发送一个空的 CBOR 映射作为数据。

获取日期时间响应

获取日期时间响应头部字段：

`OP`	`Group ID`	`Command ID`
`1`	`0`	`4`

成功响应的 CBOR 数据：

{
    (str)"datetime" : (str)
}

出错时，CBOR 数据的形式如下：

{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}

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

其中：

“datetime”	格式为 `yyyy-MM-dd'T'HH:mm:ss.SSSSSSZZZZZ` 的字符串。
“err” -> “group”	`mcumgr_group_t` 基于分组的错误码所属的组。仅在使用 SMP 版本 2 且返回错误时出现。
“err” -> “rc”	包含基于分组的错误码的索引。仅在使用 SMP 版本 2 且该值非零（错误状态）时出现。
“rc”	`mcumgr_err_t`，仅在使用 SMP 版本 1 且该值非零（错误状态）时出现，或在使用 SMP 版本 2 且出现 SMP 错误时出现。

设置日期时间

该命令用于为设备设置日期时间。

设置日期时间请求

设置日期时间请求头部字段：

`OP`	`Group ID`	`Command ID`
`2`	`0`	`4`

响应的 CBOR 数据：

{
    (str)"datetime" : (str)
}

其中：

“datetime”

格式为 yyyy-MM-dd'T'HH:mm:ss.SSSSSSZZZZZ 的字符串。

设置日期时间响应

设置日期时间响应头部字段：

`OP`	`Group ID`	`Command ID`
`3`	`0`	`4`

成功时，该命令发送一个空的 CBOR 映射作为数据。出错时，CBOR 数据的形式如下：

{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}

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

其中：

“err” -> “group”	`mcumgr_group_t` 基于分组的错误码所属的组。仅在使用 SMP 版本 2 且返回错误时出现。
“err” -> “rc”	包含基于分组的错误码的索引。仅在使用 SMP 版本 2 且该值非零（错误状态）时出现。
“rc”	`mcumgr_err_t`，仅在使用 SMP 版本 1 且该值非零（错误状态）时出现，或在使用 SMP 版本 2 且出现 SMP 错误时出现。

System reset

执行系统复位。设备应在复位前发出响应，以便 SMP 客户端能够收到命令已被接受的信息。默认情况下，该命令在所有条件下都会被接受；但如果启用了 CONFIG_MCUMGR_GRP_OS_RESET_HOOK 且应用注册了回调，则在发出该命令时会调用该回调，可用于在模块重启之前执行必要的清理操作，或直接以错误响应拒绝复位请求。有关此功能的详细信息，请参见 MCUmgr 回调。

系统复位请求

系统复位请求头部字段：

`OP`	`Group ID`	`Command ID`
`2`	`0`	`5`

通常该命令发送一个空的 CBOR 映射作为数据；但如果上一次复位尝试返回的 “rc” 等于 MGMT_ERR_EBUSY，则可以发送以下映射以强制复位：

{
    (opt)"force"       : (int)
    (opt)"boot_mode"   : (uint)
}

其中：

“force”	值大于 0 时强制复位，为 0 时可选。
“boot_mode”	指定映像或应用的启动模式/选择，需要启用 `CONFIG_MCUMGR_GRP_OS_RESET_BOOT_MODE`。

系统复位响应

系统复位响应头部字段

`OP`	`Group ID`	`Command ID`
`3`	`0`	`5`

成功时，该命令发送一个空的 CBOR 映射作为数据。出错时，CBOR 数据的形式如下：

{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}

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

其中：

“err” -> “group”	`mcumgr_group_t` 基于分组的错误码所属的组。仅在使用 SMP 版本 2 且返回错误时出现。
“err” -> “rc”	包含基于分组的错误码的索引。仅在使用 SMP 版本 2 且该值非零（错误状态）时出现。
“rc”	`mcumgr_err_t`，仅在使用 SMP 版本 1 且该值非零（错误状态）时出现，或在使用 SMP 版本 2 且出现 SMP 错误时出现。

MCUmgr 参数

用于获取 mcumgr 库的参数。

MCUmgr 参数请求

MCUmgr 参数请求头部字段：

`OP`	`Group ID`	`Command ID`
`0`	`0`	`6`

该命令发送一个空的 CBOR 映射作为数据。

MCUmgr 参数响应

MCUmgr 参数响应头部字段

`OP`	`Group ID`	`Command ID`
`1`	`0`	`6`

成功响应的 CBOR 数据：

{
    (str)"buf_size"     : (uint)
    (str)"buf_count"    : (uint)
}

出错时，CBOR 数据的形式如下：

{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}

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

其中：

“buf_size”	单个 SMP 缓冲区的大小，包含 SMP 头部和 CBOR 载荷。
“buf_count”	支持的 SMP 缓冲区数量。
“err” -> “group”	`mcumgr_group_t` 基于分组的错误码所属的组。仅在使用 SMP 版本 2 且返回错误时出现。
“err” -> “rc”	包含基于分组的错误码的索引。仅在使用 SMP 版本 2 且该值非零（错误状态）时出现。
“rc”	`mcumgr_err_t`，仅在使用 SMP 版本 1 且该值非零（错误状态）时出现，或在使用 SMP 版本 2 且出现 SMP 错误时出现。

OS/应用信息

用于获取正在运行的映像的信息，功能类似于 Linux 的 uname 命令，可以返回内核名称、内核版本、构建日期/时间、处理器类型以及应用定义的详细信息。可通过 CONFIG_MCUMGR_GRP_OS_INFO 启用此功能。

OS/应用信息请求

OS/应用信息请求头部字段：

`OP`	`Group ID`	`Command ID`
`0`	`0`	`7`

请求的 CBOR 数据：

{
    (str,opt)"format"      : (str)
}

其中：

“format”

返回响应的格式说明符，各字段按其索引自然升序追加，而不是按命令接收字符的顺序追加。格式说明符：
* s 内核名称
* n 节点名称
* r 内核发行版
* v 内核版本
* b 构建日期和时间（需要 CONFIG_MCUMGR_GRP_OS_INFO_BUILD_DATE_TIME）|br| * m 机器
* p 处理器
* i 硬件平台
* o 操作系统
* a 所有字段（以上所有选项的简写）|br| 如果未提供此选项，将使用 s 内核名称选项。

OS/应用信息响应

OS/应用信息响应头部字段

`OP`	`Group ID`	`Command ID`
`1`	`0`	`7`

成功响应的 CBOR 数据：

{
    (str)"output"       : (str)
}

出错时，CBOR 数据的形式如下：

{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}

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

其中：

“output”	包含所请求参数的文本响应。
“err” -> “group”	`mcumgr_group_t` 基于分组的错误码所属的组。仅在使用 SMP 版本 2 且返回错误时出现。
“err” -> “rc”	包含基于分组的错误码的索引。仅在使用 SMP 版本 2 且该值非零（错误状态）时出现。
“rc”	`mcumgr_err_t`，仅在使用 SMP 版本 1 且该值非零（错误状态）时出现，或在使用 SMP 版本 2 且出现 SMP 错误时出现。

Bootloader 信息

允许获取板载 bootloader 及其参数的信息。

Bootloader 信息请求

Bootloader 信息请求头部：

`OP`	`Group ID`	`Command ID`
`0`	`0`	`8`

请求的 CBOR 数据：

{
    (str,opt)"query"  : (str)
}

其中：

“query”

表示参数查询的字符串；对查询的形式没有限制，因为查询的处理由 bootloader 后端负责。如果没有查询，则响应将返回标识 bootloader 的字符串。

Bootloader 信息响应

Bootloader 信息响应头部：

`OP`	`Group ID`	`Command ID`
`1`	`0`	`8`

当请求中未提供“query”时，响应的 CBOR 数据为：

{
    (str)"bootloader"      : (str)
}

其中：

“bootloader”

表示 bootloader 名称的字符串

当提供了“query”时：

{
    (str,opt)<response>   : ()
    ...
}

其中：

<response>	对“query”的响应。此项为可选，当查询没有返回结果时可以省略，此时预期使用 OS_MGMT_ERR_QUERY_YIELDS_NO_ANSWER SMP 版本 2 错误码。响应可能返回多个参数，也可能是一个映射，具体取决于 bootloader 后端和查询。
...	参数特性信息。

参数可以附带额外的、特定于参数的信息关键字及赋给它们的值。

出错时，CBOR 数据的形式如下：

{
    (str)"err" : {
        (str)"group"    : (uint)
        (str)"rc"       : (uint)
    }
}

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

其中：

“err” -> “group”	`mcumgr_group_t` 基于分组的错误码所属的组。仅在使用 SMP 版本 2 且返回错误时出现。
“err” -> “rc”	包含基于分组的错误码的索引。仅在使用 SMP 版本 2 且该值非零（错误状态）时出现。
“rc”	`mcumgr_err_t`，仅在使用 SMP 版本 1 且该值非零（错误状态）时出现，或在使用 SMP 版本 2 且出现 SMP 错误时出现。

Bootloader 信息：MCUboot

当 MCUboot 作为应用 bootloader 时，对空请求的响应为：

{
    (str)"bootloader"      : (str)"MCUboot"
}

目前“MCUboot”支持查询运行模式：

{
    (str)"query"           : (str)"mode"
}

对“mode”的响应为：

{
    (str)"mode"                     : (int)
    (str,opt)"no-downgrade"         : (bool)
}

其中“mode”为以下之一：

-1	未知的 MCUboot 模式。
0	MCUboot 处于单应用模式。
1	MCUboot 处于使用 scratch 分区的交换模式。
2	MCUboot 处于覆盖（仅升级）模式。
3	MCUboot 处于无 scratch 的交换模式。
4	MCUboot 处于不带 revert 的 DirectXIP 模式。
5	MCUboot 处于带 revert 的 DirectXIP 模式。
6	MCUboot 处于 RAM 加载器模式。

no-downgrade 字段是一个标志，为 true 时总会发送，表示 MCUboot 已启用降级防护；降级防护是指，如果上传的映像版本低于当前运行的应用版本，MCUboot 将不会使用它进行更新。

在此配置下，MCUmgr 可能会拒绝版本较低的映像。