June 2008 v2.0
This application note guide describes the use and functionality of the so called embedded script files. This application note applies to all platform firmware releases from R7.4.2 on and upwards.
Thomson continuously develops new solutions, but is also committed to improvingits existing products. For more information on Thomson's latest technological innovations, documents and software releases, visit us at http://www.thomson-broadband.com
Script Files (STS)
Most commonly referred to as STS files, script files are text files which contain one or more sequentially ordered Command Line Interface (CLI) commands that can be executed onthe Thomson Gateway. There are different ways of executing these scripts on the Thomson Gateway: locally after transferring the file to the Thomson Gateway via File Transfer Protocol (FTP). remotely by means of the Remote Procedure Call "Download" (with FileType equal to "3 Vendor Configuration File") in the TR-069 protocol. The Thomson Gateway will recognize an STS file by means of the STS fileextension (as opposed to a INI file). remotely by automatic downloading via BOOTP/TFTP.
Format of STS files
A valid command line script file needs to comply with the following rules: the first line must include the following two space-separated fields: TPVERSION=x: this is the so-called tag-parser version that indicates the command line interface syntax version. The tag-parser version definesthe CLI command syntax compatibility. BOARD_NAME=y: this is the hardware platform mnemonic (BANT-8, CANT-A,…) Commands are absolute, meaning they include the full path from CLI root menu. All CLI commands are executed in sequence. This is an example of the content of a simple STS-file:
TPVERSION=2.0.0 BOARD_NAME=BANT-X :env set var=CONF_VERSION value=1.1.1 :dsd urlfilter rule add url=www.yahoo.comaction=redirect redirect=www.google.net :dsd urlfilter rule add url=www.cisco.com action=block
The order of CLI commands is important. An STS file should always be closed with a carriage return (\CR), otherwise the last line in the STS file will not be executed. On most text editors this is the equivalent of one white line after the set of commands.
Testing and debugging of STS files
STSfiles can be tested locally as explained below. It is assumed that the user has already prepared a STS file for testing called "test.sts". The steps for local debugging are the following: 1 Connect your computer via the LAN to the Thomson Gateway. Use any FTP client of your choice to upload the "test.sts" file to the file system of the Thomson Gateway. The file needs to be placed in the “/ dl”directory. Start a TELNET session to the Thomson Gateway and execute the following command: :config load echo=enabled filename=test.sts 3 The Thomson Gateway will now execute one by one the commands as specified in the "test.sts" files and print the output of these commands to the TELNET prompt. If any errors pop up they can be spotted and corrected here.
E-DOC-CTC-20071112-0001 v2.0Chapter 2
Embedded STS Files
Embedded STS files have exactly the same file format and conventions as a normal STS file. An embedded STS file however is executed only once, i.e. after a remote firmware upgrade. The advantage is that it only requires one CPE WAN Management Protocol (CWMP) action to download a new build and update the configuration afterwards, whilst the userconfiguration is kept and restored. This allows to apply a firmware upgrade that preserves the user configuration but additionally applies either configuration changes or updates (e.g. for new added functionality). "Embedded" refers to the fact that these STS files are not remotely downloaded to the Thomson Gateway, but are embedded in the firmware. The process of embedding these STS files is...