# Name of the plugin.
name=OTA Bootload Cluster Server
category=ZigBee OTA Bootloading

# 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

# Description of the plugin.
description=Ember implementation of the Zigbee Over-the-air Bootload Server Cluster (a multi-hop, application bootloader).  This implementation serves up file from an OTA storage device and sends the data to clients.  It also controls when they can upgrade to the downloaded file.

# List of .c files that need to be compiled and linked in.
sourceFiles=ota-server.c, ota-server-page-request.c, ota-server-cli.c, ota-server-dynamic-block-period.c

# List of callbacks implemented by this plugin
implementedCallbacks=emberAfOtaBootloadClusterServerInitCallback, emberAfOtaBootloadClusterServerTickCallback, emberAfOtaServerIncomingMessageRawCallback, emberAfOtaServerSendImageNotifyCallback

# Turn this on by default
includedByDefault=true

# Which clusters does it depend on
dependsOnClusterServer=over the air bootloading

setup(bookkeeping) {
  # The tick above in the implementedCallbacks line is tied to an endpoint; this
  # tick is endpointless
  tick=emberAfOtaServerTick
}

options=pageRequestSupport, minBlockRequestSupport, dynamicMinBlockPeriodSupport, maxNumDynamicOtaDownloads, dynamicClientTimeoutSec, testBlockPeriodValue

pageRequestSupport.name=Page Request Support
pageRequestSupport.description=Whether the server supports clients making an OTA page request.
pageRequestSupport.type=BOOLEAN
pageRequestSupport.default=false

minBlockRequestSupport.name=Minimum Block Request Support
minBlockRequestSupport.description=Whether the server supports the Minimum Block Period support field in the Image Block Request/Response messages. This is used to rate limit clients.
minBlockRequestSupport.type=BOOLEAN
minBlockRequestSupport.default=FALSE

dynamicMinBlockPeriodSupport.name=Dynamic Block Request Support
dynamicMinBlockPeriodSupport.description=If the Minimum Block Request Support is enabled, this additional support provides dynamically treating the Minimum Block Period field as milliseconds or seconds, depending on the OTA client's support. When a client starts an OTA transfer, it will be tested to determine whether it treats the Minimum Block Period as seconds or milliseconds, and the determination will be used throughout the OTA transfer.
dynamicMinBlockPeriodSupport.type=BOOLEAN
dynamicMinBlockPeriodSupport.default=FALSE
dynamicMinBlockPeriodSupport.dependsOn=minBlockRequestSupport

maxNumDynamicOtaDownloads.name=Number of Simultaneous Dynamic Block Period Downloads
maxNumDynamicOtaDownloads.description=If the Dynamic Minimum Block Request Support is enabled, this option's value dictates how many simultaneous OTA client transfers are supported at one time. When at full capacity, Query Next Image Requests will be responded to, but Image Block Requests and Page Requests will be told to delay until a free connection opens up, which will occur when a device concludes the OTA process. A device will be aged out as an active connection if it does not query a piece of the OTA file at least once every 'Dynamic Block Period Download Timeout' seconds.
maxNumDynamicOtaDownloads.type=NUMBER:1,50
maxNumDynamicOtaDownloads.default=5
maxNumDynamicOtaDownloads.dependsOn=dynamicMinBlockPeriodSupport

dynamicClientTimeoutSec.name=Dynamic Block Period Download Timeout
dynamicClientTimeoutSec.description=This option's value dictates the amount of inactivity in seconds before the server purges a client from the dynamic block period downloads. This value must be greater than the 'Test Block Period Value' below, otherwise a client who resumes querying after a test delay will be immediately purged.
dynamicClientTimeoutSec.type=NUMBER:60,3600
dynamicClientTimeoutSec.default=120
dynamicClientTimeoutSec.dependsOn=dynamicMinBlockPeriodSupport

testBlockPeriodValue.name=Test Block Period Value
testBlockPeriodValue.description=The value a client is told to delay when determining whether it treats the Minimum Block Period as seconds or milliseconds. When a client begins an OTA download, it is sent a Minimum Block Period with this value. The amount of time that the client delays determines whether it treats this value as seconds or milliseconds (the client's delay time is judged against a threshold of this configured value). It is recommended that this value not be less than the longest expected delay time in the network, as sleepy end devices may delay longer than the Minimum Block Period amount, which tricks the OTA server into thinking that the client treats this value as seconds. Once the client is judged to be using seconds or milliseconds, the Minimum Block Period will revert to being the value contained in the otaMinimumBlockPeriodMs variable, which is settable with "plugin ota-server policy image-req-min-period."
testBlockPeriodValue.type=NUMBER:30,3600
testBlockPeriodValue.default=60
testBlockPeriodValue.dependsOn=dynamicMinBlockPeriodSupport

conditions=testValueLessThanTimeout

testValueLessThanTimeout.expression=testBlockPeriodValue < dynamicClientTimeoutSec
testValueLessThanTimeout.message=The Test Block Period Value must be less than the Dynamic Block Period Download Timeout, else a unit discovery for a client that uses seconds will time out every time and purge the client.
