Boot image config file syntax

Below is a description of all valid boot image config syntax constructs. Note that adding an undocumented parameter to an IIP will result in a build error.

# This is a comment. Empty lines and comments are ignored.

# Below is a comment that is the equivalent of passing.
# "--info <name> <value>" to build_boot_image.
# $<name>:<value>$

# Basic format without and with parameters.
iip-name
iip-name:param1=value1,param2=value2

# Include other configs (the two "" are optional).
@include "/absolute/path/to/config"
@include "../relative/this/config"

# Extra directory to search for IIPs, in addition to the ones given to
# build_boot_image with --source. May be given several times.
@search "/external/vendor/latest"

# Instead of writing "iip-name:param1=value1,param2=value2" on a single line,
# it can be split into two lines using "::" instead of ":" the second time.
# The result is that the parameters are concatenated.
iip-name:param1=value1
iip-name::param2=value2

# Remove an IIP by placing a "-" before the IIP name.
-iip-name

# Append a parameter name to remove the parameter but not the IIP.
-iip-name:param1

# Break long lines with backslash. Spaces before the backslash and at the start
# of the next line are ignored.
iip-name:long-parameter-name=with-a-long-parameter-value- \
  that-continues-on-the-next-line

# Environment variables are expanded in IIP parameters and path to include file.
iip-name:user=%USER%
@include "%HOME%/config"

# Environment variables are also expanded in the architecture list. This can be
# used to e.g. conditionally include an IIP based on the environment.
iip-name(%ARCHITECTURE%)

# A specific IIP can be include by using an absolute path.
/external/vendor/iip-name.iip:parameters

# All of the above constructs can be specified for only one or several
# architecture(s) using the syntax (arch1,arch2,...). See examples below.

# Include IIP only for VIP28x3.
iip-name(vip28x3)

# Add an extra parameter for VIP28x3.
iip-name(vip28x3)::param=value

# Include IIP for all platforms but VIP28x3.
iip-name
-iip-name(vip28x3)

# Use parameter on all platforms but VIP28x3.
iip-name:param=value
-iip-name(vip28x3):param

Example - boot image configuration

The SDK contains an example boot image configuration file, shown below. The name of the config is example.config. The following command will build the boot image for a vip43x2 box. Please, replace <sdk> with your SDK installation directory.

$ cd <sdk>/build_scripts
$ ./build_vip43x2.sh example.config

The following is the contents of example.config:

#### Boot image configuration file
#
# This file contains a list of IIPs, and their arguments. The build scripts
# read this list and produce a boot image. This configuration is intended to
# illustrate some of the common configuration options. It is strongly
# recommended to consult the documentation for each IIP
# (<doc_root>/iip_doc/index.html) and study the parameters
# carefully. Also take a look under Platform tab, 'Configuration Objects'
# category for info on the platform configuration objects (most of these
# objects can also be altered by a portal at run-time... here we just set the
# default values with kreatv-option-is-default)
# Some features are commented-out from this config by default. Simply
# remove the '#' from the start of the line to uncomment, if desired.


##### Application(s)
# The following IIP installs the Ekioh HTML Browser application into the boot
# image as the primary application. The 'start' parameter ensures that the
# application is started and shown when the STB boots up
kreatv-app-webkit-portal::start
#
# It is also possible to provide the portal IIP with a start URL. (This
# is the same as setting cfg.portal.starturl)
kreatv-app-webkit-portal::url=http://arris.com

#
# Secondary application support
# Include the example secondary web app integration
#kreatv-app-webgldemo
#
# A tech preview of the general-purpose webkit browser
#kreatv-app-webkit-browser

#
# The whitelist URLs is an XML list of other URLs which are approved to run as
# portals (with TOI active). The default start url, set above, and file://
# urls are always whitelisted.
# Here, the contents of an external XML file containing the whitelist is
# assigned to the CFG_PORTAL_WHITELISTURLS object
# Note that if you have installed an Infocast server, the whitelist is also
# transmitted from there by default, and the STB will treat the Infocast
# version as a higher priority than the one specified here.
kreatv-option-is-default::cfg.portal.whitelisturls=./whitelisturls.xml
#
# If you are deploying the boot image in an OTT scenario, it is recommended
# to ignore any infocast server:
#kreatv-option-is-adapter::infocast=false
# And for general-purpose safety, make important objects read-only:
#kreatv-option-is-access::readonly=cfg.portal.starturl
#kreatv-option-is-access::readonly=cfg.portal.whitelisturls
#kreatv-option-is-access::readonly=cfg.portal.proxylist



##### Installing a local portal
# As an alternative to loading a portal over the network it is possible to
# install a local portal (a tarball of html, javascript and images) directly
# into the bootimage:
#kreatv-option-local-portal::file=../examples/example-html-portal.tgz
# Tell the browser what URL to load on start up
#kreatv-app-webkit-portal::url=file:///usr/local/portal/example-html-portal/index.html

#### Graphics Configuration
# It is possible to configure the portal applications graphics depending on your
# requirements, hardware restrictions and memory usage.
# See the documentation at
# <doc_root>/portals/general/graphics_configuration.html for more information
# on the different configuration possibilities.
#
# Appropriate platform configuration options to set the actual sizes:
kreatv-option-is-default::cfg.portal.renderingbuffer.width=1280, \
cfg.portal.renderingbuffer.height=720

# The following IIP sets the total amount of graphics memory to the
# specified value, in KiB. More information can be found at
# <doc_root>/platform/graphics/configuration.html
# this value based on the memory requirements of the webgl demo, see profiler service
# for info on estimating this..
kreatv-option-graphics::memory_size=131072
#
# The compositor buffer is where the portal graphics and the decoded
# video are mixed
kreatv-option-graphics::compositor_buffer_size=1280x720


##### Font support
# This includes the default KreaTV font
kreatv-font-dejavu-sans
#
# If you want to add a custom font, adjust the path and uncomment the following:
# kreatv-font-file::/extra/fonts/MyFont.ttf


##### Subtitles
# The following IIP adds support for various formats of subtitles
kreatv-option-subtitles:format=dvb,format=teletext,format=webvtt
# Enabling, display position, transparency, and autoselection strategies
# are all controlled by configuration objects. Here some default values
# are set. See the documentation for these objects for more information.
# Set transparency for teletext subtitles. 0 is opaque, 100 is full transparency
kreatv-option-is-default::cfg.media.teletextsubtitling.transparency=10
# Vertical adjustment (in pixels). Negative values move the subtitles upwards
kreatv-option-is-default::cfg.media.teletextsubtitling.verticaladjustment=-10
# Enable subtitles
kreatv-option-is-default::cfg.media.subtitling.enabled=TRUE
# Enable autoselection
kreatv-option-is-default::cfg.media.subtitling.autoselection=TRUE

# Autoselection uses the following language priority list
kreatv-option-is-default::cfg.media.subtitling.languagepriority="eng,swe,dan"
# Set priority between the different types of subtitles
kreatv-option-is-default::cfg.media.subtitling.modepriority="dvb,teletext"

# Enable USB support (required if you want to use a keyboard with the STB)
kreatv-option-usb

# HDMI CEC features
# Activate and deactivate CEC features both at boot image build time
kreatv-option-hdmicec:remote_control_passthrough=false,system_standby=true,system_standby_follower=true
# Specify the On-Screen Display name for this device
kreatv-option-is-default::cfg.cec.osd.name=ARRIS

#### The following enables licensed features for evaluation on development STBs,
# without actually needing the licenses.
kreatv-option-evaluation-licenses


##### Localization options
# Central European Time (see GNU C Library timezone specification)
#kreatv-option-timezone::tz_posix="CET-1CEST-2,M3.5.0/02:00:00,M10.5.0/03:00:00"
#
# Get time via NTP
kreatv-option-timeman::time_sources=ntp
#
# Timecast is ARRIS proprietary format for use with Infocast/multicast networks
# kreatv-option-timeman::time_sources=ntp,timecast
#
# Tell the platform where to find ntp server list
# 'configurable' means to use the cfg.ntp.servers platform config object
kreatv-option-timeman::ntp_server_sources="configurable,dhcp"
#
# The actual ntp server list in descending priority order
kreatv-option-is-default::cfg.ntp.servers="0.pool.ntp.org,1.pool.ntp.org"
#
# English keymap (for usb connected keyboards)
kreatv-option-input-keymaps:names=pc-en
#

#
# Set priority for automatic selection of language track
# The configuration objects here work in a similar way to the
# subtitle autoselection
kreatv-option-is-default::cfg.media.audio.autoselection=true
kreatv-option-is-default::cfg.media.audio.languagepriority="eng,swe,dan"
kreatv-option-is-default::cfg.media.audio.formatpriority="eac3,ac3,aac,mpeg"
kreatv-option-is-default::cfg.media.audio.priorityorder="language,format"
#

##### Network and system settings
# Force IGMP v2
# kreatv-option-procfs:sys/net/ipv4/conf/eth0/force_igmp_version=2
#
# Support for remote controls
# You can remove an entry if you not using a particular type of remote
kreatv-option-rcmaps:rf4ce=greenpeak,ir=arris_nyx_kreatvir_38,ir=arris_rcu_kreatvir_37,ir=arris_srcu_kreatvir_32,ir=arris_kb_kreatvir_2,ir=arris_kb_kreatvir_5,ir=aura


##### Operator Tools
# Here are some tools which are useful when debugging, testing and working
# with STBs in a lab. Consider carefully if you will deploy these live.
#
# Logging tool - use logclient program to receive on host PC
kreatv-tool-logging
#
# Extra logging adds the software version, serial number, MAC address,
# uptime and STB model periodically to the log
kreatv-option-extralogging

# HTTPS logging
# This enables the STB to push an encrypted log file to a HTTPS server.
# this can be useful for NAT/OTT environments.
# see <doc_root>/resources/logging/http_logging.html
# kreatv-option-extralogging::certificate_file="~/Document/tls/public.pem"

#
# SSH support
# For use of this tool in live deployments, additional permission is required
# from ARRIS and CA/DRM vendors
# This IIP installs an SSH server on the STB and configures it for password
#
# "$1$SA$T1WWO86D0y74ILxhbpMHN0" corresponds to root password "kreatv"
# You must change the password in live system.
# See <doc_root>/resources/tools/ssh.html for encrypted password generation
kreatv-tool-ssh:password=$1$SA$T1WWO86D0y74ILxhbpMHN0
#
# This next line configures ssh for use with public/private key
# kreatv-tool-ssh:key=/opt/keyfile.pub,port=22

# WIFI support
kreatv-option-wifi(vip43x2)

##### Streamer Configuration
# The streamer is responsible for receiving a stream from the network,
# extracting the individual elementary streams (video, audio, teletext..) and
# passing them to the hardware decoder
# Note that default values are set here, but may be overridden when opening
# streams in the portal, by adding parameters to the URL
kreatv-option-streamer-config::startmode=normal,buftime=300


##### Power management
# The power management license is not essential. It allows the application
# to handle the power button on the remote control. The default (no license)
# is for the KreaTV platform to handle the power button (it tries to put the
# STB into a lower power profile, or wakes it)
# kreatv-license-allow-power-management-control
#
# Uncomment the following to use active_standby (the STB turns off video
# and audio outputs, but the STB remains active). The default behaviour
# is passive_standby (put STB to sleep and save power)
# kreatv-option-powermanagement::lowest_profile=active_standby

##### Protocol and Media support
# The kreatv-option-mediasource IIPs add support for containers,
# protocols and elementary stream types
# The old kreatv-option-streamclients has been replaced by these
#
# Support for basic protocols (TCP, UDP, RTSP)
kreatv-option-mediasource-protocol-basic
#
# Support for playing media from local files
kreatv-option-mediasource-protocol-file
#
# Support for playing media via HTTP
kreatv-option-mediasource-protocol-http
#
# Support for playing media with RTSP/VOD
kreatv-option-mediasource-protocol-rtsp
#
# Add support for common media containers
kreatv-option-mediasource-container-ts
#
# Add support for elementary streams
kreatv-option-mediasource-elementary-aac
kreatv-option-mediasource-elementary-pcm
#
# HLS Support
# See <doc_root>/platform/hls/index.html for details.
#kreatv-license-hls
kreatv-option-mediasource-protocol-hls
# Extra options are available when advanced_config_enabled is set to true,
# see <doc-root>/iip_doc/kreatv-option-mediasource-protocol-hls.html
#kreatv-option-mediasource-protocol-hls::advanced_config_enabled=true
#kreatv-option-mediasource-protocol-hls::memory_size=19000

##### Tools
# The kreatv-option-profiler IIP allows profiling your portal application and
# helps correctly configure graphics settings.
kreatv-option-profiler