BlackBerry Simulator Version 3.6 User Guide
BlackBerry Simulator Version 3.6 User Guide Last modified: 10 April 2003 Part number: PDF-06395-001 At the time of publication, this documentation complies with simulator version 3.6. The information in this document is RIM confidential and is for internal distribution only. © 2003 Research In Motion Limited. All Rights Reserved. The BlackBerry and RIM families of related marks, images and symbols are the exclusive properties of Research In Motion Limited. RIM, Research In Motion, ‘Always On, Always Connected’, the “envelope in motion” symbol and the BlackBerry logo are registered with the U.S. Patent and Trademark Office and may be pending or registered in other countries. All other brands, product names, company names, trademarks and service marks are the properties of their respective owners. The handheld and/or associated software are protected by copyright, international treaties and various patents, including one or more of the following U.S. patents: 6,278,442; 6,271,605; 6,219,694; 6,075,470; 6,073,318; D445,428; D433,460; D416,256. Other patents are registered or pending in various countries around the world. Visit www.rim.com/patents.shtml for a current listing of applicable patents. While every effort has been made to achieve technical accuracy, information in this document is subject to change without notice and does not represent a commitment on the part of Research In Motion Limited, or any of its subsidiaries, affiliates, agents, licensors, or resellers. There are no warranties, express or implied, with respect to the content of this document. Research In Motion Limited 295 Phillip Street Waterloo, ON N2L 3W8 Canada Research In Motion UK Limited Centrum House, 36 Station Road Egham, Surrey TW20 9LF United Kingdom Published in Canada
Contents About this guide ................................................................................................................................................................... 5 Overview .............................................................................................................................................6 Audience ..............................................................................................................................................6 Conventions.........................................................................................................................................6 Related resources................................................................................................................................6
1 Getting started...................................................................................................................................................................... 7 Installing the handheld simulator....................................................................................................8 Setting up the simulators...................................................................................................................9 Starting the simulators.....................................................................................................................10
2 Using the simulator ...........................................................................................................................................................11 Using the simulator ..........................................................................................................................12 Setting wireless coverage conditions.............................................................................................14 Configuring reception..............................................................................................................15 Configuring transmission........................................................................................................15 Using the phone................................................................................................................................16 Simulating handheld operating conditions ..................................................................................18 Simulating flash memory ................................................................................................................19 Simulating a desktop connection ...................................................................................................19
3 Simulator options ...............................................................................................................................................................21 Handheld simulator options...........................................................................................................22 Mobile Data Service simulator options .........................................................................................23
About this guide This section provides information on the following topics: •
Overview
•
Audience
•
Conventions
•
Related resources
1: About this guide
Overview This guide explains how to use handheld and network simulators to perform the following tasks: •
learn how to use BlackBerry™ handhelds
•
test web content and third-party applications
•
reproduce and troubleshoot problems that are found in the field
•
demonstrate features of BlackBerry handheld software
This guide assumes that you are comfortable installing and using software on a Windows computer.
Audience This guide is intended for web content developers, trainers, technical support representatives, and sales people who need to use simulators for testing, training, troubleshooting, and demonstrations.
Conventions This guide uses the following conventions: Icon
Description Warning: Warnings advise you that failure to take or avoid a specific action can result in data loss or physical damage. Prerequisite: Prerequisites are required conditions for the associated topic. Note: Notes contain important information on the associated topic. Tip: Tips provide optional or time-saving information on the associated topic.
Related resources Refer to the following resources for additional information: Resource
Description
BlackBerry Java Developer Guide
This guide provides information on creating Java applications for BlackBerry handhelds.
BlackBerry Browser Developer Guide
This guide provides information on creating web content and web-based applications for BlackBerry handhelds.
BlackBerry Wireless Handheld User Guide This guide provides information on using BlackBerry handhelds.
6
BlackBerry Simulator
1 Getting started This section provides information on the following topics: •
Installing the handheld simulator
•
Setting up the simulators
•
Starting the simulators
1: Getting started
Installing the handheld simulator Two simulators are available to test your web pages without using a actual handheld: •
handheld simulator
•
Mobile Data Service (MDS) simulator
Install the handheld simulator 1.
Go to the BlackBerry Developer Zone web site: http://www.blackberry.com/developers.
2.
Download the handheld simulator .zip file to your computer.
3.
Right-click the .zip file.
4.
Click Extract to folder C:\...\3.6.0.x.simpackage. A folder called 3.6.0.x.simpackage is created. In the rest of this guide, this folder is referred to as the simpackage folder.
Install the Mobile Data Service simulator Prerequisite: To use the Mobile Data Service simulator, you must install the Java runtime environment (JRE) version 1.4.0 or later. Visit the Sun web site at http://java.sun.com/j2se/1.4.1/download.html for more information.
1.
Go to the BlackBerry Developer Zone web site: http://www.blackberry.com/developers.
2.
Download the .zip file for the Mobile Data Service simulator to your computer.
3.
Right-click the .zip file.
4.
Click Extract to folder C:\...\MDS. An MDS folder is installed in the location that you selected.
8
BlackBerry Simulator
Setting up the simulators
Setting up the simulators Edit the run.bat file to specify the handheld and network type to simulate. By default, the simulator emulates the BlackBerry 6700 Series of wireless handhelds on a GPRS network.
Set the handheld type 1.
In the simpackage folder, right-click run.bat.
2.
Click Edit. The file opens in a text editor.
3.
After set rimos=, add the appropriate .dll file name: set rimos=Os6500.dll
4.
Save the file. Tip: Some simulator packages provide default batch files for each handheld type, such as runOs5800.bat, runOs6700.bat, and runOs6500.bat. Use these files if they are available so you do not have to edit the run.bat file.
Set the network type By the default, the simulator emulates a handheld on a GPRS network. To emulate a handheld running on a CDMA or iDEN™ network, you must set a command line option. 1.
In the simpackage folder, right-click run.bat file.
2.
Click Edit. The file opens in a text editor.
3.
After osloader %rimos%, add the /W option: •
/wc - CDMA networks
•
/wi - iDEN™ networks
•
/wg - GPRS networks
For example, to emulate a handheld operating on a CDMA network, add /wc: osloader %rimos% /wc /RegAddress=none /rsim=0x20000001 ... /rport=8205 jvm.dll
4.
Save the file. Tip: When you start the handheld simulator, the network type appears in the window title.
User Guide
9
1: Getting started
Set the resolution Add the /GRES option to set the resolution and color depth of the simulator LCD display. 1.
In the simpackage folder, right-click run.bat file.
2.
Click Edit. The file opens in a text editor.
3.
After osloader %rimos%, add /GRESxx16: For example, to emulate a BlackBerry 6200 Series handheld, add /GRES160x100x16: osloader %rimos% /GRES160x100x16 /RegAddress=none /rsim=0x20000001 ... jvm.dll
4.
Save the file.
Starting the simulators Start the handheld simulator 1.
In the simpackage folder, double-click run.bat. The handheld simulator appears. If a JVM error occurs, close the simulator. In the simpackage folder, delete the .dmp files and double-click run.bat again.
Start the Mobile Data Service simulator 1.
In the MDS folder, double-click load.bat. A command prompt window displays information about Mobile Data Service startup. If the Mobile Data Service starts successfully, the following message appears at the bottom of the command prompt window: INFO: Starting Coyote HTTP/1.1 on port 8080
Verify that the Mobile Data Service simulator is running 1.
In the handheld simulator, open the BlackBerry Browser. The browser appears. Tip: To select the BlackBerry Browser icon, roll the wheel button on your mouse, or press the UP ARROW or DOWN ARROW key. To open the application, click the mouse wheel button or press ENTER.
2.
Click the mouse wheel button (or press the RIGHT ARROW key). The browser menu appears.
3.
Click Go To. A dialog box appears.
4.
In the Go To field, type: http://www.blackberry.com/go/mobile/.
5.
Click OK. If the BlackBerry home page appears, the Mobile Data Service simulator is working correctly. If an error message indicates that the browser is unable to connect to the Mobile Data Service, verify that you started the Mobile Data Service simulator.
10
BlackBerry Simulator
2 Using the simulator This section provides information on the following topics: •
Using the simulator
•
Setting wireless coverage conditions
•
Using the phone
•
Simulating handheld operating conditions
•
Simulating flash memory
•
Simulating a desktop connection
2: Using the simulator
Using the simulator The handheld simulator displays a Home screen with icons for each application. When you select an icon, the name of the application appears at the bottom of the Home screen. Double-click an icon to open that application.
Phone button Trackwheel
Home screen
Escape button
Application title bar
Backspace key Alt key
Enter key Right Shift key
Left Shift key
BlackBerry handheld simulator for GPRS
Use the trackwheel The simulator trackwheel simulates the trackwheel on the handheld. Using the trackwheel, you can navigate, view, and select items on each screen in the simulator. You can roll the trackwheel to scroll through menu items or text, and click the trackwheel to select applications or menu options. If your mouse has a wheel button, simulate using the trackwheel as follows: •
To simulate rolling the trackwheel, roll the wheel button on your mouse.
•
To simulate clicking the trackwheel, click the wheel button.
12
BlackBerry Simulator
Using the simulator
If your mouse does not have a wheel button, simulate using the trackwheel as follows: •
To simulate rolling the trackwheel, left-click your mouse and drag the simulator trackwheel up or down, or press the UP ARROW or DOWN ARROW keys on your computer keyboard
•
To simulate clicking the trackwheel, right-click your mouse, or press the LEFT ARROW or RIGHT ARROW key on your computer keyboard.
Start an application 1.
In the simulator, roll the trackwheel to select an application icon. The title of the application appears at the bottom of the screen.
2.
Click the trackwheel. The application main screen appears.
3.
To open the application menu, click the trackwheel.
4.
To click a menu item, click the trackwheel.
5.
To return to the Home screen, click Close.
Use the keyboard To simulate pressing keys on the handheld, press the keys on your computer keyboard or use your mouse to click the keys on the simulator keyboard. Press ESC on your computer keyboard to simulate pressing the Escape key on the handheld. Press CTRL on the computer keyboard to simulate pressing the Alt key on the handheld.
Set the keyboard mode Your options for using the keyboard depend on the keyboard mode that is set for the simulator. 1.
In the simulator, on the Keyboard menu, click one of the following options: •
PC: In PC mode, you can type letters and numbers using the normal keys on your computer keyboard.
•
Handheld: In handheld mode, you can use only the keys on your keyboard that exist on the handheld. To type a number or symbol, hold CTRL and press the appropriate key on the computer keyboard. For example, on a BlackBerry 6700 Series handheld, to type 1, press CTRL+W.
In either mode, you can use your mouse to click keys on the simulator.
Set the display size 1.
In the simulator, on the Display menu, click one of the following options: •
Actual Size: uses the same number of pixels as on an actual handheld LCD
•
Large Display: uses a larger display with correct aspect ratios
User Guide
13
2: Using the simulator
Take screen shots You can save a bitmap image of the handheld simulator screen. The image size is the same as the resolution set on the simulator (the default is 160 by 160 pixels). 1.
In the simulator, on the Display menu, click Snapshot LCD. The Save Snapshot window appears.
2.
In the File name field, type a file name for the image.
3.
Select a folder.
4.
Click Save. The screen is saved.
Setting wireless coverage conditions 1.
In the simulator, on the Simulation menu, click Show Radio Simulation Control Panel. The Radio Simulation Control Panel appears.
Radio Simulation Control Panel
14
BlackBerry Simulator
Setting wireless coverage conditions
Configuring reception In the Radio Simulation Control Panel, the Reception section enables you to simulate different wireless network coverage conditions for receiving data.
Simulate wireless network coverage 1.
In the Radio Simulation Control Panel, select the In coverage option.
2.
Slide the coverage bar to control the received signal strength indicator (RSSI) reported to applications. The signal strength varies from –120 dBm to –50 dBm. A signal of -120 dBm is extremely weak, and the handheld typically loses coverage before reaching this number. A signal of -50 dBm is stronger than you are likely to see on the actual network.
Simulate loss of wireless network coverage In the Radio Simulation Control Panel, select the Out of coverage option. This option simulates the condition when a handheld is outside an area of sufficient wireless network coverage, and cannot receive or send data.
Configuring transmission In the Radio Simulation Control Panel, the Transmission section enables you to simulate different wireless network coverage conditions for sending data.
Simulate good wireless network coverage 1.
In the Radio Simulation Control Panel, select the All transmits succeed option. Selecting this option means that data is sent successfully from the handheld to the network. On an actual network, under good wireless network coverage conditions, almost all data is sent successfully.
Simulate network delays or user choice of transmission 1.
In the Radio Simulation Control Panel, select the Prompt for Tx success option. Selecting this option means that every time the simulator sends data to the network, you are prompted to select whether the data is transmitted successfully. The data is pending until you select Yes or No. You can use this mode to simulate very long transmission delays.
User Guide
15
2: Using the simulator
Simulate intermittent wireless network coverage 1.
In the Radio Simulation Control Panel, select the Random success option.
2.
Use the slide bar to set the probability with which data is sent successfully from the handheld. The delay for successful packets is about one and a half seconds. The delay for unsuccessful packets is three seconds (unsuccessful transmission attempts typically take longer than successful transmission attempts).
Using the phone On the BlackBerry 6700 Series handheld simulator, press the PAGE UP key on your computer keyboard to simulate pressing the Phone button on the handheld. On the BlackBerry 6500 Series handheld simulator, press the PAGE UP key on your computer keyboard to simulate pressing the PTT™ (Push-to-Talk™) button.
Simulate voice calls 1.
In the simulator, on the Simulation menu, click Show Voice Simulation Control Panel. The Voice Simulation Control Panel window appears.
Voice Simulation Control Panel
16
BlackBerry Simulator
Using the phone
2.
Select one of the following options: •
To simulate making a voice call to the handheld, click Create. The call appears in the Current Calls list. The handheld simulator displays a message that there is an incoming call, which you can then answer, answer and hold, or ignore.
•
To disconnect a call, click Disconnect. To simulate the failure of a call, from the drop-down list beside the Fail button, select a reason for the failure. Click Fail.
In the simulator, you can use the Phone application to simulate making a voice call. This call appears in the Current Calls list in the voice simulation control panel. Click Accept to simulate answering the call.
Simulate SIM card changes 1.
In the simulator, on the Simulation menu, click Show Voice Simulation Control Panel. The Voice Simulation Control Panel appears. The SIM section displays information on the current SIM card that is simulated.
2.
To simulate removing the SIM card from the handheld, click Remove. When the SIM card is removed, you can change information, such as adding voice mail phone numbers.
3.
To simulate inserting a SIM card, click Insert.
Enable supplementary services You can simulate a variety of supplementary voice services, including call barring, caller ID, and call forwarding. 1.
In the simulator, on the Simulation menu, click Show Supplementary Service Control Panel. The Supplementary Services Option window appears.
Supplementary Services Option window
User Guide
17
2: Using the simulator
2.
In the Network Option section, select one of the following check boxes: Check box
Description
Forwarding
simulates the handheld forwarding calls to specific phone numbers
Outgoing Barring
simulates the handheld ignoring outgoing phone calls
Incoming Barring
simulates the handheld ignoring incoming phone calls
Call ID Restriction
simulates the handheld preventing the caller's phone number from appearing on outgoing calls
Mobile not reachable
simulates the handheld outside of a wireless network coverage area
Mobile Roaming
simulates the handheld roaming on another wireless network
Simulating handheld operating conditions You can simulate various conditions that affect the operation of the handheld.
Simulate battery conditions You can simulate the status of the handheld battery. 1.
In the simulator window, on the Simulation menu, click one of the following options: Option
Description
Good Battery
battery power is sufficient for handheld and network use
Low Battery
battery power is too low to use the network, but the handheld is on
Dead Battery
handheld is off
Charging
handheld battery is charging
Simulate holster conditions You can simulate the handheld either in or out of the holster. When the handheld is in the holster, the screen display turns off. 1.
In the simulator, on the Simulation menu, click In holster or Out of holster.
Enable backlighting 1.
18
Press the PAGE DOWN key on your computer keyboard. Backlighting remains on for 20 seconds.
BlackBerry Simulator
Simulating flash memory
Simulating flash memory The simulator uses a .dmp file to simulate flash memory. When the simulator starts, it loads the flash memory contents from the .dmp file, or creates a .dmp file if one does not already exist. When the simulator exits, it saves flash memory contents to the .dmp file. A separate .dmp file is maintained for each handheld type. The file name is FS.dmp, where is the handheld series number, such as 5800, 6500, or 6700. The flash memory size is specified using the /F command line option.
Simulate resetting a handheld When the handheld is reset, flash memory is cleared. You can simulate this situation. 1.
In the simpackage folder, delete the FS.dmp file.
2.
Restart the simulator.
Simulating a desktop connection You can simulate a serial connection between the handheld and the BlackBerry Desktop Software. Note: The simulator supports serial port connections only. The simulator does not support USB connections.
1.
Exit the BlackBerry Desktop Software.
2.
Connect a null modem cable between COM port 1 and COM port 2 on your computer.
3.
In the simpackage folder, right-click run.bat.
4.
Click Edit. The file appears in a text editor.
5.
Before jvm.dll, add the /S1 option: osloader %rimos% ... /F8192 /H577592 /rport=19780 /rport=8205 /S1 jvm.dll
6.
Save the file.
7.
Start the simulator.
8.
Start the BlackBerry Desktop Software.
9.
In the BlackBerry Desktop Software, on the Options menu, click Connection Settings.
10. Click Detect. A message indicates that a handheld was found. The BlackBerry Desktop Manager is now connected to the simulator. If the BlackBerry Desktop Software does not detect the simulator, restart your computer and repeat steps 6 through 9. User Guide
19
2: Using the simulator
20
BlackBerry Simulator
3 Simulator options This section provides information on the following topics: •
Handheld simulator options
•
Mobile Data Service simulator options
3: Simulator options
Handheld simulator options 1.
In the simpackage folder, right click run.bat.
2.
Click Edit. The file appears in a text editor.
3.
Before jvm.dll, add options: osloader %rimos% /RegAddress=none /rsim=0x20000001 /F8192 /H577592 /rport=19780 /rport=8205 [options] jvm.dll
The following table describes the command line options for the handheld simulator. Option
Description
/APP
Set /APP=JvmEnableSecurity to set the simulator to securemode.
/B
Disable sound card.
/D
Use sectors of flash memory for file system data storage.
/E
Erase the flash memory allocation log.
/F
Simulate kilobytes of flash memory.
/GRES
Set resolution and color depth of the simulated LCD, in the following format: /GRES=xx.
/L- /L+
Turn on (L+) or turn off (L-) flash memory timing simulation.
/LN
Turn off flash memory protection.
/localtime
Specify that the simulator should return local time when applications invoke time-related methods.
/N
Delete the flash file memory system before initialization.
/RDISABLESMS
Disable SMS support in the simulator.
/REGADDRESS
Enable or disable a registration server.
/ROFF
Turn off the radio on simulator startup.
/RPHONE
Set a SIM phone number.
/RPORT
Set the handheld socket for network communication.
/RSIM
Set the simulator personal identification number (PIN).
/RSMS
Specify an SMS server and simulator ports for sending and receiving SMS messages.
/S
Specify a desktop computer serial port to use.
/SMALL
Enable the IDE to launch the simulator's LCD screen to actual size.
/W
Specify the type of network to simulate: /wc - CDMA networks /wi - iDEN™ networks /wg - GPRS networks
22
BlackBerry Simulator
Mobile Data Service simulator options
Mobile Data Service simulator options 1.
In the MDS\config folder, open the rimpublic.property file in a text editor.
2.
Edit parameters to configure the following features:
3.
•
logging
•
HTTP support
•
HTTPS support
•
push support
•
email-to-PIN mappings
Restart the Mobile Data Service simulator for changes to take effect.
Logging Parameter
Description
Default
Logging.level
Specify the type of information that is logged, if logging is enabled. 1: events, such as starting and stopping 2: events + errors 3: events + errors + warnings 4: events+errors + warnings + debug
Logging.console.log.level
Specify the type of information that appears in the console, if logging 4 is enabled. Refer to the description for the Logging.level parameter.
application.handler.http.logging
Set to TRUE or FALSE to enable or disable HTTP standard logging (HTTP TRUE headers only).
application.handler.http.logging. verbose
Set to TRUE or FALSE to enable or disable HTTP debug logging (HTTP data and headers). This parameter should be set to TRUE only when necessary to debug a specific problem.
FALSE
application.handler.http.logging
Set to TRUE or FALSE to enable or disable HTTPS logging.
TRUE
User Guide
4
23
3: Simulator options
HTTP support Parameter
Description
Default
application.handler.http. CookieSupport
Set to TRUE or FALSE to enable or disable cookie storage. If you select TRUE, the Mobile Data Service manages cookie storage instead of the handheld. This reduces the load on the handheld significantly.
application.handler.http.
Set to TRUE or FALSE to enable or disable storage of user authentication TRUE information.
AuthenticationSupport application.handler.http. AuthenticationTimeout
TRUE
If HTTP authentication is set to TRUE, this parameter determines the 3600000 length of time (in milliseconds) before the authentication information becomes invalid. This timer resets whenever the user issues a request that invokes the authentication information for a particular domain.
application.handler.http. device.connection.timeout
This parameter sets the length of time (in milliseconds) before a connection attempt to the handheld expires if the handheld is unreachable.
140000
application.handler.http. server.connection.timeout
This parameter sets the length of time (in milliseconds) before a connection attempt to a server expires if the server is unreachable.
150000
HTTPS support Parameter application.handler.https. allowUntrustedServer
Description
Default
Set to TRUE to allow the Mobile Data Service to connect to untrusted servers or FALSE to restrict access to trusted servers only. A server is trusted if its certificate is installed on the Mobile Data Service host machine.
FALSE
Push support The following parameters are related to Mobile Data Service support for push applications. You typically should not change these parameters. Parameter
Description
Default
WebServer.listen.host
This parameter defines the computer on which the Mobile Data Service localhost listens for HTTP POST requests from push applications.
WebServer.listen.port
This parameter defines the port on which the Mobile Data Service listens for HTTP POST requests from push applications.
24
8080
BlackBerry Simulator
Mobile Data Service simulator options
Email-to-PIN mapping To test push applications, map the simulator PIN to the email addresses that the push application uses. 1.
In the rimpublic.property file, add or change entries in the [Simulator] section. Entries have the following format: Simulator.=:,
The following default entry maps PIN 2100000a to email address
[email protected]: Simulator.2100000a=localhost:81,
[email protected]
2.
Change the email address, if necessary, so that when a push application sends data to that email address, it is sent to the simulator. Note: The default PIN for the simulator is 2100000a. The PIN is set using the /rsim simulator option.
User Guide
25
3: Simulator options
26
BlackBerry Simulator
©2003 Research In Motion Limited Published in Canada.
