Hack 93. Simulate Any BlackBerry

Is that image too wide for a BlackBerry screen? Is it going to look the same on a 7100g as it does on the 7290 attached to your hip? Use the simulator to find out.

Wouldn't it be nice if you could get each and every BlackBerry device that is released to put it through the paces? Does the entire web development staff need a BlackBerry solely to see how their work appears on a device? I think your money is more wisely spent in other ways and so does RIM.

The BlackBerry Simulator is not just a tool for hardcore application developers that are holed up in a dark room with black poster board over the windows. It comes in quite handy for web developers as well even your help desk could find some use for it. It comes with a slimmed down version of the Mobile Data Service, so you can get extremely close to the actual end user experience without shelling out hundreds of dollars for a device and service.

8.10.1. Obtain the Software

To use the simulators, you'll need to download and install the BlackBerry Java Development Environment. It is a free download, however, you will have to cough up some personal information and agree to a lengthy end user license agreement (EULA) to use it.

Go to the BlackBerry JDE web site http://www.blackberry.com/developers/downloads/jde/index.shtml and follow the steps to download the 4.0 version of the software. The download file is over 60 MB, so go get a cup of coffee while you wait.

As of this writing, Version 4.0.1 of the JDE is available. This version is actually an update to Version 4.0, so you'll need to have already installed 4.0. The only updates in 4.0.1 are the location API libraries for the new GPS devices. If you don't have a need for the GPS libraries, it's safe to skip the 4.0.1 release.

The JDE is installed much the same as any Windows application. Make sure you choose the complete installation to get all the goodies.

8.10.2. Run the Simulator

Once you've installed the BlackBerry JDE, bring up a command prompt and cd (change directory) to the directory where the device simulators are located. By default, they are located in C:\Program Files\Research In Motion\BlackBerry JDE 4.0\simulator.

In that directory, there will be several files including batch (.bat) and XML configuration files for each device that the JDE can simulate. Run the batch file for the BlackBerry model of your choice.

 C:\Program Files\Research In Motion\BlackBerry JDE 4.0\simulator> 7290.bat 

After a moment or two, you should see the device simulator appear as simply another application on your desktop (see Figure 8-16).

8.10.3. Access the Keys

Most of the keys will map to their corresponding keys on your computer's QWERTY keyboard, but you'll have to take note of the ways to access the keys that are unique to the BlackBerry (the trackwheel, for instance). Table 8-2 shows how the device keys map to the PC keyboard.

Figure 8-16. The 7290 simulator

Table 8-2. Accessing the unique device keys

Key	Using keyboard	Using mouse
Alt	Control	Click the Alt key
Rolling the trackwheel	Up and down arrows	Use the mouse scrollwheel
Clicking the trackwheel	The Enter key or left arrow	Click the trackwheel
The Escape key	The Escape key or right arrow	Click the Escape key
Backlight	Page Down	Click the Backlight key
The Symbol key	Delete	Click the Symbol key
The Phone key	Page Up	Click the Phone key

8.10.4. Browse the Web

When you try to access a web site using the browser, you'll get an error message, as shown in Figure 8-17.

Figure 8-17. The error when the MDS simulator isn't started

To get the browser to work, you'll need to start the Mobile Data Service simulator. This program simulates an actual MDS instance on your desktop, allowing the browser to access web sites just as if it were accessing it using a real MDS. Go to your Start menu, and then select Program Files Research In Motion BlackBerry Java Development Environment 4.0 MDS Simulator. This brings up a command window that stays running in the background, as shown in Figure 8-18. You can check this window for error messages and other activity as you do your testing. The MDS simulator and the email simulator described in the next section can be started in any order before or after you start the handheld simulator.

Figure 8-18. The MDS simulator command window

Once the MDS simulator is running, you can use the BlackBerry Browser to test any web site that is accessible from your computer. Because it's an (almost) fully functioning Mobile Data Service, you can test your push applications using the simulator. The default PIN for the handheld simulator is 2100000A. This can be changed by editing the batch file used to start the specific model's simulator. Look for the /pin=0x2100000a string in the file and change it to use another PIN.

8.10.5. Simulate Email

The BlackBerry JDE also provides an email server simulator. This provides basic sending and receiving functionality to your handheld simulator. You can point the email simulator to a POP3 mailbox and have new messages delivered to your handheld. It also allows you to enter an SMTP server to deliver outbound messages from your device. Start the Email Server Simulator by going to your Start menu and selecting Program Files Research In Motion BlackBerry Java Development Environment 4.0 Email Server Simulator. A command window will appear, and eventually a dialog appears that allows you to enter your POP3 configuration for your mailbox along with the outbound SMTP server (see Figure 8-19).

Figure 8-19. The email server simulator

If you try to send email messages on your handheld simulator without the email server simulator running, the messages will stay in the message list as if you were out of network coverage on a real BlackBerry device. Once you start the simulator, they'll be sent immediately, as if you came back into a coverage area.

8.10.6. Hack the Hack

When you peer into the batch files that start the simulator, you'll see that they call an executable named fledge.exe that actually runs the simulator. If you run fledge.exe directly, you can use a variety of command-line options to customize the simulator's behavior. Table 8-3 shows some of the interesting ones to try on for size.

Table 8-3. Command-line switches for the simulator

Command-line switch	Function
/help	Show all command-line switches.
/pin={int}	Give the device a pin of your choice.
/secure	Enable device security such that custom apps have to be signed [Hack #98].
/session={string}	Write to specific logfiles for this session of the simulator.
/title={string}	Use a custom title for the simulator window.
/no-show-plastics	Don't show the device, just its LCD screen.
/zoom={float}	Magnify the simulator by the given factor.
/no-save-flash	Don't save the flash memory to disk upon exit.
/phone-number={number}	Assign a custom phone number to the simulator.