STB Software

Imageupdate file

STB software is a set of programs that are intended to control STB operation. STB software includes Linux kernel and Root File System (Root FS) that contains software components provided by manufacturers of CPU and STB.

The procedure of combining STB software components (STB software building) is performed at the STB manufacturing plant. As a result of the building procedure, the system image file (hereinafter - image) is created which is applied for loading and running in STB. This file-image that named as imageupdate is used for the STB software update.

STB manufacturer permits customers (IPTV operators and individual users) to make changes to certain components of STB software and independently create the STB software image according to instructions of the manufacturer. This process is called STB software customization. This enables IPTV operators to configure STBs according to their own work environments and preferences, as well as, to integrate STB software with other developers' applications.

There are several kinds of imageupdate to produce by the manufacturer and operators.

Open and closed platforms of STB

STB models with open and closed platforms

STBs of MAG family can be produced on the basis of open or closed hardware-software platforms, depending on the focus of its application. Produced STB models are listed in Basic models of STB Linux & WebKit section, considering the division into open and closed platforms.

Distinctions between open and closed STB platforms

The idea of the open platform is to provide users (both individual users and IPTV/OTT operators) with the opportunity to make changes (perform customizations on their own) of STB software and integrate it with applications of other developers.

In turn, сlosed platform is intended for operator solutions that use CAS/DRM system providing content protection. The CAS/DRM system is a hardware-software complex integrated into the particular operator's IPTV network as well as into subscriber receivers (STBs) dedicated to operating in this network. To secure media content, encryption of transmitting audio-video streams is used that allows media content to be played back only on registered models of media players (STBs) of the particular IPTV operator. In addition, the content protection system restricts various actions with copyrighted audio-video content (copying, modification, repeated playback, distribution, etc.). There are various types of content protection systems that differ in hardware/software implementations, levels of content protection, types of content being processed, and so on. A particular CAS/DRM system to be used in the IPTV project is selected by the IPTV operator. STBs that used on the particular network must support this type of CAS/DRM, be registered in the operator's CAS/DRM system, and should contain in firmware relevant operator's CAS/DRM system settings.

STB software for the closed platform is produced at the manufacturing plant by individual agreement with every concerned operator. STB software with the closed platform prohibits modifying STB software by users, without the participation of the IPTV operator whose signature (operator key) is set in STB.

Open and closed platforms STB software images

To meet various requirements of customers, several options of open platform's STB software image are designed that can be divided into two groups:

1. PublicImage and FactoryImage - created and provided by the manufacturer. They are intended mainly for individual users as well as for users of OTT operators.
2. CustomImage and OperatorImage - created and provided by the operator. They are intended for users of IPTV operators.

STB software image is created in accordance with the manufacturer's instructions on the basis of software components comprised of STB software release. It may include customized operator settings.

Closed platform STBs, which are focused on IPTV operator solutions, use OperatorImage that is signed by a certain operator's digital signature (operator key).

STB software versions

STB software version parameters

STB software version (also called as image version) consists of the following parameters:

• Model - model number of STB, for which the version is intended;
• Version - a number that is assigned by the developer during image-making. For images from the STB manufacturer three-digit number is used;
• Date - date of image creation that is assigned automatically during image-making;
• Description - detailed description of the software version. It can be assigned by a developer during image-making. The image creator can use this parameter to specify the image type, operator name, STB software features, and so on. For example, description 0.2.18-r19-pub-254 means: version - 218, release (within the version) - 19; image type - public image; STB model - MAG-254.

How to learn STB software version

STB software version can be obtained by user:

• MAG250/254/270 - from Bootloader menu ⇒ Image info section. See Version, Date, Description items:

• MAG256/MAG3xx/MAG4xx and higher - from System Recovery Utility menu ⇒ Device information section. See Image version number, Image date, Image description items:

• From Embedded portal: Settings ⇒ System settings ⇒ Device info (see Image version, Image description, Image date items):

Software version info encapsulated into imageupdate file

The imageupdate file comprises a brief release description that can be viewed, for example on a computer, with a text editor app. To get this info, open the imageupdate file in text view mode. Software version info is located at the top of the window. For example:

STB software release

STB software releases are means of distributing software from the STB MAG manufacturer through its Web repository to all parties concerned (users, operators, developers, etc.).
Each STB software release (hereinafter - release) represents a new software version of a specific STB model. Once issued for a specific STB model, the release defines the current working software version for this STB model.

Software release location

Releases for various STB models are issued in open access by the next URL:

where:

 <model>  - number value of basic STB model (for example, 254, 256, 322, etc.);

Example of URL for STB MAG322 release: http://soft.infomir.com/mag322/release/

Release for a particular basic STB model can be applied to all its derivative models. For example, MAG254 release is also applied for MAG254w1, MAG254w2 models.

Release parameters

Since every release contains a particular STB software version, some release options can coincide with STB software version parameters. List of Release parameters:

• STB model to which the Release/Version is intended;
• Release version = software version, included in the Release;
• Release date.

The example of the release for STB MAG420 is given below: version 2.20.03-r2, date - 2020-04-02.

Release content

Release contains the following main files:

• imageupdate - public image, created by the manufacturer, which based on software components included in the Release;
• Bootstrap - startup file containing OS kernel image. It is used for updating from Bootloader in the case of STB models MAG250/254/270. It is also used for system recovery in the case of STB models MAG-256/3xx/4xx and higher - as an example see Emergency startup MAG4xx .
• portal-dev-<date>.tgz - archived package of portal's source codes. It can be applied to customize interaction with portals to be loaded into STB that can affect the procedure of loading portal into STB, the design of various pages of the Embedded portal and applications, etc. Some customization features and compiling procedure of the Embedded Portal are described in the developer section - see Customization, Embedded software and Embedded software localization subsections.
• rootfs-<date>.tar.gz - archived package of STB root file system (RootFS). All STB software customization performs by making changes in RootFS and further building of image containing modernized RootFS.

• uImage_<model>.clean or vmlinux.bin.mag<model> - original kernel image of the appropriate STB model (specified as <model>). It is used in image building.

STB software provided by manufacturer - public and factory images

STB software is issued and provided by the manufacturer in open access. The following two basic variants of STB software are applied:

• Factory image is created by the factory and installed in STB at the factory in the manufacturing process. The Factory image is distributed for STB updating - the last version of the Factory image (imageupdate file) is provided to users from the manufacturer's web-server. The Factory image contains a mechanism that prevents updating to other (non-factory) images. This mechanism allows using only proven (factory-made) STB software. In the Factory image, access to the STB root file system on the SSH protocol is forbidden.
• Public image is created by the manufacturer and is issued in the Release of every STB model. At the same time, the manufacturer provides with the Release the necessary software components, on-base which users can create your own public image modification (in order to customize software) according to instructions of the manufacturer.
  Public versions of the software are signed with the public key (ID_KEY = STB_PUBLIC), included in Operator Utilities.
  The Public image can be updated in STB manually by the user at the STB booting stage (from the Bootloader menu - for STB MAG-250/254/270 or System Recovery Utility menu for STB MAG-256 and MAG-322/324/349/351).
  As a rule,
  Public image is intended for debugging, operative changes of internal settings, monitoring, and other auxiliary purposes. Public image is open for changing the running STB software. To access the STB root file system SSH protocol is used.

Update to Factory image

Update to Factory image is performed from the STB  Embedded portal -  automatically or manually (by user commands).
If STB runs the Factory image, for updating only Factory image versions are accepted. Any different image types (public, custom) are rejected when trying to upgrade from the Embedded portal.

Autoupdate

Automatic updating to the factory image is carried out over network (HTTP protocol), from URL specified in STB software. Automatic update settings can be accessed by the user from the STB Embedded portal or performed by the Middleware server administrator (if STB connected to an external portal).

Manual update

Manual updating to factory image is performed from the Embedded portal. Depending on the location of an update file (imageupdate) which can be placed on the manufacturer's web-server or locally on a USB-drive, the following update options are available:

• Software update from Portal by HTTP
• Software update from Portal by USB

Factory image versions are issued at the manufacturer's web-server of by address:

where <model> is a number value of basic STB model (for example 250, 254, 256, 322, etc.).

For example, for STB MAG322 the last factory image version address: http://update.infomir.com/mag/322/imageupdate

As a rule, only one last stable version of the software for every STB model is located on the update server. But in some cases, the update server comprises several software versions of the same STB model to select by the user (they are accessible from the Embedded portal).

Update to Public image

Update to Public image is performed manually only on the booting stage of STB (from Bootloader menu - for STB MAG-250/254/270 or System Recovery Utility menu - for STB MAG-256, MAG-3xx, and MAG-4xx). This way users can update STB to the required version of Public image or make the transition from any other type of image (factory, custom) to Public image.

Public image versions produced by the manufacturer are issued in STB Releases .

Images created by Operators

As described in STB software provided by the manufacturer section, operators can create their own public image modifications (PublicImage). In addition, two special kinds of the SW image are intended to be used in operators' IPTV-networks: Custom Image (CustomImage) and Operator Image (OperatorImage).

Every operator creates the image on his own and handles it with your own secure cryptographic key (see Cryptographic signature of image section). When attempting to update the STB software, the digital signature is checked. This ensures that only the software created by a particular operator is used in STB.

STB software image version created by an operator is put on his web-server. In order to provide STB updating, STB software image should comprise a specific update URL defined in STB software image (see STB software customization - setting update URL, auto-update URL).

Unlocking STB  with installed operator key

Update to Custom image

Update STB to Customimage is performed from a Portal - external or embedded. Update means the transition to another version of Сustomimage of the same Operator.
Note. Description of specific first two-stage installation of CustomImage is described in the CustomImage making instruction. Subsequent updates of Сustom image are carried out in the usual way from the portal (using HTTP or USB methods).

CustomImage contains an installed operator (custom) key, which is checked when trying to update the image. Thus, if STB is running Customimage, only the same operator CustomImage versions (containing the same custom key) are allowed to update STB from Portal. Image versions of other types (Factory image, Public image) or Customimage with a different custom key are rejected when trying to update.

Update to Customimage from the Embedded Portal is similar to the one described for Update to Factory image - in automatic or manual mode. However, as the update file is hosted on the Operator's Web server, a corresponding update URL changes.
Note. The addresses for manual and/or automatic updates are specified during image-making - see STB software customization.

Example of how to configure update from External portal

1. Manual Update configuring from the MW Ministra Portal (update from URL):

2. Configuring STB update in MW Ministra administration panel:

• How to conduct the automatic STB firmware update?
• How to set the firmware update condition?

Cryptographic signature of the image

In order to prevent the running of unauthorized software in STB, every STB software image is signed with a digital signature, using the GnuPG (GPG) program. The RSA algorithm is applied to provide data encryption and integrity of image checking as well.

GPG program generates сryptographic key that consists of a secret part (private key or secret key) and an open part (public key). When creating each сryptographic key, it is assigned a key identifier (ID_KEY) which is the unique key name in the GPG database.
The Private key is a property of the image creator (i.e. Operator). It is kept secret and used for new images signing during the image building process.
Using public key installed in the STB, the authenticity of the SW image being loaded in STB is checked. During an image loading in the STB, the signature availability and correctness are checked (whether public and private keys match each other). In the case of the keys mismatch, the 'Wrong Signature' error is displayed, and the image is not loaded in the STB.

To create Operator images (CustomImage, OperatorImage), the operators use their own keys. If OperatorImage is used by the operator, the public part of the operator key must be signed with the Manufacturer key before installation in STBs. Creating images by operators and installing the operator key in STB are performed according to instructions of the manufacturer of STB.

Public images (PublicImage) are signed with the Manufacturer's default operator key (ID_KEY = STB_PUBLIC). The public key of the default operator key is installed in the STB at the factory.
The private part of the default operator key
is included in Image-making utilities (файл stb_secbin.key). It is used in the build procedure of PublicImage and CustomImage.

Instructions for building image

Public image

• PublicImage - preparing, making for MAG254

Operator images

• CustomImage - preparing, making for MAG254
• OperatorImage - instructions for making and updating the image are provided to operators after agreeing with the commercial department on the procedure for signing the operator's key.
• Making the operator or custom key:
  • Custom key preparation
  • Notes on using GPG
  • Some details on the operator image are described in the Operator_Guide_MAG200.pdf (see Operation with keys chapter, p. 20)

Additional

• SSH - change password, port, disable/enable

STB software customization

STB software customizing refers to configure STB software user interface and STB operation parameters according to customer (operator) demands, as well as integrating necessary applications, including external media portal support.

To customize certain STB model, IPTV operator makes changes to STB image according to STB manufacturer instructions. STB image components are provided in STB software release. During the customization process, necessary changes are made to the root file system, before including it in the image building.

As a rule, image customization is used to create custom and operator images. For the purpose of testing and debugging, customization can be also performed in public image.
Customization can deal with the following points:

• Logo of Bootloader;
• Checking variables (setting required default values) during STB/portal start;
• STB default settings that defined with environment variables, during image building (see contents of env.txt). List of possible settings and relevant variables:
  • Background and font color of the Bootloader - bg_color, fg_color;
  • Specific country or region settings like Embedded portal language, time zone - language, timezone_conf;
  • URL of time server (NTP) - ntpurl;
  • Video displaying parameters in Bootloader and media-portal mode (PAL / NTSC format, video output mode, graphic resolution of the screen, auto-adjustment of frame rate) - bootTVsystem, tvsystem, graphicres, auto_framerate;
  • URL of the external portal to be auto-loaded in STB - portal1;
  • Ability to hide/view URL of external portals - custom_URL_hider;
  • URL of STB update in Embedded portal (System settings ⇒ Software update ⇒ URL option) - update_url;
  • URL and conditions of STB auto-update (see Autoupdate module description section) - autoupdateURL, autoupdate_cond;
    Note. A more detailed list of environment variables as well as the method of observing variables values directly in STB is given in the Most used variables section.
• Enabling / disabling user access to Settings, using rules.js (during the preparation of software image building):
  • Disabling/Enabling items of System settings, Settings menus;
  • Configuring of Select a portal for loading window (allow to open window with Menu key of RC; permission on entering to Embedded portal and System settings);
  • Configuring of Page loading error window (page 404);
  • Access to System settings with a password.
    

• Localization (interpretation) of Embedded portal user interface to language that is not supported by default;
• SSH protocol access to the STB file system;
• Automatic updating of playlists from a given URL;
• For applications, determination of URL to transition on exit (Referrer);
• etc.

New portal development

To perform customization of web applications, the manufacturer provides the users (operators) with an API set. Thus, users (operators) can create their own versions of the media portal to control the operation of the set-top box. In addition, the manufacturer provides the ability to upgrade the Embedded portal of STB (the source code of the portal is provided in each SW release) and build its version of the portal with its further inclusion in the customized image of STB software. For example, you can change the algorithm for loading and operating the portal, change the design of the portal, etc.

Description of some issues related to portal customization is given in the next sections:

• Customization and image-making for embedded portal
• Specification JavaScript API (SW ver. prior to 0.2.18)
• Specification JavaScript API (SW ver. from 0.2.18)
• API. STB application development