blackberry smart phone simulator development guide 1640741 0916031807 001 7.0 us

8/2/2019 Blackberry Smart Phone Simulator Development Guide 1640741 0916031807 001 7.0 US

1/65

BlackBerry Smartphone

SimulatorVersion: 7.0

Development Guide


2/65

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


3/65

Contents1 BlackBerry Smartphone Simulator.................................................................................................................... 5

Overview........................................................................................................................................................... 5

2 Starting the BlackBerry Smartphone Simulator................................................................................................ 6

Start the BlackBerry Smartphone Simulator..................................................................................................... 6

3 Using the BlackBerry Smartphone Simulator.................................................................................................... 8

Simulating touch screen input.......................................................................................................................... 8

Sending input from the computer.................................................................................................................... 9

Simulating trackball input................................................................................................................................. 9

Simulating trackwheel input............................................................................................................................. 10

Simulate a convenience key.............................................................................................................................. 11

Simulate a multi-function key........................................................................................................................... 11

Changing the BlackBerry smartphone orientation........................................................................................... 11

Change screen orientation........................................................................................................................ 12

Simulate tilting a BlackBerry device in 3-D space...................................................................................... 12View the event log............................................................................................................................................ 12

View messages from the JVM........................................................................................................................... 12

4 Testing applications using the BlackBerry Smartphone Simulator................................................................... 13

Load an application for testing......................................................................................................................... 13

Testing GPS applications................................................................................................................................... 13

Testing JavaScript and webpages..................................................................................................................... 14Test MIDlets...................................................................................................................................................... 14

Testing BlackBerry Enterprise Server APIs and IT policies................................................................................ 14

Test a BlackBerry Smartphone Simulator with a BlackBerry Enterprise Server........................................ 14

Configuring the BlackBerry MDS Simulator and the BlackBerry Smartphone Simulator for BlackBerry

Messenger........................................................................................................................................................ 15

5 BlackBerry Device Software applications.......................................................................................................... 16Using the camera.............................................................................................................................................. 16

Viewing a picture....................................................................................................................................... 16

Take a picture............................................................................................................................................ 16

Delete a picture......................................................................................................................................... 16

Picture resolutions..................................................................................................................................... 16

Recording video................................................................................................................................................ 17

Set video recording options....................................................................................................................... 17Using the phone application............................................................................................................................. 17


4/65

Simulate an incoming call.......................................................................................................................... 17

Simulate an outgoing call.......................................................................................................................... 18

Using voice dialing..................................................................................................................................... 18

6 Changing BlackBerry Smartphone Simulator display options........................................................................... 19

Magnify the BlackBerry device image............................................................................................................... 19

Hide the faceplate............................................................................................................................................. 19

Turn full-screen mode on and off..................................................................................................................... 19

Specify graphics acceleration............................................................................................................................ 19

Taking screen shots........................................................................................................................................... 19

Save a screen shot..................................................................................................................................... 20

Copy a screen shot to the clipboard.......................................................................................................... 20

7 Changing BlackBerry device operating conditions............................................................................................ 21

Use a single-button headset............................................................................................................................. 21

Use a multibutton headset............................................................................................................................... 21

Disconnect a headset........................................................................................................................................ 21

Change holster conditions................................................................................................................................ 21

Close a flip screen............................................................................................................................................. 22

Open or close a sliding BlackBerry device......................................................................................................... 22

Simulate battery conditions.............................................................................................................................. 22

Simulate the absence of a SIM card.................................................................................................................. 22

Simulating network conditions......................................................................................................................... 22

Add a network........................................................................................................................................... 23

Set the network signal strength................................................................................................................. 23

Specify the rescan interval for a Wi-Fi network connection...................................................................... 23

Simulate supplementary phone services.......................................................................................................... 23

How the BlackBerry Smartphone Simulator simulates application storage..................................................... 24

Clear the application storage..................................................................................................................... 24

Simulating BlackBerry Enterprise Server APIs and IT policies........................................................................... 24

Using the BlackBerry Smartphone Simulator in secure mode.......................................................................... 24

Enable secure mode.................................................................................................................................. 25

Connecting to Bluetooth USB accessories........................................................................................................ 25

Simulating a USB connection to the computer................................................................................................. 25

Simulate a USB connection to the computer............................................................................................ 25

Simulating a media card................................................................................................................................... 26

Simulate a media card with a folder.......................................................................................................... 26

Format of a simulated media card............................................................................................................. 26


5/65

8 Using GPS and Location Based Services............................................................................................................ 28

Simulating GPS location information................................................................................................................ 28

Add a GPS location.................................................................................................................................... 28

Change a GPS location............................................................................................................................... 28

Delete a GPS location................................................................................................................................ 28

Managing GPS routes........................................................................................................................................ 29

Create a GPS route by using existing locations.......................................................................................... 29

Create a GPS route by using NMEA 0183 sentences................................................................................. 29

Create a GPS route by using a random set of your locations.................................................................... 29

Change a GPS route................................................................................................................................... 30

Delete a GPS route.................................................................................................................................... 30

Simulate a GPS route................................................................................................................................. 30

9 Testing NFC applications................................................................................................................................... 32

Testing NFC applications on the BlackBerry Smartphone Simulator................................................................ 32

Setting up the NFC Controller Simulator.......................................................................................................... 32

Set the NFC parameters.................................................................................................................................... 32

Command prompt parameters related to NFC................................................................................................. 33

Test an NFC application.................................................................................................................................... 34

10 Simulating magnetometer information............................................................................................................ 35

Magnetometer.................................................................................................................................................. 35

Displaying magnetometer information............................................................................................................ 35

Create or edit a magnetic path......................................................................................................................... 36

Change the smartphone orientation in a key............................................................................................ 37

Change the magnetic flux information in a key......................................................................................... 37

Play back the current magnetic path......................................................................................................... 38

Load a magnetic path file.......................................................................................................................... 38

Save the current magnetic path................................................................................................................ 39

Display rotation in the BlackBerry Smartphone Simulator window................................................................. 39

11 Testing applications that require an HTTP connection..................................................................................... 40

Testing push applications................................................................................................................................. 40

Map the internet messaging address to the BlackBerry Smartphone Simulator PIN................................ 40

Change the BlackBerry Smartphone Simulator PIN................................................................................... 40

Testing messaging applications........................................................................................................................ 41

BlackBerry Email Simulator........................................................................................................................ 41

Send a message......................................................................................................................................... 41

Receive a message..................................................................................................................................... 41


6/65

12 Using the BlackBerry Smartphone Simulator programmatically...................................................................... 42

Using test scripts............................................................................................................................................... 42

Start the BlackBerry Smartphone Simulator controller tool............................................................................. 42

Syntax for the BlackBerry Smartphone Simulator controller tool............................................................. 43

Send commands to the BlackBerry Smartphone Simulator.............................................................................. 43

Test BlackBerry Smartphone Simulator events by using a script...................................................................... 44

Close the BlackBerry Smartphone Simulator controller tool session............................................................... 45

See a list of BlackBerry Smartphone Simulator commands.............................................................................. 45

Accessory commands....................................................................................................................................... 45

Application commands..................................................................................................................................... 46

Network and phone commands....................................................................................................................... 47

Application environment and GPS commands................................................................................................. 49

Keyboard and event commands....................................................................................................................... 51

IT policy commands.......................................................................................................................................... 53

13 Troubleshooting................................................................................................................................................ 55

The BlackBerry Smartphone Simulator takes a long time to start.................................................................... 55

I have a JVM error 543...................................................................................................................................... 55

Files for the BlackBerry Smartphone Simulator................................................................................................ 55

The location of user settings............................................................................................................................. 56

14 Glossary............................................................................................................................................................ 57

15 Provide feedback.............................................................................................................................................. 60

16 Legal notice....................................................................................................................................................... 61


7/65

BlackBerry Smartphone Simulator 1

OverviewThe 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 BlackBerry Smartphone Simulator

5


8/65

Starting the BlackBerry Smartphone Simulator 2

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 SimulatorFor 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 Steps

Start the BlackBerry Smartphone

Simulator from the Windows

taskbar.

On the taskbar, click Start > All Programs > Research In Motion >

BlackBerry Smartphone Simulatorsx.x.x> software_bundle_number>

device_name.


Simulator from the command

prompt with the supplied batch

file.

a. At the command prompt, navigate to the folder that contains the

version of the BlackBerry Smartphone Simulator that you want to

start.

b. At the command prompt, type:

.bat


Simulator from the command

prompt.

a. At the command prompt, navigate to the folder that contains the


start.


fledge /app-Jvm.dll /handheld=

Start the BlackBerry SmartphoneSimulator from the command

prompt and open a specified file

for debug messages.

a. At the command prompt, navigate to the folder that contains theversion of the BlackBerry Smartphone Simulator that you want to

start.


fledge /handheld= /app-param=JvmDebugFile

Development Guide Starting the BlackBerry Smartphone Simulator

6


9/65

Task Steps


Simulator from the commandprompt and open a specified

webpage.

a. If you are using a BlackBerry Smartphone Simulator earlier than 6.1,

start the BlackBerry MDS Simulator.b. At the command prompt, navigate to the folder that contains the


start.

c. At the command prompt, type:

fledge /handheld= /app-param=url: /app=jvm.dll

Development Guide Start the BlackBerry Smartphone Simulator

7


10/65

Using the BlackBerry Smartphone Simulator 3

Simulating touch screen inputWhen you simulate input for a touch screen BlackBerry device on the BlackBerry Smartphone Simulator all

commands use the mouse.

Gesture to simulateBlackBerry Device

Software versionsSteps

Click the screen. 4.71 to 5.1 Move the pointer to the simulated screen and click the left mouse

button.

Drag a finger. 4.7.1 and later 1. On the simulated screen, click either mouse button down and

hold it.

2. Move the pointer.

3. Release the mouse button.

Swipe across the

screen.

4.7.1 and later1. Click and hold the left or right mouse button.2. Quickly move the pointer in the desired direction.


Tap the screen. 6.0 and later With the left or right mouse button, click a spot on the simulated

screen.

Double-tap the

screen.

6.0 and later With the left or right mouse button, double-click a spot of the

simulated screen.

Pinch open or pinchclosed.

4.7.1 and later 1. On the Simulate menu, click Multitouch Mode.

2. With the left or right mouse button, click and drag anywhere

within the simulated screen area.

3. Perform the same action elsewhere on the screen.

After you complete the second action, both touches are simulated

as if they were done at the same time.

Touch the screen. 4.71 to 5.1 Click with the right mouse button on the simulated screen.Touch and hold

screen.

6.0 and later 1. On the simulated screen, click the left or right mouse button

and hold it.


Touch an item. 4.71 to 5.1 Right-click the mouse button on the item.

Touch the screen in

two locations at the

same time.

4.7.1 and later 1. On the Simulate menu, click Multitouch Mode.

2. With the left or right mouse button, click anywhere within the

simulated screen area.

3. Perform the same action elsewhere on the screen.

Development Guide Using the BlackBerry Smartphone Simulator

8


11/65

Gesture to simulateBlackBerry Device

Software versionsSteps

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 Keyboard mapping

Using the trackpad in an

application 1. Press F12 to activate the trackpad.2. Move your mouse over the BlackBerry Smartphone Simulator window.

3. Move your mouse in the direction you want to scroll.

To deactivate the trackpad, press F12 again.

Performing a trackpad click Make sure that you have activated the trackpad, then press F9 or click the wheel on

your mouse.

Navigating the Home

screen

Press UP or DOWN, or roll the scroll wheel on your mouse.

Using the Back button Press the ESC key, or right-click with your mouse.

Typing Use the keyboard.

Increasing the volume Press PLUS SIGN.

Decreasing the volume Press MINUS SIGN.

Accessing the Phone

application

Press PGUP.

Ending a phone call Press END.

Using alternate characters Press CTRL.

Muting the smartphone Press F7 to toggle between muted and unmuted.

Locking the smartphone Press F6 to toggle between locked and unlocked.

Inserting a currency symbol 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 Mouse with trackball mode on Mouse with trackball mode off

Turn trackball

mode on or

off.

Press F12. 1. On the Edit menu, click

Map Middle Mouse

Button > Toggle TrackballMode.

1. On the Edit menu, click

Map Middle Mouse

Button > Toggle TrackballMode.

Development Guide Sending input from the computer

9


12/65

Input Keyboard Mouse with trackball mode on Mouse with trackball mode off

2. Click the middle mouse

button.

2. Click the middle mouse

button.Click the

trackball.

Press F9. Click the left mouse button. On the trackball in the

simulator, click the middle

mouse button.

Roll the

trackball.

Press the arrow keys. Move the mouse. On the trackball in the

simulator, click and drag the

mouse.

Press the

Escape

button.

Press ESC. Click the right mouse button. On the trackball in the

simulator, click the right

mouse button.

Simulating trackwheel inputThe 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 Keyboard Mouse

Roll the trackwheel. Press the UP ARROW or DOWN

ARROW key.

Roll the mouse wheel button.

Click the trackwheel. Press the LEFT ARROW key. Click the mouse wheel button.

Press the Escape key. Press ESC or the RIGHT ARROW key. Click the right mouse button.Turn on BlackBerry device

backlighting.

Press PAGE DOWN. Click the Power button on the

BlackBerry Smartphone Simulator

keyboard.

Press the Symbol key. Press DELETE. Click the Symbol key on the


keyboard.

Press the Alt key. Press CTRL. Click the Alt key on the BlackBerry

Smartphone Simulator keyboard.

Press the BlackBerry device keys. Press the keys on your computer

keyboard.

Click the keys on the BlackBerry

Smartphone Simulator keyboard.

Press the phone/PTT (Push to Talk)

button.

Press PAGE UP.

Development Guide Simulating trackwheel input

10


13/65

Simulate a convenience key

Some keys that are present on BlackBerry devices are not present on computer keyboards. The BlackBerrySmartphone Simulator uses other keyboard keys to represent those BlackBerry keys.

Perform one of the following tasks:

Task Steps

Act as the Front Convenience key. Press INSERT.

Act as the Side Convenience key. Press PAGE UP.

Act as the Currency symbol key. Press F5.

Act as the Speaker phone key. Press F6.

Simulate a multi-function keySome 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 Steps

Act as the Front Convenience key. Press I.

Act as Menu key. Press INSERT.

Act as Right Side Convenience key. Press \.Act as Left Side Convenience key. Press PAGE UP.

Act as Volume Up key. Press F8.

Act as Volume Down key. Press F7.

Changing the BlackBerry smartphone orientationBlackBerry smartphones with touch screens support displaying screen information in either landscape or portrait

mode, depending on how the physical smartphone is oriented.

Orientation mode Description

Top-Side-Up The smartphone is oriented normally.

Left-Side-Up The smartphone is rotated 90 degrees to the right.

Right-Side-Up The smartphone is rotated 90 degrees to the left.Bottom-Side-Up The smartphone is rotated 180 degrees, upside-down.

Development Guide Simulate a convenience key

11


14/65

Orientation mode Description

Front-Side-Up The smartphone screen is facing upward.

Back-Side-Up The smartphone screen is facing downward.

Change screen orientation

Use the BlackBerry Smartphone Simulator to simulate a screen orientation change.

1. On the Simulate menu, click Tilt BlackBerry.

2. 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:

video card that supports OpenGL 1.1 or later

BlackBerry Smartphone Simulator 2.13 or later for a BlackBerry device with an accelerometer

1. On the Simulate menu, click Tilt BlackBerry.

2. Place the mouse pointer at a corner of the device.

The mouse pointer changes to an image of a device.

3. To rotate and tilt the device, press and hold the left mouse button while moving the mouse.

4. To stop rotating and tilting the device, release the mouse button.

View the event logThe 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 JVMThe 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.

Development Guide View the event log

12


15/65

Testing applications using the BlackBerrySmartphone Simulator

4

Load an application for testing

Perform one of the following tasks:

Task Steps

Load an application while theBlackBerry Smartphone

Simulator is running.

a. Compile the application as a .cod file.b. On the File menu, click on Load Theme or Application.

c. Click the .cod file that contains the application.

d. Click OK.

e. If your application consists of multiple .cod files, repeat steps 1 to

4 for each file.

Load an application while the


is running.

a. Compile the application as a .cod file.b. On the desktop, drag the .cod file to the BlackBerry Smartphone

Simulator.

Load an application by file

placement when starting the

BlackBerry Smartphone Simulator.

a. Compile the application as a .cod file.

b. Copy the .cod file into the BlackBerry Smartphone Simulator folder.

c. Start the BlackBerry Smartphone Simulator.

Load an application by using the

BlackBerry Java Plug-in for

Eclipse.

In Eclipse Package Manager, right-click the folder that contains the

application and select Run As > Simulator or Debug As > Simulator.

Load an application by using the

BlackBerry WebWorks Plug-in

for Eclipse.

In the Eclipse Package Manager, right-click the folder that contains

the application and select Run As > Simulator or Debug As >

Simulator.

Testing GPS applicationsYou 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.

Development Guide Testing applications using the BlackBerry Smartphone Simulator

13


16/65

Testing JavaScript and webpages

If you use the BlackBerry Smartphone Simulator version earlier than 6.0, you must save a webpage as a BlackBerryWebWorks 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 MIDletsIf 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. Place the .jad and .jar files on a web server.

2. Start the BlackBerry MDS Simulator.

3. Start the BlackBerry Smartphone Simulator.

4. On the BlackBerry Smartphone Simulator screen, click the Browser icon.5. Use the browser to navigate to the location of the application .jad file.

6. 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 policiesThe 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 EnterpriseServer

Before you begin: The BlackBerry Enterprise Server that you have an account on is running.

1. Start the BlackBerry Smartphone Simulator.

Development Guide Testing JavaScript and webpages

14

l d f h l k l d h l k h l f l k


17/65

2. On the Home screen, click the Turn Wireless Officon.

3. From the taskbar, click Start > Programs > BlackBerry > BlackBerry Desktop Software.

4. From the BlackBerry Smartphone Simulator taskbar, click Simulate >USB Cable Connected.5. In the BlackBerry Desktop Software, click Get started with this device.

6. Follow the instructions to generate a new encryption key.

7. 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 theBlackBerry Smartphone Simulator for BlackBerryMessenger

To test a BBM connected application on a BlackBerry Smartphone Simulator, you must install and configure theBlackBerry 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.

Development Guide Configuring the BlackBerry MDS Simulator and the BlackBerry Smartphone Simulator for BlackBerry

Messenger

15

Development Guide BlackBerry Device Software applications
http://docs.blackberry.com/en/developers/subcategories/?userType=21&category=BlackBerry+Messenger+Social+Platform+SDK


18/65

BlackBerry Device Software applications 5

Using the cameraMake 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 orturn 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. Click the Camera icon.2. 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.

3. To take a picture, click the trackball.

4. To take another picture, click Take Another Picture.

Delete a picture

1. Click Delete Picture.

2. 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.

Development Guide BlackBerry Device Software applications

16

Development Guide Recording video


19/65

BlackBerry Device Software version Resolution in pixels

4.2 1280 x 1024 (1.3 megapixels)

5.x 2048 x 1536 (3.2 megapixels)

6.0 2560 x 1920 (5.0 megapixels)

Recording videoBefore 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. Click the Video Camera icon.

2. Click the Menu key.

3. Click Options.

4. Perform any of the following actions:

Task Steps

Set the video light. Specify the Video Light option.

Set the color effect Specify the Color Effect option.

Set the video resolution. 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. On the Simulate menu, click Incoming Voice Call.

2. In the New Incoming Call dialog box, for the originating phone number, type a new phone number or the phonenumber of an existing contact.

3. Set one of the following Caller ID options:

Option Description

Allowed The BlackBerry smartphone can display the phone number of the originating

phone.

Private The phone number of the originating phone is blocked and not available fordisplay on the BlackBerry smartphone.

Development Guide Recording video

17

Development Guide Using the phone application


20/65

Option Description

Unknown The BlackBerry smartphone cannot determine the phone number of the

originating phone.

4. To place the phone call to the BlackBerry Smartphone Simulator, click Create Call.

5. Click Answer or Ignore.

6. End the call by performing one of the following actions:

Task Steps

Simulate the termination of the call by the originating

phone.

Click Disconnect.

Simulate a network failure. a. Set a reason for failure.

b. Click Fail.

Simulate an outgoing call

1. Open Call Log.

2. In the Call Log menu, click Call From Address Book.

3. In the Call field, type a new phone number or set a contact.

4. Press the Enter key.

5. Open the menu.

6. Click Continue.

7. 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.

Development Guide Using the phone application

18

Development Guide Changing BlackBerry Smartphone Simulator display options


21/65

Changing BlackBerry Smartphone Simulatordisplay options

6

Magnify the BlackBerry device image

1. On the View menu, click Zoom.

2. Click a percentage.

3. On the View menu, click Smooth Magnified LCD.

Hide the faceplateBy 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 offIf 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 accelerationBy 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. In the BlackBerry Smartphone Simulator, on the View menu, click Graphics Acceleration.2. Click the level of acceleration that you want.

Taking screen shotsYou 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 imageof the BlackBerry device screen as a .png file. You can override the default.

p g g y p p y p

19

Development Guide Taking screen shots


22/65

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


23/65

Changing BlackBerry device operatingconditions

7

Use a single-button headset

1. On the Simulate menu, click Headset Connected.

2. In the Headset dialog box, perform one of the following actions:

Task Steps

Connect a single-button

headset.Select the One button headset inserted option.

Click the button on a single-

button headset.Click Click.

Use a multibutton headset


2. Complete one of the following tasks:

Task Steps

Connect a multibutton

headset.In the Headset dialog box, select the Multibutton headset inserted option.

Click a button on amultibutton headset.

Under the Multibutton headset inserted option, click one of buttons.

Disconnect a headset


2. In the Headset dialog box, select the No headset option.

Change holster conditionsWhen 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


24/65

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 deviceWhen 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. On the Simulate menu, click Battery Properties.

2. Set one of the following options:

Option DescriptionFull The battery level is sufficient for BlackBerry device and network use.

Low The BlackBerry device alerts the user, but remains turned on and can still use the

network.

Very Low The BlackBerry device cannot access the network, but the device remains turned

on.

Camera flash is disabled.

Dead The BlackBerry device turns off immediately.

If you select this option, the BlackBerry Smartphone Simulator shuts down.

Other This option enables you to specify the battery level as a percentage.

Simulate the absence of a SIM cardThe 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= /no-sim-present

Simulating network conditions

The BlackBerry Smartphone Simulator can simulate various states of network coverage, from a strong signal to avery weak signal. The BlackBerry Smartphone Simulator can also simulate a loss of network coverage.

22

Development Guide Simulate supplementary phone services


25/65

Add a network

1. On the Simulate menu, click Network Properties.

2. Click Add.

3. Type the network properties in the dialog.

4. Click OK.

Set the network signal strength

1. On the Simulate menu, click Network Properties.2. Select the network you want to simulate from the Networks list.

3. If you want to edit the network properties, click Edit and type new values. Click OK.

4. Select or clear the In coverage check box.

5. 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 connectionYou 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. On the Simulate menu, click Network Properties.2. In the Available Network Properties section, click a Wi-Fi network.

3. In the Global Network Properties section, move the slide bar to the interval that you want.

4. Click Close.

Simulate supplementary phone services

A number of supplementary phone services, such as call forwarding or call waiting, might be available on a BlackBerrydevice. You can simulate the availability of these services. By default, the BlackBerry Smartphone Simulator is set up

with all supplementary services.

1. On the Simulate menu, click Provision Supplementary Services.

2. In the Supplementary Services Provisioned dialog box, enable or disable services.

23

Development Guide How the BlackBerry Smartphone Simulator simulates application storage


26/65

How the BlackBerry Smartphone Simulator simulatesapplication storageThe 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 *.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 BlackBerrySmartphone Simulator exits, it saves the application storage contents to the .dmp files.

Clear the application storage

1. Close the BlackBerry Smartphone Simulator.

2. 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 policiesTo 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 securemodeBefore you deploy your application, you should test the application in secure mode.

24

Development Guide Connecting to Bluetooth USB accessories


27/65

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\\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 accessoriesThe 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 computerSimulating 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


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


28/65

a. On the Tools menu, click Connection options.

b. In the Connection Type drop-down list, click USB.

c. Click Simulation.

2. In the BlackBerry Smartphone Simulator, on theSimulate menu, select or clear the USB Cable Connected option.

Simulating a media cardThe BlackBerry Smartphone Simulator loads and saves the media card image to *.sdcard in the

working directory, unless you have set the /sdcard= 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/sdcard-

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. Create a folder on your computer to store files for the media card.

2. In the BlackBerry Smartphone Simulator, on the Simulate menu, click Change SD Card.

3. In the list of available media cards, click one.

4. Click the Mount icon.

5. 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 Simulating a media card


29/65

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


30/65

Using GPS and Location Based Services 8

Simulating GPS location informationYou 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. On the Simulate menu, click GPS Location.

2. In the Location section, click Add.

3. In the Name field, type a name.

4. In the Latitude and Longitude fields, type a latitude and longitude.

5. In the Altitude field, type an altitude in meters above or below the WGS 84 reference ellipsoid.

6. 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.

7. 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. On the Simulate menu, click GPS Location.

2. In the Location drop-down list, click a location.

3. Click Edit and change the values in the appropriate fields.

Renaming a location can cause existing routes that contain that location name to fail.

4. Click Save.

Delete a GPS location


2. In the Location drop-down list, click a location to delete.

3. Click Delete.

28

Development Guide Managing GPS routes


31/65

Managing GPS routesTo 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


2. In the Route section, click Add.

3. Click existing locations.

4. Type a name for the new route

5. Select the starting location of the route.

6. Type a speed value and set the rate of speed for the path.7. Click Insert to insert this location into the route.

8. To add additional locations to the route, repeat steps 3 through 5.

9. 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.



3. In the Create New Route dialog box, click data from a file and click OK.

4. Select the file that contains the sentence and click OK.

5. Click Close.

Create a GPS route by using a random set of your locations



29



32/65

3. Select Create route using random route generator.

4. Click OK.

5. 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


2. Set a route to change.

3. Perform one or more of the following procedures:

Task Steps

Change the route name. In the Name field, type a new name for the route.

Add a location to the route. a. Click Insert.

b. In the Start Location drop-down list, click a location.

c. Type a speed value and set the rate of speed for the path.

Change a location. a. In the text box, under the Name field, set the location you want

to change.

b. In the Start Location drop-down list, click the location you want

to change to.

c. Type a speed value and set the rate of speed for the path.

Remove a location. a. From the text box, under the Name field, set a location.b. Click Delete.

4. In the Name field, type a new name for the route.

5. Click Save.

Delete a GPS route


2. In the Route drop-down list, click a route to delete.

3. 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. On the Simulate menu, click GPS Location.

30



33/65

2. Perform one of the following actions:

Task Steps

Play a route. In the Route section, click the Play (right arrow) icon.

Stop a route. 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


34/65

Testing NFC applications 9

Testing NFC applications on the BlackBerry SmartphoneSimulatorSome 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 asa 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 SimulatorThe 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 S imulator.

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 parametersSome of the NFC parameters can be set within the BlackBerry Smartphone Simulator. You must set the others at

the command prompt.

1. On the Simulate menu, click NFC Options.

2. Perform either of the following tasks:

32

Development Guide Command prompt parameters related to NFC
http://sourceforge.net/projects/open-nfc/files/http://sourceforge.net/projects/open-nfc/files/http://sourceforge.net/projects/open-nfc/files/http://sourceforge.net/projects/open-nfc/files/http://sourceforge.net/projects/open-nfc/files/


35/65

Task Steps

Initialize NFC for the NFC Controller Simulator rather

than a test board, whenever the BlackBerrySmartphone Simulator starts. This is identical to using

the /nfcc-using-sim parameter at the command

prompt.

Beside Use NFC Simulator, check the box.

Specify location of the NFC Controller 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 optionprevents all NFC communication between the

BlackBerry Smartphone Simulator and the NFC

Controller.

In the text box under NFC Controller URI, enter the

URI for the NFC Simulator.

3. On the Simulate menu, click Initialize NFC.

Command prompt parameters related to NFC

Parameters Description

/ump= 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./nfcc-uri= 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


/nfcc-using-sim= This parameter defines whether you are using an

NFC simulator application. By default, it is set to

false, but when using an NFC simulatorapplication, this value should be set to true. You

can set this value on the BlackBerry Smartphone

Simulator.

33

Development Guide Test an NFC application


36/65

Test an NFC applicationIf 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. Start the Connection Center.

2. Start the NFC Controller Simulator.

3. On older versions of the NFC Controller Simulator, on the NFC Device #1 menu, click Start.

4. In the Connection Center, on the Global tab, click Service List to display a dialog box with a list of services.

5. 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).

6. In the Connection Center, click Copy service URI.

7. At the command prompt, start the BlackBerry Smartphone Simulator with the additional parameters /nfcc-

using-sim=true and /nfcc-uri=. If the URI contains spaces, enclose the entire URI in double

quotation marks.

8. 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.

9. In the NFC Controller Simulator, in the NFC Object Manager window, perform one of the following:

Task Steps

Present an NFC card or token. In the Object List, double-click the name of the NFC

card or token.

Remove an NFC card or token. Under the label NFC Device #1 Antenna, double-click

the image.

10. In the BlackBerry Smartphone Simulator, test the application.

34

Development Guide Simulating magnetometer information


37/65

Simulating magnetometer information 10

MagnetometerA 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 directionalmagnetometer 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 informationBecause 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


38/65

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.

Create or edit a magnetic pathEach 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. On the Simulate menu, click Manipulate Device.

2. To edit an existing magnetic path, load it from a .mag file.

3. If necessary, add or delete keys.

4. For each key, add the necessary BlackBerry smartphone rotation data.

5. For each key, add the necessary magnetic data.

6. In the Playback section, in the Duration field, specify the length of time for the playback, in seconds.

7. 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.


2. In the Playback section, click the playback line at about one-third its length.

3. Click Add Key.

4. In the Tilt field, type 180.

5. Click in one of the other fields.

6. Click Apply.

7. Click the N icon in the top right corner.

8. In the Inclination field, type 90.

9. 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



39/65

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. To add a key, in the Playback section, click in the playback line where you want the new key and click Add Key.

2. Click the key that you want to change.

3. Do one of the following:

Task Description

Set the rotation around the z axis. 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.Set the tilt around the x axis. 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.

Set the direction around the y axis. Do one of the following:

Click on the black circle and drag it until the arrowpoints in the direction you want.

In the Manual Input section, in the Direction field,

type the angle, in degrees, and click Apply.

Move a key to a new location. Click and drag the key to the new location.

4. If necessary, change the magnetic field reading.

5. 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. To add a key, in the Playback section, click in the path window where you want the new key and click Add Key.2. Click the key that you want to change.

37

f h f ll



40/65

3. Do any of the following:

Task Description

Set the difference between true north and

magnetic north.

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.

Set the vertical angle of the magnetic field. 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.

Set the strength of the magnetic field a. In the Manual Input section, in the Field

Strength(microTesla) field, type the field strength, in

microTeslas.

b. Click Apply.

Set the reliability of the magnetometer

reading.a. In the Manual Input section, in the Reading Quality field,

select one ofUnreliable, Low, Medium, or High.

b. Click Apply.

Note: When you set the Reading Quality to Low, you can only

recalibrate after a subsequent reading ofHigh.

Move a key to a new location. Click and drag the key to the new location.

4. If necessary, change the smartphone orientation in the key.

5. 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.


2. Click Load.

3. In the Open Magnetometer animation file dialog box, click on the .mag file to load.

4. Click Open.

38

Development Guide Display rotation in the BlackBerry Smartphone Simulator window


41/65

Save the current magnetic path

Before you begin: Make sure that the Device Manipulator window is open.

1. Click Save.

2. Type a name for the magnetic path file.

3. Click Save.

4. Click OK.

Display rotation in the BlackBerry Smartphone SimulatorwindowYou 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

Testing applications that require an HTTP 11

Development Guide Testing applications that require an HTTP connection


42/65

Testing applications that require an HTTPconnection

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 SmartphoneSimulator 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. Navigate to the \Program Files\Research In Motion\BlackBerry Email and M

blackberry smart phone simulator development guide 1640741 0916031807 001 7.0 us

Documents