Blackberry Smart Phone Simulator Development Guide 1640741 0916031807 001 7.0 US

BlackBerry Smartphone Simulator
Version: 7.0
Development Guide
Published: 2011-08-03 SWD-1640741-0916031807-001
Contents
1 BlackBerry Smartphone Simulator.................................................................................................................... Overview........................................................................................................................................................... 2 Starting the BlackBerry Smartphone Simulator................................................................................................ Start the BlackBerry Smartphone Simulator..................................................................................................... 3 Using the BlackBerry Smartphone Simulator.................................................................................................... Simulating touch screen input.......................................................................................................................... Sending input from the computer.................................................................................................................... Simulating trackball input................................................................................................................................. Simulating trackwheel input............................................................................................................................. Simulate a convenience key.............................................................................................................................. Simulate a multi-function key........................................................................................................................... Changing the BlackBerry smartphone orientation........................................................................................... Change screen orientation........................................................................................................................ Simulate tilting a BlackBerry device in 3-D space...................................................................................... View the event log............................................................................................................................................ View messages from the JVM........................................................................................................................... 4 Testing applications using the BlackBerry Smartphone Simulator................................................................... Load an application for testing......................................................................................................................... Testing GPS applications................................................................................................................................... Testing JavaScript and webpages..................................................................................................................... Test MIDlets...................................................................................................................................................... Testing BlackBerry Enterprise Server APIs and IT policies................................................................................ Test a BlackBerry Smartphone Simulator with a BlackBerry Enterprise Server........................................ Configuring the BlackBerry MDS Simulator and the BlackBerry Smartphone Simulator for BlackBerry Messenger........................................................................................................................................................ 5 BlackBerry Device Software applications.......................................................................................................... Using the camera.............................................................................................................................................. Viewing a picture....................................................................................................................................... Take a picture............................................................................................................................................ Delete a picture......................................................................................................................................... Picture resolutions..................................................................................................................................... Recording video................................................................................................................................................ Set video recording options....................................................................................................................... Using the phone application............................................................................................................................. 5 5 6 6 8 8 9 9 10 11 11 11 12 12 12 12 13 13 13 14 14 14 14 15 16 16 16 16 16 16 17 17 17
Simulate an incoming call.......................................................................................................................... Simulate an outgoing call.......................................................................................................................... Using voice dialing..................................................................................................................................... 6 Changing BlackBerry Smartphone Simulator display options........................................................................... Magnify the BlackBerry device image............................................................................................................... Hide the faceplate............................................................................................................................................. Turn full-screen mode on and off..................................................................................................................... Specify graphics acceleration............................................................................................................................ Taking screen shots........................................................................................................................................... Save a screen shot..................................................................................................................................... Copy a screen shot to the clipboard.......................................................................................................... 7 Changing BlackBerry device operating conditions............................................................................................ Use a single-button headset............................................................................................................................. Use a multibutton headset............................................................................................................................... Disconnect a headset........................................................................................................................................ Change holster conditions................................................................................................................................ Close a flip screen............................................................................................................................................. Open or close a sliding BlackBerry device......................................................................................................... Simulate battery conditions.............................................................................................................................. Simulate the absence of a SIM card.................................................................................................................. Simulating network conditions......................................................................................................................... Add a network........................................................................................................................................... Set the network signal strength................................................................................................................. Specify the rescan interval for a Wi-Fi network connection...................................................................... Simulate supplementary phone services.......................................................................................................... How the BlackBerry Smartphone Simulator simulates application storage..................................................... Clear the application storage..................................................................................................................... Simulating BlackBerry Enterprise Server APIs and IT policies........................................................................... Using the BlackBerry Smartphone Simulator in secure mode.......................................................................... Enable secure mode.................................................................................................................................. Connecting to Bluetooth USB accessories........................................................................................................ Simulating a USB connection to the computer................................................................................................. Simulate a USB connection to the computer............................................................................................ Simulating a media card................................................................................................................................... Simulate a media card with a folder.......................................................................................................... Format of a simulated media card.............................................................................................................
17 18 18 19 19 19 19 19 19 20 20 21 21 21 21 21 22 22 22 22 22 23 23 23 23 24 24 24 24 25 25 25 25 26 26 26
8 Using GPS and Location Based Services............................................................................................................ Simulating GPS location information................................................................................................................ Add a GPS location.................................................................................................................................... Change a GPS location............................................................................................................................... Delete a GPS location................................................................................................................................ Managing GPS routes........................................................................................................................................ Create a GPS route by using existing locations.......................................................................................... Create a GPS route by using NMEA 0183 sentences................................................................................. Create a GPS route by using a random set of your locations.................................................................... Change a GPS route................................................................................................................................... Delete a GPS route.................................................................................................................................... Simulate a GPS route................................................................................................................................. 9 Testing NFC applications................................................................................................................................... Testing NFC applications on the BlackBerry Smartphone Simulator................................................................ Setting up the NFC Controller Simulator.......................................................................................................... Set the NFC parameters.................................................................................................................................... Command prompt parameters related to NFC................................................................................................. Test an NFC application.................................................................................................................................... 10 Simulating magnetometer information............................................................................................................ Magnetometer.................................................................................................................................................. Displaying magnetometer information............................................................................................................ Create or edit a magnetic path......................................................................................................................... Change the smartphone orientation in a key............................................................................................ Change the magnetic flux information in a key......................................................................................... Play back the current magnetic path......................................................................................................... Load a magnetic path file.......................................................................................................................... Save the current magnetic path................................................................................................................ Display rotation in the BlackBerry Smartphone Simulator window................................................................. 11 Testing applications that require an HTTP connection..................................................................................... Testing push applications................................................................................................................................. Map the internet messaging address to the BlackBerry Smartphone Simulator PIN................................ Change the BlackBerry Smartphone Simulator PIN................................................................................... Testing messaging applications........................................................................................................................ BlackBerry Email Simulator........................................................................................................................ Send a message......................................................................................................................................... Receive a message.....................................................................................................................................
28 28 28 28 28 29 29 29 29 30 30 30 32 32 32 32 33 34 35 35 35 36 37 37 38 38 39 39 40 40 40 40 41 41 41 41
12 Using the BlackBerry Smartphone Simulator programmatically...................................................................... Using test scripts............................................................................................................................................... Start the BlackBerry Smartphone Simulator controller tool............................................................................. Syntax for the BlackBerry Smartphone Simulator controller tool............................................................. Send commands to the BlackBerry Smartphone Simulator.............................................................................. Test BlackBerry Smartphone Simulator events by using a script...................................................................... Close the BlackBerry Smartphone Simulator controller tool session............................................................... See a list of BlackBerry Smartphone Simulator commands.............................................................................. Accessory commands....................................................................................................................................... Application commands..................................................................................................................................... Network and phone commands....................................................................................................................... Application environment and GPS commands................................................................................................. Keyboard and event commands....................................................................................................................... IT policy commands.......................................................................................................................................... 13 Troubleshooting................................................................................................................................................ The BlackBerry Smartphone Simulator takes a long time to start.................................................................... I have a JVM error 543...................................................................................................................................... Files for the BlackBerry Smartphone Simulator................................................................................................ The location of user settings............................................................................................................................. 14 Glossary............................................................................................................................................................ 15 Provide feedback.............................................................................................................................................. 16 Legal notice.......................................................................................................................................................
42 42 42 43 43 44 45 45 45 46 47 49 51 53 55 55 55 55 56 57 60 61
Development Guide

Overview
The BlackBerry Smartphone Simulator includes the BlackBerry device applications that are typically available on BlackBerry devices. The simulator enables you to load and test your own applications. You can simulate and test various connectivity and state changes by using the BlackBerry Smartphone Simulator. The BlackBerry Smartphone Simulator can run BlackBerry device applications on your computer. When you use the BlackBerry Smartphone Simulator to perform testing, you might need to simulate BlackBerry services, such as email delivery or web access, without connecting to a BlackBerry Enterprise Server. The BlackBerry Email Simulator provides email delivery. The BlackBerry MDS Simulator provides Internet access for push applications. The BlackBerry MDS Simulator also provides web access and GPS access for simulating BlackBerry devices that are running BlackBerry 6 or earlier. Both simulators are in the BlackBerry Email and MDS Services Simulator Package.
Development Guide
Starting the BlackBerry Smartphone Simulator
Starting the BlackBerry Smartphone Simulator

The BlackBerry Smartphone Simulator is available either as a part of the BlackBerry Java Development Environment or as a standalone installation of the BlackBerry simulator package. Visit www.blackberry.com/ developers for more information about downloading the BlackBerry Smartphone Simulator.
Start the BlackBerry Smartphone Simulator

For information about starting the BlackBerry Smartphone Simulator from a plug-in, see the documentation for that plug-in. Before you begin: Download and install the BlackBerry Smartphone Simulator. To start the BlackBerry Smartphone Simulator, perform one of the following tasks: Task Start the BlackBerry Smartphone Simulator from the Windows taskbar. Start the BlackBerry Smartphone Simulator from the command prompt with the supplied batch file. Steps On the taskbar, click Start > All Programs > Research In Motion > BlackBerry Smartphone Simulators x.x.x > software_bundle_number > device_name. a. At the command prompt, navigate to the folder that contains the version of the BlackBerry Smartphone Simulator that you want to start. At the command prompt, type:
<model_number>.bat
b.
Start the BlackBerry Smartphone Simulator from the command prompt.
a.
At the command prompt, navigate to the folder that contains the version of the BlackBerry Smartphone Simulator that you want to start. At the command prompt, type:
fledge /app-Jvm.dll /handheld=<model_number>
b. Start the BlackBerry Smartphone Simulator from the command prompt and open a specified file for debug messages.
a.
At the command prompt, navigate to the folder that contains the version of the BlackBerry Smartphone Simulator that you want to start. At the command prompt, type:
fledge /handheld=<model_number> /appparam=JvmDebugFile<file_name>
b.
Development Guide
Start the BlackBerry Smartphone Simulator
Task Start the BlackBerry Smartphone Simulator from the command prompt and open a specified webpage.
Steps a. b. If you are using a BlackBerry Smartphone Simulator earlier than 6.1, start the BlackBerry MDS Simulator. At the command prompt, navigate to the folder that contains the version of the BlackBerry Smartphone Simulator that you want to start. At the command prompt, type:
fledge /handheld=<model_number> /appparam=url:<URL> /app=jvm.dll
c.
Development Guide
Using the BlackBerry Smartphone Simulator
Using the BlackBerry Smartphone Simulator

Simulating touch screen input
When you simulate input for a touch screen BlackBerry device on the BlackBerry Smartphone Simulator all commands use the mouse. BlackBerry Device Software versions 4.71 to 5.1 4.7.1 and later
Gesture to simulate Click the screen. Drag a finger.
Steps Move the pointer to the simulated screen and click the left mouse button. 1. 2. 3. On the simulated screen, click either mouse button down and hold it. Move the pointer. Release the mouse button. Click and hold the left or right mouse button. Quickly move the pointer in the desired direction.
Swipe across the screen. Tap the screen. Double-tap the screen. Pinch open or pinch closed.
4.7.1 and later
1. 2.
6.0 and later 6.0 and later 4.7.1 and later
3. Release the mouse button. With the left or right mouse button, click a spot on the simulated screen. With the left or right mouse button, double-click a spot of the simulated screen. 1. 2. 3. On the Simulate menu, click Multitouch Mode. With the left or right mouse button, click and drag anywhere within the simulated screen area. Perform the same action elsewhere on the screen.
Touch the screen. Touch and hold screen. Touch an item. Touch the screen in two locations at the same time.
4.71 to 5.1 6.0 and later
After you complete the second action, both touches are simulated as if they were done at the same time. Click with the right mouse button on the simulated screen. 1. On the simulated screen, click the left or right mouse button and hold it.
4.71 to 5.1 4.7.1 and later
2. Release the mouse button. Right-click the mouse button on the item. 1. 2. 3. On the Simulate menu, click Multitouch Mode. With the left or right mouse button, click anywhere within the simulated screen area. Perform the same action elsewhere on the screen.
Development Guide
Sending input from the computer
Gesture to simulate
BlackBerry Device Software versions
Steps After you complete the second action, both touches are simulated as if they were done at the same time.
Sending input from the computer

Action Using the trackpad in an application Keyboard mapping 1. 2. Press F12 to activate the trackpad. Move your mouse over the BlackBerry Smartphone Simulator window.
Performing a trackpad click Navigating the Home screen Using the Back button Typing Increasing the volume Decreasing the volume Accessing the Phone application Ending a phone call Using alternate characters Muting the smartphone Locking the smartphone Inserting a currency symbol
3. Move your mouse in the direction you want to scroll. To deactivate the trackpad, press F12 again. Make sure that you have activated the trackpad, then press F9 or click the wheel on your mouse. Press UP or DOWN, or roll the scroll wheel on your mouse. Press the ESC key, or right-click with your mouse. Use the keyboard. Press PLUS SIGN. Press MINUS SIGN. Press PGUP. Press END. Press CTRL. Press F7 to toggle between muted and unmuted. Press F6 to toggle between locked and unlocked. Press F5.
Simulating trackball input

On a BlackBerry Smartphone Simulator for a BlackBerry device with a trackball, you can use a keyboard and mouse to simulate BlackBerry device functionality. Note that rolling the mouse wheel does not generate trackball rolls. Input Keyboard Turn trackball Press F12. mode on or off. Mouse with trackball mode on Mouse with trackball mode off 1. On the Edit menu, click 1. Map Middle Mouse Button > Toggle Trackball Mode. On the Edit menu, click Map Middle Mouse Button > Toggle Trackball Mode.
Development Guide
Simulating trackwheel input
Input
Keyboard
Mouse with trackball mode on Mouse with trackball mode off 2. Click the middle mouse button. Click the left mouse button. Click the middle mouse button. On the trackball in the simulator, click the middle mouse button. On the trackball in the simulator, click and drag the mouse. On the trackball in the simulator, click the right mouse button. 2.
Click the trackball. Roll the trackball. Press the Escape button.
Press F9.
Press the arrow keys.
Move the mouse.
Press ESC.
Click the right mouse button.
Simulating trackwheel input

The BlackBerry Smartphone Simulator assigns BlackBerry device functionality to the following computer keyboard and mouse procedures. Some procedures are not supported on all BlackBerry devices. Input Roll the trackwheel. Click the trackwheel. Press the Escape key. Turn on BlackBerry device backlighting. Press the Symbol key. Keyboard Press the UP ARROW or DOWN ARROW key. Press the LEFT ARROW key. Press ESC or the RIGHT ARROW key. Press PAGE DOWN. Mouse Roll the mouse wheel button. Click the mouse wheel button. Click the right mouse button. Click the Power button on the BlackBerry Smartphone Simulator keyboard. Click the Symbol key on the BlackBerry Smartphone Simulator keyboard. Click the Alt key on the BlackBerry Smartphone Simulator keyboard. Click the keys on the BlackBerry Smartphone Simulator keyboard.
Press DELETE.
Press the Alt key. Press the BlackBerry device keys. Press the phone/PTT (Push to Talk) button.
Press CTRL. Press the keys on your computer keyboard. Press PAGE UP.
10
Development Guide
Simulate a convenience key
Simulate a convenience key

Some keys that are present on BlackBerry devices are not present on computer keyboards. The BlackBerry Smartphone Simulator uses other keyboard keys to represent those BlackBerry keys. Perform one of the following tasks: Task Act as the Front Convenience key. Act as the Side Convenience key. Act as the Currency symbol key. Act as the Speaker phone key. Steps Press INSERT. Press PAGE UP. Press F5. Press F6.
Simulate a multi-function key

Some keys that are present on BlackBerry devices are not present on computer keyboards. The BlackBerry Smartphone Simulator uses other keyboard keys to represent those BlackBerry device keys. Perform one of the following tasks: Task Act as the Front Convenience key. Act as Menu key. Act as Right Side Convenience key. Act as Left Side Convenience key. Act as Volume Up key. Act as Volume Down key. Steps Press I. Press INSERT. Press \. Press PAGE UP. Press F8. Press F7.
Changing the BlackBerry smartphone orientation

BlackBerry smartphones with touch screens support displaying screen information in either landscape or portrait mode, depending on how the physical smartphone is oriented. Orientation mode Top-Side-Up Left-Side-Up Right-Side-Up Bottom-Side-Up Description The smartphone is oriented normally. The smartphone is rotated 90 degrees to the right. The smartphone is rotated 90 degrees to the left. The smartphone is rotated 180 degrees, upside-down.
11
Development Guide
View the event log
Orientation mode Front-Side-Up Back-Side-Up
Description The smartphone screen is facing upward. The smartphone screen is facing downward.
Change screen orientation

Use the BlackBerry Smartphone Simulator to simulate a screen orientation change. 1. 2. On the Simulate menu, click Tilt BlackBerry. Select an orientation mode for the BlackBerry screen.
Simulate tilting a BlackBerry device in 3-D space

You can use the tilt feature to view the rotation and tilt of a BlackBerry device in 3-D space. Before you begin: Verify that you have the following components installed on your computer: 1. 2. 3. 4. video card that supports OpenGL 1.1 or later BlackBerry Smartphone Simulator 2.13 or later for a BlackBerry device with an accelerometer On the Simulate menu, click Tilt BlackBerry. Place the mouse pointer at a corner of the device. The mouse pointer changes to an image of a device. To rotate and tilt the device, press and hold the left mouse button while moving the mouse. To stop rotating and tilting the device, release the mouse button.
View the event log

The event log window displays information about events that occur between a simulated BlackBerry smartphone and its environment. The BlackBerry Smartphone Simulator logs event messages for events including when you simulate playing audio files, placing a phone call, and blinking the light. From the Tools menu, click Show Event Log.
View messages from the JVM

The BlackBerry Smartphone Simulator can display the standard.out and standard.err streams of messages that the BlackBerry Java Virtual Machine sends. On the Tools menu, click Show Output Log.
12
Development Guide
Testing applications using the BlackBerry Smartphone Simulator
Testing applications using the BlackBerry Smartphone Simulator

Load an application for testing
Perform one of the following tasks: Task Load an application while the BlackBerry Smartphone Simulator is running. Steps a. b. c. d. e. Load an application while the BlackBerry Smartphone Simulator is running. Load an application by file placement when starting the BlackBerry Smartphone Simulator. Load an application by using the BlackBerry Java Plug-in for Eclipse. Load an application by using the BlackBerry WebWorks Plug-in for Eclipse. a. b. a. b. c. Compile the application as a .cod file. On the File menu, click on Load Theme or Application. Click the .cod file that contains the application. Click OK.
If your application consists of multiple .cod files, repeat steps 1 to 4 for each file. Compile the application as a .cod file. On the desktop, drag the .cod file to the BlackBerry Smartphone Simulator. Compile the application as a .cod file. Copy the .cod file into the BlackBerry Smartphone Simulator folder. Start the BlackBerry Smartphone Simulator. In Eclipse Package Manager, right-click the folder that contains the application and select Run As > Simulator or Debug As > Simulator. In the Eclipse Package Manager, right-click the folder that contains the application and select Run As > Simulator or Debug As > Simulator.
Testing GPS applications

You can test GPS applications using the BlackBerry Smartphone Simulator. A GPS application on the BlackBerry Smartphone Simulator can access GPS data such as the direction, the speed, and the number of visible satellites (satellites provide GPS information). The GPS feature in the BlackBerry Smartphone Simulator should function the same as when the GPS application runs on a BlackBerry smartphone. The currently simulated location determines the number of satellites that are visible. When you create a new location, the value you specify in the Visible satellites field becomes the default value for that field. Most locations are visible to four satellites or more.
13
Development Guide
Testing JavaScript and webpages
Testing JavaScript and webpages

If you use the BlackBerry Smartphone Simulator version earlier than 6.0, you must save a webpage as a BlackBerry WebWorks application to test its appearance. If you use the BlackBerry Smartphone Simulator 6.0 or later, the BlackBerry Browser can interpret a webpage and any JavaScript on it. With the BlackBerry Browser, you can load a file from a web server. With the Files icon, you can load a file directly from a simulated media card.
Test MIDlets
If the MIDlet is contained in .jad and .jar files, you need to convert these files to a .cod file before loading the .cod file to the BlackBerry Smartphone Simulator. You can use the BlackBerry MDS Simulator to convert the .jad and .jar files to a .cod file. 1. 2. 3. 4. 5. 6. Place the .jad and .jar files on a web server. Start the BlackBerry MDS Simulator. Start the BlackBerry Smartphone Simulator. On the BlackBerry Smartphone Simulator screen, click the Browser icon. Use the browser to navigate to the location of the application .jad file. Download the .jad file to the BlackBerry Smartphone Simulator.
After you finish: The BlackBerry Smartphone Simulator will automatically load the .cod file on start up. See the BlackBerry Java Development Environment Development Guide for more information about converting .jad and .jar files.
Testing BlackBerry Enterprise Server APIs and IT policies

The BlackBerry Smartphone Simulator can connect to an account on the BlackBerry Enterprise Server. If you have access to a BlackBerry Enterprise Server, you can simulate all the functionality that is available when connecting a BlackBerry device to a BlackBerry Enterprise Server. Use this option to simulate use of the BlackBerry Enterprise Server Extension Application Programming Interface (API), and applied IT policies. This option requires knowledge of BlackBerry Enterprise Server administration, and introduces network dependency to testing. You will not require a BlackBerry MDS Simulator or an BlackBerry Email Simulator.
Test a BlackBerry Smartphone Simulator with a BlackBerry Enterprise Server

Before you begin: The BlackBerry Enterprise Server that you have an account on is running. 1. Start the BlackBerry Smartphone Simulator.
14
Development Guide
Configuring the BlackBerry MDS Simulator and the BlackBerry Smartphone Simulator for BlackBerry Messenger
2. 3. 4. 5. 6. 7.
On the Home screen, click the Turn Wireless Off icon. From the taskbar, click Start > Programs > BlackBerry > BlackBerry Desktop Software. From the BlackBerry Smartphone Simulator taskbar, click Simulate > USB Cable Connected. In the BlackBerry Desktop Software, click Get started with this device. Follow the instructions to generate a new encryption key. If the Initial Plug-in: Verifying Applications dialog box appears, click Cancel.
After you finish: When the initial synchronization with the computer is complete, the enterprise activation starts. After the enterprise activation, you can simulate use of the BlackBerry Enterprise Server Extension API, applied IT policies, email traffic, browser traffic, HTTP/TCP connections, BlackBerry Application Mobility Suite, and push functionality.
Configuring the BlackBerry MDS Simulator and the BlackBerry Smartphone Simulator for BlackBerry Messenger
To test a BBM connected application on a BlackBerry Smartphone Simulator, you must install and configure the BlackBerry MDS Simulator and the BlackBerry Smartphone Simulator with settings that enable communication between the BlackBerry MDS Simulator and two instances of the BlackBerry Smartphone Simulator. To learn how to configure the simulators for BBM, see the BlackBerry Messenger Getting Started Guide.
15
Development Guide
BlackBerry Device Software applications
BlackBerry Device Software applications

Using the camera
Make sure your webcam is connected and functioning properly. If the BlackBerry Smartphone Simulator does not detect a connected webcam, a prompt appears and you can select a picture file from your hard drive.
Viewing a picture
When an application switches to camera viewfinder mode, the viewfinder of BlackBerry Smartphone Simulator displays an image. If you have a webcam connected to your computer, the image is the one that your webcam sends. If you do not have a webcam connected, the viewfinder of the BlackBerry Smartphone Simulator displays the picture that you select by using the Camera Image menu item. If no picture is selected before and there is no webcam, the viewfinder displays the file selector. You can select an image of equal or greater resolution than the cameras maximum resolution. If you select a picture with a higher resolution or different aspect ratio than the camera, the Camera application displays only the center of the picture. If the picture is larger than the device screen, the image is resized. If you choose Camera Pan mode from the Simulate menu, it is not resized but the touch screen is used to navigate the picture until you leave the Camera application or turn off Camera Pan mode. The last picture that you select becomes the default picture that is displayed the next time you start the BlackBerry Smartphone Simulator.
Take a picture
1. 2. 3. 4. Click the Camera icon. If prompted, to save pictures to the media card on the BlackBerry Smartphone Simulator, click Yes. To save pictures to the BlackBerry Smartphone Simulator device memory, click No. To take a picture, click the trackball. To take another picture, click Take Another Picture.
Delete a picture
1. 2. Click Delete Picture. Click Delete to confirm.
Picture resolutions
The maximum resolution of the camera differs on BlackBerry device models. Each version of the BlackBerry Smartphone Simulator supports the highest resolution that the associated version of the BlackBerry Device Software supports.
16
Development Guide
Recording video
BlackBerry Device Software version 4.2 5.x 6.0
Resolution in pixels 1280 x 1024 (1.3 megapixels) 2048 x 1536 (3.2 megapixels) 2560 x 1920 (5.0 megapixels)
Recording video
Before you being, ensure that your webcam is connected and functioning properly. If the BlackBerry Smartphone Simulator does not detect a connected webcam, a prompt appears and you can select a jpeg file from your hard drive. You can then click on the LCD an drag the image around to record the movements as a video.
Set video recording options

1. 2. 3. 4. Click the Video Camera icon. Click the Menu key. Click Options. Perform any of the following actions: Task Set the video light. Set the color effect Set the video resolution. Steps Specify the Video Light option. Specify the Color Effect option. Specify the Video Format action.
Using the phone application

Simulate an incoming call
The procedure outlined can generate either a failed call or a successful one. 1. 2. 3. On the Simulate menu, click Incoming Voice Call. In the New Incoming Call dialog box, for the originating phone number, type a new phone number or the phone number of an existing contact. Set one of the following Caller ID options: Option Allowed Private Description The BlackBerry smartphone can display the phone number of the originating phone. The phone number of the originating phone is blocked and not available for display on the BlackBerry smartphone.
17
Development Guide
Using the phone application
Option Unknown 4. 5. 6.
Description The BlackBerry smartphone cannot determine the phone number of the originating phone.
To place the phone call to the BlackBerry Smartphone Simulator, click Create Call. Click Answer or Ignore. End the call by performing one of the following actions: Task Steps Simulate the termination of the call by the originating Click Disconnect. phone. Simulate a network failure. a. Set a reason for failure. b. Click Fail.
Simulate an outgoing call

1. 2. 3. 4. 5. 6. 7. Open Call Log. In the Call Log menu, click Call From Address Book. In the Call field, type a new phone number or set a contact. Press the Enter key. Open the menu. Click Continue. In the Call to dialog box, perform one of the following actions: Click Answer. To simulate a failed connection, set a reason for failure. Click Fail.
Using voice dialing

To use the voice dialing feature of the BlackBerry device in the BlackBerry Smartphone Simulator, your computer must have a microphone. After the microphone is connected to your computer, the voice dialing feature of the BlackBerry Smartphone Simulator works in the same way as the feature on the BlackBerry device.
18
Development Guide
Changing BlackBerry Smartphone Simulator display options
Changing BlackBerry Smartphone Simulator display options

Magnify the BlackBerry device image
1. 2. 3. On the View menu, click Zoom. Click a percentage. On the View menu, click Smooth Magnified LCD.
Hide the faceplate

By default, the BlackBerry Smartphone Simulator displays the BlackBerry device faceplate. You can hide the faceplate so that only the device screen is visible. On the View menu, click LCD Only.
Turn full-screen mode on and off

If the BlackBerry Smartphone Simulator is in full-screen mode, point to the top of the computer screen. The menu bar appears when the pointer is near the top of the screen. On the View menu, click Full Screen.
Specify graphics acceleration

By default, graphics acceleration is turned on in the BlackBerry Smartphone Simulator. You can choose from four levels of acceleration or turn graphics acceleration off. Before you begin: Verify that you have the following components installed on your computer: Video card that supports OpenGL 2.1 or later, and has 64 MB or more BlackBerry Smartphone Simulator 2.13 or later 1. 2. In the BlackBerry Smartphone Simulator, on the View menu, click Graphics Acceleration. Click the level of acceleration that you want.
Taking screen shots

You can save an image of a simulated BlackBerry device. You can save either the screen or the entire device. In the BlackBerry Smartphone Simulator, the image of the entire BlackBerry device is called the faceplate. By default, the BlackBerry Smartphone Simulator saves an image of the BlackBerry device as a .jpg file, and an image of the BlackBerry device screen as a .png file. You can override the default.
19
Development Guide
Taking screen shots
Save a screen shot

On the Edit menu, click Save Device Snapshot or Save LCD Snapshot.
Copy a screen shot to the clipboard

On the Edit menu, click Copy Device Snapshot or Copy LCD Snapshot.
20
Development Guide
Changing BlackBerry device operating conditions
Changing BlackBerry device operating conditions

Use a single-button headset
1. 2. On the Simulate menu, click Headset Connected. In the Headset dialog box, perform one of the following actions: Task Steps Connect a single-button Select the One button headset inserted option. headset. Click the button on a singleClick Click. button headset.
Use a multibutton headset

1. 2. On the Simulate menu, click Headset Connected. Complete one of the following tasks: Task Connect a multibutton headset. Click a button on a multibutton headset. Steps In the Headset dialog box, select the Multibutton headset inserted option. Under the Multibutton headset inserted option, click one of buttons.
Disconnect a headset
1. 2. On the Simulate menu, click Headset Connected. In the Headset dialog box, select the No headset option.
Change holster conditions

When the BlackBerry device is in the holster, the screen display turns off. By default, the BlackBerry device uses different notifications when in the holster. On the Simulate menu, click In Holster.
21
Development Guide
Close a flip screen
Close a flip screen

When a BlackBerry Pearl Flip Series smartphone is flipped shut, the flip screen displays notifications. On the Simulate menu, click Flipped.
Open or close a sliding BlackBerry device

When a BlackBerry Torch device is closed, it operates as a touch screen device. When the device is open, it operates as a keyboard device. On the Simulate menu, click Open slider.
Simulate battery conditions

1. 2. On the Simulate menu, click Battery Properties. Set one of the following options: Option Full Low Very Low Description The battery level is sufficient for BlackBerry device and network use. The BlackBerry device alerts the user, but remains turned on and can still use the network. The BlackBerry device cannot access the network, but the device remains turned on. Camera flash is disabled. The BlackBerry device turns off immediately. If you select this option, the BlackBerry Smartphone Simulator shuts down. This option enables you to specify the battery level as a percentage.
Dead Other
Simulate the absence of a SIM card

The BlackBerry Smartphone Simulator for BlackBerry devices with SIM cards allow you to simulate the absence of a SIM card. By default, the BlackBerry Smartphone Simulator simulates the SIM card being present. At the command prompt, type the following command when you start the device:
fledge /handheld=<model_number> /no-sim-present
Simulating network conditions

The BlackBerry Smartphone Simulator can simulate various states of network coverage, from a strong signal to a very weak signal. The BlackBerry Smartphone Simulator can also simulate a loss of network coverage.
22
Development Guide
Simulate supplementary phone services
Add a network
1. 2. 3. 4. On the Simulate menu, click Network Properties. Click Add. Type the network properties in the dialog. Click OK.
Set the network signal strength

1. 2. 3. 4. 5. On the Simulate menu, click Network Properties. Select the network you want to simulate from the Networks list. If you want to edit the network properties, click Edit and type new values. Click OK. Select or clear the In coverage check box. Move the Signal strength (RSSI) slide bar to set a value. The signal strength can be between -120 dBm and -40dBm.
Specify the rescan interval for a Wi-Fi network connection

You can specify how often the BlackBerry Smartphone Simulator scans for Wi-Fi networks. The default interval is five seconds. The range is 5 to 500 seconds. Before you begin: Install the BlackBerry Smartphone Simulator 2.12 or later for a BlackBerry device that supports Wi-Fi connections. 1. 2. 3. 4. On the Simulate menu, click Network Properties. In the Available Network Properties section, click a Wi-Fi network. In the Global Network Properties section, move the slide bar to the interval that you want. Click Close.
Simulate supplementary phone services

A number of supplementary phone services, such as call forwarding or call waiting, might be available on a BlackBerry device. You can simulate the availability of these services. By default, the BlackBerry Smartphone Simulator is set up with all supplementary services. 1. 2. On the Simulate menu, click Provision Supplementary Services. In the Supplementary Services Provisioned dialog box, enable or disable services.
23
Development Guide
How the BlackBerry Smartphone Simulator simulates application storage
How the BlackBerry Smartphone Simulator simulates application storage

The BlackBerry device and some of its accessories use application storage, previously called flash memory. For each session, the BlackBerry Smartphone Simulator creates several files named <session_name>*.dmp. Each .dmp file corresponds to a different region of application storage. By default, the session name represents the model number of the BlackBerry device that you are simulating. For example, the application storage session files for a BlackBerry 7100 Series device simulator have names such as 7100-fs.dmp, 7100-nv.dmp, and 7100-as.dmp. When the BlackBerry Smartphone Simulator starts, it loads the application storage for the device profile. If no files for application storage exist, the BlackBerry Smartphone Simulator creates new files. When the BlackBerry Smartphone Simulator exits, it saves the application storage contents to the .dmp files.
Clear the application storage

1. 2. Close the BlackBerry Smartphone Simulator. Restart the BlackBerry Smartphone Simulator using the /clear-flash command prompt option.
Example
fledge /handheld=7730 /serial-port=2 /comm=serial /clear-flash
Simulating BlackBerry Enterprise Server APIs and IT policies

To test applications that use the BlackBerry Enterprise Server Extension API, applied IT policies, email and browser messaging, HTTP/TCP connections, or push functionality, you can use the BlackBerry Enterprise Server. You can connect the BlackBerry Smartphone Simulator to an account on a BlackBerry Enterprise Server. You do not require a BlackBerry MDS Simulator or a BlackBerry Email Simulator. Using the BlackBerry Enterprise Server requires knowledge of BlackBerry Enterprise Server administration. It also introduces a network dependance to testing. Depending on the application you are testing, you might also require the BlackBerry Desktop Manager and the BlackBerry Device Manager. To use the following programs with the BlackBerry Smartphone Simulator, each of the BlackBerry Enterprise Server, BlackBerry Desktop Manager and BlackBerry Device Manager should be version 4.0 or later.
Using the BlackBerry Smartphone Simulator in secure mode

Before you deploy your application, you should test the application in secure mode.
24
Development Guide
Connecting to Bluetooth USB accessories
By default, the BlackBerry Smartphone Simulator has two features that an make it easy to use but that are not found on the BlackBerry device. The simulator does not check for required code signatures on applications and it does not prompt you before connecting to the network. You can disable those features by running the BlackBerry Smartphone Simulator in secure mode. When you enable BlackBerry Smartphone Simulator secure mode, you cannot use the .cod files that come with the BlackBerry Smartphone Simulator. You must use the .cod files that are installed on the BlackBerry device. To obtain the appropriate .cod files, you can copy BlackBerry device .cod files from your computer to the BlackBerry Smartphone Simulator installation folder. By default, the location of the installation folder is: C:\Program Files\Common Files\Research In Motion\Shared \Loader Files\<Handheld>\Java.
Enable secure mode

You can only set secure mode as an option from the command prompt. At the command prompt, start the BlackBerry Smartphone Simulator with the /secure option. Example: Enabling secure mode with a simulation of the BlackBerry Torch 9800 smartphone
fledge /handheld=9800 /secure
Connecting to Bluetooth USB accessories

The BlackBerry Smartphone Simulator can connect to some Bluetooth headsets. To connect through a Bluetooth USB connection, you must have the CSR driver btiasb2.inf installed. You can only enable a Bluetooth USB connection from the command prompt by using the /bluetooth-usb parameter with the fledge command.
Simulating a USB connection to the computer

Simulating a USB cable connection enables you to connect the BlackBerry Smartphone Simulator to the BlackBerry Desktop Software. You must set up the environment in the BlackBerry Desktop Software and then enable or disable the connection in the BlackBerry Smartphone Simulator. Because the USB cable connection is simulated, you cannot transfer files between the computer and the BlackBerry Smartphone Simulator. This option is only available for BlackBerry device models that do not use a cradle.
Simulate a USB connection to the computer

BlackBerry Desktop Software 6.0 and later automatically uses a USB connection. 1. If you have BlackBerry Desktop Manager version 5.1 or earlier, perform the following:
25
Development Guide
Simulating a media card
a. b. c. 2.
On the Tools menu, click Connection options. In the Connection Type drop-down list, click USB. Click Simulation.
In the BlackBerry Smartphone Simulator, on the Simulate menu, select or clear the USB Cable Connected option.

The BlackBerry Smartphone Simulator loads and saves the media card image to <session_name>*.sdcard in the working directory, unless you have set the /sdcard= <path> option. When the BlackBerry Smartphone Simulator starts, it loads the media card image for the BlackBerry device profile. If no image exists or you have specified / clear-sdcard, the BlackBerry Smartphone Simulator creates a new media card image when the BlackBerry Smartphone Simulator starts. The size of the media card image is 32MB, unless you specify otherwise using /sdcardsize=<size> . You must clear the existing card image using /clear-sdcard to create a new card with the specified size. If a media card image exists, its size will be retained even if you specify a different size using the /sdcard-size command. The BlackBerry Smartphone Simulator inserts the media card when the BlackBerry Smartphone Simulator unless you specify /no-sdcard-inserted.
Simulate a media card with a folder

You can simulate a media card by using an image file of a media card, or a folder. To test SQLite database applications on the BlackBerry Smartphone Simulator, you must simulate a media card by using a folder. 1. 2. 3. 4. 5. Create a folder on your computer to store files for the media card. In the BlackBerry Smartphone Simulator, on the Simulate menu, click Change SD Card. In the list of available media cards, click one. Click the Mount icon. Click Close.
Format of a simulated media card

You can create a folder to simulate a media card for use with the BlackBerry Smartphone Simulator, either as a local Windows folder, or in FAT image format. When you use Windows format, the BlackBerry Smartphone Simulator uses a standard folder as the simulated media card. The format is the same between the desktop computer and the simulated smartphone. To use as the simulated media card, the simulator creates a folder named BlackBerry that contains subfolders, such as Music and Pictures. When you use media card image format, the BlackBerry Smartphone Simulator uses an image file as the simulated media card.
26
Development Guide
On startup, the BlackBerry Smartphone Simulator reads the simulated media card. If you want to add a media file to the simulated media card without using the BlackBerry Smartphone Simulator, you must add it before you start the simulator, or mount the media card folder again. The BlackBerry Smartphone Simulator saves any database files that it creates to the simulated media card.
27
Development Guide
Using GPS and Location Based Services
Using GPS and Location Based Services

Simulating GPS location information
You can simulate movement between fixed GPS locations.
A location represents one end point of a path. A route can contain one or more paths. The BlackBerry Smartphone Simulator emulates movement between locations on a route across one or more paths. You can create and save multiple locations that you can simulate. Once you save the route, run the simulation.
Add a GPS location

1. 2. 3. 4. 5. 6. 7. On the Simulate menu, click GPS Location. In the Location section, click Add. In the Name field, type a name. In the Latitude and Longitude fields, type a latitude and longitude. In the Altitude field, type an altitude in meters above or below the WGS 84 reference ellipsoid. In the Satellites field, type the number of satellites that are visible from the location. You determine the value, but it must be 0 or higher, and 4 is the minimum for a reliable location. Click Save.
Change a GPS location

The valid range for latitude is -90 to 90. The valid range for longitude is -180 to 180. 1. 2. 3. 4. On the Simulate menu, click GPS Location. In the Location drop-down list, click a location. Click Edit and change the values in the appropriate fields. Renaming a location can cause existing routes that contain that location name to fail. Click Save.
Delete a GPS location

1. 2. 3. On the Simulate menu, click GPS Location. In the Location drop-down list, click a location to delete. Click Delete.
28
Development Guide
Managing GPS routes
Managing GPS routes

To simulate movement between different GPS locations, set up a route with one or more paths. Each path represents a straight line between two adjacent locations. Each path contains information about the rate of speed used to travel between the path start and end locations. You can use the following rates of speed: metres per second (m/s), kilometres per hour (km/h), metres per hour (m/ h), and feet per second (f/s). The speed limit in terms of metres per second is 655 m/s, with respective limits set for other rates.
Create a GPS route by using existing locations

1. 2. 3. 4. 5. 6. 7. 8. 9. On the Simulate menu, click GPS Location. In the Route section, click Add. Click existing locations. Type a name for the new route Select the starting location of the route. Type a speed value and set the rate of speed for the path. Click Insert to insert this location into the route. To add additional locations to the route, repeat steps 3 through 5. Save the route.
Create a GPS route by using NMEA 0183 sentences

The BlackBerry Smartphone Simulator accepts files that contain data sentences written in one of the Global Positioning System Fixed Data format, known as GGA format, and the Recommended Minimum Specific GPS/Transit Data format, known as RMC format. These sentences are defined in NMEA 0183 V2.3 and later. Before you begin: When you use a version of the BlackBerry Smartphone Simulator earlier than 6.0.1, make sure the BlackBerry MDS Simulator is running. 1. 2. 3. 4. 5. On the Simulate menu, click GPS Location. In the Route section, click Add. In the Create New Route dialog box, click data from a file and click OK. Select the file that contains the sentence and click OK. Click Close.
Create a GPS route by using a random set of your locations

1. 2. On the Simulate menu, click GPS Location. In the Route section, click Add.
29
Development Guide
Managing GPS routes
3. 4. 5.
Select Create route using random route generator. Click OK. In the new dialog, specify the route name, the number of legs, the duration of the route (in seconds), as well as a start and end location. If you generated the route successfully, the New Route dialog displays the route information.
Change a GPS route

1. 2. 3. On the Simulate menu, click GPS Location. Set a route to change. Perform one or more of the following procedures: Task Change the route name. Add a location to the route. Steps In the Name field, type a new name for the route. a. b. c. Change a location. a. b. c. Remove a location. 4. 5. a. b. Click Insert. In the Start Location drop-down list, click a location. Type a speed value and set the rate of speed for the path. In the text box, under the Name field, set the location you want to change. In the Start Location drop-down list, click the location you want to change to. Type a speed value and set the rate of speed for the path. From the text box, under the Name field, set a location. Click Delete.
In the Name field, type a new name for the route. Click Save.
Delete a GPS route

1. 2. 3. On the Simulate menu, click GPS Location. In the Route drop-down list, click a route to delete. Click Delete.
Simulate a GPS route

Route simulation uses the Haversine formula to calculate the changing GPS coordinates and updates the location, the direction, and the coordinates every second. 1.
30
On the Simulate menu, click GPS Location.
Development Guide
Managing GPS routes
2.
Perform one of the following actions: Task Play a route. Stop a route. Steps In the Route section, click the Play (right arrow) icon. In the Route section, click the Stop (black square) icon.
3.
To restart the route, stop the simulation. Press the Play Route button.
31
Development Guide
Testing NFC applications
Testing NFC applications
Testing NFC applications on the BlackBerry Smartphone Simulator

Some BlackBerry smartphones are equipped for NFC. BlackBerry smartphones that support NFC can read a smart tag, a smart accessory or some other NFC-enabled device. NFC technology is designed to transfer small amounts of data over a short distance. The BlackBerry Smartphone Simulator simulates only insecure passive communication. You can use smart tags to: Provide a URL where a user can retrieve more information about an advertisement on a smart poster, such as a movie or a coupon Provide pairing information for a Bluetooth accessory Provide identification information for a smart dock To test an NFC application using the BlackBerry Smartphone Simulator, you also need the tools in the Open NFC package, available from SourceForge. The two tools, the NFC Simulator application and the Connection Center application, run on the same computer as the BlackBerry Smartphone Simulator. You can download the package for the NFC Controller Simulator program from SourceForge at http:// sourceforge.net/projects/open-nfc/files. If you are developing for BlackBerry Device Software 7.0, download the Core or PC edition of the NFC Controller Simulator version 4.2.3.
Setting up the NFC Controller Simulator

The NFC Controller Simulator application, from SourceForge, runs on your computer. You can use it to send signals as though it were an NFC card or token and test your BlackBerry smartphone application. The NFC Controller Simulator program must run on the same computer as the BlackBerry Smartphone Simulator. You can download the package for the NFC Controller Simulator program from SourceForge at http:// sourceforge.net/projects/open-nfc/files. To install the NFC Controller Simulator application on your computer, see the instructions with the NFC Controller Simulator program.
Set the NFC parameters

Some of the NFC parameters can be set within the BlackBerry Smartphone Simulator. You must set the others at the command prompt. 1. 2. On the Simulate menu, click NFC Options. Perform either of the following tasks:
32
Development Guide
Command prompt parameters related to NFC
Task Steps Initialize NFC for the NFC Controller Simulator rather Beside Use NFC Simulator, check the box. than a test board, whenever the BlackBerry Smartphone Simulator starts. This is identical to using the /nfcc-using-sim parameter at the command prompt. Specify location of the NFC Controller Simulator. In the text box under NFC Controller URI, enter the URI for the NFC Simulator. Entering a URI using this option does not take effect until the next time the BlackBerry Smartphone Simulator starts. Until it restarts, setting this option prevents all NFC communication between the BlackBerry Smartphone Simulator and the NFC Controller. 3. On the Simulate menu, click Initialize NFC.
Command prompt parameters related to NFC

Parameters
/ump=<path_to_UMD_DLL>
/nfcc-uri=<URI_string>
/nfcc-using-sim=<Boolean>
Description This parameter loads the NFC User Mode Driver when the BlackBerry Smartphone Simulator starts. This option is only necessary if your installation of the Java programming language has no NFC support. This parameter loads the URI that points to an NFC simulator program or the evaluation board. The default value points to an evaluation board. You can set the value of the URI on the BlackBerry Smartphone Simulator. This parameter defines whether you are using an NFC simulator application. By default, it is set to false, but when using an NFC simulator application, this value should be set to true. You can set this value on the BlackBerry Smartphone Simulator.
33
Development Guide
Test an NFC application
Test an NFC application

If you run the BlackBerry Smartphone Simulator from a batch file, remember that any % characters in the URL string must have an additional % sign, so a string such as /nfcc-uri=NFC%20Device%20%231 becomes /nfcc-uri-NFC %%20Device%%20%%231 in the batch file. Before you begin: You must install and run the components of the NFC Simulator package. 1. 2. 3. 4. 5. 6. 7. Start the Connection Center. Start the NFC Controller Simulator. On older versions of the NFC Controller Simulator, on the NFC Device #1 menu, click Start. In the Connection Center, on the Global tab, click Service List to display a dialog box with a list of services. In the Connection Center, under NFC Controller (NFC HAL), right-click NFC Device #1 (on older versions of the application, the entry is called NFC Simulator). In the Connection Center, click Copy service URI. At the command prompt, start the BlackBerry Smartphone Simulator with the additional parameters /nfccusing-sim=true and /nfcc-uri=<copied_URI_string>. If the URI contains spaces, enclose the entire URI in double quotation marks. If you use the /nfcc-uri command prompt parameter, skip to step 9. In the BlackBerry Smartphone Simulator, on the Simulate menu, click Initialize NFC. The NFC Controller Simulator presents a dialog box showing a set of protocols and another dialog box showing the defined objects. In the NFC Controller Simulator, in the NFC Object Manager window, perform one of the following: Task Present an NFC card or token. Remove an NFC card or token. Steps In the Object List, double-click the name of the NFC card or token. Under the label NFC Device #1 Antenna, double-click the image.
8.
9.
10. In the BlackBerry Smartphone Simulator, test the application.
34
Development Guide
Simulating magnetometer information
Simulating magnetometer information

Magnetometer
10
A magnetometer is a sensor that is similar to a compass. A compass detects the horizontal component of the direction of a magnetic field. Magnetometers detect both the directional components and the strength of a magnetic field. Magnetometers in BlackBerry devices are calibrated to sense the magentic field of the earth. They are designed to measure and remove interference caused by local magnetic fields so that only the magentic field of the earth is measured. You can test the calibration quality of a magnetometer and trigger a new calibration when necessary. An obvious use of a magnetometer is to create a digital compass by creating a UI that presents the directional magnetometer data. Because a magnetometer includes additonal information about the magnetic field, such as the field strength, you can use it for many other purposes. For example, magnetometers are used in metal detectors, geological exploration tools, stud and pipe finders, and applications that require precise inclination measurements.
Displaying magnetometer information

Because the BlackBerry Smartphone Simulator does not move, the simulator displays a small image showing the orientation of the simulated BlackBerry smartphone. In the Manipulate Device window, you specify information about the current orientation and magnetic flux density for the simulated BlackBerry smartphone. The Manipulate Device window consists of two sections. In the top section of the window, you can switch between the device rotation mode, where you can define the orientation of the BlackBerry smartphone, and the magnetic north mode, where you can define the magnetic flux data. You can switch between the two by clicking the icon in the upper-right corner. In smartphone rotation mode, you can define the orientation of the BlackBerry smartphone along the x, y, and z axes. To specify an orientation, you can drag the circle representing the axis or you can type a number in degrees in a field in the Manual Input section. If you type the number of degrees manually, the image in the Device Manipulator window is not updated until you click Apply. When smartphone rotation mode is displayed, the icon displays a picture of an N and clicking the icon switches you to the magnetic north mode. Magnetic north mode shows the magnetic flux information. In this mode, you can define the declination, inclination, field strength, and the reading quality. You can define the declination and inclination graphically or manually, but you can only define the field strength and the reading quality manually. When the compass is displayed, the icon in the upper-right displays a symbol representing a smartphone and clicking the icon switches you to the smartphone rotation mode. The lower section of the Manipulate Device window displays the playback information. You can record, load, or play back a series of readings using the Playback section. A series of readings is called a magnetic path. A magnetic path consists of a first key, a last key, and possibly other keys. A key contains both the smartphone rotation data and the magnetic flux data for that instant in the animation.
35
Development Guide
Create or edit a magnetic path
To add readings to the magnetic path, you can add keys to the path. The BlackBerry Smartphone Simulator tries to make the transitions between keys as smooth as possible when you play back the path animation. You do not need to save an animation to play it back.

Each key in a magnetic path can specify both magnetic field data and rotational data for the position of the BlackBerry smartphone. During animation playback, the simulator presents a smooth transition between the values in each key. 1. 2. 3. 4. 5. 6. 7. On the Simulate menu, click Manipulate Device. To edit an existing magnetic path, load it from a .mag file. If necessary, add or delete keys. For each key, add the necessary BlackBerry smartphone rotation data. For each key, add the necessary magnetic data. In the Playback section, in the Duration field, specify the length of time for the playback, in seconds. When the changes to the magnetic path are finished, save the magnetic path animation in a .mag file.
Example: Creating a magnetic path The following steps demonstrate how to create a new magnetic path that takes 9 seconds to play. As a result of steps two through four, approximately one-third of the way through the path, the simulated BlackBerry smartphone tilts upside down and the magnetic field inclination changes to 90 degrees. For the remainder of the animation, both the inclination and smartphone rotation return to the original state. 1. 2. 3. 4. 5. 6. 7. 8. 9. On the Simulate menu, click Manipulate Device. In the Playback section, click the playback line at about one-third its length. Click Add Key. In the Tilt field, type 180. Click in one of the other fields. Click Apply. Click the N icon in the top right corner. In the Inclination field, type 90. Click in one of the other fields.
10. Click Apply. 11. In the Duration field, type 9. 12. Click the Play icon. If you view the playback of the path in magnetic north mode, the inclination arrow rises and then slowly drops. If you view the playback in smartphone orientation mode, the simulated BlackBerry smartphone flips over and then slowly turns back.
36
Development Guide
Change the smartphone orientation in a key

This task is part of creating or editing a magnetic path. The smartphone orientation in a key consists of the accelerometer data that is reported when the playback cursor passes that key. Before you begin: Make sure that the Device Manipulator window is open and is displaying the smartphone orientation mode. 1. 2. 3. To add a key, in the Playback section, click in the playback line where you want the new key and click Add Key. Click the key that you want to change. Do one of the following: Task Set the rotation around the z axis. Description Do one of the following: Click on the green circle and drag it until the BlackBerry smartphone image points in the direction you want. In the Manual Input section, in the Rotation field, type the angle, in degrees, and click Apply. Do one of the following: Click on the blue circle and drag it until the arrow points in the direction you want. In the Manual Input section, in the Tilt field, type the angle, in degrees, and click Apply. Do one of the following: Click on the black circle and drag it until the arrow points in the direction you want. In the Manual Input section, in the Direction field, type the angle, in degrees, and click Apply. Click and drag the key to the new location.
Set the tilt around the x axis.
Set the direction around the y axis.
Move a key to a new location. 4. 5. If necessary, change the magnetic field reading. If necessary, save the magnetic path.
Change the magnetic flux information in a key

This task is part of creating or editing a magnetic path. Magnetic information in a key consists of the magnetic flux information that is reported when the playback cursor passes that key. Before you begin: Make sure that the Device Manipulator window is open and displays magnetic north mode. 1. 2. To add a key, in the Playback section, click in the path window where you want the new key and click Add Key. Click the key that you want to change.
37
Development Guide
3.
Do any of the following: Task Set the difference between true north and magnetic north. Description Do one of the following: Click on the red circle and drag it until the N of the compass points in the direction you want. In the Manual Input section, in the Declination field, type the angle, in degrees, and click Apply. Do one of the following: Click on the blue circle and drag it until the arrow points in the direction you want. In the Manual Input section, in the Inclination field, type the angle, in degrees, and click Apply. a. In the Manual Input section, in the Field Strength(microTesla) field, type the field strength, in microTeslas. Click Apply. In the Manual Input section, in the Reading Quality field, select one of Unreliable, Low, Medium, or High. Click Apply.
Set the vertical angle of the magnetic field.
Set the strength of the magnetic field
b. Set the reliability of the magnetometer reading. a. b.
Move a key to a new location. 4. 5.
Note: When you set the Reading Quality to Low, you can only recalibrate after a subsequent reading of High. Click and drag the key to the new location.
If necessary, change the smartphone orientation in the key. If necessary, save the magnetic path.
Play back the current magnetic path

Before you begin: Make sure that the Device Manipulator window is open. In the Playback section of the Device Manipulator window, click the play icon.
Load a magnetic path file

The BlackBerry Smartphone Simulator can record and store magnetic path files. 1. 2. 3. 4.
38
On the Simulate menu, click Manipulate Device. Click Load. In the Open Magnetometer animation file dialog box, click on the .mag file to load. Click Open.
Development Guide
Display rotation in the BlackBerry Smartphone Simulator window
Save the current magnetic path

Before you begin: Make sure that the Device Manipulator window is open. 1. 2. 3. 4. Click Save. Type a name for the magnetic path file. Click Save. Click OK.
Display rotation in the BlackBerry Smartphone Simulator window

You can configure the BlackBerry Smartphone Simulator displays rotation happening in a magnetic path animation. When this feature is enabled, the image of the BlackBerry smartphone in the main BlackBerry Smartphone Simulator window rotates when you play a magnetic path animation that includes rotation. Before you begin: Make sure that the Device Manipulator window is open and in smartphone orientation mode. Click the bottom icon on the right.
39
Development Guide
Testing applications that require an HTTP connection
Testing applications that require an HTTP connection
11
The BlackBerry MDS Simulator is designed to simulate the BlackBerry MDS Connection Service component of the BlackBerry Enterprise Server. Using the BlackBerry Smartphone Simulator with the BlackBerry MDS Simulator enables you to test network, push, and browser applications that are designed for use with a BlackBerry Enterprise Server. If you are testing applications that require an HTTP connection, you will require the BlackBerry Smartphone Simulator and the BlackBerry MDS Simulator. You can download the BlackBerry Smartphone Simulator and the BlackBerry MDS Simulator by visiting www.blackberry.com/developers/downloads.
Testing push applications

Map the internet messaging address to the BlackBerry Smartphone Simulator PIN
In a production environment, the BlackBerry Enterprise Server automatically maps an Internet messaging address to the PIN of its BlackBerry device. Using the BlackBerry Smartphone Simulator, you can simulate the mapping between Internet messaging addresses and PIN. You must provide the mappings. You are required to map Internet messaging addresses to PIN values if you are testing a push application. For more information, see the API reference for the BlackBerry Java SDK. 1. 2. 3. 4. Navigate to the \Program Files\Research In Motion\BlackBerry Email and MDS Services Simulators x.x.x\MDS \config folder. With a text editor, open the rimpublic.property file. In the [Simulator] section, add or change entries for Simulator.<PIN> properties. In the push application, change the email address to the address of the specified BlackBerry Smartphone Simulator, so that when the push application sends data, it sends data to the specified simulator.
Example: Mapping an internet messaging address to a PIN The following entry in the rimpublic.property file assigns PIN 12A34B56C to email address user01@example.com:
Simulator.12A34B56C=localhost:81, user01@example.com
Change the BlackBerry Smartphone Simulator PIN

The PIN for the BlackBerry Smartphone Simulator can only be changed through a command line option. The default PIN is 0x2100000A. 1. 2.
40
At the command prompt or in the batch file that contains the command for the BlackBerry Smartphone Simulator, add the following option to the command: /pin=<new_pin> Start the BlackBerry Smartphone Simulator with the new command.
Development Guide
Testing messaging applications
After you finish: The port must match the value set in the IPPP.push.listen.tcp.port parameter. The default number is 81.
Testing messaging applications

The BlackBerry Email Simulator is designed to send and receive messages between the BlackBerry Smartphone Simulator and either a messaging application, such as Microsoft Outlook, or POP3 and SMTP servers. You do not require a BlackBerry Enterprise Server. The BlackBerry Email Simulator is available for download from the BlackBerry Developer Zone web site at http://www.blackberry.com/developers.
BlackBerry Email Simulator

The BlackBerry Email Simulator is designed to send and receive messages between the BlackBerry Smartphone Simulator and either a messaging application, such as Microsoft Outlook, or POP3 and SMTP servers. You do not require a BlackBerry Enterprise Server. To get the BlackBerry Email Simulator, visit www.blackberry.com/developers and download the BlackBerry Email and MDS Services Simulator Package.
Send a message
1. 2. 3. 4. 5. 6. 7. 8. 9. 10. 11. Start the BlackBerry Email Simulator. In the Email Server Simulator window, select the Standalone mode option. Click Launch. Start the BlackBerry Smartphone Simulator. In the BlackBerry Smartphone Simulator, click the Messages icon. In the Messages application of the simulated BlackBerry device, open the menu. Click Compose Email. In the To field, type an email address. Complete the Cc, Subject, and Body fields. Open the menu. Click Send.
Receive a message
1. 2. 3. 4. 5. Start the BlackBerry Email Simulator. In the Email Server Simulator window, select the Standalone mode option. Click Launch. Start the BlackBerry Smartphone Simulator. When the BlackBerry Smartphone Simulator receives an email, in the BlackBerry Smartphone Simulator, open the Messages application.
41
Development Guide
Using the BlackBerry Smartphone Simulator programmatically
Using the BlackBerry Smartphone Simulator programmatically
12
The BlackBerry Smartphone Simulator contains a controller tool, named fledgecontroller.exe. This controller tool is a command prompt tool that is you can use to programmatically control the BlackBerry Smartphone Simulator in test scripts. When events occur inside the BlackBerry Smartphone Simulator, the controller tool generates messages. The controller tool is designed to enable you to test events that normally would only be perceived visually or audibly. The controller tool provides commands that can instruct the BlackBerry Smartphone Simulator to simulate application commands, device commands, or external event commands. Application commands are commands for manipulating the simulated device on the BlackBerry Smartphone Simulator, such as a command to close the BlackBerry Smartphone Simulator, or to load a particular .cod file. Device commands control the simulated device and its immediate environment, such as whether it is open or closed, or device movement between GPS locations. External events are events that are generated externally from the BlackBerry device, such as an incoming call or a network event.
Using test scripts

You can produce automated tests by including the BlackBerry Smartphone Simulator controller tool within batch files. The BlackBerry Smartphone Simulator controller tool issues commands to the BlackBerry Smartphone Simulator. The controller tool is designed to enable you to test events that normally would only be perceived visually or audibly. When the BlackBerry Smartphone Simulator receives events or carries out commands, the controller tool presents messages on standard output. You do not require tools that automate GUI tests. For example, you can use test scripts to test your application on several models of the BlackBerry device simultaneously. The BlackBerry Smartphone Simulator controller tool accepts commands from either standard input or from a text file.You must connect the controller tool to a simulator session. You can create a .bat file that contains both the instructions for starting the simulator and the controller tool commands, or you can divide them into separate files. You must issue one controller tool command per line. The BlackBerry Smartphone Simulator controller tool commands are like function calls. Optional parameters are at the end of the command and can be omitted if the default parameter is acceptable for your needs. Case is not important. White space around the parentheses is not important. When you disconnect the controller tool from the BlackBerry Smartphone Simulator, the simulator still reflects the events that happened. For example, if you set the battery level to a new value, the simulator continues to reflect that value until the level is set again or the simulator is started again.
Start the BlackBerry Smartphone Simulator controller tool

At the command prompt, type fledgecontroller /session=<nnnn> with any additional parameters. Example: Starting the controller tool with the /execute parameter
42
Development Guide
Send commands to the BlackBerry Smartphone Simulator
The BlackBerry Smartphone Simulator controller tool issues the BatteryLevel(5) command to the BlackBerry Smartphone Simulator for the BlackBerry 7290 smartphone and exits.
fledgecontroller /session=7290 /execute=BatteryLevel(5)
Syntax for the BlackBerry Smartphone Simulator controller tool

The BlackBerry Smartphone Simulator controller tool reads from standard input and writes to standard output. The controller tool has the following syntax:
fledgecontroller /session=<model_name> [/execute=<command>] [/ timeout=<time_in_seconds>] [/get-sessions]
Parameter
/session=<model_name> /execute=<command>
/timeout=<time_in_seconds> /get-sessions
Description This parameter specifies the session of the BlackBerry Smartphone Simulator to attach to. This parameter is required. This parameter specifies which BlackBerry Smartphone Simulator command to be run. After running the command, the BlackBerry Smartphone Simulator controller tool closes. This parameter specifies how long, in seconds, the controller tool should run before closing. This parameter lists the names of any BlackBerry Smartphone Simulator sessions that are running. When this parameter is specified, even if other parameters are specified, the BlackBerry Smartphone Simulator controller tool closes after listing the names of existing sessions.
Send commands to the BlackBerry Smartphone Simulator

The BlackBerry Smartphone Simulator UI reflects the commands you type. 1. 2. 3. 4. At the command prompt, navigate to either the installation folder for the simulator or the bin folder of your BlackBerry Java Development Environment installation files. If necessary, start the BlackBerry Smartphone Simulator. Using the controller tool, named fledgecontroller.exe, connect the BlackBerry Smartphone Simulator controller tool to a running BlackBerry Smartphone Simulator. Type a BlackBerry Smartphone Simulator controller tool command.
Example The following set of commands is entered at the command prompt in the folder that contains the BlackBerry JDE. The commands start the BlackBerry Smartphone Simulator, start the BlackBerry Smartphone Simulator controller tool, set the battery level to one-half, and stop the controller tool.
43
Development Guide
Test BlackBerry Smartphone Simulator events by using a script
$ cd \Program Files\Research In Motion\BlackBerry JDE 4.2.0\bin fledge /handheld=9800 fledgecontroller /session=9800 BatteryLevel(50) quit
Test BlackBerry Smartphone Simulator events by using a script

1. 2. 3. 4. 5. 6. If necessary, create a command file and save it in the folder that contains your BlackBerry Smartphone Simulator or the bin folder of your BlackBerry Java Development Environment. Create a .bat file with commands to start the BlackBerry Smartphone Simulator and create a session. In the .bat file, write commands for connecting the BlackBerry Smartphone Simulator controller to the session, with a command that inputs data from the command file and directs output to a text file. Save the .bat file in the same folder that contains your command file. At a command prompt, navigate to the same folder that contains your command file. Start the .bat file.
Example The BlackBerry Smartphone Simulator controller starts and issues the test commands in PhoneTest.txt to the BlackBerry Smartphone Simulator. After all the commands in the test command file are issued, the BlackBerry Smartphone Simulator closes and messages are written to a text file named out.txt. Both the test command file and the .bat file are in the same folder as the BlackBerry Smartphone Simulator. The test command file, PhoneTest.txt, contains the following commands:
Pause(45) RemoteCallCreation("519-555-0100") Pause(2) ThumbwheelPress ThumbwheelRelease Pause(10) KeyPress(ESCAPE) Pause(2) KeyRelease(ESCAPE) Exit
The .bat file contains the following commands:

fledge /handheld=9800 FledgeController.exe /session=9800 < PhoneTest.txt > out.txt
After running the .bat file, the out.txt file contains the following messages:
44
Development Guide
Close the BlackBerry Smartphone Simulator controller tool session
Audio: alert stopped Connecting to Fledge session "test"... connected. Buzzer: alert started Buzzer: alert stopped Audio: alert started Disconnected
Close the BlackBerry Smartphone Simulator controller tool session

Perform one of the following tasks: Task Close the session connection. Close the session connection and close the BlackBerry Smartphone Simulator. Steps Perform one of the following actions: At the command prompt, type quit. Press CTRL+Z. At the command prompt, type exit.
See a list of BlackBerry Smartphone Simulator commands

To view a list of commands for controlling the BlackBerry Smartphone Simulator, perform one of the following actions: Action View a list of commands from the BlackBerry Smartphone Simulator. View a list of BlackBerry Smartphone Simulator commands from a command prompt. Description On the Help menu, click Controller Command Help.
At the command prompt, type fledge help. For more information on running the BlackBerry Smartphone Simulator controller, type FledgeController /help.
Accessory commands
Device accessory or peripheral commands generate events on the BlackBerry Smartphone Simulator that involve BlackBerry device accessories or peripheral events.
45
Development Guide
Application commands
Command
BatteryLevel (int level)
ExternalPower (bool charging) HeadsetConnection (bool connected) RemoteCallDisconnec tion (string number) HeadsetClick (bool pressed) Holster (bool holstered) SimInsertion (bool inserted)
Description Parameter Specifies the charge level of the battery level : Specifies the charge level of the battery as a percentage, where 100 represents a full charge, 0 represents empty Specifies whether battery charging is on charging : If true, the battery charging or off is on; if false, the battery charging is off Specifies whether the external headset connected : If true, the external is connected headset is connected; if false, the external headset is distconnected Specifies that the remote phone should number : Specifies the phone number to hang up disconnect from Specifies the state of the button on the external headset
pressed : If true, the button appears pressed; if false, the button does not appear pressed Specifies whether the BlackBerry device holstered : If true, the BlackBerry is holstered device is in the holster; if false, the BlackBerry device is not in the holster Specifies whether the SIM card is inserted : If true, the SIM card is inserted inserted; if false, the SIM card is not inserted
Application commands
Application commands can control the behavior and appearance of the BlackBerry Smartphone Simulator. Command
AllowFocusChange CarCradleAccessory (uint state) Exit (bool saveflash)
Description Specifies that another application can obtain the foreground window focus Specifies whether the car cradle accessory is connected Specifies that the BlackBerry Smartphone Simulator close
Parameter
state If true, specifies that the car cradle is connected
Default value is false save-flash : If true, saves your changes to simulated application storage before closing Default value is true
46
Development Guide
Network and phone commands
Command
GetPid
Help
Kill
LoadCod (Path path) Pause (int time) Reset SaveLcdSnapshot (Path filename)
Description Specifies that the controller tool return the ID of the BlackBerry Smartphone Simulator process Specifies that the controller tool generate help on controller tool commands Specifies that the BlackBerry Smartphone Simulator process ends without saving simulated application storage, but the BlackBerry Smartphone Simulator ends immediately if the cleanup process fails Specifies a Java application in .cod format to load Specifies a period of inactivity for the BlackBerry Smartphone Simulator Specifies that the BlackBerry Smartphone Simulator resets Specifies that the current LCD image be saved as a snapshot in either .jpg format or .png format Specifies that the main BlackBerry Smartphone Simulator window move behind all other windows Specifies that the main BlackBerry Smartphone Simulator window move to the foreground The Windows operating system blocks this command unless the application with focus calls the AllowSetForegroundWindow API. Specifies that the Windows operating system show or hide the main BlackBerry Smartphone Simulator window
Parameter
path : The full path to the .cod file of the
application
time : The number of seconds to pause
the BlackBerry Smartphone Simulator

filename : The path and file name of the
WindowLower
saved image, where the format is determined by the extension of the file name
WindowRaise
WindowShow (bool show)
show : If true, the BlackBerry
Smartphone Simulator displays the main window Default value is true

Network commands generate data and phone events.
47
Development Guide
Command
NetworkCoverage (int RSSI, WAFtypes WAF)
Description Specifies the wireless coverage level
Parameter
RSSI : Specifies the dB level, with -40 being strong and -256 being outside the wireless coverage area WAF : Specifies the wireless access family, which is one of: WAF_3GPP WAF_CDMA WAF_DUMMY WAF_IDEN WAF_NONE WAF_USB WAF_VPN WAF_WLAN
Default value is WAF_NONE

RemoteCallAnswer RemoteCallCreation (string number, presentationindicator-types
Specifies that a remote phone answers a call placed from the BlackBerry device Specifies a call from a remote phone to the BlackBerry device
number : Specifies the phone number that you call presentation-indicator :
presentationindicator, alternate-line-type alternate-line)
Specifies the display of the caller ID, which is one of: PI_ALLOWED PI_PRIVATE PI_UNKNOWN Default value is PI_ALLOWED alternate-line : Specifies the line on the device that receives the call, which is one of: VOICE_LINE_1 VOICE_LINE_2
RemoteCallDisconnec tion (string number)
Specifies that the remote phone hangs up
Default value is VOICE_LINE_1 number : Specifies the phone number to disconnect from
48
Development Guide
Application environment and GPS commands
Command
RemoteCallFailure (string number, reason-types reason)
Description Specifies that the call fails
Parameter
number : Specifies the phone
SupplementaryServic eProvisioning (service-types service, bool provisioned)
Specifies the addition or removal of a supplementary phone service
number to use for the remote call reason : Specifies the reason for the remote call failure, which is one of the reason documented on the online help service : Specifies the supplementary service type to simulate, which is one of the supplementary services documented on the online help provisioned : Specifies the service is provisioned, if true

Application environment commands can control the environment of the simulated BlackBerry device, including the GPS information. Command
BodyChanged(string state) OrientationChanged (string orientation) RenderingAccelerati onChanged (int
Description Parameter If the BlackBerry device is a flip phone or state : Specifies the possible states for a slider phone, specifies whether the the device are open and shut BlackBerry device is open or shut Default value is open Specifies the new orientation of the orientation : Specifies the possible BlackBerry device orientation of the device are top, left, right, bottom, front, and back Default value is top Specifies the graphics rendering acceleration for the BlackBerry Smartphone Simulator Specifies the new GPS location of the BlackBerry device
renderingAcceleration : Specifies
renderingAccelerati on) GpsAddLocation (string Name, double Latitude, double Longitude, short Altitude, int Satellites)
the speed of the graphics rending as one of off, low, medium, high, and max
Name : Specifies a name of the
location, chosen by the BlackBerry device user Latitude : Specifies the latitude value, between 89.99 and -90.00 degrees
49
Development Guide
Command
Description
Parameter
Longitude : Specifies the longitude
GpsDeleteLocation(s tring Name) GpsAddRoute(string Name) GpsDeleteRoute(stri ng Name) GpsAddLocationToRou te(string route, string location, double speed )
Specifies the GPS location that the BlackBerry device should delete Specifies the addition of a new empty route Specifies the removal of the named route Specifies a location to be added to the named route
value, between 179.99 and -180.00 degrees Altitude : Specifies the altitude in meters above or below the WGS 84 ellipsoid; default value is 0 Satellites : Specifies the number of visible satellites; default value is 4 Name : Specifies the name of the location
Name : Specifies the name of the route Name : Specifies the name of the route
route : Specifies the name of the
route
location : Specifies the name of
GpsAddCoordsToRoute (string route, double speed, double latitude, double longitude, short altitude, int num-sats)
Specifies coordinates that are added to the named route
GpsGenerateRandomRo ute (string name, string start,
Specifies that the BlackBerry Smartphone Simulator create a new route
the GPS location to add speed : Specifies the speed of travel, in meters per second route : Specifies the name of the route speed : Specifies the speed of travel, in meters per second latitude : Specifies the latitude value, between 89.99 and -90.00 degrees longitude : Specifies the longitude value, between 179.99 and -180.00 degrees altitude : Specifies the altitude in meters above or below the WGS 84 ellipsoid; default value is 0 num-sats : Specifies the number of visible satellites; default value is 4 name : Specifies the name of the new route
50
Development Guide
Keyboard and event commands
Command
string finish, double legs, double time)
Description
Parameter
start : Specifies the starting
GpsLoadRouteFromFil e (Path file, string name) GpsSetCoords (double latitude, double longitude, short altitude, int num-sats)
GpsSetLocation (string location) GpsStartRoutePlayba ck (string name) GpsStopRoutePlaybac k (string name)
location of the route, which must be an existing named location or the word Random finish : Specifies the ending location of the route, which must be an existing named location or the word Random legs : Specifies the number of sections in the route time : Specifies the time, in seconds, to complete the route Specifies the name of a file that contains file : Specifies the path to the file the route, one route to a file name : Specifies the name that the route is given Specifies by coordinates the current GPS latitude : Specifies the latitude location for the BlackBerry device value, between 89.99 and -90.00 degrees longitude : Specifies the longitude value, between 179.99 and -180.00 degrees altitude : Specifies the altitude in meters above or below the WGS 84 ellipsoid; default value is 0 num-sats : Specifies the number of visible satellites; default value is 4 Specifies by name the current GPS location : Specifies the name of the location for the BlackBerry device location Specifies that the BlackBerry device start name : Specifies the name of the route playing the named route Specifies that the BlackBerry device stop name name : Specifies the name of the playing the named route route

The input commands generate keyboard events and BlackBerry smartphone input events.
51
Development Guide
Command
KeyPress (key-types key) KeyRelease (keytypes key) KeyCodePress (int key, int depth)
Description Specifies the key-press signal to send
StringInjection (string key)
PreTranslatedKeyPre ss (char key) PreTranslatedKeyRel ease (char key) SimulateSwipe( int direction )
ThumbwheelPress ThumbwheelRelease ThumbwheelRoll (int movement)
TrackballPress TrackballRelease TrackballRoll (int x-delta, int ydelta)
Parameters key : Specifies the key to use for a keypress event Specifies the key-release signal to send key : Specifies the key to use for a keyrelease event Specifies the press and release of the key key : Specifies the key code of the with the given key code key to press, which defaults to 0 depth : Specifies the level of clicks for the key event, which defaults to -1 Specifies the character string to be string : Specifies an ASCII character inserted into the application string to enter into the application, even if the characters in the string cannot be created using the keyboard of the BlackBerry smartphone Specifies the pre-translated key that is key : Specifies the key that you want to pressed use for a press pre-translated key event Specifies the pre-translated key that is key : Specifies the key that you want to released use for a release pre-translated key event Specifies a swipe event on a touchscreen direction: Specifies the direction of the simulated swipe, which is one of the following: 0 represents an upward swipe 1 represents a swipe to the right 2 represents a downward swipe 3 represents a swipe to the left Specifies a press of the trackwheel Specifies a release of the trackwheel Specifies that the trackwheel is moved a movement : Specifies the number of clicks number of clicks to roll the trackwheel, where a positive value indicates a downward roll and a negative value indicates an upward roll Specifies a press of the trackball Specifies a release of the trackball Specifies that the trackball is rolled a x-delta : Specifies the number of number of clicks. clicks to roll the trackball in the left or right direction, where a positive value indicates a right roll and a negative value indicates a left roll
52
Development Guide
IT policy commands
Command
Description
Parameters
y-delta : Specifies the number of
clicks to roll the trackball in the up or down direction, where a positive value indicates an upward roll and a negative value indicates a downward roll
TouchScreenClick TouchScreenUnclick TouchScreenPress( i nt x, int y, int finger)
Specifies a click on the touch screen Specifies the end of a click on the touch screen Specifies a press on the touch screen
x : The x coordinate to press on,
TouchScreenUnpress( int finger)
Specifies the end of a press on the touch screen
where the coordinate is displayed in the lower corner of the BlackBerry Smartphone Simulator y : The y coordinate to press on, where the coordinate is displayed in the lower corner of the BlackBerry Smartphone Simulator finger : Specifies the finger to press with, used when performing multitouch events, which defaults to 0 finger : Specifies the finger to release, which defaults to 0
IT policy commands
The IT policy commands generate and accept IT policy events. To use these events, you must be set up your BlackBerry Smartphone Simulator to test BlackBerry Enterprise Server IT policies. Command Description ITPolicyQueue(unsign Specifies which IT policy to put into ed long Tag, the queue
unsigned long SubTag, string Value) ITPolicySend
Parameters
Tag : Specifies the IT policy category SubTag : Specifies the name of the IT
policy
Value : Specifies the value or content
of the IT policy Specifies that the controller should send all IT policies in the queue to the BlackBerry smartphone
53
Development Guide
IT policy commands
Command
ITPolicyACQueue(ITP_ AC_ID ID, ITP_AC_VALUE Value) ITPolicyACSend
Description Specifies that the BlackBerry Smartphone Simulator controller should queue up an application control permission Specifies that the controller should send all application control permissions that are in the queue to the BlackBerry smartphone
Parameters
ID : Specifies the application control ID Value : Specifies the permission given
to the application control ID, which is currently ITP_AC_DENY
54
Development Guide
Troubleshooting
Troubleshooting
13
The BlackBerry Smartphone Simulator takes a long time to start

Possible cause
Afer the BlackBerry Smartphone Simulator starts, it loads the BlackBerry Java Virtual Machine and the .cod files. If the previous BlackBerry Smartphone Simulator ended unexpectedly or if you have never run this version of the simulator on your computer before, the simulator must also link the files of the simulated file system together. Try one of the following: Avoid recreating and linking the file system. If possible, do not delete any *.dmp files in the folder that contains the BlackBerry Smartphone Simulator. Avoid restarting the BlackBerry Smartphone Simulator. Instead of restarting to load a .cod file, load a .cod file while the BlackBerry Smartphone Simulator runs. On the File menu, click Load BlackBerry Application or Theme.
Possible solution
I have a JVM error 543

Possible cause
The file system is from a previous instance of the BlackBerry Smartphone Simulator. Try one of the following: On the BlackBerry Smartphone Simulator, on the File menu, click Reset. At the command prompt, add the /reset-filesystem option to the command. Delete the *.dmp files.
Possible solution
Files for the BlackBerry Smartphone Simulator

The following files are in the installation folder of the BlackBerry Smartphone Simulator. By default, the location of the installation folder is Program Files\Research In Motion\BlackBerry Smartphone Simulators 6.x.x\6.n.n.nnn (<model_number>). File *.alx <model_number>.bat *.dmp Description For each application, specifies how it should be deployed on the BlackBerry device. Specifies the batch file to start the BlackBerry Smartphone Simulator Specifies dump files, the simulated file system and, if it exists, the media card
55
Development Guide
The location of user settings
File *.debug clean.bat fledge.exe fledge.dat fledge<model_number>.dll fledgeextractor.exe fledge-user.chm fledgecontroller.exe fledgecontroller.dll ide-update.bat
Description Specifies debugging versions of the files Specifies the batch file to clean up the simulator folder Specifies the BlackBerry Smartphone Simulator application and supporting files
_manifest Java\*.cod
Specifies the BlackBerry Smartphone Simulator user help file Specifies the BlackBerry Smartphone Simulator controller tool and associated dynamic library, for using the BlackBerry Smartphone Simulator with scripts Specifies the batch file to update the the IDE.jar file of the BlackBerry Java Development Environment with newer BlackBerry Smartphone Simulator options Specifies the master list of files, used when cleaning the directory Specifies the application .cod files
The location of user settings

The computer operating system specifies the location of the default folder with the .conf configuration files that contain your settings. For all operating systems, if the BlackBerry Smartphone Simulator cannot save information to the specified folder (%PROFILE%\net\rim\fledge-2), it saves your settings to your temporary folder. Operating system Windows XP and Windows Vista Windows 7 Location C:\Documents and Settings\<user_name>\net\rim\fledge-2 C:\Users\<user_name>\net\rim\fledge-2\
56
Development Guide
Glossary
Glossary
14
.alx file A .alx file is the application descriptor that provides information about a BlackBerry Java Application and the location of the application's .cod files to a BlackBerry device. AES Advanced Encryption Standard DES Data Encryption Standard FQDN fully qualified domain name flash memory The flash memory is an internal file system on a BlackBerry device that stores application data and user data. HTTP Hypertext Transfer Protocol HTTPS Hypertext Transfer Protocol over Secure Sockets Layer IDE integrated development environment IEEE Institute of Electrical and Electronics Engineers IMAP Internet Message Access Protocol IP Internet Protocol IT policy An IT policy consists of various IT policy rules that control the security features and behavior of BlackBerry smartphones, BlackBerry PlayBook tablets, the BlackBerry Desktop Software, and the BlackBerry Web Desktop Manager. IT policy rule
57
Development Guide
Glossary
An IT policy rule permits you to customize and control the actions that BlackBerry smartphones, BlackBerry PlayBook tablets, the BlackBerry Desktop Software, and the BlackBerry Web Desktop Manager can perform. JDE Java Development Environment JDK Java Development Kit JVM Java Virtual Machine LDAP Lightweight Directory Access Protocol MAPI Messaging Application Programming Interface MicroSD card Micro Secure Digital card NFC Near Field Communication NMEA National Marine Electronics Association PIN personal identification number POP Post Office Protocol RIM signing authority system The RIM signing authority system is a collection of servers that sign the boot ROM code for a BlackBerry device during the manufacturing process. SIM Subscriber Identity Module Triple DES Triple Data Encryption Standard WGS
58
Development Guide
Glossary
World Geodetic System
59
Development Guide
Provide feedback
Provide feedback
To provide feedback on this deliverable, visit www.blackberry.com/docsfeedback.
15
60
Development Guide
Legal notice
Legal notice
16
2011 Research In Motion Limited. All rights reserved. BlackBerry, RIM, Research In Motion, and related trademarks, names, and logos are the property of Research In Motion Limited and are registered and/or used in the U.S. and countries around the world. Casira End Point is a trademark of Bluetooth Designer. Java is a trademark of Sun Microsystems, Inc. Microsoft, Outlook, and Windows are trademarks of Microsoft Corporation.All other trademarks are the property of their respective owners. This documentation including all documentation incorporated by reference herein such as documentation provided or made available at www.blackberry.com/go/docs is provided or made accessible "AS IS" and "AS AVAILABLE" and without condition, endorsement, guarantee, representation, or warranty of any kind by Research In Motion Limited and its affiliated companies ("RIM") and RIM assumes no responsibility for any typographical, technical, or other inaccuracies, errors, or omissions in this documentation. In order to protect RIM proprietary and confidential information and/or trade secrets, this documentation may describe some aspects of RIM technology in generalized terms. RIM reserves the right to periodically change information that is contained in this documentation; however, RIM makes no commitment to provide any such changes, updates, enhancements, or other additions to this documentation to you in a timely manner or at all. This documentation might contain references to third-party sources of information, hardware or software, products or services including components and content such as content protected by copyright and/or third-party web sites (collectively the "Third Party Products and Services"). RIM does not control, and is not responsible for, any Third Party Products and Services including, without limitation the content, accuracy, copyright compliance, compatibility, performance, trustworthiness, legality, decency, links, or any other aspect of Third Party Products and Services. The inclusion of a reference to Third Party Products and Services in this documentation does not imply endorsement by RIM of the Third Party Products and Services or the third party in any way. EXCEPT TO THE EXTENT SPECIFICALLY PROHIBITED BY APPLICABLE LAW IN YOUR JURISDICTION, ALL CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS, OR WARRANTIES OF ANY KIND, EXPRESS OR IMPLIED, INCLUDING WITHOUT LIMITATION, ANY CONDITIONS, ENDORSEMENTS, GUARANTEES, REPRESENTATIONS OR WARRANTIES OF DURABILITY, FITNESS FOR A PARTICULAR PURPOSE OR USE, MERCHANTABILITY, MERCHANTABLE QUALITY, NON-INFRINGEMENT, SATISFACTORY QUALITY, OR TITLE, OR ARISING FROM A STATUTE OR CUSTOM OR A COURSE OF DEALING OR USAGE OF TRADE, OR RELATED TO THE DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NON-PERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES REFERENCED HEREIN, ARE HEREBY EXCLUDED. YOU MAY ALSO HAVE OTHER RIGHTS THAT VARY BY STATE OR PROVINCE. SOME JURISDICTIONS MAY NOT ALLOW THE EXCLUSION OR LIMITATION OF IMPLIED WARRANTIES AND CONDITIONS. TO THE EXTENT PERMITTED BY LAW, ANY IMPLIED WARRANTIES OR CONDITIONS RELATING TO THE DOCUMENTATION TO THE EXTENT THEY CANNOT BE EXCLUDED AS SET OUT ABOVE, BUT CAN BE LIMITED, ARE HEREBY LIMITED TO NINETY (90) DAYS FROM THE DATE YOU FIRST ACQUIRED THE DOCUMENTATION OR THE ITEM THAT IS THE SUBJECT OF THE CLAIM. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, IN NO EVENT SHALL RIM BE LIABLE FOR ANY TYPE OF DAMAGES RELATED TO THIS DOCUMENTATION OR ITS USE, OR PERFORMANCE OR NONPERFORMANCE OF ANY SOFTWARE, HARDWARE, SERVICE, OR ANY THIRD PARTY PRODUCTS AND SERVICES
61
Development Guide
Legal notice
REFERENCED HEREIN INCLUDING WITHOUT LIMITATION ANY OF THE FOLLOWING DAMAGES: DIRECT, CONSEQUENTIAL, EXEMPLARY, INCIDENTAL, INDIRECT, SPECIAL, PUNITIVE, OR AGGRAVATED DAMAGES, DAMAGES FOR LOSS OF PROFITS OR REVENUES, FAILURE TO REALIZE ANY EXPECTED SAVINGS, BUSINESS INTERRUPTION, LOSS OF BUSINESS INFORMATION, LOSS OF BUSINESS OPPORTUNITY, OR CORRUPTION OR LOSS OF DATA, FAILURES TO TRANSMIT OR RECEIVE ANY DATA, PROBLEMS ASSOCIATED WITH ANY APPLICATIONS USED IN CONJUNCTION WITH RIM PRODUCTS OR SERVICES, DOWNTIME COSTS, LOSS OF THE USE OF RIM PRODUCTS OR SERVICES OR ANY PORTION THEREOF OR OF ANY AIRTIME SERVICES, COST OF SUBSTITUTE GOODS, COSTS OF COVER, FACILITIES OR SERVICES, COST OF CAPITAL, OR OTHER SIMILAR PECUNIARY LOSSES, WHETHER OR NOT SUCH DAMAGES WERE FORESEEN OR UNFORESEEN, AND EVEN IF RIM HAS BEEN ADVISED OF THE POSSIBILITY OF SUCH DAMAGES. TO THE MAXIMUM EXTENT PERMITTED BY APPLICABLE LAW IN YOUR JURISDICTION, RIM SHALL HAVE NO OTHER OBLIGATION, DUTY, OR LIABILITY WHATSOEVER IN CONTRACT, TORT, OR OTHERWISE TO YOU INCLUDING ANY LIABILITY FOR NEGLIGENCE OR STRICT LIABILITY. THE LIMITATIONS, EXCLUSIONS, AND DISCLAIMERS HEREIN SHALL APPLY: (A) IRRESPECTIVE OF THE NATURE OF THE CAUSE OF ACTION, DEMAND, OR ACTION BY YOU INCLUDING BUT NOT LIMITED TO BREACH OF CONTRACT, NEGLIGENCE, TORT, STRICT LIABILITY OR ANY OTHER LEGAL THEORY AND SHALL SURVIVE A FUNDAMENTAL BREACH OR BREACHES OR THE FAILURE OF THE ESSENTIAL PURPOSE OF THIS AGREEMENT OR OF ANY REMEDY CONTAINED HEREIN; AND (B) TO RIM AND ITS AFFILIATED COMPANIES, THEIR SUCCESSORS, ASSIGNS, AGENTS, SUPPLIERS (INCLUDING AIRTIME SERVICE PROVIDERS), AUTHORIZED RIM DISTRIBUTORS (ALSO INCLUDING AIRTIME SERVICE PROVIDERS) AND THEIR RESPECTIVE DIRECTORS, EMPLOYEES, AND INDEPENDENT CONTRACTORS. IN ADDITION TO THE LIMITATIONS AND EXCLUSIONS SET OUT ABOVE, IN NO EVENT SHALL ANY DIRECTOR, EMPLOYEE, AGENT, DISTRIBUTOR, SUPPLIER, INDEPENDENT CONTRACTOR OF RIM OR ANY AFFILIATES OF RIM HAVE ANY LIABILITY ARISING FROM OR RELATED TO THE DOCUMENTATION. Prior to subscribing for, installing, or using any Third Party Products and Services, it is your responsibility to ensure that your airtime service provider has agreed to support all of their features. Some airtime service providers might not offer Internet browsing functionality with a subscription to the BlackBerry Internet Service. Check with your service provider for availability, roaming arrangements, service plans and features. Installation or use of Third Party Products and Services with RIM's products and services may require one or more patent, trademark, copyright, or other licenses in order to avoid infringement or violation of third party rights. You are solely responsible for determining whether to use Third Party Products and Services and if any third party licenses are required to do so. If required you are responsible for acquiring them. You should not install or use Third Party Products and Services until all necessary licenses have been acquired. Any Third Party Products and Services that are provided with RIM's products and services are provided as a convenience to you and are provided "AS IS" with no express or implied conditions, endorsements, guarantees, representations, or warranties of any kind by RIM and RIM assumes no liability whatsoever, in relation thereto. Your use of Third Party Products and Services shall be governed by and subject to you agreeing to the terms of separate licenses and other agreements applicable thereto with third parties, except to the extent expressly covered by a license or other agreement with RIM. Certain features outlined in this documentation require a minimum version of BlackBerry Enterprise Server, BlackBerry Desktop Software, and/or BlackBerry Device Software.
62
Development Guide
Legal notice
The terms of use of any RIM product or service are set out in a separate license or other agreement with RIM applicable thereto. NOTHING IN THIS DOCUMENTATION IS INTENDED TO SUPERSEDE ANY EXPRESS WRITTEN AGREEMENTS OR WARRANTIES PROVIDED BY RIM FOR PORTIONS OF ANY RIM PRODUCT OR SERVICE OTHER THAN THIS DOCUMENTATION. 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
63

Blackberry Smart Phone Simulator Development Guide 1640741 0916031807 001 7.0 US

Diunggah oleh

Informasi Dokumen

Hak Cipta

Format Tersedia

Bagikan dokumen Ini

Bagikan atau Tanam Dokumen

Opsi Berbagi

Apakah menurut Anda dokumen ini bermanfaat?

Apakah konten ini tidak pantas?

Hak Cipta:

Format Tersedia

Blackberry Smart Phone Simulator Development Guide 1640741 0916031807 001 7.0 US

Diunggah oleh

Hak Cipta:

Format Tersedia

BlackBerry Smartphone Simulator

Published: 2011-08-03 SWD-1640741-0916031807-001

BlackBerry Smartphone Simulator

BlackBerry Smartphone Simulator

Starting the BlackBerry Smartphone Simulator

Starting the BlackBerry Smartphone Simulator

Start the BlackBerry Smartphone Simulator

Start the BlackBerry Smartphone Simulator from the command prompt.

Start the BlackBerry Smartphone Simulator

Using the BlackBerry Smartphone Simulator

Using the BlackBerry Smartphone Simulator

Gesture to simulate Click the screen. Drag a finger.

4.7.1 and later

6.0 and later 6.0 and later 4.7.1 and later

4.71 to 5.1 6.0 and later

4.71 to 5.1 4.7.1 and later

Sending input from the computer

BlackBerry Device Software versions

Sending input from the computer

Simulating trackball input

Simulating trackwheel input

Press the arrow keys.

Move the mouse.

Click the right mouse button.

Simulating trackwheel input

Simulate a convenience key

Simulate a convenience key

Simulate a multi-function key

Changing the BlackBerry smartphone orientation

View the event log

Orientation mode Front-Side-Up Back-Side-Up

Change screen orientation

Simulate tilting a BlackBerry device in 3-D space

View the event log

View messages from the JVM

Testing applications using the BlackBerry Smartphone Simulator

Testing applications using the BlackBerry Smartphone Simulator

Testing GPS applications

Testing JavaScript and webpages

Testing JavaScript and webpages

Testing BlackBerry Enterprise Server APIs and IT policies

Test a BlackBerry Smartphone Simulator with a BlackBerry Enterprise Server

BlackBerry Device Software applications

BlackBerry Device Software applications

BlackBerry Device Software version 4.2 5.x 6.0

Set video recording options

Using the phone application

Using the phone application

Simulate an outgoing call

Using voice dialing

Changing BlackBerry Smartphone Simulator display options

Changing BlackBerry Smartphone Simulator display options

Hide the faceplate

Turn full-screen mode on and off

Specify graphics acceleration

Taking screen shots

Taking screen shots

Save a screen shot

Copy a screen shot to the clipboard

Changing BlackBerry device operating conditions

Changing BlackBerry device operating conditions

Use a multibutton headset

Change holster conditions

Close a flip screen