> | # Configuration Applet ## Introduction This sample exposes the codebase for the configuration applet shipped with the device server. This material is offered for demonstration purposes so users may learn how to create custom java applications that configure and control the device server. Although the device ships with this applet as the installed default, users can replace the shipped applet with one of their choosing to customize the user interface to the device. Customized applets could be minor twists on the current applet or they could be totally unique representations of the device that the server is attached to (see the messanger applet as an example). The configuration applet is built upon a set of Digi utility classes found in the common.jar library. The classes available in this library are described in the accompanying java doc. You can build and run this code as an applet or as a standalone application. Please be aware that this is sample code that is provided AS-IS. There is no written or expressed warantee or support for this code. Feel free to examine and extend the code to your liking but understand that future releases of this code may changed without notice. The configuration applet runs by pointing a browser at the IP address of the device server. This opens the index.htm file on the device which in turn downloads and invokes the applet within the browser's jvm plugin. This applet is written such that it requires the Sun java plugin version 1.4.2 or newer. This was done to take advantage of the advanced UI and networking features available in this jvm. Your custom written applets and applications can be written to run on jvm's offered by other vendors as you see fit. This configuration application has been developed with a number of customer extention points in mind. The current implementation allows users to customize some of the look and feel of the application without having to re-code the applet. Things such as changing string labels, changing screen colors, or setting background images can all be done easily without changing a line of code. ## How To Build This sample has been written and tested with the J2SE 1.4.2 SDK and can be built using Apache Ant 1.5.3. These can be downloaded from the following locations: http://java.sun.com/j2se/1.4.2/download.html (download the appropriate SDK for your platform under the Download J2SE v 1.4.2 section) http://ant.apache.org/bindownload.cgi ### To build this sample Open a command prompt. Go to the configapp directory. Execute the build.bat file, specifying the target 'all' (e.g. build all) Two environment variables are required to build the sample: JAVA_HOME and ANT_HOME. The default values for these are C:\j2sdk1.4.2 and C:\apache-ant-1.5.3-1, respectively. If you install Java or Ant into different directories you will need to set these environment variables appropriately. ### Output of the build The build creates 2 subdirectories: build and dist. The build subdirectory contains the all the generated class files, javadoc files, jar files, etc. The dist subdirectory is intended to be used as a self-contained distribution of the application and contains the jar files and associated files to execute the application or applet. ## How to Sign This applet requires that the applet be signed with a digital signed certificate in order to communicate with the device over the network. This is used to prevent malicious behavior from unsigned applets as well as secure your applet. By default, the applet is signed with a temporary digitial certificate. If you rebuild the applet, or provide your own version of the applet with your products, you should sign the jar file with your own digitial signature. The steps below show how to request a Java Sun Signing Digitial ID from VeriSign. These steps require that the environment variable JAVA_HOME be set appropriately as described in the How to Build section. Open a command prompt. Go to the configapp directory. Generate the key and keystore: > %JAVA_HOME%/bin/keytool -genkey -dname "cn=Digi International Inc., o=Digi International Inc., l=Minnetonka, s=Minnesota, c=US" -alias digi -keypass <mypassword>; -keystore mykeystore -storepass <mypassword> -keyalg "RSA" Replace the Digi name and alias and Minnetonka location with your company's respective name and location. Generate certificate request: > %JAVA_HOME%/bin/keytool -v -certreq -alias digi -file certreq.cer -keystore mykeystore Request certificate from VeriSign (the machine used to request the certificate and the machine used to retrieve the certificate must be the same): Go to http://www.versign.com. Select Code Signing IDs. Select VeriSign Code Signing Digital IDs Select Sun Java Signing Digital ID Click Buy Now button Import certificate into keystore: > %JAVA_HOME%/bin/keytool -import -trustcacerts -alias digi -file mycert.cer -keystore mykeystore Digitally sign the applet: > %JAVA_HOME%/bin/jarsigner -keystore mykeystore -storepass <mypassword> -verbose configapp.jar digi Replace the "digi" alias with your Company's alias as selected when generating the keystore. ## How To Run This sample can be run as an applet or an application. When run as an applet the configapp resides on the device and is downloaded and run from within a browser on your PC. When run as an application the configapp resides on your PC and is executed from there. ### To run as an applet: You must load the jar and HTML files onto the device (this only has to be done once). When executed, the configuration applet will connect back to the device it was loaded from. Access the web interface by entering the following URL in in a browser's URL window: http://ip-address-of-device/home.htm Select File Management under the Administration menu. Click Browse. Locate and select the common.jar file in the configapp\dist\bin\applet directory. Click Open. Click Upload. Click Browse. Locate and select the configapp.jar file in the configapp\dist\bin\applet directory. Click Open. Click Upload. Click Browse. Locate and select the index.htm file in the configapp\dist\bin\applet directory. Click Open. Click Upload. Click Browse. Locate and select the config.ini file in the configapp\dist\bin\applet directory. Click Open. Click Upload. Click index.htm to run the configuration applet from the device. (to access the applet directly use the URL http://ip-address-of-device/FS/WEB/index.htm) To have the applet run as the default interface so that the applet runs every time you log into the device using the URL http://ip-address-of-device, follow the following steps after having loaded the applet into the file system. Access the web interface by entering the following URL in in a browser's URL window: http://ip-address-of-device/home.htm Under the User Interfaces section on the Home page click Set as Default for the Custom Interface. ### To run as an application: Execute the batch file provided. You must specify the IP address of the device you want the configuration application to connect to. Open a command prompt. Go to the configapp\dist\bin\applet directory. Execute the configME.bat file, specifying the IP address of the device (e.g. configme 192.168.1.100). ### Configuring the device: Once started, the configuration utility can be used to configure various aspects of the device server. ## Customizing the Configuration Application ### Overview There are a number of ways to customize the provided configuration application that range from simply editing a configuration file to actually writing or changing java code. The customization options can be broken down as follows: Look and Feel adjustments can be made by editing the config.ini file UI label and message text adjustments can be made by editing the resource .properties files Custom views and content adjustments can be made by editing the .java source files Each of these options will be described in more detail below. ### Look and Feel Adjustments The config.ini file contains a number of settings that control the look and feel of the configuration application. Some of these settings are global and affect the entire UI while others are specific to one of the views in the UI. #### Global Settings The following settings apply to the entire user interface: TextColor=R,G,B specifies the color of text and most component outlines. MenuColor=R,G,B specifies the color of menu text. ControlColor=R,G,B specifies the background color of controls such as buttons, dialogs, etc... DisableColor=R,G,B specifies the color of disabled components. BackgroundColor=R,G,B specifies the color application background. HeadingBarBackgroundColor=R,G,B,A specifies the color of heading bars in some views. TabbedPaneBackgroundColor=R,G,B,A specifies the color of a tabbed pane background. TextFont=name,size,style specifies the font to use for all text in the application. Style value can be 0 (Plain), 1 (Bold), 2 (Italics), or 3 (BoldItalics). The User Interface of the configuration utility is made up of several different subpanels. Each of these panels can be configured to have a unique background color or background image. The background color can be set to be solid, transparent, or semitransparent. Each panel in the user interface has a unique name and that name should be used in specifying the configuration of that panel. The default config.ini file contains the names and settings for each panel. Many of these settings are commented out but you can uncomment the settings to alter the look of the user interface. #### View Background Color The background color of a panel can be expressed by the use of the BackgroundColor keyword. For example, to set the background color of the message panel specify the panel name & keyword followed by the R,G,B,A values that make up the desired background color. All values range from 0-255. R,G,and B specify the Red, Green, and Blue components of the color and the A value represents the Alpha Channel (ie transparency) of the background. A value of 0 means the background is completely transparent and a value of 255 means the background is solid. Some examples and their meanings follow:
>                       MessagePanelBackgroundColor   = 255,0,0,255
> This line sets the background color of the MessagePanel to be solid Red.
>                       NavigationPanelBackgroundColor   = 255,255,255,255
> This line sets the background color of the navigation panel (the menu area) to be solid WHITE.
>                       ContentPanelBackgroundColor   = 200,200,255,50
> This line sets the background color of the content panel (the main view area) to be a translucent light blue. Using this setting, the user will be able to see through the content panel to see the application panel that is behind it. #### View Background Image The background of a panel can contain an image of the users choice by using the BackgroundImage keyword. For example, to set the background image of the message panel, specify the panel name and keyword followed by the name of the image to be displayed. The image must be stored in the .gif format and the image must be placed in the \src\main\com\digi\config\images directory before rebuilding the configuration application. Additional keywords allow the user to specify if the background image should be tiled, stretched or positioned at a specific location in the panel. The following examples show use of these keywords:
>                       AppPanelBackgroundImage   = digi_logo_embossed.gif
>                       AppPanelBackgroundTile    = true
>                       AppPanelBackgroundStretch = false
> The lines above specify that the application panel (backdrop for all other panels) should be painted with the digi_logo_embossed.gif image. Furthermore, the image should be tiled across the entire application background.
>                       NavigationPanelBackgroundImage   = digi_logo.gif
>                       NavigationPanelBackgroundImagePos= 8;
>                       NavigationPanelBackgroundTile    = false
>                       NavigationPanelBackgroundStretch = false
> The lines above specify that the navigation panel should be painted with the digi_logo.gif image. Furthermore, the image should not be tiled or stretched but instead placed in its natural size in bottom center of the panel.
>                       RebootViewPanelBackgroundImage  = sunset.gif
>                       RebootPanelBackgroundTile       = false
>                       RebootPanelBackgroundStretch    = true
The lines above specify that the reboot view panel should be painted with the sunset.gif image. Furthermore, the image should be stretched to fit the size of the reboot view panel. One thing to note is that if a panel specifies a background image, the user must specify a background color that is transparent or semi-transparent. Otherwise, the background image will not show through the specified background color. The default background color for all panels is transparent but this too can be customized (see DefaultPanelBackgroundColor). The following config.ini files are provided for your reference. config.ini - the default Digi theme white_config.ini - a basic white background theme black_config.ini - a basic black background theme fancy_config.ini - a theme that mixes various background bitmaps and colors You can use try these ini files by renaming them to config.ini and uploading them to your device. You will then need to reload your applet for the new theme to take effect. ### Text Adjustments The configuration application stores all text strings displayed in the GUI in a set of resource files. The resource files are all found in the \src\main\com\digi\config\resources directory. By editing the text strings in these files and rebuilding the application, you can change the text that is displayed when the application is run. The resource files are partitioned as follows: Basic Labels are found in the ConfigUIResourceBundle.properties file. These are labels used on menus, buttons, as well as strings displayed in the various configuration view panels. Error Messages are found in the ConfigResourceBundle.properties file. This file contains the primary and secondary text associated the various error messages that are displayed in the scrolling message area of the configuration application. This file has special formatting that is described in the heading of the file. Application Image file names are found in the ConfigImgResourceBundle.properties file. The configuration application refers to images used on buttons and other UI controls by name. This file maps those names to the associated .gif image file. The .gif image files must be placed in the \src\main\com\digi\config\images directory before building the application. ### Custom View Adjustments Customers familiar with java devlopment can use the sample configuration applet as a base to create more extensive customizations. The configuration sample applet is packaged such that views can be removed, modified, or added fairly easily. The configuration application is packaged in the configapp.jar and consists primarily of user interface classes. The application also makes use of the common.jar shared library which provides the underlying communication and device management classes.The details about how these jar files are organized and how the classes should be used can be found in the corresponding javadoc links below: configapp.jar javadoc common.jar javadoc
Digi International Inc. | 11001 Bren Road E. Minnetonka, MN 55343 PH: (952) 912-3444 or 877-912-3444 FX: (952) 912-4952