Low level API for OTA

Macros
#define	OTA_UPGRADE_HEADING_DATA   (sizeof(zb_zcl_ota_upgrade_file_header_t) + 2 /* fw tag Id */ + 4 /* fw length */)
#define	OTA_UPGRADE_HASH_SIZE   16
#define	OTA_UPGRADE_TRAILING_DATA   (2 /* hash tag Id */ + 4 /* hash length */ + OTA_UPGRADE_HASH_SIZE /* Hash */)

Functions
void *	zb_osif_ota_open_storage (void)
void	zb_osif_ota_close_storage (void *dev)
void	zb_osif_ota_erase_fw (void *dev, zb_uint_t offset, zb_uint_t size)
zb_uint32_t	zb_osif_ota_get_erase_portion (void)
void	zb_osif_ota_write (void *dev, zb_uint8_t *data, zb_uint32_t off, zb_uint32_t block_size, zb_uint32_t image_size)
void	zb_osif_ota_mark_fw_ready (void *ota_dev, zb_uint32_t size, zb_uint32_t revision)
void	zb_osif_ota_mark_fw_absent (void)
void	zb_osif_ota_mark_fw_updated (void)
zb_bool_t	zb_osif_ota_verify_integrity (void *dev, zb_uint32_t raw_len)
zb_bool_t	zb_osif_ota_verify_integrity_async (void *dev, zb_uint32_t raw_len)
void	zb_osif_ota_verify_integrity_done (zb_uint8_t integrity_is_ok)
void	zb_osif_ota_read (void *dev, zb_uint8_t *data, zb_uint32_t addr, zb_uint32_t size)
zb_bool_t	zb_osif_ota_fw_size_ok (zb_uint32_t image_size)
zb_uint8_t *	zb_osif_ota_srv_get_image (void *dev, zb_uint32_t offset, zb_uint32_t len)
zb_uint8_t *	zb_osif_ota_srv_get_image_header (void *dev)

Detailed Description

Macro Definition Documentation

OTA_UPGRADE_HASH_SIZE

#define OTA_UPGRADE_HASH_SIZE   16

Size of the OTA image hash.

See also

Zigbee Cluster Library specification revision 7 subsection 11.7.2.1 Hash Value Calculation

OTA_UPGRADE_HEADING_DATA

#define OTA_UPGRADE_HEADING_DATA   (sizeof(zb_zcl_ota_upgrade_file_header_t) + 2 /* fw tag Id */ + 4 /* fw length */)

Size of sub-element includes OTA header.

See also

Zigbee Cluster Library specification revision 7 subsection 11.4.3 Sub-element Format

OTA_UPGRADE_TRAILING_DATA

#define OTA_UPGRADE_TRAILING_DATA   (2 /* hash tag Id */ + 4 /* hash length */ + OTA_UPGRADE_HASH_SIZE /* Hash */)

Size of sub-element includes a hash value.

See also

Zigbee Cluster Library specification revision 7 subsection 11.4.8 Image Integrity Code Sub-element

Function Documentation

zb_osif_ota_close_storage()

void zb_osif_ota_close_storage

(

void *

dev

)

Close device used for OTA image write

Parameters

dev	flash device handle used to write OTA image

See also

zb_osif_ota_open_storage

zb_osif_ota_erase_fw()

void zb_osif_ota_erase_fw	(	void *	dev,
		zb_uint_t	offset,
		zb_uint_t	size
	)

Erase flash to be used for OTA image store.

Note

: offset and size must be aligned to minimal eraseable page boundary - see zb_osif_ota_get_erase_portion().

Parameters

dev	flash device handle

See also

zb_osif_ota_open_storage

Parameters

offset	file offset in flash memory
size	OTA file image size

zb_osif_ota_fw_size_ok()

zb_bool_t zb_osif_ota_fw_size_ok

(

zb_uint32_t

image_size

)

Check whether the current device flash memory has enough space for the OTA file image.

Parameters

image_size

OTA file image size

Returns

ZB_TRUE if ok, ZB_FALSE if error

zb_osif_ota_get_erase_portion()

zb_uint32_t zb_osif_ota_get_erase_portion

(

void

)

Get portion of OTA storage which can be erased at once.

Returns

erase block size in bytes

zb_osif_ota_mark_fw_absent()

void zb_osif_ota_mark_fw_absent

(

void

)

Mark new FW as absent so bootloader does not attempt to re-flash it.

To be called when starting OTA.

zb_osif_ota_mark_fw_ready()

void zb_osif_ota_mark_fw_ready	(	void *	ota_dev,
		zb_uint32_t	size,
		zb_uint32_t	revision
	)

Mark FW as downloaded and ready to use by bootloader.

To be called when finishing OTA, after FW loaded and verified.

Parameters

ota_dev

flash device handle used to write OTA image

See also

zb_osif_ota_open_storage

Parameters

size	OTA image size, without CRC
revision	OTA image revision

zb_osif_ota_mark_fw_updated()

void zb_osif_ota_mark_fw_updated

(

void

)

Mark FW upgrade finished, so bootloader just loads current FW.

To be called from newly started application FW. Usually not need to be called by the application. ZBOSS kernel cares about it.

zb_osif_ota_open_storage()

void* zb_osif_ota_open_storage

(

void

)

Open device to be used for OTA image write or read.

Take into account which flash (A or B) current FW is running at.

See also

zb_osif_ota_close_storage

Returns

handle

zb_osif_ota_read()

void zb_osif_ota_read	(	void *	dev,
		zb_uint8_t *	data,
		zb_uint32_t	addr,
		zb_uint32_t	size
	)

Read OTA image data from flash.

Parameters

dev	flash device handle

See also

zb_osif_ota_open_storage

Parameters

data	pointer to the read data
addr
size	amount of data to read

zb_osif_ota_srv_get_image()

zb_uint8_t* zb_osif_ota_srv_get_image	(	void *	dev,
		zb_uint32_t	offset,
		zb_uint32_t	len
	)

Get OTA image data at OTA server

Parameters

dev	flash device handle used to write OTA image

See also

zb_osif_ota_open_storage

Parameters

offset	offset in the OTA image
len	- length of image block to get

Returns

pointer to image block

zb_osif_ota_srv_get_image_header()

zb_uint8_t* zb_osif_ota_srv_get_image_header

(

void *

dev

)

Get OTA header at OTA server

Parameters

dev	flash device handle used to write OTA image

See also

zb_osif_ota_open_storage

Returns

pointer to header block

zb_osif_ota_verify_integrity()

zb_bool_t zb_osif_ota_verify_integrity	(	void *	dev,
		zb_uint32_t	raw_len
	)

Verify OTA file image written to device dev.

Parameters

dev	flash device handle used to write OTA image

See also

zb_osif_ota_open_storage

Parameters

raw_len

- OTA image file length

Returns

ZB_TRUE if ok, ZB_FALSE if error

zb_osif_ota_verify_integrity_async()

zb_bool_t zb_osif_ota_verify_integrity_async	(	void *	dev,
		zb_uint32_t	raw_len
	)

Verify OTA file image written to device dev asynchronously.

Parameters

dev	flash device handle used to write OTA image

See also

zb_osif_ota_open_storage

Parameters

raw_len

- OTA image file length

Returns

ZB_TRUE if ok, ZB_FALSE if error

zb_osif_ota_verify_integrity_done()

void zb_osif_ota_verify_integrity_done

(

zb_uint8_t

integrity_is_ok

)

Check whether OTA image recording was successful and finalize OTA.

Parameters

integrity_is_ok

- is verification of OTA image recording successful

zb_osif_ota_write()

void zb_osif_ota_write	(	void *	dev,
		zb_uint8_t *	data,
		zb_uint32_t	off,
		zb_uint32_t	block_size,
		zb_uint32_t	image_size
	)

Write OTA image data to flash.

Deal with alignment.

Parameters

dev	flash device handle

See also

zb_osif_ota_open_storage

Parameters

data	pointer to the data to write
off	offset in OTA file
block_size	amount of data to write
image_size	total image size