Hacking the webOS

Becoming Mojo Man

In previous articles we have examined the market positioning of the Palm pre and the operating system it rode in on — the webOS. In this article I would like to dispense with the marketing speak and jump in a bit deeper. We are going to look at the webOS from the inside-out by actually modifying one of the built-in applications. Don’t worry, if all goes well, we won’t actually hurt anything. Or, if you prefer you can always deviate from the prescribed course and attempt to make permanent changes to your device. The choice is yours. I am going to be working via the development environment’s Emulator, but the changes we are making here may also be made to a rooted device. Let’s get started.

The first thing we need to do is start the Palm Emulator. This process varies depending on which host operating system you are running. I have run the Palm Emulator on both my MacBook and my Windows XP machine. I don’t want to get too bogged down in the vagaries of using the Palm SDK on one platform versus another — for now, I am just going to demonstrate on my Windows laptop. So, assuming you have your Palm Emulator running you will want to connect to it via ssh. While MacOSX includes an ssh client, we need to use a third party client on Windows. Fortunately for us, Palm thought ahead on this one and provided putty.exe with the other tools included in the SDK:

C:\Program Files\Palm\SDK\bin>dir
 Volume in drive C has no label.
 Volume Serial Number is ABCD-1234
 Directory of C:\Program Files\Palm\SDK\bin
07/19/2009  07:00 PM    <DIR>          .
07/19/2009  07:00 PM    <DIR>          ..
07/19/2009  07:00 PM    <DIR>          novacom
06/18/2009  03:41 PM            13,312 novacom.exe
07/09/2009  01:18 AM             1,199 palm-emulator.bat
07/09/2009  01:14 AM               761 palm-generate.bat
07/09/2009  01:14 AM               750 palm-install.bat
07/09/2009  01:14 AM               747 palm-launch.bat
07/09/2009  01:14 AM               786 palm-package.bat
06/18/2009  03:41 PM            72,704 PalmEmulator.exe
06/18/2009  03:41 PM           454,656 putty.exe
               8 File(s)        544,915 bytes
               3 Dir(s)  21,373,145,088 bytes free
C:\Program Files\Palm\SDK\bin>

Connect to “localhost”, or 127.0.0.1, on the secure shell port, # 22. Once connected you will want to connect as “root”. The password is blank — i.e. don’t type anything, just hit enter. This will place you into a shell environment. From here you can navigate the file system like any other Linux system. You can see the start-up scripts in the /etc folder and the devices in the /dev folder. Our old friend the vi editor is there as well. Hopefully you are comfortable with this seemingly timeless editor because we’re going to be using here in a moment. If you are following along I would encourage you to take a few moments to simply cruise around the file system. It’s quite fun — really. I’ll wait here. OK, had enough? Let’s proceed to see if we can get into some trouble here.

Application Structure

webOS applications are stored in a directory with multiple files and sub-directories constituting the entire application. The “built-in” applications are stored in the /usr/palm/applications directory. User applications – i.e. the ones you and I write are stored in /var/usr/palm/applications. Let’s focus right now on the built-in applications found in /usr/palm/applications. This directory contains the applications the normal user will be interacting with on a daily basis — Email, Notes, Alarm/Clock, Media player, etc. Here’s one: com.palm.app.phone. I wonder what that is for? Have no fear, there is even a YouTube application. Here is a listing of the applications found on my Palm Emulator:

root@qemux86:/usr/palm/applications# ls
com.palm.app.backup                com.palm.app.location
com.palm.app.bluetooth             com.palm.app.maps
com.palm.app.browser               com.palm.app.messaging
com.palm.app.calculator            com.palm.app.musicplayer
com.palm.app.calendar              com.palm.app.notes
com.palm.app.camera                com.palm.app.ondevicedemo
com.palm.app.certificate           com.palm.app.pdfviewer
com.palm.app.clock                 com.palm.app.phone
com.palm.app.collectlogs           com.palm.app.phoneprefs
com.palm.app.contacts              com.palm.app.photos
com.palm.app.dataimport            com.palm.app.screenlock
com.palm.app.dateandtime           com.palm.app.soundsandalerts
com.palm.app.deviceinfo            com.palm.app.streamingmusicplayer
com.palm.app.devmodeswitcher       com.palm.app.tasks
com.palm.app.docviewer             com.palm.app.usbpassthrough
com.palm.app.email                 com.palm.app.videoplayer
com.palm.app.firstuse              com.palm.app.videoplayer.launcher
com.palm.app.help                  com.palm.app.wifi
com.palm.app.languagepicker        com.palm.app.youtube
root@qemux86:/usr/palm/applications#

Note that all of the applications follow the naming convention of “com” plus vendor — in this case Palm, but your applications would have your company name. Then “app”, followed by the name of the application. Let’s take a closer look at one of the applications. We will choose something relatively straight-forward — the calculator application. To look further at the calculator application, we need to change directory to com.palm.app.calculator, as shown here:

login as: root
root@localhost's password:
root@qemux86:/var/home/root# cd /usr/palm/applications/com.palm.app.calculator/
root@qemux86:/usr/palm/applications/com.palm.app.calculator# ls -l
drwxr-xr-x    5 root     root         1024 Jul  7 16:22 app
-rw-r--r--    1 root     root          101 Sep  7 19:23 appinfo.json
-rw-r--r--    1 root     root         6497 Jul  7 16:16 icon.png
drwxr-xr-x    2 root     root         1024 Jul  7 16:22 images
-rw-r--r--    1 root     root          685 Jul  7 16:16 index.html
drwxr-xr-x    2 root     root         1024 Jul  7 16:16 javascripts
drwxr-xr-x   10 root     root         1024 Jul  7 16:22 resources
drwxr-xr-x    2 root     root         1024 Jul  7 16:22 stylesheets
root@qemux86:/usr/palm/applications/com.palm.app.calculator#

Here is a quick run-down of the elements of a Palm webOS application:

• app – this folder contains the core of the application including the user interface files and programming logic, or code. You will spend quite a bit of time in the sub-folders of this directory when developing your own applications.
• appinfo.json — this required file contains important information about the application itself. We’ll look at this file in greater detail in a moment when we modify it.
• icon.png — this file is usually the home-screen’s application icon. It is a 48×48 pixel image.
• images — this folder is used as an organizational tool to manage the images needed by a webOS application.
• index.html — entry point for the application. If all goes well, you will never see this file visually — it should just happily load the Mojo framework and fade into the background.
• javascripts — an optional folder for holding javascript files needed by the application.
• resources — another optional folder used to hold application resources such as a database file or other meta data useful to an application.
• stylesheets — this folder contains the application’s style-sheet. If you are not comfortable with style-sheets you’ll want to study up on this topic as they constitute a core component of webOS development.

Let’s look into the app folder.

root@qemux86:/usr/palm/applications/com.palm.app.calculator# cd app
root@qemux86:/usr/palm/applications/com.palm.app.calculator/app# ls -l
drwxr-xr-x    2 root     root         1024 Jul  7 16:22 controllers
drwxr-xr-x    2 root     root         1024 Jul  7 16:22 models
drwxr-xr-x    3 root     root         1024 Jul  7 16:22 views

The webOS is based on the “Model-View-Controller” design pattern. Model represents your data — for example the model in a word processor would be a document. The “view” represents the visual aspect of your application — what the document looks like. For example, an application may employ more than one view to represent data in an application. Think about a document in “edit” mode versus “print preview” — same data, different views. Lastly there is the “Controller”. Controller represents the code logic, or the brains, of the operation. Digging into the specifics of the relation between controllers and views in webOS is a topic for another day. Trust me that the controller code is stored in the controllers folder and the views in the view folder, etc. The controller code is implemented in javascript (*.js) files and the views are implemented as html files.

For now we’re going to look for a quick-fix to satisfy our curiosity and actually change the look of this built-in application in a noticeable but nominal fashion. The change we are going to make is a trivial one but the good news here is that all of the source code to the application is contained in these folders and is readily modifiable by you! So if you want to take things a bit further and say change the calculator to perform arithmetic in hex instead of decimal, go for it! Of course, doing something on the Emulator is pretty harmless, but be mindful that this sort of thing can (and probably shouldn’t) be done on a real device.

1 + 1 = 3

We are going to avoid the temptation to change the Calculator application by making math easier for mere mortals — we’re just going to stick with some very low-hanging fruit for now. We are going to change the name of the application on the launcher screen and in the application itself by making a minor change in the appinfo.json file. Recall that a json file is a JavaScript Object Notation file format. In other words, it can be evaluated at runtime. Here is the file as shipped by Palm:

{
        "title": "Calculator",
        "type": "web",
        "main": "index.html",
        "id": "com.palm.app.calculator"
}

And here is what the application looks like when running on the Emulator.

Now we are going to make a minor modification to the file, simply changing the title of the application from “Calculator” to “LinuxMag-Calc”. You can use the built-in vi editor to make this simple change.

root@qemux86:/usr/palm/applications/com.palm.app.calculator# vi appinfo.json

{
        "title": "LinuxMag-Calc",
        "type": "web",
        "main": "index.html",
        "id": "com.palm.app.calculator"
}

After you make this change and save the file, exit out of vi. Now we need to restart the device for our changes to take affect. Simply type reboot and hit enter. This will restart the device. When the device restarts, we should see our changes as below.

Well, you have now modified a Palm webOS application — which of course is just the start. We’ll revisit webOS in a future installment.