Image Management Client

MCUmgr Image management client API. More...

Files
file	img_mgmt_client.h
	Header file for the MCUmgr image management client API.

Data Structures
struct	mcumgr_image_list_flags
	Image list flags. More...
struct	mcumgr_image_data
	Image list data. More...
struct	mcumgr_image_state
	MCUmgr Image list response. More...
struct	mcumgr_image_upload
	MCUmgr Image upload response. More...
struct	img_gr_upload
	IMG mgmt client upload structure. More...
struct	img_mgmt_client
	IMG mgmt client object. More...

Macros
#define	IMG_MGMT_CLIENT_HASH_MAX_LEN   64
	Maximum supported image digest length.

Functions
void	img_mgmt_client_init (struct img_mgmt_client *client, struct smp_client_object *smp_client, int image_list_size, struct mcumgr_image_data *image_list)
	Inilialize image group client.
int	img_mgmt_client_upload_init (struct img_mgmt_client *client, size_t image_size, uint32_t image_num, const char *image_hash)
	Initialize image upload.
int	img_mgmt_client_upload (struct img_mgmt_client *client, const uint8_t *data, size_t length, struct mcumgr_image_upload *res_buf)
	Upload part of image.
int	img_mgmt_client_state_write (struct img_mgmt_client *client, const char *hash, size_t hash_len, bool confirm, struct mcumgr_image_state *res_buf)
	Write the state of an image.
int	img_mgmt_client_state_read (struct img_mgmt_client *client, struct mcumgr_image_state *res_buf)
	Read image state.
int	img_mgmt_client_erase (struct img_mgmt_client *client, uint32_t slot)
	Erase selected Image Slot.

Detailed Description

MCUmgr Image management client API.

Macro Definition Documentation

IMG_MGMT_CLIENT_HASH_MAX_LEN

#define IMG_MGMT_CLIENT_HASH_MAX_LEN   64

#include <img_mgmt_client.h>

Maximum supported image digest length.

An image list response can contain a SHA-256 (32-byte) or SHA-512 (64-byte) digest, depending on the target's MCUboot configuration.

Note

Unlike IMG_MGMT_DATA_SHA_LEN, this value does not specify the fixed SHA-256 digest length used for image uploads.

Function Documentation

img_mgmt_client_erase()

int img_mgmt_client_erase	(	struct img_mgmt_client *	client,
		uint32_t	slot )

#include <img_mgmt_client.h>

Erase selected Image Slot.

Parameters

client	IMG mgmt client object
slot	Slot number

Returns

0 on success.

mcumgr_err_t code on failure.

img_mgmt_client_init()

void img_mgmt_client_init	(	struct img_mgmt_client *	client,
		struct smp_client_object *	smp_client,
		int	image_list_size,
		struct mcumgr_image_data *	image_list )

#include <img_mgmt_client.h>

Inilialize image group client.

Function initializes image group client for given SMP client using supplied image data.

Parameters

client	IMG mgmt client object
smp_client	SMP client object
image_list_size	Length of image_list buffer.
image_list	Image list buffer pointer.

img_mgmt_client_state_read()

int img_mgmt_client_state_read	(	struct img_mgmt_client *	client,
		struct mcumgr_image_state *	res_buf )

#include <img_mgmt_client.h>

Read image state.

Parameters

client	IMG mgmt client object
res_buf	Pointer for command response structure.

Returns

0 on success.

mcumgr_err_t code on failure.

img_mgmt_client_state_write()

int img_mgmt_client_state_write	(	struct img_mgmt_client *	client,
		const char *	hash,
		size_t	hash_len,
		bool	confirm,
		struct mcumgr_image_state *	res_buf )

#include <img_mgmt_client.h>

Write the state of an image.

Sends an image state write request to the target. The image is selected by its digest, which must match the hash reported by img_mgmt_client_state_read. The digest can use SHA-256 or SHA-512, depending on the target configuration.

The requested operation depends on hash and confirm:

• If hash is not NULL and confirm is false, the selected image is marked for test. Depending on the MCUboot mode, the image is swapped in or selected on the next boot and can be reverted unless it is later confirmed.
• If hash is not NULL and confirm is true, the selected image is requested for confirmation. The target can reject confirmation of a non-active image.
• If hash is NULL and confirm is true, the currently active image is confirmed.
• If hash is NULL and confirm is false, the request is invalid.

Parameters

client	IMG mgmt client object.
hash	Image digest used to select the target image. Set to NULL to select the currently active image. This is valid only when confirm is true.
hash_len	Length of hash in bytes: 32 for SHA-256 or 64 for SHA-512. Set to 0 when hash is NULL.
confirm	Set to false to test the image or true to confirm it.
res_buf	Command response structure. The image state returned by the target is stored here when the request succeeds.

Return values

0	The request completed successfully.

Returns

A mcumgr_err_t error code on failure.

img_mgmt_client_upload()

int img_mgmt_client_upload	(	struct img_mgmt_client *	client,
		const uint8_t *	data,
		size_t	length,
		struct mcumgr_image_upload *	res_buf )

#include <img_mgmt_client.h>

Upload part of image.

Parameters

client	IMG mgmt client object
data	Pointer to data.
length	Length of data
res_buf	Pointer for command response structure.

Returns

0 on success.

mcumgr_err_t code on failure.

img_mgmt_client_upload_init()

int img_mgmt_client_upload_init	(	struct img_mgmt_client *	client,
		size_t	image_size,
		uint32_t	image_num,
		const char *	image_hash )

#include <img_mgmt_client.h>

Initialize image upload.

Parameters

client	IMG mgmt client object
image_size	Size of image in bytes.
image_num	Image slot Num.
image_hash	Pointer to HASH for image must be SHA256 hash of entire upload if present (32 bytes). Use NULL when HASH from image is not available.

Returns

0 on success.

mcumgr_err_t code on failure.