name=OTA Bootload Cluster Client
category=ZigBee OTA Bootloading

description=Ember implementation of the Zigbee Over-the-air Bootload Client Cluster (a multi-hop, application bootloader).  This implementation finds the OTA server in the network, periodically queries the server for a new image to download, downloads the data, and then waits for the server command to tell it to upgrade.  Optionally it can cryptographically verify the image prior to upgrade.

# Any string is allowable here.  Generally it is either: Production Ready, Test Tool, or Requires Extending
qualityString=Production Ready (Certifiable)
# This must be one of the following:  productionReady, testTool, extensionNeeded
quality=production

introducedIn=se-1.1-07-5356-16

providedApis=ota-client

sourceFiles=ota-client.c, ota-client-signature-verify.c, ota-client-page-request.c, ota-client-cli.c

implementedCallbacks=emberAfOtaBootloadClusterClientInitCallback, emberAfOtaBootloadClusterClientTickCallback, emberAfOtaClientIncomingMessageRawCallback, emberAfOtaClientStartCallback, emberAfOtaBootloadClusterClientDefaultResponseCallback, emberAfPluginOtaStorageSimpleEepromEraseCompleteCallback, emberAfPluginOtaClientStackStatusCallback

includedByDefault=true

dependsOnClusterClient=over the air bootloading

# CBKE DSA Verification required if the plugin uses signature verification
requiredApis=cbke-dsa-verify
api.cbke-dsa-verify.condition=signatureVerificationSupport

options=autoStart, setImageStamp, queryDelayMinutes, queryErrorThreshold, downloadDelayMs, downloadErrorThreshold, upgradeWaitThreshold, serverDiscoveryDelayMinutes, runUpgradeRequestDelayMinutes, usePageRequest, pageRequestSize, pageRequestTimeoutSeconds, signatureVerificationSupport, verifyDelayMs, signerEui0, signerEui1, signerEui2, minBlockPeriodUnits, ignoreLoopbackServer, ignoreNonTrustCenter

setImageStamp.name=Set Image Stamp Attribute (35x SOC only)
setImageStamp.description=The OTA Client will automatically set the Image Stamp Attribute based on the image stamp value in the AAT.  The Image Stamp value in the AAT is created using em3xx_convert, which will hash the AAT and all flash pages.  You must also enable the optional Image Stamp attribute for the client cluster.
setImageStamp.type=BOOLEAN
setImageStamp.default=true

autoStart.name=Auto Start on Stack Up (random delay)
autoStart.description=Automatically start the OTA client on EMBER_NETWORK_UP.  This will include a random delay up to 5 minutes to prevent an issue where multiple devices in the network all query the server simultaneously after a power-outage.
autoStart.type=BOOLEAN
autoStart.default=true

usePageRequest.name=Use Page Request
usePageRequest.description=This causes the device to use an OTA Page Request command to ask for a large block of data all at once, rather than use individual image block requests for each block.
usePageRequest.type=BOOLEAN
usePageRequest.default=false

pageRequestSize.name=Page Request Size
pageRequestSize.description=The size of the page to request from the server.
pageRequestSize.type=LIST:1024,2048,4096
pageRequestSize.default=1024

pageRequestTimeoutSeconds.name=Page Request Timeout (seconds)
pageRequestTimeoutSeconds.description=The length of time to wait for all blocks from a page request to come in.  After this time has expired, missed packets will be requested individually with image block requests.
pageRequestTimeoutSeconds.type=NUMBER:1,10
pageRequestTimeoutSeconds.default=5

signatureVerificationSupport.name=Signature Verification Support (SE 1.x only)
signatureVerificationSupport.description=This requires all received images to be signed with an ECDSA signature and verifies the signature once the download has completed.  If an image fails verification it is discarded.   This verification will occur prior to any custom verification that might verify the contents.
signatureVerificationSupport.type=BOOLEAN
signatureVerificationSupport.default=false
signatureVerificationSupport.callbacks=emberDsaVerifyHandler, ezspDsaVerifyHandler

queryDelayMinutes.name=Query OTA Server Delay (minutes)
queryDelayMinutes.description=How often the client queries the OTA server for a new upgrade image.
queryDelayMinutes.type=NUMBER
queryDelayMinutes.default=5

queryErrorThreshold.name=Query Error Rediscovery Threshold
queryErrorThreshold.description=How many sequential query errors will cause a device to look for a new OTA server. 
queryErrorThreshold.type=NUMBER
queryErrorThreshold.default=10

downloadDelayMs.name=Download Delay (ms)
downloadDelayMs.description=How often a new block of data (or page) is requested during a download by the client.  A value of 0 means the client will request the blocks (or pages) as fast as the server responds.
downloadDelayMs.type=NUMBER
downloadDelayMs.default=0

downloadErrorThreshold.name=Download Error Threshold
downloadErrorThreshold.description=How many sequential errors will cause a download to be aborted.
downloadErrorThreshold.type=NUMBER:1,255
downloadErrorThreshold.default=10

upgradeWaitThreshold.name=Upgrade Wait Threshold
upgradeWaitThreshold.description=How many sequential, missed responses to an upgrade end request will cause a download to be applied anyway.
upgradeWaitThreshold.type=NUMBER:1,255
upgradeWaitThreshold.default=10

serverDiscoveryDelayMinutes.name=Server Discovery Delay (minutes)
serverDiscoveryDelayMinutes.description=How often a client will look for an OTA server in the network when it did not successfully discover one.  Once a client discovers the server, it will remember that server until it reboots, or until the Query Error Rediscovery Threshold is hit.
serverDiscoveryDelayMinutes.type=NUMBER
serverDiscoveryDelayMinutes.default=10

runUpgradeRequestDelayMinutes.name=Run Upgrade Request Delay (minutes)
runUpgradeRequestDelayMinutes.description=How often the client will ask the server to apply a previously downloaded upgrade when the server has previously told the client to wait.
runUpgradeRequestDelayMinutes.type=NUMBER
runUpgradeRequestDelayMinutes.default=10

verifyDelayMs.name=Verification Delay (ms)
verifyDelayMs.description=This controls how often an ongoing verification process executes.  When Signature verification is enabled this will control how often digest calculation is executed.  Digest calculation can take quite a long time for an OTA image.  Other processing for the system may be deemeded more important and therefore we add delays between calculations.  This also controls how often custom verification written by the application developer is executed.  A value of 0 means the calculations run to completion.
verifyDelayMs.type=NUMBER
verifyDelayMs.default=10

signerEui0.name=Image Signer EUI64 0
signerEui0.description=The big endian EUI64 address of a device authorized to sign OTA images for this client.  A value of all 0's will be ignored.
signerEui0.type=EUI64
signerEui0.default=00 0d 6f 00 00 19 8b 36

signerEui1.name=Image Signer EUI64 1
signerEui1.description=The big endian EUI64 address of a device authorized to sign OTA images for this client.  A value of all 0's will be ignored.
signerEui1.type=EUI64
signerEui1.default=00 00 00 00 00 00 00 00

signerEui2.name=Image Signer EUI64 2
signerEui2.description=The big endian EUI64 address of a device authorized to sign OTA images for this client.  A value of all 0's will be ignored.
signerEui2.type=EUI64
signerEui2.default=00 00 00 00 00 00 00 00

minBlockPeriodUnits.name=Minimum Block Period Units
minBlockPeriodUnits.description=The units applied to the Minimum Block Period field in an ImageBlockRequest and ImageBlockResponse. Optionally, the feature can be disabled.
minBlockPeriodUnits.type=LIST:Seconds,Milliseconds,Disable Feature
minBlockPeriodUnits.default=Milliseconds

ignoreLoopbackServer.name=Ignore loopback server endpoints
ignoreLoopbackServer.description=During OTA server discovery, ignore service discovery responses that come as loopback messages (from the local node) so the first remote server to respond is the one the client will use.  This allows a combination OTA client/server device to find other servers.
ignoreLoopbackServer.type=BOOLEAN
ignoreLoopbackServer.default=true

ignoreNonTrustCenter.name=Ignore non Trust Center for OTA server
ingoreNonTrustCenter.description=During OTA server discovery, ignore service discovery responses from non Trust Center nodes
ignoreNonTrustCenter.type=BOOLEAN
ignoreNonTrustCenter.default=false