AN001. Customization Options in Our Products

What's in this Application Note

Our Customers that supply Tibbo Device Servers with their own equipment (systems) often wonder if it is possible to alter default setting values of the DS, hide certain settings so they could not be seen and edited in the DS Manager , hide some installation components (for example, VSP Manager ), display their Company name instead of Tibbo, etc. This article describes an array of customization options that are available.

** **Contents:

• Define your own default (post-initialization) setting values

  • Hide settings so they cannot be viewed (edited) through the DS Manager

  • Select which DST components should be installed on your User's PC

• Replace default name and logo (bitmap) with your own name and logo in the installation program

• Prepare your own installation file (distribution CD)

Define your own default (post-initialization) setting values

Important note: Release3.5 branch of application firmware (i.e. firmware for second-generation devices) only supports custom profiles starting from V3.54 . Unfortunately, there remains a limitation regarding how the firmware file with custom profile attached can be loaded into the DS. Custom profile will only work if upgrade was performed through the network. If firmware file (with custom profile attached) was loaded through the serial port then custom profile will not work correctly. We apologize for inconvenience but nothing can be done to remove this limitation. Release3.0 branch of application firmware does not have this limitation.

It is now possible to define your own, different, post-initialization setting values. Why would you want this? Well, if you supply a system in which the DS is always used in TCP/IP mode, then you might want to make the Transport Protocol (TP) setting default to 1(TCP) instead of 0(UDP), as it is "by default". And if you know that your serial device works at 19200bps, then wouldn't it be good to set this baudrate as a default value for the Baudrate (BR) setting (instead of the "factory default" of 38400bps).

The process of defining your own post-initialization defaults starts with creating a profile file . This file should have a .txt extension. You can use a Notepad or any other simple text editor to create this file. In our example we will create a profile for a Company named "XYZCORP". We will create a custom profile that will make the following changes to the original post-initialization values of the DS:

-Transport Protocol (TP) setting = 1(TCP)

-Routing Mode (RM) setting = 2(client)

-Baudrate (BR) setting = 4(19200bps)

-Parity (PR) setting = 2(odd)

Open the notepad and create the file named profile.txt that contains the following data:

_XYZCORP

TP1

RM2

BR4

PR2

Note: put <CR> even on the last line so this line is complete.

Each line of this file except the first one corresponds to a particular setting. Setting mnemonics and desired values are exactly the same as the ones used for DS programming via the serial port or network- you can find this data here .

The first line of this file is reserved for the profile name. This name is displayed by the DS Manager in the caption of the settings dialog . This feature is provided so that it was possible to tell whether the DS is running a "profile-modified" firmware or default firmware. The profile name must start with the underscore sign ("_") or it will not be recognized.

Now that your profile is created you need to merge it with the DS firmware file. To do this, you need to use a small DOS program called add_prof.exe . The program can be emailed to you on request.

Put all three files (firmware file, profile file, and add_prof.exe) into the same directory. The firmware file should be of "W" or "S" type (i.e. em_314w.bin or em_314s.bin ). As explained above, this means that only "older" devices (EM100-00/ -01/ -02, DS100-00/ -01/ -02) can use profile files at the moment.

The executable is a DOS program, so open a DOS session and run the program like this:

add_prof input_firmware_file profile_file output_binary_file

Note: you don't need to specify file extensions, the program will assume that input_firmware_file and output_binary_file have .bin extension, and the profile_file has the .txt extension. So, in our example you should type:

add_prof em_312s.bin profile em_xyz

The output file, em_xyz.bin will contain exactly the same firmware code plus the profile data you have defined. Now upgrade your DS using this new file.

After the upgrade launch the DS Manager and open the settings dialog of the DS that you've just upgraded. Notice that dialog caption now displays the name of your profile.

Now close the dialog and initialize the DS. After the initialization is finished open the settings dialog again and observe new default setting values that have been set.

Hide settings so they cannot be viewed (edited) through the DS Manager

Custom initialization profiles allow you to alter the initial post-initialization values of settings but they do not protect those settings from being edited by the User. Sometimes it makes a good sense to hide certain settings. For example, if you know that in your system the DS is always used in TCP/IP mode then it may be a good idea to hide the Transport Protocol (TP) setting so it is not displayed by the DS Manager at all. The principle here is: "less choices offered- less questions asked".

In our DST software the list of settings displayed for the DS by the DS Manager is defined by the .sdf files (SDF= Setting Definition File). During installation those files are copied into the .../Program files/Tibbo/Device Server Toolkit/sdf folder . Filenames correspond to the firmware versions of DS (except for the file wizserial.sdf - this one is used by the Connection Wizard and must be always kept as is). For example, your /sdf folder can contain the files V2-21.sdf and V3-00.sdf . These files correspond to firmware V2.21 or higher and V3.00 or higher. That is, when the DS Manager encounters the DS with firmware V2.53 it will use the file V2-21.sdf because 2.53 is later that 2.21 but earlier than 3.00.

The data structure inside the .sdf file is very straightforward: each line represents one Setting or Setting group. Here is one (abstracted) example of such a file:

I=$NET;D=Network Settings;T=GROUP

I=ON;D=Owner name;T=STRING;C=EDIT;MAXLEN=8;F=R

I=DN;D=Device name;T=STRING;C=EDIT;MAXLEN=8;F=R

...

...

I=E1;D=Stop-character (ASCII code);T=INT;C=STATIC;M=CHARDLG;V=E1>255? "ASCII code cannot exceed 255":""

I=P1;D=Number of post-characters;T=INT;C=EDIT/SPIN/0/1/1/1;V=P1>15? "Maximum number of post-characters is 15":""

The first line in the above example creates a setting group "Network Settings". Each group gets its own tab in the settings dialog of the DS Manager . All other lines in the above example represent individual settings. You can change the way the DS Manager displays the settings by rearranging and/or editing the data in the .sdf file. For example, supposing you want to create another group of settings called "Advanced" and put two settings there: Owner Name (ON) , and Device Name (DN) . All you have to do is add three lines to the end of the .sdf file:

...

...

I=$ADVANCED;D=Advanced;T=GROUP

I=ON;D=Owner name;T=STRING;C=EDIT;MAXLEN=8;F=R

I=DN;D=Device name;T=STRING;C=EDIT;MAXLEN=8;F=R

Save the file and reopen the settings dialog : you will see the new tab:

To hide settings simply remove corresponding lines from the .sdf file.

All .sdf files are supplied to the User as a part of the Device Server Toolkit installation. To see those files download the .zip archive of our distribution to your PC and unzip this archive into a separate folder. You can change the .sdf files and then prepare your own installation that you will distribute with your system (see below for details).

Select which DST components should be installed on your User's PC

You can hide certain DST components from being installed on your User's PC. This may come handy sometimes. For example, if you distribute the DS in a system that does not utilize the VSPD then why install the VSP Manager ? This will only create confusion and extra questions!

Components that can be selected/deselected are listed in the tdst.ini file found inside the DST distribution. To see the tdst.ini file download the .zip archive of our distribution to your PC and unzip this archive into a separate folder. Open the file using any simple text editor (i.e. Notepad ). You will see that the file contains the following data:

...

showdlg = 1

conwizard = 1

vsp = 1

The first line specifies whether the User will be presented with the screen asking him to choose which components to install. When showdlg = 1 the screen will be shown during the installation. When showdlg = 0 the screen will not be shown. The second line defines the default choice for the Connection Wizard : 1- "install", 0- "do not install". When showdlg = 1 the User will still have a chance to reverse this default selection, but when the showdlg = 0 the User won't be able to choose and the Connection Wizard will be installed or not installed according to the value of conwizard entry in tdst.ini . This means that if you set showdlg = 0 and conwizard = 0 then the Wizard will never be installed (and the User won't even know that there is such an option).

The third line (vsp=x ) defines whether the VSP Manager and the Port Monitor will be installed (Port Monitor is always installed together with the VSP Manager ). Currently, there is no any way to disable the DS Manager so this component is always present.

It is not enough to just change the file tdst.ini. You need to "sign it up" in order for the installation program to recognize this changed file. See below for more information.

Replace default name and logo (bitmap) with your own name and logo in the installation program

When you distribute the DST as part of your own system you may wish to display your own Company name and logo in the installation screens.

You can achieve this by editing the data in the tdst.ini file. To see the tdst.ini file download the .zip archive of our distribution to your PC and unzip this archive into a separate folder. Open the file using any simple text editor (i.e. Notepad ). You will see that the file contains the following data:

companyname = Tibbo Inc.

companyshortname = Tibbo

productname = Device Server Toolkit

setupimage = Tibbo.bmp

setupimageparams = 1;;;255,0,255

...

Companyshortname and productname define the default installation directory of the software. Directory is:

.../Program Files/companyshortname/productname

So, if your Company name is "XYZCorp" and you wish the software to be called "DST" then input the following data:

companyshortname = XYZCorp

productname = DST

In this case the default installation directory for the software will be:

.../Program Files/XYZCorp/DST

Productname is also shown during the software installation. You can define your own setupimage as well. This is a bitmap that is displayed in the installation screens. Unfortunately, there is no way to define the position of this bitmap in the window- InstallShield software used to generate installation files doesn't provide this flexibility. So, the bitmap position is fixed. The only thing you can do is define if this bitmap will contain a transparent color.

Setupimageparams line has several parameters. The first one specifies if there is a transparent color (1 for "yes" and 0 for "no"). Last three numbers specify which color is to be transparent. For example, if you don't want any transparency then set setupimageparams=0;;;0,0,0 . And if you want the white color to be considered transparent then set setupimageparams=1;;;255,255,255 .

One remaining parameter that we haven't mentioned yet is companyname . It is not displayed anywhere in the software itself but it is saved into the Windows registry upon installation.

Prepare your own installation file (distribution CD)

If you have made changes to the file tdst.ini or have modified the bitmap specified by the setupimage line then you need to signup your changes first. Signup process calculates the hash on the file contents and saves this hash in the signature= line of the tdst.ini . When the signature and the contents of the files do not match the changes you have made are ignored. You need to perform the signup process after you have made all the changes. Signup does not include the .sdf files so if you just changed these files you don't need to do it.

Here is what you need to do to signup your changes. First, request (from us) an archive called signup.zip . After you receive the file unzip it into the same directory where you unzipped all the installation files for the DST . Signup.exe is a DOS program and you run it like this:

signup tdst.ini

If everything is OK the program will generate the following output:

tdst.ini has been successfully signed up

You can distribute the modified version of the DST as a set of files or you can create a self-extracting ZIP archive (recommended). Signup.exe and tdstsign.dll files should not be included with your distribution. Please, make sure these files don't get included by mistake!