Application/software image management group

Application/software image management management group defines following commands:

`Command ID`	Command description
`0`	State of images
`1`	Image upload
`2`	File (reserved but not supported by Zephyr)
`3`	Corelist (reserved but not supported by Zephyr)
`4`	Coreload (reserved but not supported by Zephyr)
`5`	Image erase

Notion of “slots” and “images” in Zephyr

The “slot” and “image” definition comes from mcuboot where “image” would consist of two “slots”, further named “primary” and “secondary”; the application is supposed to run from the “primary slot” and update is supposed to be uploaded to the “secondary slot”; the mcuboot is responsible in swapping slots on boot. This means that pair of slots is dedicated to single upgradable application. In case of Zephyr this gets a little bit confusing because DTS will use “slot0_partition” and “slot1_partition”, as label of fixed-partition dedicated to single application, but will name them as “image-0” and “image-1” respectively.

Currently Zephyr supports at most two images, in which case mapping is as follows:

Image	Slot labels	Slot Names
1	“slot0_partition” “slot1_partition”	“image-0” “image-1”
2	“slot2_partition” “slot3_partition”	“image-2” “image-3”

State of images

The command is used to set state of images and obtain list of images with their current state.

Get state of images request

Get state of images request header fields:

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

The command sends sends empty CBOR map as data.

Get state of images response

Get state of images response header fields:

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

Note

Below definition of the response contains “image” field that has been marked as optional(opt): the field may not appear in response when target application does not support more than one image. The field is mandatory when application supports more than one application image to allow identifying which image information is listed.

A response will only contain information for valid images, if an image can not be identified as valid it is simply skipped.

CBOR data of successful response:

{
    (str)"images" : [
        {
            (str,opt)"image"        : (int)
            (str)"slot"             : (int)
            (str)"version"          : (str)
            (str)"hash"             ; (str)
            (str,opt)"bootable"     : (bool)
            (str,opt)"pending"      : (bool)
            (str,opt)"confirmed"    : (bool)
            (str,opt)"active"       : (bool)
            (str,opt)"permanent"    : (bool)
        }
        ...
    ]
    (str,opt)"splitStatus" : (int)
}

In case of error the CBOR data takes form:

{
    (str)"rc" : (int)
    (str,opt)"rsn" : (str)
}

where:

“image”	semi-optional image number; the field is not required when only one image is supported by running application
“slot”	slot number within “image”; each image has two slots : primary (running one) = 0 and secondary (for DFU dual-bank purposes) = 1
“version”	string representing image version, as set with `imgtool`
“hash”	hash of an upload; this is used to identify an upload session, for example to allow mcumgr library to continue broken session Note By default mcumgr-cli uses here a few characters of sha256 of the first uploaded chunk.
“bootable”	true if image has bootable flag set; this field does not have to be present if false
“pending”	true if image is set for next swap this field does not have to be present if false
“confirmed”	true if image has been confirmed this field does not have to be present if false
“active”	true if image is currently active application this field does not have to be present if false
“permanent”	true if image is to stay in primary slot after next boot this field does not have to be present if false
“splitStatus”	states whether loader of split image is compatible with application part; this is unused by Zephyr
“rc”	Status/error codes in responses
“rsn”	optional string that clarifies reason for an error; specifically useful for error code `1`, unknown error

Note

For more information on how does image/slots function, please refer to the MCUBoot documentation https://www.mcuboot.com/documentation/design/#image-slots

Set state of image request

Set state of image request header fields:

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

CBOR data of request:

{
    {
        (str,opt)"hash"     : (str)
        (str)"confirm"      : (bool)
    }
}

If “confirm” is false an image with the “hash” will be set for test, which means that it will not be marked as permanent and upon hard reset the previous application will be restored to the primary slot. In case when “confirm” is true, the “hash” is optional as the currently running application will be assumed as target for confirmation.

Set state of image response

The response takes the same format as Get state of images response

Image upload

The image upload command allows to update application image.

Image upload request

The image upload request is sent for each chunk of image that is uploaded, until complete image gets uploaded to a device.

Set state of image request header fields:

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

CBOR data of request:

{
    {
        (str,opt)"image"    : (uint)
        (str,opt)"len"      : (uint)
        (str)"off"          : (uint)
        (str,opt)"sha"      : (str)
        (str,opt)"data"     : (byte str)
        (str,opt)"upgrade"  : (bool)
    }
}

where:

“image”	optional image number, it does not have to appear in request at all, in which case it is assumed to be 0; only request with “off” 0 can contain image number
“len”	optional length of an image, it only appears in the first packet of request, where “off” is 0
“off”	offset of image chunk the request carries
“sha”	string identifying update session; it should only be present if “off” is zero; although name suggests it might be SHA, it can actually be any string
“data”	optional image data
“upgrade”	optional flag that states that only upgrade should be allowed, so if version of uploaded software is lower then already on device, the image update should be rejected (unused by Zephyr at this time)

Note

There is no field representing size of chunk that is carried as “data” because that information is embedded within “data” field itself.

The mcumgr library uses “sha” field to tag ongoing update session, to be able to continue it in case when it gets broken. If library gets request with “off” equal zero it checks stored “sha” within its state and if it matches it will respond to update client application with offset that it should continue with.

Image upload response

Set state of image request header fields:

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

CBOR data of response:

{
    (str,opt)"off"  : (uint)
    (str)"rc"       : (int)
    (str,opt)"rsn"  : (str)
}

where:

“off”	offset of last successfully written byte of update
“rc”	Status/error codes in responses
“rsn”	Optional string that clarifies reason for an error; specifically useful for error code `1`, unknown error

The “off” field is only included in responses to successfully processed requests; if “rc” is negative the “off’ may not appear.

Image erase

The command is used for erasing image slot on a target device.

Note

Currently Zephyr version of mcumgr is hardcoded to always erase secondary slot of the first image.

Note

This is synchronous command which means that a sender of request will not receive response until the command completes.

Image erase request

Image erase request header fields:

`OP`	`Group ID`	`Command ID`
`2`	`1`	`5`

The command sends sends empty CBOR map as data.

Image erase response

Image erase response header fields:

`OP`	`Group ID`	`Command ID`
`3`	`1`	`5`

CBOR data of response:

{
    (str)"rc"       : (int)
    (str,opt)"rsn"  : (str)
}

where:

“rc”	Status/error codes in responses
“rsn”	Optional string that clarifies reason for an error; specifically useful for error code `1`, unknown error

Note

Response from Zephyr running device may have “rc” value of 6, bad state (Status/error codes in responses), which means that the secondary image has been marked for next boot already and may not be erased.