Tibbo Technology - Support - Customization options in Tibbo Products

Last updated:	05 Sep. 2003
Target auditory:	Companies that supply Tibbo Device Servers (and software) with their own equipment (systems).
Corresponding firmware:	V3.12 or higher
Corresponding PC software:	V3.08 or higher

What's in this article

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 EM100 (DS100), 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 we have provided in our firmware/software RELEASE3.

Contents:

Define your own default (post-initialization) Setting values
Hide Settings so they cannot be viewed (edited) through the DS Manager
Select which TDST components should be installed on your User's PC
Replace Tibbo name and logo (bitmap) with your own ones in the installation program
Prepare your own installation file (distribution CD)

Define your own default (post-initialization) Setting Values

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 DS100 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). 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 BR Setting (instead of the "factory default" of 38400bps)? Of course, there is a Connection Wizard that can make all the necessary choices for your Customer, but its use is not always possible or desirable. Therefore, being able to define your own post-initialization defaults is a very useful feature.

The process of defining your own 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 call ourselves "XYZCORP". We will create a custom profile that makes the DS100 (EM100) deviate from the default factory profile in the following: Transport Protocol (TP)=TCP, Routing Mode (RM)=Client, Baudrate (BR)=19200, Parity (PR)=Odd.

Open the notepad and create the file 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 one Setting. Setting mnemonics are exactly the same ones that you use when you manually program the DS100 (EM100) via the serial port. To set the Transport Protocol to 1 (TCP) you send STP1 (encapsulated in <STX> and <CR>, of course). The profile file should contain exactly the same text, only without the first 'S' (i.e. "TP1").

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 EM100 is running a "profile-modified" firmware or default firmware. The profile name must start with the underscore sign ("_") or it will not be recognized. Do not place your Setting values on the first line even if you don't want to use the name (use of names is recommended though: without then how would you be able to tell if there is a special profile loaded into a particular DS100?).

Now that your profile is created you need to merge it into the DS100 (EM100) firmware file (you can use the file em_XXXs.bin or em_XXXw.bin but not the file em_XXXsn.bin). First, download the firmware file (V3.12 or later). Then, download the file add_prof.exe. All this is available from http://www.tibbo.com/downloads.php. Put all three files (firmware file, profile file, and add_prof.exe) into the same directory. 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 the .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 DS100 (EM100) using this new file. Upgrade procedure can be found here.

After the upgrade launch the DS Manager and open the Settings of the DS100 (EM100) that you've just upgraded. Notice that dialog caption now displays the name of your profile (Fig. 1).

Fig.1

Now close the dialog and initialize the DS100 (EM100). After the initialization is finished open the Settings dialog again and observe new default Setting values that have been set.

One final note: as we have already mentioned it is not possible to add the custom profile to the em_XXXsn.bin firmware file. Files of the "sn" type contain the NetLoader within them. NetLoader is a separate firmware component that facilitates network upgrades. All Tibbo devices are shipped from the factory with the NetLoader already installed. You don't need to install the NetLoader again so you can just upgrade the DS100s (E100s) with the profile-modified firmware file created by you. If, for some reason, you do need to re-install the NetLoader then you will have to perform the upgrade in two steps: first, install the em_XXXsn.bin file. This will upgrade your NetLoader. Then, install the firmware file that you have created.

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 DS100 is always used in TCP/IP mode then it may be a good idea to hide the Transport Protocol Setting so it is not displayed by the DS Manager. Of course, you can just protect the Settings by a password (PW Setting) but the User will still see that the Transport Protocol Setting is there and have more questions: why is it there? What if I choose UDP instead of TCP?... It is this extra confusion that you often want to avoid.

In our TDST software RELEASE3 the list of Settings displayed by the DS100 is defined by the .sdf files (SDF= Setting Definition File). During installation those files are copied into the .../Program files/Tibbo/Tibbo Device Server Toolkit/sdf folder. Filenames correspond to the firmware versions (except 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 DS100 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 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 your new tab and the Settings you have in there (Fig.2).

Fig.2

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

All sdf files are supplied to the User as a part of the Tibbo 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 prepare your own installation file for more information.

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

You can hide certain components from being installed on your User's PC. This may come handy sometimes. For example, if you distribute the DS100 (EM100) 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 in the TDST 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". This defines whether the Connection Wizard component will be selected or deselected by default. 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. This means that if you set showdlg = 0 and conwizard = 0 then the wizard will never be installed.

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 prepare your own installation file for more information.

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

When you distribute Tibbo software 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 Technology Inc.
companyshortname = Tibbo
productname = Tibbo Device Server Toolkit
setupimage = tibbo.bmp
setupimageparams = 1;;;255,0,255
...

Companyshortname and productname define the default installation directory of the software: it is .../Program Files/companyshortname/productname. So, if your Company name is "XYZCorp" and you wish the software to be callsed "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 (Fig.3). You can define your own "setupimage" as well. This is a bitmap that is displayed in the installation screens (Fig.3). Unfortunately, there is no way to define the position of this bitmap in the window- InstallShield software 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.

Fig.3

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 system registry on 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, download this archive: signup.zip. Notice that your profile must have special permissions to be able to get this file. If you don't have these permissions at the moment then let us know (support@tibbo.com). We will evaluate your case and (most probably) approve your request. After you get the file unzip it into the same directory where you unzipped all the installation files for the TDST. Signup.exe, this 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 TDST 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.