Dune HD STB can check for available online firmware upgrades in different
ways, depending on what kind of firmware and firmware customization is
used:
- If the native Dune UI is used: using online firmware upgrade mechanism
built-in into the native Dune UI.
- If custom application (e.g. middleware client) is used instead of the
native Dune UI, and the custom application does not implement its own
logic for online firmware upgrade: using so called "STB upgrade
checker" mechanism (automatic firmware upgrade on STB boot).
- If custom application implements its own logic for online fimware
upgrade: according to this logic. In this case, the custom application
should check (whenever it needs to, and using the way it needs it) for
available firmware upgrade, and once it is available, determine the
URL pointing to the firmware image and call Dune JS STB API operation
to perform the upgrade.
Not depending on which firmware upgrade checking mechanism is used, there
are two phases:
1. Check if firmware upgrade is required and determining the URL pointing
to the firmware image.
2. Perform the firmware upgrade itself, which includes: downloading the
firmware image from the URL, checking the image, updating the flash
memory of the STB, rebooting.
The following document describes the protocols available for firmware image
downloading:
http://files.dune-hd.com/sdk/doc/html/dune_firmware_download_protocols.html
Firmware upgrade mechanism built-in into native Dune UI
Native Dune UI has a built-in mechanism for checking for online firmware
upgrades, which works in the following way:
- The STB periodically checks (by sending HTTP requests to a firmware
upgrade server) if a firmware upgrade is available.
- If a firmware upgrade is found, the information about available
firmware upgrade is shown to the user, and the user is asked to confirm
firmware upgrade.
- If the firmware upgrade is confirmed, the firmware upgrade procedure
starts.
- The firmware upgrade procedure first downloads the firmware image from
a HTTP server (into RAM of STB), then verifies the downloaded image,
and finally writes the image into the STB flash memory.
Checking for firmware upgrade is implemented by sending HTTP GET request to
a certain HTTP URL, which should return a plain-text file (called "online
firmware upgrade configuration file").
The HTTP URL which should return the online firmware upgrade configuration
file is constructed in the following way:
- a) Protocol variant 1 -- used for STB models based on
SMP8642/SMP8652/SMP8670 chipsets, for STB models based on SMP8672/8674
chipsets before firmware version 130221_1050_b4, and for Android STB
models (including TV-175):
{HTTP URL prefix}/{Product ID}.txt
- b) Protocol variant 2 -- used for STB models based on SMP8672/SMP8674
chipsets starting with firmware version 130221_1050_b4:
{HTTP URL prefix}/v2_{Product ID}.txt
In the standard retail Dune HD firmware, HTTP URL prefix points to the
standard Dune HD upgrade server.
- Example for protocol variant 1:
- HTTP URL prefix: http://dune-hd.com/online_upgrade
- Product ID: hdtv_101
- Resulting URL: http://dune-hd.com/online_upgrade/hdtv_101.txt
- Example for protocol variant 2:
- HTTP URL prefix: http://dune-hd.com/online_upgrade
- Product ID: tv102
- Resulting URL: http://dune-hd.com/online_upgrade/v2_tv102.txt
In custom firmware versions, the HTTP URL prefix can be customized to point
to a custom firmware upgrade server.
- Example for protocol variant 1:
- HTTP URL prefix: http://customer.com/upgrade/dunehd
- Product ID (customized): customer__hdtv_101
- Resulting URL: http://customer.com/upgrade/dunehd/customer__hdtv_101.txt
- Example for protocol variant 2:
- HTTP URL prefix: http://customer.com/upgrade/dunehd
- Product ID (customized): customer__tv102
- Resulting URL: http://customer.com/upgrade/dunehd/v2_customer__tv102.txt
The online upgrade configuration file is just a plain text file enumerating
available firmware versions. The first line in this file corresponds to the
latest available firmware version. Sample content of such a file may be
obtained here:
- Example for protocol variant 1:
- http://dune-hd.com/firmware/online_upgrade/hdtv_101.txt
- Example for protocol variant 2:
- http://dune-hd.com/firmware/online_upgrade/v2_tv102.txt
Here is sample content of such a file:
- Example for protocol variant 1:
120202_1544_beta http://files3.dune-hd.com/firmware/hdtv_101/dune_firmware_hdtv_101_120202_1544_beta.dff.gz non-stable 166
111122_0159_beta http://files3.dune-hd.com/firmware/hdtv_101/dune_firmware_hdtv_101_111122_0159_beta.dff.gz non-stable 166
110923_1710 http://files3.dune-hd.com/firmware/hdtv_101/dune_firmware_hdtv_101_110923_1710.dff.gz stable 166
- Example for protocol variant 2:
130222_1831_b5 http://files3.dune-hd.com/firmware/tv102/dune_firmware_tv102_130222_1831_b5.dff.gz stable 177
130221_1050_b4 - stable 139
Each line in such a file consists of 4 columns:
- 1) Firmware version.
- 2) URL to the firmware image. NOTE: There is no requirement that the
firmware image should reside on the same server which is used by the
STB to retrieve online upgrade configuration file. The firmware image
may reside on any HTTP server (or it can also be downloaded via
multicast, see "Protocols for downloading firmware image" section).
- 3) Whether the firmware is considered stable or non-stable (beta). The
beta versions are automatically suggested to the user only if the user
enables automatic check for beta firmware versions in Setup / Misc /
Firmware Upgrade.
- 4) Firmware file size in MB multiplied by 2.
- NOTE: this parameter was effectively used only in very old firmware
versions, and is not actually used in current firmware versions. It
is safe to specify any number here, e.g. "0".
The new firmware is automatically suggested to the user only if the file
contains a line corresponding to the firmware version which is currently
installed on the STB. So, all firmware versions that could potentially
reside on boxes which should be upgraded via online upgrade should be
listed in the file.
Starting with firmware version 130221_1050_b4, the following additional
feature is supported: "-" can be specified instead of firmware image URL
in the online upgrade configuration file. This means that this firmware
version will not be proposed to the user, but if this version is installed
on the box, the box will still be proposed to upgrade to newer versions.
This allows to remove older firmware versions from the list of firmware
versions proposed to the user in online upgrade.
The following document describes firmware upgrade error codes reported to
the user in Native Dune UI:
http://files.dune-hd.com/sdk/doc/html/firmware_upgrade_error_codes.html
Automatic firmware upgrade on STB boot (STB upgrade checker mechanism)
Dune STBs can upgrade firmware automatically on boot of device. This
feature works if it is enabled in the firmware and corresponding
configuration file is found on the STB. Thus the feature is subject to
custom firmware build.
NOTE: The automatic upgrade takes place before displaying the middleware UI
or Native Dune UI, and does not provide any way for the user to alter
network settings, so this mechanism can be used only if default network
configuration (Ethernet connection with automatic DHCP configuration) is
used.
Automatic upgrade works in the following way:
- On start of STB configuration files are checked, if file is not found
STB continues to boot normally.
- If configuration file is found it is read and analyzed.
- STB starts to wait for IP address displaying corresponding message.
- If after 60 seconds IP address is not obtained, STB displays error
message and continues to wait forever.
- After obtaining IP address STB starts to check whether updated
firmware is available with methods listed in the configuration file.
- If some check method finds version and URL of updated firmware
available, comparison is made between version of currently installed
firmware and version of updated firmware.
- If versions differ (not equal) automatic upgrade of firmware is
started without confirmation of the user.
Configuration of automatic upgrade is stored in
/firmware/config/stb_upgrade_checker.properties or
/config/stb_upgrade_checker.properties file. The latter one takes
precedence over the former one. Configuration file is plain text file with
lines like "name = value". E.g.:
check_methods = dhcp url
url_prefix = http://customer.com/upgrade/
osd_width = 1280
osd_height = 720
left = 80
top = 40
alignment = center
font_path = /config/custom_font.ttf
line_height = 42
font_height = 40
foreground_color = 0xffffff
background_color = 0x000000
waiting_for_ip.lines = 5
waiting_for_ip.line.0 = Waiting for IP address...
waiting_for_ip.line.1 = Product id: ${product_id}
waiting_for_ip.line.2 = MAC address: ${mac_address}
waiting_for_ip.line.3 = Firmware version: ${firmware_version}
waiting_for_ip.line.4 = IP address: ${ip_address}
waiting_for_ip_error.lines = 1
waiting_for_ip_error.line.0 = Network connection problem. Waiting for IP address...
get_fw_info.lines = 1
get_fw_info.line.0 = Checking firmware version...
All parameters in the configuration file are optional except parameter
"check_methods". "url" check method requires "url_prefix" parameter to work
correctly.
Check methods are used for retrieving version and URL of updated firmware.
Supported check methods are "dhcp" and "url". If no methods are specified
automatic upgrade is not performed. One or two check methods can be
specified, space is used as separator. Checks are done in order the methods
are specified in the configuration file: in the example above "dhcp" method
is used at first, if it fails "url" method is used.
"dhcp" check method retrieves information on updated firmware from DHCP
server. See http://files.dune-hd.com/sdk/doc/html/dune_dhcp_settings.html on
how to configure DHCP server to provide Dune vendor specific options like
version and URL of updated firmware.
"url" check method retrieves information on updated firmware from URL
constructed with "url_prefix" parameter and product ID. E.g.:
- URL prefix: http://customer.com/upgrade/dunehd/
- Product ID (customized): customer__hdtv_101
- Resulting URL: http://customer.com/upgrade/dunehd/customer__hdtv_101
With "url" check method STB retrieves resulting URL and parses it. Content
should be plain text file with the following format:
<firmware version> <firmware image URL>
For example:
130101_0101 http://download.customer.com/dunehd/dune_firmware_customer__hdtv_101_130101_0101.dff.gz
Firmware upgrade URLs supplied by DHCP and HTTP server can be multicast or
unicast ones, see section "Protocols for downloading firmware image".
For customization of messages displayed during initial stages of automatic
upgrade parameters like <stage name>.lines and <stage name>.<number> can be
used. The following stage names are supported:
- waiting_for_ip
- waiting_for_ip_error
- get_fw_info
Any message can contain the following variables as part of its text:
- ${product_id}
- ${mac_address}
- ${firmware_version}
- ${ip_address}
They are replaced with actual values of corresponding STB settings.
OSD width and height, font and line height, left and top offset of
automatic upgrade messages are specified in pixels. Supported alignments
for messages are "center" and "left".
Bootstrap upgrade checker mechanism
The bootstrap upgrade checker mechanism is a special version of the
described above upgrade checker mechanism which is enabled by default in
the factory firmware of "operator" version of Dune HD STBs (such as Dune HD
TV-102-O).
NOTE: This mechanism works only when the standard factory firmare of
"operator" version of Dune HD STB is used. It does not work when
non-"operator" version of Dune HD STB is used, or if a custom firmware is
already installed on the STB.
An operator can use this mechanism to ensure the operator custom firmware
version is automatically installed onto an STB when the STB is powered on
for the first time.
This mechanism uses the following sequence of check methods:
1) "dhcp"
2) "url", using URL prefix "http://dunehdbootstrap/dunehd/firmware"
The "dhcp" method allows the operator to deliver the information about the
updated firmware to STBs via DHCP. This approach is suitable in case when
the STBs are connected via Ethernet directly to operator's managed
network (rather than via home router).
The "url" method allows the operator to deliver the information about the
updated firmware to STBs via DNS and HTTP. The operator's DNS should be
configured to map "dunehdbootstrap" to the IP address of the proper
operator's HTTP server. This approach is suitable in case when the operator
can control DNS settings which are used by STBs connected to the operator's
network.
If updated firmware is found using one of these check methods, it is
automatically installed (w/o any questions and user confirmations), full
factory settings reset is performed, and the STB boots into the updated
firmware.
In order to install a custom "operator-locked" firmware update using this
mechanism, the firmware update should be of type "to_custom". For more
information, see the description of "to_custom" value of "fw_type"
parameter here:
http://files.dune-hd.com/sdk/doc/html/dfb.html
If the STB fails to obtain IP address immediately on STB power on, the
mechanism waits for the IP address for up to 60 seconds, and then continues
booting into the standard factory firmware in the usual way.
If IP address is obtained but no updated firmware is found, the STB boots
into the standard factory firmware in the usual way.
Checking for firmware upgrade in custom application
If STB is configured to boot to a custom application instead of the native
UI (e.g. HTML application is launched using
[/firmware]/config/stb_home/index.html file), the custom application may
implement its own logic for checking for firmware upgrades.
This approach is generally more recommended than using the automatic
firmware upgrade on STB boot mechanism, because it provides more
flexibility and does not have the limitations of the automatic firmware
upgrade on STB boot mechanism (e.g. it can support showing network setup UI
on STB boot and thus can support Wi-Fi and manual network configuration).
To use this approach, typically, the following logic should be implemented
in the custom application:
1. On STB boot, wait for IP address (using Dune STB API operations for
checking current network status). While the STB waits for the IP
address, show some boot logo/message to the user.
2. If the STB fails to obtain IP address during some timeout, inform the
user about the problem and, if the user should be allowed to manually
configure the network, propose the user to show network setup UI (or
show it automatically). Network setup UI can be implemented in the
following ways:
- The application can implement the network setup UI on its own
(using Dune STB API operations for getting/setting STB network
configuration). This is the recommended approach if the application
wants to provide the user with a consistent custom UI.
- The application can launch the native Dune UI (using Dune STB API
operations launchNativeUI or launchNativeUIExt). There are 3
possibilities:
- Show the main screen of the native Dune UI (the user will need
to navigate into the network setup menu manually):
- Use launchNativeUI() call.
- Show directly the network setup menu, with the possibility to
exit the network setup menu and browse full native Dune UI:
- Use launchNativeUiExt("setup://network") call.
- Show directly the network setup menu, without the possibility to
exit the network setup menu and browse full native Dune UI:
- Use launchNativeUiExt("setup://network:::standalone=1") call.
3. Once the STB has IP address, check if the information about firmware
upgrade is available. Typically, one of the following approaches is
used:
- Get the information about the available firmware version (and the
URL to download the firmware image) from DHCP options.
- The following Dune STB API operations can be used to access
these DHCP options from the custom application:
- getFirmwareUpgradeUrl()
- getFirmwareUpgradeVersion()
- See here for more information about DHCP options and DHCP server
configuration:
http://files.dune-hd.com/sdk/doc/html/dune_dhcp_settings.html
- Get the information about the available firmware version (and the
URL to download the firmware image) from an HTTP URL.
4. If the information about firmware upgrade is available, and the
available firmware version differs from the firmware version currently
installed on the STB, launch the firmware upgrade.
- To check the firmware version currently installed on the STB, use
the following Dune STB API operataion:
- getFirmwareVersion()
- To launch the firmware upgrade, use the following Dune STB API
operation:
- startFirmwareUpgrade()
Additionally, in a custom firmware build which uses this approach, it may
be desired to use "/firmware/config/nav_fw_upgrade_dont_ask_confirmations"
firmware configuration flag in order to disable all configuration dialogs
shown by the native UI. See here for more information:
http://files.dune-hd.com/sdk/doc/html/dune_custom_firmware.html