The main goal of this example is to show how to use the .AmuletOS script file to create a single file which includes a project file, an Amulet OS and custom LCD settings. This single file can be saved as a .uht or .pdb which can be programmed into any Amulet module, regardless of which OS is currently loaded. The CompileMe.htm is taken directly from the Keyboard example. Since the specifics of the Keyboard example is not within the scope of this example, see the Keyboard's ReadMe.htm for information regarding the inner workings of that example. In this example, we will concentrate on creating a .AmuletOS file and changing the LCD settings so we can create a custom OS file.
There is currently a file called CustomOS.AmuletOS in this (projects\Examples\CustomOS) directory. It is a text file and it only has three lines in it. You should open it up on Notepad or another text editor of your choice. It should look like this:
..\..\..\binaries\AmuletOSv3.3.5_RAW.uht
CompileMe.uht
NoFontHdr
CompileMe.uht is the name of the previously saved project which resides in this directory. To create CompileMe.uht, open the HTMLCompiler and compile the file named CompileMe.htm in this directory. Once it has successfully compiled, save the compiled project as CompileMe.uht. (Tip: Hit Ctrl-S to create a file called CompileMe.uht. You can also setup your HTMLCompiler to have a "Save file.uht" button, which will also create a file called CompileMe.uht.)
..\..\..\binaries\AmuletOSv3.3.5_RAW.uht
is the name of the current raw Amulet OS file. The version
number might be different than what is found in this CustomOS.AmuletOS file,
so go to the Amulet\binaries folder and find the version of the raw Amulet OS
file which matches the HTMLCompiler you are using*. If it's different than what
is found in the .AmuletOS file, put this name in place of the AmuletOSv3.3.5_RAW.uht.
Make sure that you put in the name of an OS file which ends with _RAW. A raw
Amulet OS file contains the Amulet OS as well as all the pages the OS requires
to work correctly. It does not include any project files, though. Notice that
all files specified within CustomOS.AmuletOS are relative to the directory where CustomOS.AmuletOS
resides.
* To determine the version of your HTMLCompiler, go to Help->About
and read the first line of the dialog box.
NoFontHdr is a key which tells the HTMLCompiler to use the font header information which is included with your project, instead of trying to auto generate one. Anytime you create a .AmuletOS file, you must include the key NoFontHdr.
Once your CustomOS.AmuletOS file is completed, save it. Now, in the HTMLCompiler, go to File->Open and browse to the Amulet\projects\Examples\CustomOS directory and select CustomOS.AmuletOS. Assuming both files exist and were generated from the same version of the HTMLCompiler as what you are currently using, your HTMLCompiler should look something like:
Tip: Your HTMLCompiler most likely does not look like the one above. Go to Settings->HTMLCompiler Skin to change the look and feel to suit your tastes.
At this point, you have created a custom OS which includes the raw Amulet OS and the project called CompileMe.uht. In some cases, this might be good enough, because the OS is setup, by default, to work on a 320 x 240 display, with a frame frequency of 70 Hz, and a negative display polarity, which is the normal display polarity for the 5.7" Easy GUI Starter Kit. By default, any time you reload the raw Amulet OS, it will require you to do a touchscreen calibration, as well. Try programming your Flash right now and the new OS should be loaded as well as the project CompileMe.uht. You can also save this as a .uht or .pdb file. Try loading the file you just saved, CustomOS.uht, and you should be able to reprogram your Easy GUI again.
Now, let's say we want to customize the OS file to our particular display. You can do this by entering the LCD Characteristics Dialog box by going to Settings->LCD. The LCD Type will probably be listed as either AmuletGT320 or AmuletGT570. Let's create our own LCD Type. Start by going to the drop down box for LCD Type and select OtherLCD. Now put in the correct LCD width and height. We'll assume you are using a standard QVGA display, so we'll enter 320 for the width and 240 for the height.
Now choose a frame frequency. By default, the Amulet displays are shipped with a frame frequency of 70Hz, but for this example, let's change it to 80Hz. All displays sold by Amulet are setup for a negative PixClk Active Edge and a positive Line Pulse Polarity, so let's leave those in that state.
Now we need to choose the Display Polarity. The current raw OS starts out with a negative polarity and if your display is transmissive that is the polarity that you are probably accustomed to. We'll keep the negative polarity unless you want to experiment. If you are using an Amulet transflective display, a positive polarity is how it is shipped from the factory, so changing it to negative polarity will probably look different than you are used to.
Most QVGA displays use 4 bits/pixel clock, so we'll leave that at 4 unless your display requires a different number.
If your display has a touchscreen, it is a good idea to force touchscreen calibration. This requires the user to first calibrate the touchpanel upon powering the display for the very first time. Once the calibration routine has been completed, it will not automatically appear again. (You can still get there by setting DIP switch 4 to OFF or using an href in your html page of Amulet:calibrate()) So, as long as you have a touchscreen, let's check the Force Touchscreen Calibration check box.
Finally, and this is the key, you must check the Always Program Settings check box. This will write the LCD information we just selected every single time the HTMLCompiler either saves a project or programs the project into flash. So, by selecting this check box, when we choose to save the custom OS file we just created, the LCD characteristics will be saved right along with it, integrated into the .uht or .pdb.
Your LCD Characteristics dialog box should look like this now:
Now we want to save this LCD Type so we can easily come back to these settings at any time. Press the Save button and you should see a text box show up along with a button that says Save New File. Type in the name of your new LCD Type. For this example, I will call it MyCustom. One thing to note, make sure you do not use spaces in your new file name. The bottom of the LCD Characteristics dialog box should now look like this:
Choose the Save New File button and the LCD Characteristics screen will shut down. Now relaunch the LCD Characteristics dialog box by going back to Settings->LCD. Let's just confirm that your new LCD Type was created and that all the values are what we want. Here's a screen shot of what it should look like:
Assuming your LCD Characteristics screen looks okay, hit the Save button. The LCD Characteristics screen will shut down again. Now in the HTMLCompiler, recompile the CustomOS.AmuletOS file. (Tip: You can quickly recompile the last file you compiled by hitting Ctrl-Enter)
(Another tip: You can recompile one of the last five files you compiled by
going to File-> and choosing your file from one of the files showing up on
the menu.)
After recompiling the CustomOS.AmuletOS, save the resultant file as CustomOS.uht. Before doing anything else, go back to the LCD Configurations dialog box and uncheck the Always Program Settings check box. The reason why we checked that was so that the configuration settings would be saved in the CustomOS.uht file. Now that CustomOS.uht has been saved, now we no longer need to always program these settings.
Now, use the HTMLCompiler to load the file CustomOS.uht. After it has been fully loaded, the Program Flash button should appear. Make sure that your computer is hooked up to the Amulet Easy GUI module and that the module is powered up. Hit the Program Flash button to load your new OS file along with the project CompileMe.uht. After loading, the Easy GUI should require you to recalibrate the touchscreen, just like we requested it to do, and the polarity should be negative, just like we selected.
You can now go in and make some changes, like not requiring a touchpanel calibration or a positive polarity and resave the MyCustom LCD Type to see how these changes will affect your Custom OS. If you do go back to make changes, remember you must select the Always Program Settings check box and you must recompile the CustomOS.AmuletOS file and resave it.
That should be everything you need to know to create your own custom OS file which can be used in production.
NOTES: