Skip navigation

Operator Utilities and instructions for building STB software image

Image-making Operator Utilities

To make STB software image, customers (operators) should use the following Operator Utilities provided by the manufacturer:

Operator Utilities

Requirements to OS of Development Host

It is required to use the *nix i386 (32-bit) system. We recommend using Ubuntu OS Linux distribution.

In the case of use 64-bit OS, it should be additionally installed appropriate packages for supporting 32-bit shared libraries. For example, for Ubuntu 14.04 - 16.04, the lib32z1 package (32-bit shared libraries for AMD64) must be installed.

All examples in this manual are given for Ubuntu Server 12.04 i386.

Required Linux OS packages

For recommended OS, the following packages should be installed:

Ubuntu Server 12.04 i386: sudo apt-get install mtd-utils

Ubuntu Server 12.04-16.04 x86_64: sudo apt-get install mtd-utils && sudo apt-get install lib32z1

Software image variants

Operator utilities provide making three different variants of STB software image:

  • PublicImage - image signed with standard manufacturer's public key (ID = STB_PUBLIC). PublicImage version by the manufacturer (imageupdate file) is put in the root directory of each current release of the appropriate STB model.
    Options for updating from PublicImage:
    1. It is updated from the Bootloader menu or System Recovery Utility menu to various versions of PublicImage and transitional version of CustomImage.
    2. It is updated from the Portal menus (using 'HTTP' or 'USB' methods) only to the Factory image software versions.
  • CustomImage - image signed with custom-key which is created by operators without requesting the manufacturer of STB. This kind of image is recommended for those operators who want to implement secure software updating from the portal only to their own software versions (using HTTP / USB methods) with the ability to update to PublicImage public software versions from Bootloader menu or System Recovery Utility menu.
    Options for updating from CustomImage:
    1. It is updated from the Bootloader menu or System Recovery Utility menu to various versions of PublicImage and transitional version of CustomImage.
    2. It is updated from the Portal menu (using 'HTTP' or 'USB' methods) only to software versions signed with the same custom-key. 
  • OperatorImage - image signed with operator key. Before setting in STB, the operator key must be signed by the manufacturer of STB.
    Updating variants from OperatorImage: It can be updated to OperatorImage versions signed only with the same operator's key.

Creation of software image. Key points

Before making an image, we recommend to familiarize with the following documents:

Operator's Guide (pdf)
Specification JavaScript API (SW ver. prior to 0.2.18)
Specification JavaScript API (SW ver. from 0.2.18)

It is recommended:

  • Run all commands with root permission.
  • Use the tar command line archiver.

Warning! The Command Shell which is in the scripts and System Shell can be different from each other!

The image creation algorithm in the general case is as follows:

1. Preparation of environment variables.
2. Profile preparation.
3. Copying the kernel source file from the STB release to the working directory of Operator Utilities.
4. Creation kernel images (running the kernel signing script).
5. Running the image building.

1. Preparation of environment variables

Required values of environment variables, that should be set in software image, are specified in the env.txt file. The original version of the file (which should be edited according to operator's preference) located in images subdirectory of the Operator Utilities directory. Access path to images directory depends on STB model - example for MAG-254: ./images/env.txt

  Example of env.txt 
bg_color=0x00006498
fg_color=0x00FFFFFF
portal1=http://10.1.0.1/stalker_portal/c/index.html
language=en
update_url=http://10.1.0.1/imageupdate
ntpurl=10.1.0.1
timezone_conf=Europe/Kiev

Some environment variables are described in the Most used variables section.

By default, update and auto-update in the Embedded portal by HTTP perform only to Factory image versions.

In case of building your own image it is recommended:

  • Specify URL of your own imageupdate version in the Update_url variable.
  • Arrange your own automatic update system and specify appropriate values of the variables autoupdateURL, autoupdate_cond, and betaupdate_cond, guided by the Autoupdate module description section. Otherwise, you must turn off the Autoupdate URL.

  • In order to improve security and prevent unauthorized changes of variables, it is recommended to check necessary/critical variables during STB software loading (for example portal1, portal2, update_url, autoupdate_cond, etc.). Read more - Checking of variables during STB / portal start.

2. Profile preparation

Image building options are specified in the profile. Profile templates for various STB models, that should be properly edited before image-making, are located in the root of Operator Utilities directory: ./img_make.profile.mag<model_number> For example, for MAG254: ./img_make.profile.mag254

  Example of ./img_make.profile.mag254 
#    Kernel's file system
export KERNEL_PATH=./uImzlib_mag254.img
#    File name for enviroment variable
export ENV_VARIABLE_PATH=./images/env_mag254.txt
#    Userfs
export USERFS_VERSION=1
export USERFS_PATH=./images/userfs.img
#    File name for SecondBoot
export SECONDBOOT_PATH=./images/SbootIm_mag254
#    File name for Logotype
#export LOGOTYPE_PATH=./images/logo.bmp.gz
export MAG200_OP_KEY=STB_PUBLIC
  Profile variables description
Name Description
KERNEL_PATH Location path for the system image file that contains the kernel. If the variable is not assigned, then  ./UImzlib.img value will be used.
ENV_VARIABLE_PATH This variable should contain a location path for the file containing a list of bootloader variables and corresponding values to be set in imageupdate. As an example of such a file, see env.txt. which shows how to set environment variables, in particular, font color and background color. “$” Symbol should be screened.
USERFS_VERSION The number of image version which should be located in NAND partition named Userfs. If number of current image (installed in STB) and the new one are the same, the update will not start.
USERFS_PATH Path location for the Userfs image. The image is made using userfs_img.sh script. The operator should preliminarily put all needed files in the subdirectory named /userfs.
SECONDBOOT_PATH Path location for the second image bootloader.
LOGOTYPE_PATH Path location for the logo file, prepared by the operator.

For correct work of Operator Utilities, KERNEL_PATH variable should be set to: ./uImzlib_mag<model_number>.img For example, for MAG254: ./uImzlib_mag254.img Variables ENV_VARIABLE_PATH, USERFS_VERSION, USERFS_PATH, SECONDBOOT_PATH, LOGOTYPE_PATH might be commented. In this case, there will not be such a section in the image.
Variable
MAG200_OP_KEY must contain a key identifier (ID_key) that will be used to image signing. ID_key should set to:

  • STB_PUBLIC - for public image-making. Operator Utilities contain public key;
  • Custom-keyID - for custom image-making;
  • Operators keyID - for operator image-making.

3. Copying the original kernel image from release into Operator Utilities directory

The original kernel image is located in the release of an appropriate STB model:

  • MAG-250/254/270 - the following file is used:

vmlinux.bin.mag<model_number>

  • MAG-256/3xx/4xx - the following file is used:

uImage_mag<model_number>.clean where is <model_number> - STB model number. For example: for MAG-254 - vmlinux.bin.mag254; for MAG-324 - uImage_mag324.clean.

Pay attention! For MAG322 and MAG324 the same file is used: uImage_mag324.clean.

File vmlinux.bin.mag<model_number> or uImage_mag<model_number>.clean should be downloaded from release of appropriate STB model and put into subdirectory images of Operator Uilities directory.

4. Kernel signing, producing files uImage / Bootstrap, uImzlib_null.img, uImzlib.img

  • For MAG-2xx/3xx the following script file is used:

kernel_sign_<model_number>.sh where <model_number> - STB model number (250, 254, 270, 256, 324, 349, 351)

Example of script running for MAG254:

./kernel_sign_254.sh

Use for MAG322 and MAG324 models the same file: ./kernel_sign_324.sh

  • For MAG-4xx the following script file is used:

    ./kernel_sign.sh

Command to running the script: 

./kernel_sign.sh <STB model> <path to kernel> <profile>

Example for MAG-420: 

./kernel_sign.sh mag420 ./mag420/images/uImage_mag420.clean img_make.profile.mag420
As result of script executing the following files are created: uImage_mag <model_number> or Bootstrap (kind of the file depends on STB model), uImzlib_null_mag <model_number> .img, uImzlib_mag <model_number> .img. They are placed into the directory of Operator Utilities.

5. Imageupdate making

Syntax:

./img_make.sh <version_number> "<description>" <path_to_rootfs> <modelname> <path_to_profile>
  Image making variables description
<version_number>

Version number of the image, must be a number (3 digits). After successful upgrading, environment variable Image_Version

takes this value.
<description>

Description of STB software image. Attention! Space characters are not allowed! After successful upgrading, environment variable Image_Desc takes this value.
<path_to_rootfs>

Location path to Root File System which should be included in the created software image of STB. You can get Root File System rootfs-….tar.gz from the release of the required STB model. You must specify the path to the previously unzipped directory.
<modelname>

Basic model name of STB for which the image is making (for example MAG200, MAG250, MAG254, MAG256, MAG270, MAG322, MAG324, MAG349, MAG351, 420 etc.)
<path_to_profile> 

Location path for the profile which can be used to configure additional sections of image-making (see Profile preparation item). Profile name format should be as follows: img_make.profile.<modelname>

For example, for MAG254: img_make.profile.mag254

Example for MAG254:

./img_make.sh 218 "Test_my_version" ../../254/rootfs-0.2.18r14 MAG254 ./img_make.profile.mag254

Example for MAG256:

 ./img_make.sh 220 "Test_my_version" ../../256/rootfs-2.20.04 MAG256 ./img_make.profile.mag256

Example for MAG420:

 ./img_make.sh 220 "Test_my_version" ../../420/rootfs-2.20.02-r5 MAG420 ./img_make.profile.mag420

As a result of successful command execution, the imageupdate file will be created and placed into the directory of Operators Utilities.

Notes on using GPG

To deal with secure keys and creating a digital signature of images the program GPG is used - gnupg.org, GNU Privacy Guard - Wikipedia

For example, to transfer the key from one computer (or virtual machine) to another you can use the following commands:

  • to save the secret key in the file opsecbin.KEY:
 gpg -o opsecbin.KEY --export-secret-keys ID_Key
  • to add this key to the GPG from the file opsecbin.KEY:
 gpg --import opsecbin.KEY
  • to look through currently available keys:
gpg --list-keys

PublicImage - preparing, making

CustomImage - preparing, making

OperatorImage

Instructions for making and updating the image are provided after agreeing on the procedure for signing the operator's key with the commercial department.

Need Help

Dave is an expert on the MAG STB and the author of this article.

Was this article helpful?

Yes No

Sorry to hear that.
How can we improve this article?

Send
We use cookies in order to optimise our website, provide you with the best possible user experience and help us promote our products. Please read our Cookie Policy to find out how we use cookies and how you can control cookies.
By using this website or closing this message, you acknowledge our Privacy Policy and agree to our use of cookies as described in our Cookie Policy.