Boot IP-STB with HTTP

Only parts of the HTTP 1.1 specification are implemented, URLs containing non-escaped reserved characters are not supported. Server redirects with code 301, 302 and 303 are supported.

KreaTV HTTP boot is a two step download mechanism where the first step is always an HTTP GET from HTTP server. The second step can be all protocols except from USB, i.e. TFTP, Infocast, Local Storage or HTTP.

The HTTP server address and port is configured via DHCP options, KreaTV boot loader menu or production parameters.

Downloading the StbConfig meta data file in the first step is done by requesting a page from the server's root using the bootcast id, i.e. for VIP4302WBT the request will be http://www.example.com/arris-vip4302wbt-dev

For making the HTTP boot more dynamic and configurable on the server side, the requests to the HTTP server will add product (i.e., bootcastid), serial number, MAC address, boot loader version, software version, splash version and diagnostic image version as parameters to the request, e.g.

http://www.example.com/arris-vip4302wbt-dev?product=arris-vip4302wbt-dev&serial=1931690851&mac=00:02:9b:00:01:02&fw_version=6.3&kernel_version=1.0&splash_version=1.0&diagnostic_version=1.0

In the second step of the KreaTV HTTP boot STB will start to download the splash and boot image with the protocols specified in the meta data file, see Types of URLs in StbConfig below for protocol syntax and StbConfig meta data file example for a meta data file example.

For HTTP protocol in the second step it has the same limitations as the first step and the parameters is also added to the request for making this step scriptable on the server side.

Version handling

The version tags KernelVersion and SplashVersion are used to determine if a software update is required. Some devices store the boot image and boot splash image in flash memory. If a version tag changes, the device will discard the version stored in flash and download the newer version from the network next time it boots.

The boot splash image itself does not contain version information and the version tag SplashVersion can be set arbitrarily. It is stored together with the boot splash image in flash memory.

The boot image version tag KernelVersion must match the one stored in the boot image binary. The boot image version is chosen when a boot image binary is built. A boot image is built using the build_boot_image command. The boot image version is specified using the --info version parameter. The command boot_image_version can be used to retrieve the version of a boot image.

Permanent parameters

HTTP boot allows user parameters to be set in flash. This is done by setting subtags to the tag PermanentParams. Below is a list of the supported parameters as it looks right now. Please keep in mind the supported parameters may change slightly in different DBL versions. See the Std Config meta data file example section for an example.

StbConfig

StbConfig DTD

<!ELEMENT StbConfig (BootParams, PermanentParams?)>
<!ELEMENT BootParams (KernelUrl, KernelVersion?, SplashUrl?, SplashVersion?. DiagnosticUrl?, DiagnosticUrlVersion?, NfsServerAddress?, NfsRootPath?)>
<!ELEMENT KernelUrl (#PCDATA)>
<!ELEMENT KernelVersion (#PCDATA)>
<!ELEMENT SplashUrl (#PCDATA)>
<!ELEMENT SplashVersion (#PCDATA)>
<!ELEMENT DiagnosticUrl (#PCDATA)>
<!ELEMENT DiagnosticVersion (#PCDATA)>
<!ELEMENT NfsServerAddress (#PCDATA)>
<!ELEMENT NfsRootPath (#PCDATA)>
<!ELEMENT PermanentParams (IPConfigMethod?, IPAddress?, Netmask?, Gateway?, DNS1?, DNS2?, DhcpTimeout?, SplashOrder?, BootOrder?, DiagnosticOrder?, FirmwarelogAddress?, NetconsolelogAddress?, Bootcast?, BootcastTimeout?, BootcastAttempts?, BootcastId?, IgnoreBootcastVersion?, TftpServer1?, TftpServer2?, TftpServer3?, TftpServer4?, TftpPoolAttempts?, TftpNodeAttempts?, TftpTimeout?, TftpRrqTimeout?, TftpBlockSize?, SapAddress?, SapTimeout?, SapAttempts?, SapId?, HttpServer?, HttpPort?, HttpTimeout?, HttpAttempts?, HttpProxy?, HttpProxyPort?, SplashFilename?, KernelFilename?, DiagnosticFilename?, NtpServerAddress?, NtpServerList?, DhcpServerAddress?, IgmpVersion?, VendorClassId?, CurrentColorCoding?, FrontButtonCode?, FrontButtonCodeExt?, FrontButtonHardReset?, LedStandbyState?, ShowIPSettings?, ShowAdvancedSettings?, AllowSubmenuCodes?, MenuHidden?, HideTvSystem?, InternalProgress?, ProgressbarColor?, RFFrequency?, Language?, StatusScreen?, StatusScreenColor?, HideUpdatingMsg?, HideNoPwrOffMsg?, InfoScreen?, InfoKey?, MenuKey?, DiagnosticKey?, FactoryReset?, RemoveSoftware?, BootWithoutNet?, DvbNetworkId?, DvbFrequency?, DvbSymbolRate?, DvbModulation?, IRFrequency?, IRProtocols?, IgnoreVci?, Diagnostic?, TblShowSplash?, WifiWizardDisabled?, WifiWPSDisabled?, WiFiRSSI?, RF4CEPairingDisabled?, DiagnosticStorageDevice?)> 	
<!ELEMENT IPConfigMethod (#PCDATA)>
<!ELEMENT IPAddress (#PCDATA)>
<!ELEMENT Netmask (#PCDATA)>
<!ELEMENT Gateway (#PCDATA)>
<!ELEMENT DNS1 (#PCDATA)>
<!ELEMENT DNS2 (#PCDATA)>
<!ELEMENT DhcpTimeout (#PCDATA)>
<!ELEMENT SplashOrder (#PCDATA)>
<!ELEMENT BootOrder (#PCDATA)>
<!ELEMENT DiagnosticOrder (#PCDATA)>
<!ELEMENT FirmwarelogAddress (#PCDATA)>
<!ELEMENT NetconsolelogAddress (#PCDATA)>
<!ELEMENT Bootcast (#PCDATA)>
<!ELEMENT BootcastTimeout (#PCDATA)>
<!ELEMENT BootcastAttempts (#PCDATA)>
<!ELEMENT BootcastId (#PCDATA)>
<!ELEMENT IgnoreBootcastVersion (#PCDATA)>
<!ELEMENT TftpServer1 (#PCDATA)>
<!ELEMENT TftpServer2 (#PCDATA)>
<!ELEMENT TftpServer3 (#PCDATA)>
<!ELEMENT TftpServer4 (#PCDATA)>
<!ELEMENT TftpPoolAttempts (#PCDATA)>
<!ELEMENT TftpNodeAttempts (#PCDATA)>
<!ELEMENT TftpTimeout (#PCDATA)>
<!ELEMENT TftpRrqTimeout (#PCDATA)>
<!ELEMENT TftpBlockSize (#PCDATA)>
<!ELEMENT SapAddress (#PCDATA)>
<!ELEMENT SapTimeout (#PCDATA)>
<!ELEMENT SapAttempts (#PCDATA)>
<!ELEMENT SapId (#PCDATA)>
<!ELEMENT HttpServer (#PCDATA)>
<!ELEMENT HttpPort (#PCDATA)>
<!ELEMENT HttpTimeout (#PCDATA)>
<!ELEMENT HttpAttempts (#PCDATA)>
<!ELEMENT HttpProxy (#PCDATA)>
<!ELEMENT HttpProxyPort (#PCDATA)>
<!ELEMENT SplashFilename (#PCDATA)>
<!ELEMENT KernelFilename (#PCDATA)>
<!ELEMENT DiagnosticFilename (#PCDATA)>
<!ELEMENT NtpServerAddress (#PCDATA)>
<!ELEMENT NtpServerList (#PCDATA)>
<!ELEMENT DhcpServerAddress (#PCDATA)>
<!ELEMENT IgmpVersion (#PCDATA)>
<!ELEMENT VendorClassId (#PCDATA)>
<!ELEMENT CurrentColorCoding (#PCDATA)>
<!ELEMENT FrontButtonCode (#PCDATA)>
<!ELEMENT FrontButtonCodeExt (#PCDATA)>
<!ELEMENT FrontButtonHardReset (#PCDATA)>
<!ELEMENT LedStandbyState (#PCDATA)>
<!ELEMENT ShowIPSettings (#PCDATA)>
<!ELEMENT ShowAdvancedSettings (#PCDATA)>
<!ELEMENT AllowSubmenuCodes (#PCDATA)>
<!ELEMENT MenuHidden (#PCDATA)>
<!ELEMENT HideTvSystem (#PCDATA)>
<!ELEMENT InternalProgress (#PCDATA)>
<!ELEMENT ProgressbarColor (#PCDATA)>
<!ELEMENT RFFrequency (#PCDATA)>
<!ELEMENT Language (#PCDATA)>
<!ELEMENT StatusScreen (#PCDATA)>
<!ELEMENT StatusScreenColor (#PCDATA)>
<!ELEMENT HideUpdatingMsg (#PCDATA)>
<!ELEMENT HideNoPwrOffMsg (#PCDATA)>
<!ELEMENT InfoScreen (#PCDATA)>
<!ELEMENT InfoKey (#PCDATA)>
<!ELEMENT MenuKey (#PCDATA)>
<!ELEMENT DiagnosticKey (#PCDATA)>
<!ELEMENT FactoryReset (#PCDATA)>
<!ELEMENT RemoveSoftware (#PCDATA)>
<!ELEMENT BootWithoutNet (#PCDATA)>
<!ELEMENT DvbNetworkId (#PCDATA)>
<!ELEMENT DvbFrequency (#PCDATA)>
<!ELEMENT DvbSymbolRate (#PCDATA)>
<!ELEMENT DvbModulation (#PCDATA)>
<!ELEMENT IRFrequency (#PCDATA)>
<!ELEMENT IRProtocols (#PCDATA)>
<!ELEMENT IgnoreVci (#PCDATA)>
<!ELEMENT Diagnostic (#PCDATA)>
<!ELEMENT TblShowSplash (#PCDATA)>
<!ELEMENT WifiWizardDisabled (#PCDATA)>
<!ELEMENT WifiWPSDisabled (#PCDATA)>
<!ELEMENT WiFiRSSI (#PCDATA)>
<!ELEMENT RF4CEPairingDisabled (#PCDATA)>
<!ELEMENT DiagnosticStorageDevice (#PCDATA)>

Types of URLs in StbConfig

[] = Required
<> = Optional

Infocast: infocast://[multicast group]<:port>/[object name]
TFTP    : tftp://[server ip]<:port>/[path/to/file]
Local   : local://
HTTP    : http://<username:password@>[server name or ip]<:port>/[path/to/file]

User name and password can be percent-encoded and is used for basic access authorization. This feature is only supported in DBL version 6.7 and newer.

StbConfig meta data file example

The following example is booting a boot image named bootimage and a splash image called splashimage from http://www.example.com. It is also utilizing the permanent parameters to set the color of status and error messages to black. This file can be placed in your web server root directory and be named to match your bootcast ID, e.g. arris-vip4302wbt-dev. Kernel (i.e. boot image) and splash paths should be set according to Types of URLs in StbConfig.

    
<?xml version="1.0"?>
<!DOCTYPE StbConfig SYSTEM "stbconfig.dtd">
<StbConfig>
<BootParams>
  <KernelUrl>http://www.example.com/bootimage</KernelUrl>
  <KernelVersion>1.0</KernelVersion>
  <SplashUrl>http://www.example.com/splashimage</SplashUrl>
  <SplashVersion>1.0</SplashVersion>
</BootParams>
<PermanentParams>
  <StatusScreenColor>0,0,0</StatusScreenColor>
</PermanentParams>
</StbConfig>

  

Example Apache2 configurations

This section contains an python CGI-BIN example script illustrating how to utilize the HTTP request parameters. It is for instance possible to send out certain boot images to STBs with certain serial numbers or MAC addresses. This can be quite handy if friendly test users should receive a different software image.

Simple internal redirect using mod_rewrite

Make sure that AllowOverride All is set in the Apache configuration file and restart the server.

Create the following .htaccess file in your WWW root directory.

RewriteEngine on
RewriteRule   ^arris-vip(.*)$ cgi-bin/stbconfig [L]

Simple external redirect using mod_rewrite

Make sure that AllowOverride All is set in the Apache configuration file and restart the server.

Create the following .htaccess file in your WWW root directory.

Rewrit  Engine on
RewriteRule   ^arris-vip4302wbt-dev$ http://www.example2.com/cgi-bin/stbconfig [R]

Example CGI script

Create the following file, stbconfig, in your cgi-bin directory, remember to make the file executable.

#
#!/usr/bin/python
# Copyright (c) 2016 ARRIS Enterprises, Inc. All rights reserved.
# This program is confidential and proprietary to ARRIS Enterprises, Inc.
# (ARRIS), and may not be copied, reproduced, modified, disclosed to others,
# published or used, in whole or in part, without the express prior written
# permission of ARRIS.

# This is an example CGI-BIN script for hosting boot images for HTTP boot
# See the documentation page booting/methods/http_boot.html for more information

import os
import traceback

def generate_stbconfig(server, image, splash):
  out = """<?xml version="1.0"?>
<!DOCTYPE StbConfig SYSTEM "stbconfig.dtd">
<StbConfig>
<BootParams>
  <KernelUrl>%s/%s</KernelUrl>
  <KernelVersion>1.0</KernelVersion>
  <SplashUrl>%s/%s</SplashUrl>
  <SplashVersion>1.0</SplashVersion>
</BootParams>
<PermanentParams>
  <StatusScreenColor>0,0,0</StatusScreenColor>
</PermanentParams>
</StbConfig>
"""
  return out % (server, image, server, splash)

def parse_qs(qs):
  d = {}
  for item in qs.split('&'):
      name, value = item.split('=')
      if name in d:
          d[name].append(value)
      else:
          d[name] = [value]
  return d

serial_db = {'1931690851': 'kreatv-bi-special_4302.bin'}
product_db = {'arris-vip4302wbt-dev': ('kreatv-bi-default_4302.bin',
                                     'splash-4302.bmp')}
output = ''
try:
  http_server = 'http://%s' % os.getenv('SERVER_ADDR')
  parameters = parse_qs(os.getenv('QUERY_STRING'))

  default_bi, splash = product_db[parameters['product'][0]]
  image = serial_db.get(parameters['serial'][0],
                        default_bi)
  output += generate_stbconfig(http_server,
                               image,
                               splash)
  output = 'Content-type: text/xml\n\n' + output
except Exception, e:
  output = 'Status: 500 Internal Server Error\n'
  output += 'Content-type: text/html\n\n'
  output += '<html><body>HTTP/1.1 500 Internal Server Error\n'
  output += '<br>%s</body></html>' % traceback.format_exc()

print output