Dune HD Firmare Build service (DFB) is an online service allowing to build
custom Dune HD firmware images in an automated way.
A special account is required to use DFB service.
Linux user experience and a Linux PC are required.
Overview
The process to create a custom firmware via DFB service is the following:
1. Decide on the base firmware, install the base firmware on the STB,
prepare/test all needed modifications.
2. Obtain the "tango" filesystem image corresponding to the base
firmware, apply all needed modification to it. Optionally
(recommended), test the resulting custom "tango" image on the STB.
3. Prepare so called "DFB request".
4. Submit the DFB request to the DFB service.
5. Wait for the DFB request to complete and obtain its result (the
created custom firmware image).
6. Test the created custom firmware image on the STB.
DFB service can be accessed in the following ways:
- Via the provided "dfb_tool" script.
- Via the provided HTTP API (in particular, using command line utilities
such as "curl" and "wget").
Related documentation
The following documentation is recommended for reading before using the DFB
service:
- http://files.dune-hd.com/sdk/doc/html/dune_devel_info.html
- Especially see the following sections:
- "Filesystem and partitions overview"
- "Modifying files in read-only /tango filesystem"
- http://files.dune-hd.com/sdk/doc/html/dune_custom_firmware.html
Usage recommendations
Before using DFB service for building a custom firmware image (and even
before requesting an getting DFB account), it is recommended, when
possible, first to test and debug all the changes on a real STB, by
manually installing all the needed changes into the flash memory of the
STB.
After everything is debugged, send a request to the DFB service to
create the final firmware image in the DFF format.
If possible, avoid using DFB service too frequently, and avoid relying on
100% availability of the DFB service in your custom firmware development
process (there may be short periods of maintainance, when the DFB service
may be temporarily not available).
Getting DFB account
To use DFB service, you need to get DFB account (client ID and password).
You also need to ensure that the following settings of your DFB account are
configured in the way you need:
- Customer IDs.
- Base firmware versions.
NOTE: It is typically recommended to avoid getting and using DFB account
before you are really going to create a custom firmware image (typically
for production use or pre-production tests), and especially before you have
tested and verified that a particular base firmware version suits your
needs.
To obtain the DFB account or change DFB account configuration please
fill-in the following form and e-mail it with subject "New DFB account" or
"Modify DFB account" to the e-mail address < dfba _at_ dune-hd.com >:
- Client ID: ...
(MANDATORY)
Description:
Client ID identifying your DFB account. Client ID uniquely
identifies your organization in the scope of DFB service, and
typically corresponds to the name of your organization. It
should consist of lowercase alphanumeric and optionally
underscore ('_') characters. Is used only to
identify/authenticate your DFB requests, and is not used for
anything else (in particular, the created custom firmware
builds will not contain any information about this Client ID).
When a new DFB account is created, Dune HD may either use your
suggestion or adjust it as needed (based on uniqueness
considerations).
Example:
some_company
- Customer ID(s): ...
(MANDATORY)
Description:
Customer ID(s) which should be available in your DFB account.
Customer ID uniquely identifies your custom firmware images, and
typically corresponds to the name of a particular
project/service/operator, for which the custom firmware is
targeted. When a new Customer ID is allocated, Dune HD may
either use your suggestion or adjust it as needed (based on
uniqueness considerations). NOTE: Customer ID may consist of
lowercase alphanumeric characters only. For more details, see
"Customer ID" section here:
http://files.dune-hd.com/sdk/doc/html/dune_custom_firmware.html
Example:
besttv
- Base firmware version(s): ...
(MANDATORY)
Description:
The exact filenames of DFF files corresponding to the base
firmware versions which should be available in your DFB
account. Please provide the complete list of base firmware
images for all products (STB models) you need.
Example:
dune_firmware_tv102_130515_2104_b6.dff
dune_firmware_tv303d_130515_2104_b6.dff
- Special cross-upgrade requirements: ...
(OPTIONAL)
Description:
By default, the only available cross-upgrade kind is
"not_allowed", and the only available firmware type is
"normal"; these default settings are recommended for most
projects. If for some reason you need other settings, please
specify here which exactly settings are required and describe
what is the reason for this. Dune HD will analyze this request
and will decide if the requested settings are reasonable for
the described needs and should be allowed.
The request will be processed typically in 1-2 days and you will get an
e-mail with a confirmation (and assigned DFB client ID and password in case
a new DFB account is created). If you do not get a reply or in case of any
troubles, please forward your e-mail to your Dune HD contacts.
Quick How To
Here is an example of a typical sequence of commands (to be performed on a
Linux PC) to create a custom firmware image:
# Download the "dfb_tool" script
wget http://files.dune-hd.com/sdk/misc/dfb_tool
chmod +x dfb_tool
# Specify your DFB account credentials
export DFB_CLIENT_ID=...
export DFB_PASSWORD=...
# Download the original tango.cramfs image
./dfb_tool download dune_firmware_tv102_130402_1912_b5.tango.cramfs
# Unpack tango.cramfs image into tango/ folder
./dfb_tool unpack_cramfs dune_firmware_tv102_130402_1912_b5.tango.cramfs tango
# Apply needed modifications to the content of tango/ folder
mkdir -p tango/firmware/config/stb_home
cp index.html tango/firmware/config/stb_home
# ...
# Pack tango/ folder into custom tango.cramfs image
./dfb_tool pack_cramfs tango.cramfs tango
# Optional: write custom tango.cramfs to the flash memory of the STB and
# test it on the STB
# Create and submit DFB request to the DFB service and wait for the
# result
./dfb_tool run_request \
dune_firmware_tv102_130402_1912_b5.dff \
somecustomerid \
tango.cramfs \
boot_logo.bmp
NOTE: You can also download an example script built on top of "dfb_tool"
here:
http://files.dune-hd.com/sdk/misc/dfb_usage_example.sh
dfb_tool script
The "dfb_tool" script is a simple Linux shell script which communicates
with DFB service via HTTP API using "curl" and "wget" utilities, and also
implements some additional auxilary operations (for working with CRAMFS
images etc).
The script is available here:
http://files.dune-hd.com/sdk/misc/dfb_tool
The script requires the following environment variables to be set
(according to your DFB account credentials):
DFB_CLIENT_ID
DFB_PASSWORD
The script supports the following commands:
dfb_tool download {file}
Downloads a file with base firmware (.dff.zip) or corresponding
tango.cramfs image (.tango.cramfs), using the following URL:
https://online.dune-hd.com/dfb/base_fw/{file}
dfb_tool unpack_cramfs {tango.cramfs} {folder}
Unpacks the specified tango.cramfs image file into the specified
folder. NOTE: requires "sudo" permissions to execute loop mount
command.
dfb_tool pack_cramfs {tango.cramfs} {folder}
Packs the content of the specified folder into the specified
tango.cramfs image file.
dfb_tool prepare_request {dfb_request.zip} \
{base_firmware_file.dff} \
{customer_id} \
{tango.cramfs} \
{boot_logo.bmp}
Creates a ZIP archive describing DFB request based on the specified
parameters. More exactly: creates "dfb_request" folder in the current
directory, copies the specified tango.cramfs and boot_logo.bmp files
into "dfb_request" folder, creates dfb_request.txt file in
"dfb_request" folder, and packs the content of "dfb_request" folder
into the specified dfb_request.zip file.
If DFB_REQUEST_EXTRA_DATA environment variable is specified when this
command is executed, the value of this variable is appended to the
content of the created dfb_request.txt file. Example:
DFB_REQUEST_EXTRA_DATA="fw_type = to_custom" \
dfb_tool prepare_request ...
dfb_tool submit_request {dfb_request.zip}
Submits the specified DFB request (dfb_request.zip file) to the DFB
service. On success, prints the idenfifier of the submitted DFB
request to stdout, and exits with status 0. On an error, prints error
message to stderr and exits with status 1.
dfb_tool get_result {dfb_request_id}
Waits for the DFB request with the given identifier to complete. If
the DFB request completes OK, exits with status 0 (in this case, the
resulting .dff.zip file with the created custom firmware image is
stored in the current directory). If the DFB request fails on an
error, prints the error message to stderr and exits with status 1.
dfb_tool process_request {dfb_request.zip}
Shortcut for "submit_request" command followed by "get_result" command.
dfb_tool run_request \
{base_firmware_file.dff} \
{customer_id} \
{tango.cramfs} \
{boot_logo.bmp}
Shortcut for "prepare_request" command followed by "process_request"
command.
DFB request
DFB request is a ZIP-file (you can use "dfb_request.zip" filename or any
other filename you want) containing the following files:
- dfb_request.txt
- Contains various parameters of the DFB request.
- tango.cramfs
- Contains the custom image of "tango" filesystem.
- NOTE: This file can have any filename, the exact filename to use is
specified in the "dfb_request.txt" file.
- NOTE: This file is optional, it only should be provided if changes
in "tango" filesystem are required.
- NOTE: When custom firmware image is created, the provided custom
"tango" image is automatically modified by the DFB service in
certain ways to ensure certain constraints (such as correct values
of product ID and firmware version). I.e. the "tango" image in the
created custom firmware image may not be 100% copy of the provided
custom "tango" image and may contain minor differences in several
system files.
- boot_logo.bmp
- Contains the custom boot logo picture.
- NOTE: This file can have any filename, the exact filename to use is
specified in the "dfb_request.txt" file.
- NOTE: This file is optional, it only should be provided if custom
boot logo is required.
- NOTE: The picture must be in the required format (1920x1080
256-color uncompressed BMP).
The "dfb_request.txt" file has a standard properties ("key = value") format
and can include the following parameters:
- base_dff
- Specifies the base firmware image.
- Example:
- dune_firmware_tv102_130402_1912_b5.dff
- The list of supported base firmware versions is determined by the
DFB service.
- NOTE: This DFF file must not be included into the DFB request ZIP
archive.
- customer_id
- Specifies the customer ID which should be used for the custom
firmware image.
- tango_cramfs
- Specifies the filename of the "tango.cramfs" file, which is
included into the DFB request.
- NOTE: This parameter is optional. If omitted, it means that custom
"tango" image is not specified.
- splash_screen_video_mode
- Specifies the video mode which should be used for displaying the
splash screen.
- There are three valid values:
- 1080i50 -- 1920 x 1080 x 50 Hz
- 1080i60 -- 1920 x 1080 x 60 Hz
- default -- the base firmware video mode will be used.
- NOTE: the values are case-sensitive (1080i50 and 1080I50 are
different, 1080I50 is not a valid value).
- NOTE: This parameter is optional. If omitted, it means the default
mode (usually 1080i60) will be used.
- splash_screen_bmp
- Specifies the filename of the "boot_logo.bmp" file, which is
included into the DFB request.
- NOTE: This parameter is optional. If omitted, it means that custom
boot logo picture is not specified.
- customer_fw_suffix
- Additional tag to be put into the firmware version string of the
resulting firmware.
- NOTE: This parameter is optional. If omitted, it means that no
additional tag is added to firmware version string.
- cross_upgrade_type
- Specifies cross-upgrade limitations of the firmware.
- Possible values:
- "not_allowed"
- "any"
- "to_custom"
- See here for more information:
http://files.dune-hd.com/sdk/doc/html/dune_custom_firmware.html
"Cross-upgrade limitations"
- NOTE: This parameter is optional. If omitted, "not_allowed" type is
used.
- NOTE: "any" and "to_custom" types may not be available depending on
DFB account configuration.
- fw_type
- Specifies if a special firmware image should be built, which will
change product ID from one value to another. NOTE: This is relevant
only for custom firmware built using "not_allowed"
cross_upgrade_type.
- Possible values:
- "normal"
- Installing the firmware image does not lead to changing
product ID.
- Such firmware images are intended for normal upgrading of
custom firmware from one version to another.
- "to_custom"
- Installing the firmware image leads to changing product ID
from standard product ID (e.g. "tv102") to custom product ID
(e.g. "somecustomer__tv102").
- Such firmware images are intended for converting standard
firmware into custom firmware.
- NOTE: typically, such cross-upgrade firmware images must not
be given to end users and should be used only by an
operator/integrator when preparing STBs for the customer.
- NOTE: This parameter is optional. If omitted, "normal" type is
used.
- NOTE: "to_custom" type may not be available depending on DFB
account configuration.
DFB URLs
DFB service provides the following URLs.
Download base firmware (.dff.zip):
https://online.dune-hd.com/dfb/base_fw/{fw_file_name}.dff.zip
Download tango.cramfs image (.tango.cramfs):
https://online.dune-hd.com/dfb/base_fw/{fw_file_name}.tango.cramfs
HTTP API for submitting DFB request:
https://online.dune-hd.com/dfb/request
HTTP API for getting DFB request result:
https://online.dune-hd.com/dfb/result/{request_id}
HTTP API
API for submitting DFB request:
To submit a DFB request to the DFB service, an HTTP request should be
sent using e.g. the following command:
curl -k -L --post301 -F filedata=@dfb_request.zip \
-u {client_id}:{password} \
https://online.dune-hd.com/dfb/request
This HTTP request returns a HEX string representing the assigned DFB
request identifier, like the following:
1234567890a963f1b6b25a9d42d1c871
API for obtaining DFB request result:
The DFB request typically takes a few minutes to complete. To check the
DFB request status and obtain request execution result, an HTTP request
should be sent using e.g. the following command:
wget --http-user={client_id} --http-password={password} \
--content-disposition --no-check-certificate --auth-no-challenge \
https://online.dune-hd.com/dfb/result/1234567890a963f1b6b25a9d42d1c871
This HTTP request returns the following:
- If the DFB request is still running: HTTP status "Not Found" (404).
In this case, the HTTP request should be retried.
- If the DFB request failed on an error: a plain text file with error
description.
- If the DFB request has completed OK: a ZIP archive with the
generated DFF file.
Installation of created custom firmware
The following procedure can be used to install custom firmware to the STB
on which standard Dune firmware is currently installed.
To process just one of a few STBs in a manual way (serial numbers of the
STBs will be needed), it is possible to use the approach described in
"Using cross-upgrade DSF" section.
To process any number of STBs in a more automated way, the following
approach can be used (NOTE: this functionality is available only on modern
Dune HD models starting with the models based on SMP8674 and SMP8672
chipsets):
- Download dune_firmware_upgrader_<customer_id>.zip archive from
https://online.dune-hd.com/dfb/client_profile, "Available upgraders"
- Here, <customer_id> is a "Customer ID" which is used for the custom
firmware.
- NOTE: it is OK if "dune_firmware_upgrader.zip" file name is
suggested when downloading the archive.
- Unzip the dune_firmware_upgrader archive to the root of a USB flash
drive.
- Put the DFF file with custom firmware to be installed to the root of
the same USB flash drive.
- Rename the DFF file to "dune_firmware_upgrader.dff".
- As a result, root directory of the USB flash drive should contain the
following 3 files:
- dune_firmware_upgrader.dff
- dune_firmware_upgrader.sh
- dune_firmware_upgrader.sign
- Attach the USB flash drive to the STB.
- Power on the STB.
- The STB will detect dune_firmware_upgrader files on the USB flash
drive and will automatically start firmware installation. During
firmware installation, the LED on the front panel of the STB will
blink, it should take about 1 minute.
- After the LED blinking stops, disconnect the USB flash drive from the
STB, and do power-off of the STB.
- If the procedure fails, the "dune_firmware_upgrader.log" file is
created in the root directory of the USB flash drive.
IMPORTANT: it is very important to not provide the upgrader mentioned above
to end users. If the users gets access to the upgrader, they will be able
to circumvent cross-upgrade limitation specified for the custom firmware.
Reverting from custom firmware to standard firmware
To process just one of a few STBs in a manual way (serial numbers of the
STBs will be needed), it is possible to use the approach described in
"Using cross-upgrade DSF" section.
To process any number of STBs in a more automated way, exactly the same
procedure can be used as described above in "Installation of created custom
firmware" section, with the following difference: the used DFF should be
correspond be a standard Dune HD firmware.
The standard Dune HD firmware here can be a base firmware corresponding to
the custom firmware, or any other standard Dune HD firmware (e.g. generic
retail firmware version, or any SDK firmware version) with the same product
ID.
Upgrading STB from one customer ID to another
If a custom firmware corresponding to certain customer ID is installed on
an STB, and it is needed to install a custom firmware corresponding to
another customer ID, the following procedure can be used.
To process just one of a few STBs in a manual way (serial numbers of the
STBs will be needed), it is possible to use the approach described in
"Using cross-upgrade DSF" section.
To process any number of STBs in a more automated way, the following
approach can be used:
1. Revert from currently installed custom firmware to standard firmware.
See "Reverting from custom firmware to standard firmware" section.
2. Install the new custom firmware. See "Installation of created custom
firmware" section.
Using cross-upgrade DSF
DFB allows to create so called "cross-upgrade DSF service file", which can
be used to cross-upgrade an STB with a particular serial-number between the
standard and the custom firmware versions.
Instructions:
1. In the DFB web UI, go to "Generate a new cross-ugprade DSF" page:
http://online.dune-hd.com/dfb/new_cross_upgrade_dsf
2. Choose a proper base product ID.
3. Enter the serial number of the STB. The serial number can be obtained
in the native Dune UI in Setup / Information menu, or in
/tmp/sysinfo.txt file inside the STB.
4. Launch the generated DSF service file (e.g. from a USB flash drive)
in the file browser of the native Dune UI. This will give the STB the
permission to cross-upgrade between the standard and the custom firmware
versions. The permission will be kept till STB reboot.
Testing the created custom DFF file
It is recommended to perform the following tests of the created custom DFF
file, before approving this DFF file for production use:
1. Firmware install test.
Ensure that the DFF file installs OK in the intended production
scenario. E.g. test that it installs OK from a USB flash drive, via
online firmware upgrade, etc.
2. (Very imporant) Firmware upgrade test.
Ensure that after the DFF file is installed on an STB, it is still
possible to install another firmware on the STB (in the way how further
firmware upgrades are expected to be installed -- e.g. via online
firmware upgrade). This is a very important test which guarantess that
even if the firmware has any problems, it will still be possible to
upgrade STBs to another firmware.
3. Functional tests.
Ensure that after the DFF file is installed on an STB, all main
functions the STB work as expected. In particular, it is typically
recommended to test the following:
- Main functions the users of the custom firmware will typically use
(e.g. playback of IPTV channels).
- All firmware aspects which were customized (custom applications,
custom UI skins, other UI customizations, etc).
- "Setting Reset" function (if available in the custom firmware).
- Connecting the STB to a TV using different kinds of video outputs
(e.g. HDMI and analog video output) (if applicable).
- Connecting the STB to network using different kinds of network
connections (e.g. Ethernet and Wi-Fi) (if applicable).
4. Load tests.
Ensure that after the DFF file is installed on an STB, the STB can
function under some load (e.g. playback of a TV channel) for a long
period of time (e.g. several hours or several days, depending on the
requirements).
Preparing custom firmware for preinstallation by Dune HD
If Dune HD provides a service of preinstalling the custom firmware image on
the STBs shipped to the customer, the custom firmware should be provided
according to the following requirements:
1. Custom firmware image should be provided as a DFF file.
2. If the custom firmware image is protected from cross-upgrade
(cross_upgrade_type = "not_allowed"), the provided DFF file should be of
normal firmware type ("fw_type" = "normal"), e.g.:
dune_firmware_besttv__hdtv_102_version.dff
3. It should be verified that the provided DFF file can be correctly
installed onto an STB in the following way:
- An STB with a standard generic firmware is used.
- Full settings reset is performed.
- The DFF file is installed onto this STB using the procedure
described in "Installation of created custom firmware".
- The STB is rebooted after the installation.
- After the STB completes the boot to the firmware and shows the
final picture (e.g. STB main menu), power off the STB.
- Wait 10 seconds, then power on the STB again and ensure it
correctly boots into the same final picture.
4. The provided DFF file should correctly survive STB power off at any
moment immediately after the STB boot is completed and the final picture
(e.g. STB main menu) is shown.
5. The provided DFF file should be tested according to "Testing the created
custom DFF file".