Documentation

Mistake on this page? Email us

Resuming firmware downloads

Key concepts and terms

When you attempt to update the firmware on your device(s), network interruptions can cause the download to fail. Update lets you resume a firmware download where it ended, rather than starting it from the beginning.

A full resume cycle is bounded by the maximum download activity period (http-resume-maximum-download-time-secs), which is broken up into multiple attempt cycles. Each attempt starts with some period (http-resume-initial-delay-secs) with automatic exponential increase in duration (http-resume-exponentiation-factor) up to a maximum (http-resume-maximum-delay-secs), and with randomness added.

The attempt delay is how long Update waits before attempting the download again.

Configuration

The file update-client-hub/modules/common/mbed_lib.json contains configuration parameters with default values. These are intended for devices and scenarios with moderate time and energy resources, typically Wi-Fi or Ethernet connectivity and wall power. If your devices are battery-powered or otherwise constrained, you may need to change some of these values from their defaults.

Constraints for parameters are in part to avoid violating certain assumptions made in the implementation, and in part so you don't mistakenly configure the engine with values that would adversely impact running the system.

If you give values that violate these constraints, the resume engine either raises a compile time error (for values below zero, on the grounds that these offer no clues as to suitable alternatives) or performs a runtime correction for any other violations.

Note: Update can apply some fixes automatically to values that don't meet the above criteria. Values less than the lower limit will be raised to that limit, and values greater than a higher limit will be reduced to that limit. However, don't rely on these fixes. They help you avoid breaking updates with erroneous values, but they don't replace careful configuration.

Note: These values must be positive integers. They cannot have a decimal value, or be less than or equal to zero.

Note: Thehttp-resume-maximum-download-time-secs should be bounded by the device registration session lifetime MBED_CLOUD_CLIENT_LIFETIME.

Parameter Purpose Default value Constraints
http-resume-exponentiation-factor Multiply the current attempt delay by this number for the next attempt delay. Twice the current attempt delay. Minimum value is 1. Maximum is 1024.
http-resume-initial-delay-secs The amount of time the first attempt is delayed. Five seconds. Minimum one second. Maximum 24 hours.
http-resume-maximum-delay-secs The longest period an attempt delay can be set. One hour. Minimum is the initial attempt delay. Maximum seven days.
http-resume-maximum-download-time-secs The period after which the download terminates as failed. Seven days. Minimum is the maximum attempt delay. Maximum 30 days.
http-resume-fragments-per-burst Number of fragments to be requested per HTTP GET from server. 64 Minimum is 1 (NONE). Maximum is 1024 (EXTREME).