====================================================================== DUNE HD STB -- CUSTOM FIRMWARE IMAGES ====================================================================== Firmware image for Dune HD STB is a file in a special format (DFF) that can be installed on the STB using one of firmware upgrade mechanisms supported by Dune HD STBs. Custom firmware images (DFF files) are signed (and include various components which ensure secure boot of the STB and use various encryption schemes and digital signatures), and their creation requires the use of special tools and facilities. This document provides a technical description of the available options for custom firmware creation. Overall process --------------- The overall process to create a custom firmware image is the following: 1. Determine the requirements for the custom firmware: - The base firmware. - The list of needed changes relative to the base firmware. - Customer ID. - Cross-upgrade limitations. 2. Proceed with custom firmware image creation. Depending on business approval, the following options can be used: - a) Use Dune Firmware Build service to do it on your own. - Manual processing by Dune HD is not involved here. - See "Using Dune Firmware Build" section for more information. - b) Send a request to your Dune HD contacts. - The request is then processed manually by Dune HD (possibly with several rounds of requirements clarification/negotiation). - See "Sending firmware customization request to Dune HD" section for more information. Base firmware ============= The base firmware could be a public retail firmware, a special SDK firmware, or any other firmware which have features you need in the custom firmware. Ensure all features of the base firmware, that will be kept in the custom firmware, suite your needs. E.g.: - Ensure media files and media streams in all needed formats and utilizing all needed media streaming protocols and DRM systems can be played without problems in the base firmware. - If your application is implemented as a Dune plugin or HTML app or SVG app or native GUI app, ensure all its functions work without problems in the base firmware. Possible changes in the firmware ================================ The changes in the firmware may include: 1. Custom boot logo. If custom boot logo is needed, the picture should be provided in the following format: - 1920x1080 8-bit BMP file, which does not use BMP compression. - NOTE: Ensure that BMP file does not use BMP compression. It must be uncompressed BMP file. - NOTE: Ensure that the size of the BMP file does not exceed 2MB. - NOTE: Avoid the use of too crisp and sharp lines, ensure the picture survives upscaling/downscaling without noticeable picture distortions. 2. Any changes in "tango" filesystem. The "tango" filesystem contains most software components and resources which determine the firmware behavior. Custom firmware versions may customize the "tango" filesystem by adding/removing/changing/replacing files. This typically includes the following changes: adding a custom HTML application or a custom plugin, online firmware upgrade settings, default STB settings, custom configuration for various STB functions, etc. If you understand how to change "tango" filesystem directly, you can do it on your own, test/debug things directly on a STB, and once everything is done, just pack the entire content of "tango" filesystem and provide it as a CRAMFS image or .tar.gz archive. Otherwise, you can specify the needed changes in the firmware using higher-level specs (e.g.: add given plugin, use given skin, etc). See below for the list of things that can be customized. Certain changes (e.g. changes in the native Dune UI which can not be done by modifying plugins/skins/configuration files) may require changes in the proprietary software components, and can not be achieved just by modifying files in "tango" filesystem. Such changes can only be done by Dune HD by a special customization request. Changes in Linux kernel or low-level STB boot loaders also can only be done by Dune HD by a special customization request. NOTE: additional Linux kernel modules can be built using Dune Linux Kernel SDK and included into the firmware by modifying "tango" partition. How to test customizations ========================== During development/testing process, all changes which should be applied to "tango" filesystem can be tested in several ways: - Using "bind mount" or by replacing the "tango" filesystem directly in the flash memory of the STB. See "Modifying files in read-only /tango filesystem" and "Extracting and overwriting tango filesystem image" sections here: http://files.dune-hd.com/partners/sdk/dune_devel_info.txt - For many customizations, there is an alternative more simple way to test the customization, which does not require to modify the "tango" filesystem. This may be useful for quick and convenient preliminary testing of the changes before creating and testing the final "tango" image. Such possibilities are described in "How to test" sections below. Custom boot logo can be tested by opening the BMP file in the photo viewer in native Dune UI. The final test of the custom boot logo (how it looks during the real STB boot) can only be done after getting the custom firmware build. Things that can be customized by altering "tango" filesystem ============================================================ Plugins ------- You can add, remove, replace plugins included into the firmware. Location in "tango" filesystem: /firmware_ext/plugins Default state: The default list of plugins included into the firmware depends on a particular base firmware. How to test: Additional plugins (or modified plugin versions) can be installed in a regular way, using native Dune UI. Note: wrongly implemented plugins may depend on a particular location where they are installed (or on the possibility to write into that location, which is absent in case when the plugin is included into the firmware); this should be taken into account when implementing the plugin. UI skins for native Dune UI --------------------------- You can replace the main UI skin and modify the set of additional UI skins (add, remove, replace additional skins). Location in "tango" filesystem: /firmware/skin /firmware_ext/alternative_skins Default state: The default skin and the list of additional (alternative) skins included into the firmware depends on a particular base firmware. How to test: A new skin can be first installed in a regular way as a custom skin, using native Dune UI. After the skin is debugged, it can be included into the "tango" filesystem of the custom firmware. More information about "skins" mechanism: http://dune-hd.com/support/skins UI translations for native Dune UI ---------------------------------- Native Dune UI includes UI translations for a set of languages. You can modify these UI translations, add new UI translations, remove unneeded UI translations. Location in "tango" filesystem: /firmware/translations/languages.properties This configuration files lists all available UI translations. /firmware/translations/dune_language_*.txt For each UI translation listed in the "languages.properties" file, there should be the corresponding "dune_language_*.txt" file Default state: The default list of UI translations depends on a particular base firmware. New firmware versions may include updated UI translations and additional UI translations. How to test: A new UI translation can be first installed in a regular way as a custom language file, using native Dune UI. After the UI translation is debugged, it can be included into the "tango" filesystem of the custom firmware. More information about language files mechanism: http://dune-hd.com/support/languages Default values of STB settings ------------------------------ You can specify default values for all settings that can be edited in the Setup section of the native Dune UI (and that are stored in /config/settings.properties file). Typical settings for which default values are altered in custom firmware versions: - Language. - Video connector and video mode. - Time zone and daylight saving flag. - NTP time server address. - Sleep timer. - Zoom mode. - Show or not show certain built-in apps in the main menu. Location in "tango" filesystem: /firmware/config/settings.properties Default state: The default "default values" depend on a particular base firmware. Note, the "/firmware/config/settings.properties" file may be absent in the base firmware -- in this case, to determine the default set of "default values", the following approach can be used: do a full settings reset using native Dune UI, then "touch" any setting in order to force the STB to write the settings, and then check the content of "/config/settings.properties" file. How to test: Settings can be modified via Setup menu in native Dune UI, or the file "/config/settings.properties" can be edited directly (after the file is edited, reboot the STB or restart the "shell" process using "killall shell" command). Forced upgrade of STB settings after firmware upgrade ----------------------------------------------------- If you need a firmware upgrade to force upgrading STB settings to particular values, this can be done using "upgrade_settings.properties" file. Location in "tango" filesystem: /firmware/config/upgrade_settings.properties This file should contain the following: - Settings that should be forced. - A special property "upgrade_settings_version_tag": the value of this property should be an unique version identifier (e.g. "somecustomerid-1.0"). On each STB boot, the STB checks if forced upgrade is needed by comparing the version tag specified in the upgrade_settings.properties file and the version tag corresponding to the latest applied forced upgrade (the version corresponding to the latest applied forced upgrade is stored by the STB together with the current STB settings). If the version tag specified in the upgrade_settings.properties file is not equal to the one stored by the STB, all the settings specified in the upgrade_settings.properties file are applied, and the version tag stored by the STB is updated. This allows to ensure that forced settings upgrade is performed only once after installing the new firmware which requires forced settings upgrade. The settings upgraded in such a way (by such a firmware update) can be further modified manually if required, and these manual modifications will be kept until another firmware update (with a new version tag) will request to do a forced upgrade of these settings again. Example: video_connector = hdmi video_mode = 720p50 upgrade_settings_version_tag = besttv-1.0 Default state: The file does not exist, and thus forced settings upgrade is not performed. How to test: There is no way to test this via /config directory. See the general approach for testing changes in "tango" filesystem described in "How to test customizations" section. Configuration files determining various STB behavior ---------------------------------------------------- You can adjust the behavior of STB (including the behavior of the native Dune UI) in some additional ways using special configuration files. /firmware/config/ro_config.properties Description: Contains various parameters which influence native Dune UI appearance and behavior. If some parameter is omitted, the default value is used. Supported parameters: web_browser_home_url Description: Specifies the web site URL which is proposed to the user when the user launches the Web Browser application, and which is launched when the home button inside the Web Browser application is pressed. Default value: http://dune-hd.com web_browser_home_title Description: Specifies the caption of the home button inside the Web Browser application. Default value: Dune HD fixed_ui_type Description: Forces the specified UI type (in Appearance setup it is called "Main screen style"). When fixed UI type is specified, it is forced to be the only UI type not depending on settings, and the "Main screen style" setting is hidden in Appearance setup. Possible values: type1, type2, type3. In the Appearance setup these values are called 'Plain', 'Tabs' and 'Folders' respectivelly. Default value: . By default, current UI type is taken from the Appearance setup 'Main screen style' setting. Important notes: Using this parameter is not recommended when new GUI skin is designed for custom firmware, in this case all customizations shall be performed directly in gui_skin_config.xml. However it is still convenient for restricting the default skins. fixed_setup_view Description: Forces the specified main screen view. When fixed main screen view is specified, it is forced to be the only main screen view not depending on settings and the 'Main screen view' is hidden in Appearance setup. Possible values: defined in gui_skin_config.xml of the particular GUI skin. Default value: . By default, current main screen view is taken from the Appearance setup 'Main screen view' setting. Important notes: Using this parameter is not recommended when new GUI skin is designed for custom firmware, in this case all customizations shall be performed directly in gui_skin_config.xml. However it is still convenient for restricting the default skins. fixed_setup_view Description: Forces the specified setup view. When fixed setup view is specified, it is forced to be the only setup view not depending on settings and the 'Setup view' is hidden in Appearance setup. Possible values: defined in gui_skin_config.xml of the particular GUI skin. Default value: . By default, current setup view is taken from the Appearance setup 'Setup view' setting. Important notes: Using this parameter is not recommended when new GUI skin is designed for custom firmware, in this case all customizations shall be performed directly in gui_skin_config.xml. However it is still convenient for restricting the default skins. fixed_folder_view Description: Forces the specified folder view. When fixed folder view is specified, it is forced to be the only folder view not depending on settings and the 'Folder view' is hidden in Appearance setup. Possible values: defined in gui_skin_config.xml of the particular GUI skin. Default value: . By default, current folder view is taken from the Appearance setup 'Folder view' setting. Important notes: Using this parameter is not recommended when new GUI skin is designed for custom firmware, in this case all customizations shall be performed directly in gui_skin_config.xml. However it is still convenient for restricting the default skins. sysinfo_logo_caption Description: Specifies the caption shown in "Setup / System Information" menu. Default value: Dune HD sysinfo_web_address Description: Specifies the URL shown in "Setup / System Information" menu. Default value: http://dune-hd.com sysinfo_web_address_enabled Description: Specifies whether the URL, specified in sysinfo_web_address parameter, must be shown in "Setup / System Information" menu. Posible values: "yes" and "no". Default value: yes Firmware versions: Available starting with firmware versions 131102_b9+. default_smb_server_name Description: Specifies the the default value of SMB server name setting (accessible via "Setup / Applications / SMB server" menu). Default value: Dune default_smb_server_description Description: Specifies the the default value of SMB server description setting (accessible via "Setup / Applications / SMB server" menu). Default value: Dune SMB server default_smb_server_workgroup Description: Specifies the the default value of SMB workgroup setting (accessible via "Setup / Applications / SMB server" menu). Default value: WORKGROUP fast_standby_led_on_power_off Description: Specifies LED light behaviour when system goes into standby mode by pressing "Power" RC button. Possible values are: - "no" -- LED light blinks once, then it remains "active" (blue) for a number of seconds untill all deinitialization is completed and finally switches to "inactive" (red) state. - "yes" -- LED light becomes red immediately Default value: - no - yes in firmware 130904_b8+ Firmware versions: Available starting with firmware versions 130606_b6+. native_ui_by_hotkey_in_standby_enabled Description: Specifies if special handling of "D" RC button in standby mode is enabled ("yes") or not ("no"). When enabling, pressing "D" RC button in standby mode forces the loading of the native Dune UI, even if the STB is configured to boot to "stb_home" application instead of the native Dune UI. If it is desired to ensure that the native Dune UI can not be reached in a custom firmware, should be set to "no". Default value: yes. Firmware versions: Available starting with firmware versions *_b7+. external_plugins_enabled Description: Specifies which 3-party plugins are allowed. Possible values are: - "all" -- All 3-party plugins are allowed. - "signed" -- Only 3-party plugins signed by Dune HD are allowed. The 'signer_id' must be listed in the 'allowed_plugin_signer_ids', if list is specified. - "none" -- No 3-party plugins are allowed. Only plugins included into the firmware are available for the user. It is not possible to update these preinstalled plugins (including online update mechanism). See also "Secure firmware" section below. Default value: all Firmware versions: Available starting with firmware versions 130803_b8+. allowed_plugin_signer_ids Description: Specifies a comma-separted list of allowed plugin signer identifiers. When parameter is not specified all signer identifiers are allowed. Default value: Firmware versions: Available starting with firmware versions 130803_b8+. plugins_installation_enabled Description: Specifies if the user should be able to install new plugins. Possible values are "yes" and "no". This parameter makes sense only if external_plugins_enabled != none. The value "no" does not prevent plugins, included into the firmware, from being updated via plugin online updated mechanism. Default value: yes Firmware versions: Available starting with firmware versions 130803_b8+. external_storage_plugins_enabled Description: Specifies if "System storage" (an external storage device used for system needs) can be used to store plugins. Possible values are "yes" and "no". This parameter makes sense only if external_plugins_enabled != none. The value should be set to "no" if it is needed to prevent advanced/malicious users from adding/changing plugins via direct access to this external storage device. Default value: yes Firmware versions: Available starting with firmware versions 130918_b8+. service_file_enabled Description: Specifies which DSF service files are allowed. Possible values are: - "all" -- All DSF service files are allowed. - "signed" -- Only DSF service files signed by Dune HD are allowed. See also "Secure firmware" section below. Default value: yes Firmware versions: Available starting with firmware versions 130924_b8+. dvb_channel_image_url_prefix Description: Specifies URL prefix to use for downloading icons for DVB channels. URL for a particular DVB channel icon is constructed by appending DVB channel name to this URL prefix. Default value: http://files3.dune-hd.com/channel_images/ Firmware versions: Available starting with firmware versions 130727_b6+. skip_standby Description: Whether the standby mode should be immediately exitted each time it is entered. Possible value: yes, no Default value: no Firmware versions: Available starting with firmware versions 130618_b5+. force_fw_upgrade_autocheck_updates Description: Whether to always check online updates automatically, hiding the corresponding "Check updates automatically" setting from "Firmware Upgrade" setup. Possible values: yes, no Default value: no Firmware versions: Available starting with firmware versions 130801_b8+. soft_reset_settings_enabled Description: Whether 'Soft reset' option is enabled in Setup / General / Reset settings. Possible values: yes|no Default value: yes Firmware versions: Available starting with firmware versions 140402_b9+. recording_enabled Description: Whether playback recording enabled by pressing REC RC button in native Dune UI. Possible values: yes, no Default value: yes Firmware versions: Available starting with firmware versions 130830_b8+. recording_encryption Description: When set to 1 forces LPVR recordings to be written to disk in encrypted form. Encrypted recordings can be played only on the STB the recordings were made. Possible values: 0, 1 Default value: 0 Firmware versions: Available starting with firmware versions 140331_b9+. favorites_enabled Description: Whether favorites support in native Dune UI enabled including Favorites main screen item and "Add to main screen" popup menu actions. Possible values: yes, no Default value: yes Firmware versions: Available starting with firmware versions 130830_b8+. network_folders_enabled Description: Whether network folders enabled. When enabled, network folder can be created in 'Sources' Dune menu folder. Possible values: yes|no Default value: yes Firmware versions: Available starting with firmware versions 140402_b9+. manual_network_mounts_enabled Description: Whether manual network mounts should be shown in 'Sources' Dune menu folder. Possible values: yes|no Default value: yes Firmware versions: Available starting with firmware versions 140402_b9+. storage_ipc_check_timeout Description: Timeout in milliseconds between subsequent storage_manager checks for new IPC requests. Reducing this parameter allows to speed-up some STB API operations, but this also lead to increased CPU load. Possible values: 1..1000 Default value: 500 Firmware versions: Available starting with firmware versions 140126_b9+. dvbt_item_section_index dvbc_item_section_index dvbs_item_section_index Description: If non-negative value specifed, the DVB-T/DVB-C/DVB-S menu item is moved to the main screen. Affects only "Folders" main screen style, because in other cases DVB-T/DVB-C/DVB-S menu item is already on main screen. The property value (integer) specifies the position index of menu item. Possible values: non-negative integer or -1 Default value: -1 Firmware versions: dvbt_item_section_index: Available starting with firmware versions 130906_b8+. dvbc_item_section_index, dvbs_item_section_index: Available starting with firmware versions 140328_b9+. dvbt_is_default_section dvbc_is_default_section dvbs_is_default_section Description: Whether DVB-T/DVB-C/DVB-S menu item on the main 'sections' screen should be focused by default. Is effective only when corresponding dvb_item_section_index property is set to non-negative value. Affects only "Folders" main screen style. Possible values: yes|no Default value: no Firmware versions: Available starting with firmware versions 140328_b9+. dvbt_player_only dvbc_player_only Description: Controls whether DVB-T/DVB-C application contains non-playback part. If set to yes: DVB-T/DVB-C application launches playback immediately when pressing Enter on application; if no: DVB-T/DVB-C application first enters channel browser in Dune menu. Possible values: yes|no Default value: no Firmware versions: Available starting with firmware versions 140402_b9+. dvbt_auto_suggest_scan dvbc_auto_suggest_scan Description: Specifes behaviour of default entering the DVB-T/DVB-C applications when channels not yet configured If yes: user is suggested to perform scan, otherwise user is adviced to go to DVB-C settings, adjust parameters and perform scan manually. Possible values: yes|no Default value: yes Firmware versions: Available starting with firmware versions 140402_b9+. server_messages_enabled Description: Whether server messages service enabled. Possible values: yes|no Default value: depends on build configuration; true for public builds, false for dune_native_gui_sdk/js_stb_sdk builds. Firmware versions: Available starting with firmware versions 140208_b8+. server_messages_url Description: Main URL or service messages service: contains list of actual messages. Possible values: http URL Default value: Firmware versions: Available starting with firmware versions 140208_b8+. server_messages_update_timeout Description: Timeout in seconds between subsequent checks for new server messages. Possible values: positive integer, Default value: 86400 Firmware versions: Available starting with firmware versions 140208_b8+. server_messages_key_name Description: Name of key to be used for server messages verification. The corresponsing DSA public key file .pem must exist in /firmware/config/keys/ directory. When value is empty or not specified, then the default hard-coded key will be used. Possible values: string, corresponding key-file must exist Default value: Firmware versions: Available starting with firmware versions 140208_b8+. directfb14_odelay Description: Internal setting, affects GUI initialization. Possible values: positive integer or -1 Default value: -1 Firmware versions: Available starting with firmware versions 130911_b8+. menu_protection_type Description: Enables/disables menu protection and specifies type of protection. Currently there only 'fixed_pin' protection type is available, meaning that PIN-code is hard-coded in the firmware and cannot be changed. See the description of 'fixed_pin' parameter. The exact menu components to be protected are specified in menu_config.xml by means of protected="yes" XML attribute. Possible values: none, fixed_pin Default value: none Firmware versions: Available starting with firmware versions 130911_b8+. fixed_pin Description: Specifies the fixed PIN code to be used with menu_protection_type='fixed_pin'. Possible values: Default value: Firmware versions: Available starting with firmware versions 130911_b8+. opera_files_early_caching Description: Specifies whether to force Opera browser files to be cached by the operating system before the boot spash picture disappears. This setting affects only players on 8672/8674 chips or newer with Opera browser. This setting is useful only for the custom HTML appications ('stb_home' applications). Setting this parameter to yes leads to reducing the amount of 'black screen' time between the boot splash disappearance and the Opera browser background picture appearance. However the overall loading time increases. Possible values: yes, no Default value: no Firmware versions: Available starting with firmware versions 131022_b9+. interface_language_wizard_enabled Description: Specifies whether to show "Interface Language" dialog in setup wizard. If 'no' => dialog is skipped and default iterface language is chosed. If 'yes' => dialog is shown unless /firmware/config/settings.properties contains 'interface_language' value. Possible values: yes, no Default value: yes Firmware versions: Available starting with firmware versions 130830_b8+. default_interface_language Description: Specifies the default interface language. Possible values: one of the language names, defined in /firmware/translations/language.properties. Examples: english, french, german, etc. Default value: english Firmware versions: Available starting with firmware versions 130830_b8+. force_black_screen_for_initial_wizard Description: Forces black screen background for initial setup wizard dialog. Possible values: yes, no Default value: no Firmware versions: Available starting with firmware versions 130604_b6+. force_black_screen_for_upgrade_autocheck (not supported anymore) Description: Forces black screen background for initial firmware online upgrade autocheck dialogs. In 130914_b8+ parameter is ignored, the force_black_screen_for_initial_wizard value is used instead. Possible values: yes, no Default value: no Firmware versions: Available starting with firmware versions 130604_b6+. Not supported (ignored) starting with firmware version 130914_b8+. background_url_for_initial_wizard Description: Specifies the image URL to be used as background for initial setup dialogs. Typically it is 1920x1080 jpeg included into images directory in base firmware skin /firmware/skin/images/some_image.jpg and references by gui_skin URL schema: gui_skin://images/some_image.jpg. Possible values: image URL string Default value: Firmware versions: Available starting with firmware versions 130825_b8+. network_wizard_main_check_url Description: Specifies the http URL to be used for internet availability check "Checking Internet..." during the initial network setup wizard. Possible values: http URL string pointing to permanently available Internet resource of small size. Default value: some firmware-specific http URL to *dune-hd.com. Firmware versions: Available starting with firmware versions 130816_b8+. network_wizard_additional_check_url Description: Specifies the http URL to be used for additional "Checking Server..." stage of the initial network setup wizard. If parameter not specified then no additional network checks is performed. Possible values: http URL string pointing to permanently available Internet resource of small size. Default value: Firmware versions: Available starting with firmware versions 130816_b8+. network_wizard_connection_pppoe_enabled Description: Specifies whether PPPoE connection type can be chosen in the initial network setup wizard. Possible values: yes, no Default value: yes Firmware versions: Available starting with firmware versions 130827_b8+. network_wizard_connection_none_enabled Description: Specifies whether None connection type can be chosen in the initial network setup wizard. Possible values: yes, no Default value: yes Firmware versions: Available starting with firmware versions 130827_b8+. network_wizard_advanced_settings_enabled Description: Specifies whether advanced network-setup stages are enabled during the initial setup wizard. Possible values: yes, no Default value: yes Firmware versions: Available starting with firmware versions 130827_b8+. network_wizard_continue_anyway_enabled Description: Specifies whether network setup wizard is allowed to be passed without all network checks succeeded. If value is 'no' then "Continue Anyway" button is not shown, prohibiting user to continue without entering the correct network settings. As a special administration feature, the secret key sequence can be typed to skip the "Checking network connection" stage. Possible values: yes, no Default value: yes Firmware versions: Available starting with firmware versions 130827_b8+. network_wizard_timesync_check_enabled Description: Specifies whether to enable "Time synchronization" checking. Possible values: yes, no Default value: yes Firmware versions: Available starting with firmware versions 131112_b8+. check_fw_upgrade_in_wizard Description: Specifies whether firmware upgrade autocheck shall be performed as part of the initial setup wizard. Possible values: yes, no Default value: no Firmware versions: Available starting with firmware versions 130827_b8+. force_fw_upgrade_in_wizard Description: Specifies whether firmware upgrade autocheck stage is allowed to be passed without performing the upgrade when new firmware is available. As a special administration feature, the secret key sequence can be typed to skip the error dialog. Possible values: yes, no Default value: no Firmware versions: Available starting with firmware versions 130827_b8+. force_initial_wizard Description: Specifies whether initial wizard shall be called in special use case: auto start of the HTML plugin. The parameter does not affect other use-cases. Possible values: yes, no Default value: no Firmware versions: Available starting with firmware versions 130619_b5+. fixed_wizard_tv_standard Description: If specified, the 'TV standard' stage of the initial video setup is not shown and the specified value is used. Possible values: pal, ntsc Default value: Firmware versions: Available starting with firmware versions 121201+. stbapi_color_key_enabled Description: Whether color key support is enabled. When enabled, STB API applications including web browser can set color key to make OSD layer transparent and reveal underlying video layer. Possible values: yes|no Default value: yes Firmware versions: Available starting with firmware versions 140709_b9+. ttx_loading_force_transparent_bg Description: Whether to use transparent background while showing special 'Loading...' teletext page. Possible values: yes|no Default value: yes Firmware versions: Available starting with firmware versions 140723_b9+. shell_restart_on_return_from_launch_native_ui Description: Whether to restart shell process when returning to stb_home HTML application or native application from the call to STB API operation launchNativeUi(). Can be used when it is needed to ensure full resources cleanup/reinitialization. Possible values: yes|no Default value: no Firmware versions: Available starting with firmware versions 150814_10+. Default state: See default values described above. Also see the behavior of the native Dune UI in the standard (non-customized) firmware. How to test: Put this file into /config directory. /firmware/config/nav_sections_order.txt Description: Allows to customize the order of sections in the main menu (e.g. make the "TV" section the first section). Contains one or more lines, each line specifies one section, the listed sections are put in the beginning in the specified order, the remaining sections (not specified in this file) are appended in their standard order. Example content: root://tv Default state: See Native Dune UI in the standard (non-customized) firmware. How to test: Put this file into /config directory. /firmware/config/plugin_config.xml Description: Allows to restrict some actions for some plugins; i.e. allows to specify which plugins cannot be installed/replaced/deleted. There are also the ro_config parameters 'external_plugins_enabled' and 'plugins_installation_enabled' designed for the same purpose, but they provide less flexibility. Using of these ro_config parameters toghether with plugin_config.xml is not recommended; if ro_config possibilities are not sufficient, plugin_config.xml should be used instead. Firmware versions: Available in firmware_versions 150113_b9+. Syntax: yes | signed | no yes | no yes | same_signer_id | no yes | no yes | same_signer_id | no yes | signed | no yes | no yes | same_signer_id | no ... new plugin must be signed with same signer id; (2) if previous plugin is not signed => new plugins can be not signed or signed with any signer id. NOTE: the 'allow_replace' specification does not affect online update use-case; the update is always restricted by 'same_signer_id' logic. Example 1: - signed plugins installation allowed (e.g. Dune Store plugins). - installation of not signed external plugins not allowed; - embedded plugin MyPlugin managed by customer: can be not signed, replace not allowed, online update can be enabled. - plugin_config.xml: signed yes same_signer_id no NOTE: to enable replace of MyPlugin from storage, change the corresponding allow_replace value to 'same_signer_id' or 'yes'. Example 2 - external plugins installation not allowed; - all embedded plugins: can be not signed, online update can be enabled, replace not allowed; delete not allowed. - plugin_config.xml: no no no Example 3 - everything allowed for all plugins except embedded MyPlugin; - MyPlugin cannot be deleted or replaced; online update can be enabled. - plugin_config.xml: no no /firmware/config/menu_config.xml Description: The main Dune menu configuration file. Contains the specification of top-level Dune menu and setup hierarchy in XML format. Consists of 3 parts: - global parameters; - list of top-level Dune menu sections; - list of setup screens; File structure: param_value
Supported global parameters: show_slave_sections Description: Specifies whether to show "slave" sections in "Folders" main screen style. If value "no" is specified, then appearance setup setting "Additional categories in main screen" is not shown. See below about "master" and "slave" sections. Possible values: yes, no Default value: no Section list: Specifies the ordered list of "sections" -- top-level Dune menu folders. The sections are shown at top level of Dune menu in "Tabs" and "Folders" main screen style. Each section has unique identifier known as "url". Each section URL must start with prefix root://. There is a number of predefined section URLs with special meaning, see below for details. Each section can be "master" or "slave". The master sections are always shown in menu. The slave section is shown in menu only if all the following conditions are met: 1. The "show_slave_sections" parameter is "Yes". 2. The setting "Main screen style" is "Folders". 3. The setting "Additional categories in main screen" is "Yes". Each slave sections belongs to one of the master sections. When slave section is not shown, it's items are moved to it's master section. Some sections are so-called "application containers". Most Dune applications, implemented as Dune plugin, extend the Dune menu with new items, providing section URL to specify where to put it's menu items. For correct support of all existing Dune application, all standard application-container sections URLs must present in section list. Here are the ULRs of standard application container sections: root://tv root://applications root://video root://music_and_radio root://news_and_weather root://social_networks root://games The custom menu_config.xml may also specify other application container sections. When parameter "show_slave_sections" is "no" the slave sections are never visible but they still can be used to specify where to put the corresponding application menu items. See below the example of such "dummy" slave section definition. There is also a number of sections with predefined content and behaviour; some of them must present in every menu_config.xml. Their URLs are: root://sources This section contains menu items for storages, network folders and a Network Browser. This section must present in section list. NOTE: This section can be skipped in firmware versions 131014_b8+. root://favorites This section is a "Favorites" folder: it contains the list of links, manually created by used by executing "Add to favorites" action from popup-menu or by pressing "D" RC button. This section can be skipped in section list, but only together with specifying favorites_enabled=no in ro_config.properties. root://setup This section contains Dune setup screen. See below about configuring the setup hierarchy in menu_config.xml. This section must present in section list. Master section example:
root://tv navigator_section_tv navigator_section_tv_details TV section_tv TV gui_skin://special_icons/top_section_tv.aai 1
Slave section example:
root://video root://applications navigator_section_video navigator_section_video_details VIDEO section_video SECTION_VIDEO
"Dummy slave" section example:
root://video root://applications
Section parameters description: url Description: Unique section string identifier. Must be started with prefix root://. There is a number of predefined section URLs referenced from firmware code and from a large number of existing Dune plugins. Possible values: root://* Default value: parameter is mandatory caption_t_key Description: Translation key, referencing the user-visible section name. Key must present in the default translation file. Possible values: string key existing in default translation file Default value: parameter is mandatory unless section is "dummy slave", in the latter case value is ignored. details_t_key Description: Translation key, referencing the user-visible section description. The description is auto-split into words and painted in the details block in the right of the screen when section menu item is focused. Key must present in the default translation file. Possible values: string key existing in default translation file Default value: parameter is mandatory unless section is "dummy slave", in the latter case value is ignored. small_state_text Description: String, shown in FIP display for Dune models equipped with FIP display. String is preferred to have only ASCII 127 printable characters without lowercase letter; however it is not the requirement. Possible values: string Default value: parameter is mandatory unless section is "dummy slave", in the latter case value is ignored. icon_id Desciption: String, specifying the GUI representation of the menu item. The "icon_id" is a key, referencing some IconViewItem, described in the root IconView definition of the current GUI skin. The value of this parameter must be defined in the default GUI skin of custom firmware and in all skins, supported by the custom firmware. See the following root IconView definition files in GUI skins in the default dune firmware for more details: /firmware/skin/large_icons/nav_root_*.properties ("Base" skin) /firmware_ext/alternative_skins/Black/large_icons/nav_sections_demo_5x1.properties ("Black" skin) Also see how these files are referenced from GUI skin configuration files: /firmware/skin/dune_skin_config.xml and /firmware_ext/alternative_skins/Black/dune_skin_config.xml Possible values: string, mentioned in the root IconView GUI skin file, see description for more details. Default value: parameter is mandatory unless section is "dummy slave", in the latter case value is ignored. small_icon_name Description: String, identifying "small" icon for the section. This icon is pained in the path block when section is entered. Currently only a fixed hard-coded list of small icons can be used here: all icons from "small_icons" directory of the default Dune GUI skin. See the http://files.dune-hd.com/partners/sdk/small_icons.txt for complete list of suppoted small icons with their identifiers. Possible values: string, a valid small icon identifier. Default value: parameter is mandatory unless section is "dummy slave", in the latter case value is ignored. master_section_url Description: String, specifying the master section URL, assigned to this slave section. If "master_section_url" parameter is specified, then this section called "slave"; otherwise it is called "master". The section, referenced by the "master_section_url", must be "master" itself. See the "Section list" description above for more details about master and slave sections. Possible values: string, URL of the existing section. Default value: if not specified, section is considered "master". tab_icon_url Description: Icon URL, specifying the representation of this master section in the top-box on main screen in "Tabs" main screen style. Value is ignored and should not be specified for slave sections. Normally, such icons are located in the "special_icons" folder of the current skin; so the URL shall look like: gui_skin://special_icons/. See the standard Dune firmware for examples. Possible values: gui_skin:// icon URL. Default value: value is mandatory for master sections and ignored for slave sections. tab_order_ndx Description: Integer, specifying the order of master sections in all cases when slave sections are hidden. NOTE: when slave sections are shown the order of sections is specified by order of section elements in menu_config.xml. Possible values: 0 .. number_of_master_sections-1 Default value: value is mandatory for master sections and ignored for slave sections. Setup screen list: Setup screens customization available in firmware versions 131010_b9+. Specifies the list of setup screens. There are several types of setup screens: - folder - generic - other specific setup screens with predefined behaviour: - video - network - torrents - fw_upgrade - sysstor - plugins - sysinfo The "folder" setup screens represent the list of other setup screens. Folder screens may contain other folder screens, so the multi-level hirarchy of setup screens can be specified. The "generic" setup screens represent the list of setup settings, visualized as vertical list of GUI controls: comboboxes, text fields, buttons and fixed text strings. Other "special" setup screens have specific predefined visualization and behaviour. Some of them have type-specific parameters. Every setup screen has unique string identifier "id"; some of them have the predefined meaning: - id="setup" the root setup screen, must be "folder"; - id="applications" setup screen of type "folder", many existing Dune plugins place their setup screens into this folder. Example of folder setup screen: Example of generic setup screen: Example of video setup screen: Example of network setup screen: Example of system information screen: Common setup screen parameters: id Syntax: XML attribute "id" of "screen" element. Description: Unique setup screen string identifier. The id="setup", and id="applications" have special meaning. See above the "Setup screen list" description for more details. Possible values: string Default value: value is mandatory type Syntax: XML attribute "type" of "screen" element. Description: Setup screen type. See above the "Setup screen list" description for more details. Possible values: string, one of the predefined string constants Default value: value is mandatory icon_id Syntax: XML attribute "icon_id" of "screen" element. Desciption: String, specifying the GUI representation of the setup screen item as an element of parent folder. The "icon_id" is a key, referencing some IconViewItem, described in the setup IconView definition of the current GUI skin. The value of this parameter must be defined in the default GUI skin of custom firmware and in all skins, supported by the custom firmware. See the following setup IconView definition files in GUI skins in the default dune firmware for more details: /firmware/skin/large_icons/setup_*.properties ("Base" skin) /firmware_ext/alternative_skins/Black/large_icons/setup_demo_5x2.properties ("Black" skin) Also see how these files are referenced from GUI skin configuration files: /firmware/skin/dune_skin_config.xml and /firmware_ext/alternative_skins/Black/dune_skin_config.xml Possible values: string, mentioned in the setup IconView GUI skin file, see description for more details. Default value: parameter is mandatory. small_icon_name Syntax: XML attribute "small_icon_id" of "screen" element. Description: String, identifying "small" icon for the setup screen item representation in the parent folder view. This icon is visible only when the "Setup screen view" setup setting is set to "List" which is rarely used. Currently only a fixed hard-coded list of small icons can be used here: all icons from "small_icons" directory of the default Dune GUI skin. See the http://files.dune-hd.com/partners/sdk/small_icons.txt for complete list of suppoted small icons with their identifiers. Possible values: string, a valid small icon identifier. Default value: parameter is mandatory. caption Syntax: Child XML element "caption" of "screen" element. There are two variants: - reference the translation files by the "t_key" XML attribute of a single "caption" child element. Example: - specify the caption directly with possiblity to specify different languages by placing several "caption" XML elements with different values of "lang" attribute. The default caption must be specified as "caption" child elemnt without "lang" attribute. Example: Audio וידוא Description: User-visible setup screen name with multilanguage support. Possible values: see Syntax for more details Default value: value is mandatory Additional folder screen specification: screens / screen / id Folder screen specification is an ordered list of screen identifiers: the list of folder elements. Also see above the "Example of folder setup screen". screens / screen / protected Description: The "yes" value enables menu protection for entering the child setup screen. See the description of "menu_protection_type" of the ro_config.properties for more details. Possible values: yes | no Default value: no screens / screen / advanced Description: The "yes" value turns on the following logic: when setup setting "hide_advanced_settings" is set to "Yes" then the current setup screen element is hidden; otherwise it is shown as usual. Possible values: yes | no Default value: no Addition generic screen specification: settings / setting / id Generic screen specification is, primarily, an ordered list of settings. A list of available settings is fixed in firmware, see all specifications in /firmware/config/menu_config.xml from standard Dune firmware for a complete list of available setting identifiers. Every setting have predefined visualization (as GUI control) and a predefined effect on Dune firmware behaviour. Also see above the "Example of generic setup screen". settings / settings / protected Description: The "yes" value enables menu protection for modifying this setup setting. See the description of "menu_protection_type" of the ro_config.properties for more details. Possible values: yes | no Default value: no settings / setting / advanced Description: The "yes" value turns on the following logic: when setup setting "hide_advanced_settings" is set to "Yes" then the current setup screen is hidden; otherwise it is shown as usual. Possible values: yes | no Default value: no Additional video setup screen specifications: Several customization parameters supported for video setup screen. See above the "Example of video setup screen" for example and syntax. The supported parameters are: show_auto_framerate Description: Whether to show "Auto framerate" combobox in video setup screen. Possible values: yes | no Default value: yes show_advanced_settings Description: Whether to show "Advanced settings" button in video setup screen. Possible values: yes | no Default value: yes Additional network setup screen specifications: Several customization parameters supported for network setup screen. See above the "Example of network setup screen" for example and syntax. The supported parameters are: show_wifi_ap Description: Whether to show Wi-Fi access point customization settings in network setup screen if Wi-Fi access point is supported in firmware. Possible values: yes | no Default value: yes Additional system information screen specifications: Several customization parameters supported for system information screen. See above the "Example of system information screen" for example and syntax. The supported parameters are: show_product_id show_firmware_version show_serial_number show_license show_ip show_mac show_time show_system_storage Description: Whether to show the corresponding text line in system information screen. Possible values: yes | no Default value: yes Firmware versions: System information screen parameters available in firmware versions 140402_b9+. Default state: See the content of menu_config.xml file and the behavior of the Native Dune UI in the standard (non-customized) firmware. How to test: Put this file into /config directory. Firmware versions: Available in firmware versions 130315_b6+. /firmware/config/menu_order.txt /config/menu_order.txt /config/menu_order_orig.txt Description: The menu_order.txt file specifies the initial order of elements in some Dune menu folders: - all application-container sections (folder URLS: root://tv, root://applications, root://video, etc..); - "Sources" section (folder URL: root://sources); - root setup folder screen, the same as setup section (folder URL: root://setup); - setup screen with id "applications" (folder setup://applications). Also see the description of /firmware/config/menu_config.xml for more details about Dune menu sections and setup screens. File structure / syntax: File is prosessed in forward direction. Each nonempty line contains single order declaration. The order declaration contains 2..4 fields separated by spaces: [ [ the only file /config/menu_order.txt is processed. - otherwise the /firmware/config/menu_order.txt is processed first and then the /firmware/config/menu_order.txt is processed. After that, the /firmware/config/menu_order.txt is copied to /config/menu_order.txt. Finally, all missing "plugin" order declarations are added for all existing Dune plugins and the result is saved to /config/menu_order.txt; so this file is changed by firmware each time the list of Dune plugins is changed. NOTE: as a result, if the initial menu order /firmware/config/menu_order.txt is changed during firmware upgrade, then it is merged with the effective menu order stored in the /config/menu_order.txt. How to test: Put this file into /config directory. Default state: See the content of this file and the behavior of the Native Dune UI in the standard (non-customized) firmware. Firmware versions: Available in firmware versions 130315_b6+. /firmware/config/main_plugin_name.txt Description: Contains the name of so called "main plugin". If your want to enable automatic startup of certain plugin on STB boot, you can configure auto-start parameters in the plugin manifest (see documentation on PHP plugins), and declare this plugin as "main plugin". Example content: somepluginname Default state: There is no main plugin. How to test: Put this file into /config directory. /firmware/config/nav_fw_upgrade_dont_ask_confirmations Description: A flag file which disables all confirmation dialogs shown by the native UI when firmware upgrade is triggered manually by the user by launching a firmware file (DFF) or trigerred via Dune STB API. Example content: Does not matter (only file existence is checked). Default state: These confirmation dialogs are enabled. How to test: Put this file into /config directory. /firmware/config/fw_online_upgrade_dont_ask_confirmations Description: A flag file which disables most (all except the very first one) confirmation dialogs shown by the native UI when online firmware upgrade is triggered by the built-in online firmware mechanism (when the user launches online firmware upgrade via "Setup / Misc / Firmware Upgrade" menu, or when the online firmware upgrade is triggered automatically). The very first confirmation dialog is shown not depending on this flag. Example content: Does not matter (only file existence is checked). Default state: These confirmation dialogs are enabled. How to test: Put this file into /config directory. /firmware/config/fw_autocheck_dont_confirm_new_suitable_version Description: A flag file which disables the very first confirmation dialog shown by the native UI when online firmware upgrade is automatically triggered by the built-in online firmware mechanism. Typically should be used together with "fw_online_upgrade_dont_ask_confirmations" flag file to completely disable any confirmations when automatic online firmware upgrade happens. Example content: Does not matter (only file existence is checked). Default state: This confirmation dialog is enabled. How to test: Put this file into /config directory. Firmware versions: Available starting with firmware version 130719_2101_b6. /firmware/config/fw_autocheck_force_on_resume Description: A flag file which forces online firmware upgrade auto-check to be performed each time when STB leaves standby mode, even if the auto-check was already performed recently. Normally (when this file does not exist), the auto-check is performed not more often than each 24 hours. Example content: Does not matter (only file existence is checked). Default state: Auto-check is performed not more often than each 24 hours. How to test: Put this file into /config directory. Firmware versions: Available starting with firmware version 130719_2101_b6. /firmware/config/media_player_config.properties Description: Allows to specify whether media-player functionality is enabled or not. In runtime it is possible to override the configuration from /firmware/config/media_player_config.properties file. For this purpose /tmp/run/media_player_config.properties file should be used. The files contain the following parameter: - media_player -- Specifies whether media-player functionality is completely enabled ("yes") or completely disabled ("no"). See also "Conditional enabling of media-player functionality" section below. Example content: media_player = no Default state: Media-player functionality is completely enabled. How to test: Put this file to /tmp/run/media_player_config.properties Firmware versions: Available starting with firmware versions 130831_b8+. /firmware/config/dsconfig.xml Description: Allows to customize the list of application sources for Dune Store. See more information here: http://files.dune-hd.com/partners/sdk/dune_store.txt "Using custom Dune Store server in custom firmware" Default state: Standard application source is used. How to test: Put this file into /config directory. Firmware versions: Available starting with firmware versions 130716_b6+. /firmware/config/prefer_dhcp_ntp_server.flag Description: When this flag file exists, it specifies that NTP server provided by DHCP server should be used even if NTP server is unset in STB settings (i.e. "time_server" property in "settings.properties" configuration file is set to the default value ""). Default state: NTP server specified in STB settings takes precedence over NTP server provided by DHCP server. How to test: There is no way to test this via /config directory. See the general approach for testing changes in "tango" filesystem described in "How to test customizations" section. /firmware/config/default_dhcp_time_zone Description: The content of this file specifies the time zone which should be used when the time zone is unset in STB settings (i.e. "time_zone" property in "settings.properties" configuration file is set to the default value "auto", which means "use setting from DHCP"), and DHCP server does not provide the time zone information. The format of "default_dhcp_time_zone" setting is a string in the same format as provided by DHCP server, e.g. "GMT-04:00" for GMT+4. Default state: If neither STB settings nor DHCP server specify the time zone, GMT+0 time zone is used. How to test: There is no way to test this via /config directory. See the general approach for testing changes in "tango" filesystem described in "How to test customizations" section. Custom HTML application ----------------------- Custom HTML application is launched on STB boot instead of native Dune UI. NOTE: This requires base firmware with Opera or Webkit web browser. For more information, see here: http://files.dune-hd.com/partners/sdk/html_apps.txt Location in "tango" filesystem: /firmware/config/stb_home/index.html Default state: By default, this file is absent in the base firmware (i.e. native Dune UI is started). How to test: Put the files into the following directory: /config/stb_home/ Custom web browser configuration for HTML application ----------------------------------------------------- The web browser can be started with custom parameters instead of the default ones. For more information about web browser start parameters, see "Web browser start parameters" section here: http://files.dune-hd.com/partners/sdk/html_apps.txt Location in "tango" filesystem: /firmware/config/web_browser_start_params Default state: The file does not exist, and thus the default parameters are used. How to test: Put the file into the following directory: /config Custom SVG application ---------------------- Custom SVG application is launched on STB boot instead of native Dune UI. NOTE: This requires base firmware with Ekioh browser. Location in "tango" filesystem: /firmware/stb_home/index.svg Default state: By default, this file is absent in the base firmware (i.e. native Dune UI is started). How to test: Put the files into the following directory: /config/stb_home/ Additional tools: See the description of "dune_service_install_stb_home.dsf" in "Tools for installing files into /config/stb_home" section here: http://files.dune-hd.com/partners/sdk/html_apps.txt Custom native GUI application ----------------------------- Custom native GUI application (implemented in C/C++ using DirectFB and optionally Qt, and using Dune C STB API) is launched on STB boot instead of native Dune UI. NOTE: This requires Native GUI SDK base firmware. The custom native GUI application should replace "shell" executable. Location in "tango" filesystem: a) Direct replacement of "shell" executable (recommended): /firmware/bin/shell b) Indirect replacement (when exists, this file contains the path of the executable which should be used instead of "/firmware/bin/shell"): /firmware/config/stb_exec.url Default state: By default, "/firmware/bin/shell" contains the standard version of "shell" executable (which launches native Dune UI), and "/firmware/config/stb_exec.url" file does not exist. How to test: Use "/config/stb_exec.url" as described in the Native GUI SDK documentation. Custom fonts for Opera web browser ---------------------------------- You can add custom fonts to Opera web browser (when a firmware with Opera web browser is used), by adding them into the Opera fonts folder. Location in "tango" filesystem: /firmware_ext/opera/fonts How to test: Put the fonts into the following directory: /config/fonts Custom fonts for Webkit web browser ---------------------------------- You can add custom fonts to Webkit web browser (when a firmware with Webkit web browser is used), by adding them into the Webkit fonts folder. Location in "tango" filesystem: /firmware_ext/qt47_2browser/lib/fonts How to test: There is no way to test this via /config directory. See the general approach for testing changes in "tango" filesystem described in "How to test customizations" section. Custom boot script ------------------ Custom boot script is executed during STB boot, and can do various things, e.g. it can launch background processes, modify various configuration files in RAM disk, etc. Typical usages: - Load some Linux kernel modules. - Launch some daemon in background. - Modify files in /etc (e.g. put custom root password into /etc/shadow, put custom configuration for the built-in HTTP server into /etc/httpd.conf). - Modify files (e.g. add static content or CGI scripts) in the root folder (/tmp/www) of the built-in HTTP server. Various related information: http://files.dune-hd.com/partners/sdk/dune_devel_info.txt http://files.dune-hd.com/partners/sdk/dune_boot_process.txt Location in "tango" filesystem: /firmware/config/start.sh NOTE: To ensure that this script does not block STB boot, all actions that may potentially block for a while or hangup are recommended to do in background. Default state: By default, this file does not exist. How to test: Put the custom boot script into "/config/boot/" directory. Custom environment script ------------------------- Custom environment script is intended for changing environment variables accessible by "shell" process, including web and SVG browsers, or native GUI application. The script is sourced once during STB boot if it exists. Typical usages: - Modify environment of main UI process. Location in "tango" filesystem: /firmware/config/custom_env.sh NOTE: primary goal of this script is to modify environment of main UI process. If you would like to perform various actions on STB boot it is recommended to use /firmware/config/start.sh instead, see "Custom boot script". Default state: By default, this file does not exist. How to test: Create the following file: /config/custom_env.sh Key for SSH access ------------------ NOTE: Supported only for base firmware versions which include SSH server (such as SDK firmware versions). Location in "tango" filesystem: /firmware/config/authorized_keys Default state: By default, in the SDK base firmware versions, this file contains the development public key (NOTE: the corresponding private key is documented in the SDK and thus is publically available). How to test: Put the "authorized_keys" file into "/config" directory. Custom server for online firmware upgrade ----------------------------------------- Custom firmware can implement online firmware upgrade in several ways: 1) If the custom firmware is based on the native Dune UI (e.g. custom application is implemented as a PHP plugin), it it possible to customize the HTTP URL of the firmware upgrade server used by the built-in online firmware upgrade mechanism. Location in "tango" filesystem: /firmware/config/fw_online_upgrade_url.txt This file should contain the HTTP URL prefix pointing to the firmware upgrade server. For the details, please see here: http://files.dune-hd.com/partners/sdk/dune_online_firmware_upgrade.txt "Built-in online firmware upgrade mechanism" Default state: By default, the standard Dune HD firmware upgrade server is used. How to test: Put the "fw_online_upgrade_url.txt" into "/config" directory. 2) If the custom firmware does not use the native Dune UI (e.g. HTML or SVG middleware UI is used), it can use a simple automatic firmware upgrade (also know as "STB upgrade checker") mechanism. This mechanism can also be used with the standard middleware systems, which do not provide their own online firmware upgrade mechanism. Location in "tango" filesystem: /firmware/config/stb_upgrade_checker.properties For the details, please see here: http://files.dune-hd.com/partners/sdk/dune_online_firmware_upgrade.txt "Automatic firmware upgrade (STB upgrade checker mechanism)" Default state: By default, STB upgrade checker mechanism is disabled. How to test: Put the "stb_upgrade_checker.properties" file into "/config" directory. 3) If the custom firmware does not use the native Dune UI and implements its own GUI application (e.g. in HTML, SVG, or C), and the simple STB upgrade checker mechanism is not suitable, the custom GUI application can implement checking for firmware upgrades on its own. To do it, the following should be implemented in the custom GUI application: - Check for availability of firmware upgrades (on STB startup or periodically) -- using any suitable protocol and algorithm. As the result, the application should determine if the firmware upgrade is desired, and determine the target firmware version and firmware image URL. - Possibly show a message to the user and/or get a confirmation from the user (depending on what behavior is required by the application). - Use Dune STB API operation to trigger the firmware upgrade procedure (passing the firmware image URL to it). Dune STB will download the firmware image and perform firmware upgrade on its own (native Dune GUI will be shown to indicate the firmware upgrade process). Custom STB boot procedure ------------------------- If the standard STB boot procedure is not desired for some reason, it can be replaced by modifying/replacing the corresponding files in the "tango" filesystem. See here for more information: http://files.dune-hd.com/partners/sdk/dune_boot_process.txt Custom network initialization script ------------------------------------- There is a special possibility allowing to override the standard network initialization script with a custom one, in order to implement custom network initialization logic. Location in "tango" filesystem: /firmware/config/scripts/init_network.sh If this script exists, it is used instead of the standard network initialization logic located in "/firmware/scripts/init_network.sh". NOTE: creation of a custom network initialization script may not be easy and requires detailed understanding of the standard network initialization logic located in the following files: /firmware/scripts/init_network.sh /firmware/scripts/udhcpc_callback.sh Default state: The custom script file does not exist, and the initialization logic from the standard script is used. How to test: Put the "init_network.sh" script into "/config/scripts" directory. Product ID ========== Product ID is a string which identifies a particular model of Dune HD STB. Different Dune HD models have different product IDs. Example: "hdtv_101" is a product ID for for Dune HD TV-101. Product ID is shown in the native Dune HD menu in Setup / Information. Each firmware is always built for a particular product ID, and can not be installed (excepting special cases) on the STB where the firmware for another product ID is currently installed. Customer ID =========== Custom firmware images typically have their own custom product IDs. Customer ID is a string which is added to the base product ID (as prefix or suffix) in order to distinguish custom and standard firmware versions, and optionally to protect from "cross-upgrading" between standard and custom firmware versions. Example: Base product ID: hdtv_101 Customer ID: besttv Resulting custom product ID: besttv__hdtv_101 Customer ID can be an arbitrary string (minimum length 3 characters, maximum length 32 characters) consisting of lowercase alphanumeric characters. You can choose whatever customer ID you want and confirm with your Dune HD contacts that this customer ID is valid and unique. The same customer can use different customer IDs for different projects. Cross-upgrade limitations ========================= Cross-upgrade limitations determine if end users are allowed to install custom firmware over standard firmware and vice versa. NOTE: even if end users are prohibited to do cross-upgrades, the customer itself can have a possibility to cross-upgrade the boxes in any direction (this may be required e.g. for the initial preparation of STBs and for service needs). There are the following kinds of cross-upgrade limitations for end users: - (a) ("not_allowed") Cross-upgrade is not allowed at all. - Allowed cross-upgrades: - standard -> custom: no. - custom -> standard: no. - (b) ("any") Cross-upgrade is allowed in any direction. - Allowed cross-upgrades: - standard -> custom: yes. - custom -> standard: yes. - (c) ("to_custom") Cross-upgrade is allowed from standard-fw to custom-fw only. - Allowed cross-upgrades: - standard -> custom: yes. - custom -> standard: no. Depending on the kind of cross-upgrade limitations, the custom product ID is constructed from the base product ID and customer ID in one of the following ways: - For (a) ("not_allowed"): {customer ID}__{base product ID}. - For (b) ("any") and (c) ("to_custom"): {base product ID}_{customer ID}. NOTE: The use of (c) ("to_custom") is typically not recommended. NOTE: For most projects, (a) ("not_allowed") is the most appropriate option. Secure firmware =============== In some cases, it may be desired to protect the STB from the access inside the STB by advanced (or malicious) users. For example, it may be required if the digital rights owner / DRM vendor requires this. Even in the standard firmware, there are no such direct ways (e.g. telnet access to the STB is disabled by default), but advanced/malicious users can potentially find a way to get the access inside the STB, e.g. by installing/launching a special plugin or DSF file on the STB. To protect the STB from this, the custom firmware should be made secure, which may include some or all of the following: 1) Use cross-upgrade limitation kind "not_allowed", to ensure that end users will not be able to install a standard retail firmware (or some other custom firmware) on top of your custom firmware. 2) Disable launching arbitrary DSF service files: - Put "service_file_enabled = signed" setting into /firmware/config/ro_config.properties file. 3) Disable installing and launching arbitrary 3-party plugins: - Put "external_plugins_enabled = signed" setting into /firmware/config/ro_config.properties file. 4) If the custom firmware includes telnet service (NOTE: generally not recommended, enabling SSH access is recommended instead), or if a particular STB model has UART connector/pins available and it is desired to protect this UART port, set a custom root password: - Include a custom boot script into the firmware (/firmware/config/start.sh), and put the following code into this script in order to install a custom root password into /etc/shadow file: - sed -i 's;^root::;root:@@HASH@@;' /etc/shadow - Here, @@HASH@@ string should be replaced with an actual hash, which can be obtained using the following commands performed inside the STB: - passwd root - grep "^root:" /etc/shadow | awk -F: '{print $2}' 5) If the custom firmware is built for Dune HD TV-101 model (discontinued), request and use a special "secure" base firmware, which ensures that only specially signed firmware images can be installed and that cross-upgrade limitations can not be bypassed. For all newer Dune HD STB models, this is not needed (all firmware images are signed this way by default). Conditional enabling of media-player functionality ================================================== In some cases, it may be desired to enable media-player functionality of Dune HD STB conditionally, depending on some factors (e.g. depending on the whether the user account in the billing of the operator is not blocked). In particular, this may be useful when an operator sells the STBs with a discount, or provides STBs to end users for free (and requires end users to pay for the subscription to the IPTV/VOD service only). If the custom firmware is configured to automatically boot some custom HTML or SVG application (via /firmware/config/stb_home mechanism), it is enough to ensure the following: - The application must not allow the user to launch the native Dune UI (except maybe Setup or Network Setup UI screens, which can be launched separately from the the rest of the native Dune UI) unless the application checks that this should be allowed. - Put "native_ui_by_hotkey_in_standby_enabled = no" setting into /firmware/config/ro_config.properties file. If the custom firmware is based on the native Dune UI (or if it is desired to have the native Dune UI freely accessible w/o any limitations), another approach can be used -- disabling the media-player functionality by default, and enabling it only after the custom firmware / custom application ensures that the user should be permitted to do it. Here, media-player functionality means the possibility to launch any media playback via native Dune UI or launch any application via native Dune UI. To use this approach: - Put "media_player = no" into /firmware/config/media_player_config.properties - In the custom firmware / custom application check if the user is permitted to use media-player functionality. - If the user is not permitted, do nothing. As a result, media-player functionality will be disabled. - If the user is permitted, put "media_player = yes" into /tmp/run/media_player_config.properties. As a result, media-player functionality will be enabled. Whenever conditional enabling of media-player functionality is used, it is typically needed also to make the firmware "secure" in order to ensure that advanced/malicious users will not be able to get inside the STB and find a way to bypass this restriction (see "Secure firmware" section for more information). Using Dune Firmware Build service ================================= Dune HD partners/customers can be allowed to create custom firmware images on their own (w/o manual processing on the Dune HD side), using Dune HD Firmware Build service ("DFB"). A special account is required to use DFB service. See here for more information about DFB service: http://files.dune-hd.com/partners/sdk/dfb.txt Sending firmware customization request to Dune HD ================================================= Send the request to your Dune HD contacts by e-mail. Include the following information into the request: - Dune HD model (or list of models). - Base firmware (for each model). - Customer ID. - Cross-upgrade limitations. - Boot logo picture. - Changes in one of the following forms: - (a) Custom "tango" filesystem image (for each model). - (b) Detailed list of all needed changes (relative to the base firmware) and all the corresponding files (plugins, skins, index.html, etc). If you provide the specification of the required changes as custom "tango" filesystem image, please fully test this custom "tango" filesystem image in advance on your side (ensure that after writing this custom image into the flash memory of the STB, it works fully correctly in all required use cases). If you provide the description of the required changes in other forms, in many cases, one or several rounds of requirements clarification/negotiations (and sometimes intermediate firmware releases) may be required to order to create a clear specification and create the custom firmware according to it. Depending on a particular requirements and depending on how much preparation work is to be done on Dune HD side, the overall firmware customization process may require a considerable amount of R&D work from Dune HD side. In some cases, the requested changes can not be implemented using the available firmware customization options on top of an existing base firmware, and changes in the base firmware may be required. Implementing changes in the base firmware would often require a significant amount of R&D work from Dune HD side. To minimize the dependency on the available Dune HD's R&D resources, it is recommended to do as much preparation work as possible on the customer's side, and, whenever possible, fit into already available firmware customization options.